IOFireWireLib.h

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.

IOFireWireLibIRMAllocationInterface

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. ( interface name: IOFireWirePhysicalAddressSpaceInterface )

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

IOVirtualRangeMake

CF_INLINE IOVirtualRange IOVirtualRangeMake(
    IOVirtualAddress address,
    IOByteCount length ) 

Discussion

Description forthcoming

Typedefs

FWAddressSpaceFlags

IOFireWireBusResetDoneHandler

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

IOFireWireBusResetHandler

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

IOFireWireLibCommandCallback

Callback called when an asynchronous command has completed executing

IOFireWireLibIRMAllocationLostNotificationProc

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

IOFireWireLibPHYPacketCallback

Callback called to handle incoming PHY packets

IOFireWireLibPHYPacketSkippedCallback

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

IOFireWirePseudoAddressSpaceReadHandler

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

IOFireWirePseudoAddressSpaceWriteHandler

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

IOFWAsyncStreamListenerHandler

Callback called to handle Async Stream packets.

IOFWAsyncStreamListenerSkippedPacketHandler

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

typedef enum { 
    kFWAddressSpaceNoFlags = 0, 
    kFWAddressSpaceNoWriteAccess = (
        1 << 0), 
    kFWAddressSpaceNoReadAccess = (
        1 << 1), 
    kFWAddressSpaceAutoWriteReply = (
        1 << 2), 
    kFWAddressSpaceAutoReadReply = (
        1 << 3), 
    kFWAddressSpaceAutoCopyOnWrite = (
        1 << 4), 
    kFWAddressSpaceShareIfExists = (
        1 << 5), 
    kFWAddressSpaceExclusive = (
        1 << 6) 
} FWAddressSpaceFlags;  

Discussion

FireWire address space creation flags

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

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

Callback called when an asynchronous command has completed executing

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

Fields

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

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

Callback called to handle incoming PHY packets

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

Fields

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

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

Fields

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

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

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

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

Fields

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

Callback called to handle Async Stream packets.

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

Fields

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

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

Fields

Enumerated Types

IOFireWireLib Additional Command Flags

Flags for IOFireWireLib commands

IOFireWireLib Command Flags

Flags for IOFireWireLib command objects

IOFireWireLib failOnReset Flags

Flags for IOFireWireLib commands

Flags for IOFireWireLib commands

enum { 
    kFireWireCommandUseCopy = (
        1 << 16), 
    kFireWireCommandAbsolute = (
        1 << 17) 
};  

Discussion

Pass these flags to the object's SetFlags callback.

Flags for IOFireWireLib command objects

enum { 
    kFWCommandNoFlags = 0, 
    kFWCommandInterfaceForceNoCopy = (
        1 << 0), 
    kFWCommandInterfaceForceCopyAlways = (
        1 << 1), 
    kFWCommandInterfaceSyncExecute = (
        1 << 2), 
    kFWCommandInterfaceAbsolute = (
        1 << 3), 
    kFWVectorCommandInterfaceOrdered = (
        1 << 4), 
    kFWCommandInterfaceForceBlockRequest = (
        1 << 5) 
};  

Discussion

Pass these flags to the object's SetFlags callback.

Flags for IOFireWireLib commands

enum { 
    kFWDontFailOnReset = false, 
    kFWFailOnReset = true 
};  

Discussion

Pass these flags in the failOnReset of various commands.

Last Updated: 2009-10-15