Data Structures | Defines | Typedefs | Enumerations | Functions

forensic1394.h File Reference

Main header file for libforensic1394. More...

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

Go to the source code of this file.

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.

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

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.
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines