Main header file for libforensic1394. More...

#include <stdlib.h>
#include <stdint.h>

Data Structures
struct	forensic1394_req
	A request structure used for making batch read/write requests. More...
Defines
#define	FORENSIC1394_DECL
#define	FORENSIC1394_CSR_SZ 256
	Number of uint32 elements required to store a device ROM.
Typedefs
typedef struct _forensic1394_bus	forensic1394_bus
	An opaque bus handle.
typedef struct _forensic1394_dev	forensic1394_dev
	An opaque device handle.
typedef void(*	forensic1394_device_callback )(forensic1394_bus bus, forensic1394_dev dev)
Enumerations
enum	forensic1394_result { FORENSIC1394_RESULT_SUCCESS = 0, FORENSIC1394_RESULT_OTHER_ERROR = -1, FORENSIC1394_RESULT_BUS_RESET = -2, FORENSIC1394_RESULT_NO_PERM = -3, FORENSIC1394_RESULT_BUSY = -4, FORENSIC1394_RESULT_IO_ERROR = -5, FORENSIC1394_RESULT_IO_SIZE = -6, FORENSIC1394_RESULT_IO_TIMEOUT = -7, FORENSIC1394_RESULT_END = -8 }
	Possible return status codes. More...
Functions
FORENSIC1394_DECL forensic1394_bus *	forensic1394_alloc (void)
	Allocates a new forensic1394 handle.
FORENSIC1394_DECL forensic1394_result	forensic1394_enable_sbp2 (forensic1394_bus *bus)
	Provides an SBP-2 unit directory; required for DMA to Windows systems.
FORENSIC1394_DECL forensic1394_dev **	forensic1394_get_devices (forensic1394_bus bus, int ndev, forensic1394_device_callback ondestroy)
	Gets the devices attached to the FireWire bus.
FORENSIC1394_DECL void	forensic1394_destroy (forensic1394_bus *bus)
	Destroys a bus handle.
FORENSIC1394_DECL void *	forensic1394_get_bus_user_data (forensic1394_bus *bus)
	Fetches the user data for bus.
FORENSIC1394_DECL void	forensic1394_set_bus_user_data (forensic1394_bus bus, void u)
	Sets the user data for the bus.
FORENSIC1394_DECL forensic1394_result	forensic1394_open_device (forensic1394_dev *dev)
	Opens the device dev for reading/writing.
FORENSIC1394_DECL void	forensic1394_close_device (forensic1394_dev *dev)
	Closes the device dev.
FORENSIC1394_DECL int	forensic1394_is_device_open (forensic1394_dev *dev)
	Checks if a device is open or not.
FORENSIC1394_DECL forensic1394_result	forensic1394_read_device (forensic1394_dev dev, uint64_t addr, size_t len, void buf)
	Reads len bytes from dev starting at addr into buf.
FORENSIC1394_DECL forensic1394_result	forensic1394_read_device_v (forensic1394_dev dev, forensic1394_req req, size_t nreq)
	Reads each request specified in req from dev asynchronously.
FORENSIC1394_DECL forensic1394_result	forensic1394_write_device (forensic1394_dev dev, uint64_t addr, size_t len, void buf)
	Writes len bytes from buf to dev starting at addr.
FORENSIC1394_DECL forensic1394_result	forensic1394_write_device_v (forensic1394_dev dev, const forensic1394_req req, size_t nreq)
	Writes each request specified in req to dev asynchronously.
FORENSIC1394_DECL void	forensic1394_get_device_csr (forensic1394_dev dev, uint32_t rom)
	Copies the configuration ROM for the device dev into rom.
FORENSIC1394_DECL uint16_t	forensic1394_get_device_nodeid (forensic1394_dev *dev)
	Returns the node ID of the device.
FORENSIC1394_DECL int64_t	forensic1394_get_device_guid (forensic1394_dev *dev)
	Returns the GUID of the device.
FORENSIC1394_DECL const char *	forensic1394_get_device_product_name (forensic1394_dev *dev)
	Returns the product name of the device, if any.
FORENSIC1394_DECL int	forensic1394_get_device_product_id (forensic1394_dev *dev)
	Returns the product ID of the device, if any.
FORENSIC1394_DECL const char *	forensic1394_get_device_vendor_name (forensic1394_dev *dev)
	Returns the vendor name of the device, if any.
FORENSIC1394_DECL int	forensic1394_get_device_vendor_id (forensic1394_dev *dev)
	Returns the vendor ID of the device, if any.
FORENSIC1394_DECL int	forensic1394_get_device_request_size (forensic1394_dev *dev)
	Returns the maximum request size supported by the device.
FORENSIC1394_DECL void *	forensic1394_get_device_user_data (forensic1394_dev *dev)
	Fetches the user data for the device dev.
FORENSIC1394_DECL void	forensic1394_set_device_user_data (forensic1394_dev dev, void u)
	Sets the user data for the device dev to u.
FORENSIC1394_DECL const char *	forensic1394_get_result_str (forensic1394_result r)
	Converts a return status code to a string.

Detailed Description

Main header file for libforensic1394.

Define Documentation

#define FORENSIC1394_CSR_SZ 256

Number of uint32 elements required to store a device ROM.

A FireWire configuration status ROM (CSR) is made up of unsigned 32-bit integers. The maximum size of a ROM is 1024 bytes, giving 256 elements.

#define FORENSIC1394_DECL

Typedef Documentation

typedef struct _forensic1394_bus forensic1394_bus

An opaque bus handle.

typedef struct _forensic1394_dev forensic1394_dev

An opaque device handle.

typedef void(* forensic1394_device_callback)(forensic1394_bus *bus, forensic1394_dev *dev)

A function to be called when a forensic1394_dev is about to be destroyed. This should be passed to forensic1394_get_devices and will be associated with all devices returned by the method. The callback will fire either when the bus is destroyed via forensic1394_destroy or the next time that forensic1394_get_devices is called (which has the implicit effect of destroying all existing devices first).

If user data is required it can be attached on either a per-bus or per-device level.

Parameters:

	bus	The bus owning the device.
	dev	The device being destroyed.

See also:: forensic1394_set_bus_user_data; forensic1394_set_device_user_data

Enumeration Type Documentation

enum forensic1394_result

Possible return status codes.

In general methods return 0 on success and a negative integer on failure. These codes may be used to ascertain precisely why a method failed. It is worth noting that invalid input parameters are handled with assertions as opposed to status codes.

See also:: forensic1394_get_result_str

Enumerator:

FORENSIC1394_RESULT_SUCCESS	No errors encountered.
FORENSIC1394_RESULT_OTHER_ERROR	General, unspecified, error.
FORENSIC1394_RESULT_BUS_RESET	A bus reset has occured.
FORENSIC1394_RESULT_NO_PERM	Permissions related error.
FORENSIC1394_RESULT_BUSY	Device is busy.
FORENSIC1394_RESULT_IO_ERROR	General I/O error.
FORENSIC1394_RESULT_IO_SIZE	Bad transfer size (normally too large).
FORENSIC1394_RESULT_IO_TIMEOUT	I/O Timeout.
FORENSIC1394_RESULT_END	Sentinel; internal use only.

Function Documentation

FORENSIC1394_DECL forensic1394_bus* forensic1394_alloc ( void )

Allocates a new forensic1394 handle.

This handle can then be used to query the devices attached to the bus and to update the configuration status ROM (CSR) of the bus.

Returns:: A handle to a forensic1394_bus on success, NULL otherwise.

FORENSIC1394_DECL void forensic1394_close_device ( forensic1394_dev * dev )

Closes the device dev.

This can only be called on an open device.

Parameters:

dev

The device to close.

FORENSIC1394_DECL void forensic1394_destroy ( forensic1394_bus * bus )

Destroys a bus handle.

Releases all of the memory associated with the handle, closing any open devices. After a call to this method all forensic1394 device handles are invalidated.

Parameters:

bus

The forensic1394_bus to destroy.

FORENSIC1394_DECL forensic1394_result forensic1394_enable_sbp2 ( forensic1394_bus * bus )

Provides an SBP-2 unit directory; required for DMA to Windows systems.

Updates the configuration status ROM of the bus to contain an SBP-2 unit directory. This is required in order for some connected devices to allow for direct memory access (`DMA').

Note that this is usually a global change, affecting all FireWire ports on the system.

As calling this method usually results in a bus reset it is advisable to call it as soon as a bus is available.

Parameters:

bus

The 1394 bus to add the SBP-2 unit directory to.

Returns:: A result status code.

FORENSIC1394_DECL void* forensic1394_get_bus_user_data ( forensic1394_bus * bus )

Fetches the user data for bus.

Returns the user data for bus. If forensic1394_set_bus_user_data is yet to be called on the bus the result is undefined.

Parameters:

bus

The bus.

Returns:: The user data associated with the bus.

See also:: forensic1394_set_bus_user_data

FORENSIC1394_DECL void forensic1394_get_device_csr	(	forensic1394_dev *	dev,
		uint32_t *	rom
	)

Copies the configuration ROM for the device dev into rom.

Fetches the configuration status ROM (CSR) for the device and copies it into rom. This is assumed to be of at least FORENSIC1394_CSR_SZ elements in size. Any unused space will be filled with zeros.

Parameters:

	dev	The device.
	rom	The array to copy the CSR into.

FORENSIC1394_DECL int64_t forensic1394_get_device_guid ( forensic1394_dev * dev )

Returns the GUID of the device.

This is a 48-bit value, similar to a MAC address, that uniquely identifies a FireWire device.

Parameters:

dev

The device.

Returns:: The GUID of the device.

FORENSIC1394_DECL uint16_t forensic1394_get_device_nodeid ( forensic1394_dev * dev )

Returns the node ID of the device.

It is important to note that this value does not remain constant across bus resets and is hence unsuitable for device identification.

Parameters:

dev

The device.

Returns:: The node ID of the device.

FORENSIC1394_DECL int forensic1394_get_device_product_id ( forensic1394_dev * dev )

Returns the product ID of the device, if any.

Should the property not exist then 0 is returned.

Parameters:

dev

The device.

Returns:: The product ID of the device, or 0 if it is not defined.

FORENSIC1394_DECL const char* forensic1394_get_device_product_name ( forensic1394_dev * dev )

Returns the product name of the device, if any.

Should the property not exist for the device an empty string ("") is returned. The string is guaranteed to remain valid for the lifetime of the device.

Parameters:

dev

The device.

Returns:: The product name of the device, if any.

FORENSIC1394_DECL int forensic1394_get_device_request_size ( forensic1394_dev * dev )

Returns the maximum request size supported by the device.

Parses the configuration status ROM for the device and extracts the maximum supported request size (usually 2048 bytes). This value should be taken as an upper-bound for the length of read/write calls. If a size can not be found in the CSR then 512 bytes will be returned.

The returned size is guaranteed to be a positive power of two.

Parameters:

dev

The device.

Returns:: The maximum request size in bytes.

FORENSIC1394_DECL void* forensic1394_get_device_user_data ( forensic1394_dev * dev )

Fetches the user data for the device dev.

If forensic1394_set_device_user_data is yet to be called on the device the result is undefined.

Parameters:

dev

The device.

Returns:: The user data associated with the device.

See also:: forensic1394_set_device_user_data

FORENSIC1394_DECL int forensic1394_get_device_vendor_id ( forensic1394_dev * dev )

Returns the vendor ID of the device, if any.

Should the property not exist then 0 is returned.

Parameters:

dev

The device.

Returns:: The vendor ID of the device, or 0 if it is not defined.

FORENSIC1394_DECL const char* forensic1394_get_device_vendor_name ( forensic1394_dev * dev )

Returns the vendor name of the device, if any.

Should the property not exist for the device an empty string ("") is returned. The string is guaranteed to remain valid for the lifetime of the device.

Parameters:

dev

The device.

Returns:: The vendor name of the device, if any.

FORENSIC1394_DECL forensic1394_dev** forensic1394_get_devices	(	forensic1394_bus *	bus,
		int *	ndev,
		forensic1394_device_callback	ondestroy
	)

Gets the devices attached to the FireWire bus.

This method scans the (foreign) devices attached to bus and returns a NULL-terminated list of them.

The out-parameter ndev, if not NULL, serves a dual purpose. After a call to the function if *ndev is:

>= 0 then the call was successful and it contains the number of devices attached to the system, which may be 0 if no devices are attached.
< 0 then the call was not successful and it contains the appropriate forensic1394_result error code.

Getting the attached devices is a destructive process; voiding any existing device handles. To compensate for this the ondestroy callback is provided. This argument, if not NULL, will be called when the new device list is destroyed, usually as a result of a subsequent call to forensic1394_get_devices or a call to forensic1394_destroy. The function is called for each device in the list.

Warning:: Calling this method will invalidate all active device handles.

Parameters:

	bus	The bus to get the devices for.
`[out]`	ndev	The number of devices found; NULL is acceptable.
`[in]`	ondestroy	Function to be called when the returned device list is destroyed; NULL for no callback.

Returns:: A NULL-terminated list of devices.

See also:: forensic1394_device_callback; forensic1394_result

FORENSIC1394_DECL const char* forensic1394_get_result_str ( forensic1394_result r )

Converts a return status code to a string.

Returns a textual representation of the return status code result. The string returned is guaranteed to be valid for the lifetime of the program.

In the event of an invalid code NULL is returned.

Parameters:

r

The return status code.

Returns:: A description of the error code on success; NULL otherwise.

FORENSIC1394_DECL int forensic1394_is_device_open ( forensic1394_dev * dev )

Checks if a device is open or not.

Parameters:

dev

The FireWire device.

Returns:: Non-zero if the device is open; 0 if it is closed.

FORENSIC1394_DECL forensic1394_result forensic1394_open_device ( forensic1394_dev * dev )

Opens the device dev for reading/writing.

It is necessary to open a device before attempting to read/write from it.

Parameters:

dev

The device to open.

Returns:: A result status code.

See also:: forensic1394_close_device

FORENSIC1394_DECL forensic1394_result forensic1394_read_device	(	forensic1394_dev *	dev,
		uint64_t	addr,
		size_t	len,
		void *	buf
	)

Reads len bytes from dev starting at addr into buf.

Performs a blocking (synchronous) read on the device dev, starting at the address addr and attempting to read len bytes. The resulting bytes are copied into buf.

It is worth noting that many devices impose a limit on the maximum transfer size. This limit can be obtained by calling forensic1394_get_device_request_size and is usually 2048 bytes in size.

This method is a convenience wrapper around forensic1394_read_device_v.

Parameters:

	dev	The device to read from.
	addr	The memory address to start reading from.
	len	The number of bytes to read.
`[out]`	buf	The buffer to copy the read bytes into; must be at least len bytes in size.

Returns:: A result status code.

See also:: forensic1394_get_device_request_size; forensic1394_read_device_v

FORENSIC1394_DECL forensic1394_result forensic1394_read_device_v	(	forensic1394_dev *	dev,
		forensic1394_req *	req,
		size_t	nreq
	)

Reads each request specified in req from dev asynchronously.

Vectorised, scatter input, read method. By issuing requests asynchronously this function is often able to offer better performance than a series of forensic1394_read_device calls. The performance gains, if any, depend heavily on the capabilities of the backend.

Each request must be no larger than forensic1394_get_device_request_size bytes. If any of the data buffers in req overlap then the behaviour is undefined.

The method will return early should one of the requests fail. It is not currently possible to determine which request caused the error.

Parameters:

	dev	The device to read from.
	req	The read requests to service.
	nreq	The number of requests in req.

Returns:: A result status code.

FORENSIC1394_DECL void forensic1394_set_bus_user_data	(	forensic1394_bus *	bus,
		void *	u
	)

Sets the user data for the bus.

Parameters:

	bus	The bus.
`[in]`	u	The user data to set.

See also:: forensic1394_get_bus_user_data

FORENSIC1394_DECL void forensic1394_set_device_user_data	(	forensic1394_dev *	dev,
		void *	u
	)

Sets the user data for the device dev to u.

Parameters:

	dev	The device.
`[in]`	u	The user data to set.

See also:: forensic1394_get_device_user_data

FORENSIC1394_DECL forensic1394_result forensic1394_write_device	(	forensic1394_dev *	dev,
		uint64_t	addr,
		size_t	len,
		void *	buf
	)

Writes len bytes from buf to dev starting at addr.

Performs a blocking (synchronous) write on the device dev attempting to copy len bytes from buf to the device address addr. See the documentation for forensic1394_read_device for a discussion on the maximum transfer size.

This method is a convenience wrapper around forensic1394_write_device_v.

Parameters:

	dev	The device to write to.
	addr	The memory address to start writing to.
	len	The number of bytes to write.
`[in]`	buf	The buffer to write.

Returns:: A result status code.

forensic1394_read_device

FORENSIC1394_DECL forensic1394_result forensic1394_write_device_v	(	forensic1394_dev *	dev,
		const forensic1394_req *	req,
		size_t	nreq
	)

Writes each request specified in req to dev asynchronously.

The vectorised, gather output, write method. Depending on the backend this method may issue the requests in req asynchronously in order to improve performance. See forensic1394_read_device_v for further discussion.

Parameters:

	dev	The device to write to.
`[in]`	req	The write requests to service.
	nreq	The number of requests in req.

Returns:: A result status code.

forensic1394.h File Reference

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation