ADC Home > Reference Library > Reference > Hardware & Drivers > I/O Kit Framework Reference

IOFireWireLib.h

Includes:

Overview

IOFireWireLib is the software used by user space software to communicate with FireWire devices and control the FireWire bus. IOFireWireLib is the lowest-level FireWire interface available in user space.

To communicate with a device on the FireWire bus, an instance of IOFireWireDeviceInterface (a struct which is defined below) is created. The methods of IOFireWireDeviceInterface allow you to communicate with the device and create instances of other interfaces which provide extended functionality (for example, creation of unit directories on the local machine).

References to interfaces should be kept using the interface reference typedefs defined herein. For example, you should use IOFireWireLibDeviceRef to refer to instances of IOFireWireDeviceInterface, IOFireWireLibCommandRef to refer to instances of IOFireWireCommandInterface, and so on.

To obtain an IOFireWireDeviceInterface for a device on the FireWire bus, use the function IOCreatePlugInInterfaceForService() defined in IOKit/IOCFPlugIn.h. (Note the "i" in "PlugIn" is always upper-case.) Quick usage reference:

'service' is a reference to the IOKit registry entry of the kernel object (usually of type IOFireWireDevice) representing the device of interest. This reference can be obtained using the functions defined in IOKit/IOKitLib.h.
'plugInType' should be CFUUIDGetUUIDBytes(kIOCFPlugInInterfaceID)
'interfaceType' should be CFUUIDGetUUIDBytes(kIOFireWireLibTypeID) when using IOFireWireLib

The interface returned by IOCreatePlugInInterfaceForService() should be deallocated using IODestroyPlugInInterface(). Do not call Release() on it.

C Pseudoclasses

IOFireWireAsyncStreamCommandInterface
IOFireWireCommandInterface: IOFireWireLib command object.
IOFireWireCompareSwapCommandInterface
IOFireWireCompareSwapCommandInterface_v3
IOFireWireConfigDirectoryInterface: IOFireWireLib device config ROM browsing interface.
IOFireWireDeviceInterface: IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib.
IOFireWireLibPHYPacketListenerInterface
IOFireWireLibVectorCommandInterface: IOFireWireLib command object for grouping commands execution.
IOFireWireLocalUnitDirectoryInterface
IOFireWireNubInterface: IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib.
IOFireWirePHYCommandInterface
IOFireWirePhysicalAddressSpaceInterface: IOFireWireLib physical address space object.
IOFireWirePseudoAddressSpaceInterface
IOFireWireReadCommandInterface: IOFireWireLib block read command object.
IOFireWireReadQuadletCommandInterface: IOFireWireReadQuadletCommandInterface -- IOFireWireLib quadlet read command object.
IOFireWireUnitInterface: IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib.
IOFireWireWriteCommandInterface: IOFireWireLib block read command object.
IOFireWireWriteQuadletCommandInterface: IOFireWireLib quadlet read command object.

Functions

allocateIsochResources: Use this interface to allocate isochronous resources
areIsochResourcesAllocated: Poll to see if IRM resources are still allocated
deallocateIsochResources: Deallocate previously allocated resources
GetRefCon: Get the current refcon
NotificationIsOn: Is notification on?
SetRefCon: Set a new refcon
setReleaseIRMResourcesOnFree: Set a new value for releaseIRMResourcesOnFree
TurnOffNotification: Force notification off.
TurnOnNotification: Try to turn on notifications

allocateIsochResources

Use this interface to allocate isochronous resources

IOReturn ( *allocateIsochResources)(
    IOFireWireLibIRMAllocationRef self,
    UInt8 isochChannel,
    UInt32 bandwidthUnits);

Parameters

self: The IRMAllocation interface to use.
isochChannel: The isoch channel to allocate.
bandwidthUnits: The bandwidth units to allocate.

Return Value

Returns true if allocation success

areIsochResourcesAllocated

Poll to see if IRM resources are still allocated

Boolean ( *areIsochResourcesAllocated)(
    IOFireWireLibIRMAllocationRef self,
    UInt8 *pAllocatedIsochChannel,
    UInt32 *pAllocatedBandwidthUnits);

Parameters

self: The IRMAllocation interface to use.
pAllocatedIsochChannel: If allocated, the channel
pAllocatedBandwidthUnits: If allocated, the amount of bandwidth

Return Value

Returns true if currently allocated, false otherwise

deallocateIsochResources

Deallocate previously allocated resources

IOReturn ( *deallocateIsochResources)(
    IOFireWireLibIRMAllocationRef self);

Parameters

self: The IRMAllocation interface to use.

Return Value

Returns true if deallocation success

GetRefCon

Get the current refcon

void* ( *GetRefCon)(
    IOFireWireLibIRMAllocationRef self);

Parameters

self: The IRMAllocation interface to use.

Return Value

Returns the current refcon value

NotificationIsOn

Is notification on?

Boolean ( *NotificationIsOn)(
    IOFireWireLibIRMAllocationRef self);

Parameters

self: The IRMAllocation interface to use.

Return Value

Returns true if notifications for this IRMAllocation are enabled

SetRefCon

Set a new refcon

void ( *SetRefCon)(
    IOFireWireLibIRMAllocationRef self,
    void *refCon);

Parameters

self: The IRMAllocation interface to use.
refCon: The new refcon value.

setReleaseIRMResourcesOnFree

Set a new value for releaseIRMResourcesOnFree

const void (*setReleaseIRMResourcesOnFree)( IOFireWireLibIRMAllocationRef self, Boolean doRelease);

Parameters

self: The IRMAllocation interface to use.
doRelease: The new value for releaseIRMResourcesOnFree.

TurnOffNotification

Force notification off.

void ( *TurnOffNotification)(
    IOFireWireLibIRMAllocationRef self);

Parameters

self: The IRMAllocation interface to use.

TurnOnNotification

Try to turn on notifications

Boolean ( *TurnOnNotification)(
    IOFireWireLibIRMAllocationRef self);

Parameters

self: The IRMAllocation interface to use.

Return Value

Returns true upon success

Typedefs

IOFireWireBusResetDoneHandler

Called when a bus reset has occured and FireWire has completed configuring the bus.

typedef void ( *IOFireWireBusResetDoneHandler)( 
    IOFireWireLibDeviceRef interface, 
    FWClientCommandID commandID );  // parameters may change

Fields

interface: A reference to the device on which the callback was installed.
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete().

IOFireWireBusResetHandler

Called when a bus reset has occured, but before FireWire has completed configuring the bus.

typedef void ( *IOFireWireBusResetHandler)( 
    IOFireWireLibDeviceRef interface, 
    FWClientCommandID commandID );  // parameters may change

Fields

interface: A reference to the device on which the callback was installed.
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete().

IOFireWireLibCommandCallback

Callback called when an asynchronous command has completed executing.

typedef void ( *IOFireWireLibCommandCallback)( 
    void *refCon, 
    IOReturn completionStatus);

Fields

refCon: A user-specified reference value set before command object was submitted.

IOFireWireLibIRMAllocationLostNotificationProc

Callback called when an IOFireWireLibIRMAllocationRef fails to reclaim IRM resources after a bus-reset

typedef void ( *IOFireWireLibIRMAllocationLostNotificationProc)(
    IOFireWireLibIRMAllocationRef irmAllocation,
    void *refCon);

IOFireWireLibPHYPacketCallback

Callback called to handle incoming PHY packets

typedef void ( *IOFireWireLibPHYPacketCallback)( 
    IOFireWireLibPHYPacketListenerRef listener, 
    FWClientCommandID commandID, 
    UInt32 data1, 
    UInt32 data2, 
    void *refCon );

Fields

listener: The listener which received the callback
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete()
data1: first quad of received PHY packet
data2: second quad of received PHY packet
refCon: user specified reference value specified on the listener

IOFireWireLibPHYPacketSkippedCallback

Callback called when incoming packets have been dropped from the internal queue

typedef void ( *IOFireWireLibPHYPacketSkippedCallback)( 
    IOFireWireLibPHYPacketListenerRef listener, 
    FWClientCommandID commandID, 
    UInt32 skippedPacketCount, 
    void *refCon );

Fields

listener: The listener which dropped the packets
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete()
skippedPacketCount: The number of skipped packets
refCon: user specified reference value specified on the listener

IOFireWirePseudoAddressSpaceReadHandler

Handles read requests to pseudo address spaces.

typedef UInt32 ( *IOFireWirePseudoAddressSpaceReadHandler)( 
    IOFireWireLibPseudoAddressSpaceRef addressSpace, 
    FWClientCommandID commandID, 
    UInt32 packetLen, 
    UInt32 packetOffset, 
    UInt16 srcNodeID, // nodeID of requester 
    UInt32 destAddressHi, // destination on this node 
    UInt32 destAddressLo, 
    void *refCon);

Fields

addressSpace: The address space to which the request is being made.
commandID: An FWClientCommandID which should be passed to ClientCommandIsComplete when the buffer has been filled in.
packetLen: Number of bytes requested.
packetOffset: Number of bytes from beginning of address space backing store.
srcNodeID: NodeID of the requester.
destAddressHi: High 16 bits of destination address on this computer.
destAddressLo: Low 32 bits of destination address on this computer.
refCon: User-specified reference number passed in when the address space was created.

Discussion

This callback is called to handle read requests to pseudo address spaces. This function should fill in the specified area in the pseudo address space backing store and call ClientCommandIsComplete with the specified command ID.

IOFireWirePseudoAddressSpaceSkippedPacketHandler

Callback called when incoming packets have been dropped from the internal queue.

typedef void ( *IOFireWirePseudoAddressSpaceSkippedPacketHandler)( 
    IOFireWireLibPseudoAddressSpaceRef addressSpace, 
    FWClientCommandID commandID, 
    UInt32 skippedPacketCount);

Fields

addressSpace: The address space which dropped the packet(s).
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete().
skippedPacketCount: The number of skipped packets.

IOFireWirePseudoAddressSpaceWriteHandler

Callback called to handle write requests to a pseudo address space.

typedef UInt32 ( *IOFireWirePseudoAddressSpaceWriteHandler)( 
    IOFireWireLibPseudoAddressSpaceRef addressSpace, 
    FWClientCommandID commandID, 
    UInt32 packetLen, 
    void *packet, 
    UInt16 srcNodeID, // nodeID of sender 
    UInt32 destAddressHi, // destination on this node 
    UInt32 destAddressLo, 
    void *refCon);

Fields

addressSpace: The address space to which the write is being made.
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete().
packetLen: Length in bytes of incoming packet.
packet: Pointer to the received data.
srcNodeID: Node ID of the sender.
destAddressHi: High 16 bits of destination address on this computer.
destAddressLo: Low 32 bits of destination address on this computer.
refCon: User-specified reference number passed in when the address space was created.

IOFWAsyncStreamListenerHandler

Callback called to handle Async Stream packets.

typedef UInt32 ( *IOFWAsyncStreamListenerHandler)( 
    IOFWAsyncStreamListenerInterfaceRef listener, 
    FWClientCommandID commandID, 
    UInt32 size, 
    void *packet, 
    void *refCon);

Fields

listener: The listener which received the callback
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete()
packet: Pointer to the received data
refCon: user specified reference number passed in when async stream interface is created

IOFWAsyncStreamListenerSkippedPacketHandler

Callback called when incoming packets have been dropped from the internal queue

typedef void ( *IOFWAsyncStreamListenerSkippedPacketHandler)( 
    IOFWAsyncStreamListenerInterfaceRef listener, 
    FWClientCommandID commandID, 
    UInt32 skippedPacketCount);

Fields

listener: The listener which dropped the packets
commandID: An FWClientCommandID to be passed to ClientCommandIsComplete()
skippedPacketCount: The number of skipped packets

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2009-02-23