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

IOFireWireDeviceInterface

Declared In:

IOFireWireLib.h

Overview

IOFireWireDeviceInterface is your primary gateway to the functionality contained in IOFireWireLib.

Discussion

You can use IOFireWireDeviceInterface to:

perform synchronous read, write and lock operations
perform other miscellanous bus operations, such as reset the FireWire bus.
create FireWire command objects and interfaces used to perform synchronous/asynchronous read, write and lock operations. These include:

IOFireWireReadCommandInterface
IOFireWireReadQuadletCommandInterface
IOFireWireWriteCommandInterface
IOFireWireWriteQuadletCommandInterface
IOFireWireCompareSwapCommandInterface

create interfaces which provide a other extended services. These include:

IOFireWirePseudoAddressSpaceInterface -- pseudo address space services
IOFireWirePhysicalAddressSpaceInterface -- physical address space services
IOFireWireLocalUnitDirectoryInterface -- manage local unit directories in the mac
IOFireWireConfigDirectoryInterface -- access and browse remote device config directories

create interfaces which provide isochronous services (see IOFireWireLibIsoch.h). These include:

IOFireWireIsochChannelInterface -- create/manage talker and listener isoch channels
IOFireWireLocalIsochPortInterface -- create local isoch ports
IOFireWireRemoteIsochPortInterface -- create remote isoch ports
IOFireWireDCLCommandPoolInterface -- create a DCL command pool allocator.

Functions

AddCallbackDispatcherToRunLoop: Installs the proper run loop event source to allow callbacks to function.
AddCallbackDispatcherToRunLoopForMode: Adds a run loop event source to allow IOFireWireLib callbacks to function.
AddIsochCallbackDispatcherToRunLoop: Adds an event source for the isochronous callback dispatcher to the specified CFRunLoop.
AddIsochCallbackDispatcherToRunLoopForMode: Add a run loop event source to allow IOFireWireLib isoch callbacks to function.
AllocateIRMBandwidthInGeneration: Attempt to allocate some isochronous bandwidth from the IRM
AllocateIRMChannelInGeneration: Attempt to allocate an isochronous channel from the IRM
BusReset: Cause a bus reset
ClientCommandIsComplete
Close: Releases exclusive access to the device.
CompareSwap: Perform synchronous lock operation
CompareSwap64: Performs synchronous lock operation.
CreateAsyncStreamCommand: Create a command object for sending Async Stream packets
CreateAsyncStreamListener: Creates a async stream listener object and returns an interface to it.
CreateCompareSwapCommand: Create a quadlet compare/swap command object.
CreateCompareSwapCommand64: Creates a quadlet compare/swap command object and initializes it with 64-bit values.
CreateConfigDirectoryWithIOObject: This function can be used to create a config directory object and a corresponding interface from an opaque IOObject reference. Some configuration directory interface methods may return an io_object_t instead of an IOFireWireLibConfigDirectoryRef. Use this function to obtain an IOFireWireLibConfigDirectoryRef from an io_object_t.
CreateDCLCommandPool: Creates a command pool object and returns an interface to it.
CreateInitialUnitsPseudoAddressSpace: Creates a pseudo address space in initial units space.
CreateIRMAllocation: Attempt to create an IRM allocation that persists accross bus-resets.
CreateIsochChannel: Creates an isochronous channel object and returns an interface to it.
CreateLocalIsochPort: Creates a local isochronous port object and returns an interface to it.
CreateLocalIsochPortWithOptions: Creates a local isoch port
CreateLocalUnitDirectory: Creates a local unit directory object and returns an interface to it. An instance of a unit directory object corresponds to an instance of a unit directory in the local machine's configuration ROM.
CreatePHYCommand: Create a command object for sending a PHY packet
CreatePHYPacketListener: Create a listener object for receiving PHY packets
CreatePhysicalAddressSpace: Creates a physical address space object and returns an interface to it.
CreatePseudoAddressSpace: Creates a pseudo address space object and returns an interface to it. This will create a pseudo address space (software-backed) on the local machine.
CreateReadCommand: Create a block read command object.
CreateReadQuadletCommand: Create a quadlet read command object.
CreateRemoteIsochPort: Creates a remote isochronous port object and returns an interface to it.
CreateVectorCommand: Create a vector command object.
CreateWriteCommand: Create a block write command object.
CreateWriteQuadletCommand: Create a quadlet write command object.
FireLog: Logs string to in-kernel debug buffer.
GetBusCycleTime: Gets bus and cycle time.
GetBusGeneration: Gets bus generation number.
GetConfigDirectory: Creates a config directory object and returns an interface to it. The created config directory object represents the config directory in the remote device or unit to which the creating device interface is attached.
GetCycleTime: Get bus cycle time.
GetCycleTimeAndUpTime: Get bus cycle time and cpu uptime.
GetDevice: Gets the I/O Kit service to which this interface is connected.
GetGenerationAndNodeID: (Obsolete) Get bus generation and remote device node ID.
GetIsochAsyncPort: Returns the notification port used for async and isoch callbacks
GetLocalNodeID: (Obsolete) Get local node ID.
GetLocalNodeIDWithGeneration: Gets node ID of local machine.
GetRefCon: Gets user reference value set on this interface.
GetRemoteNodeID: Gets node ID of device to which this interface is attached.
GetResetTime: Get time since last bus reset.
GetSpeedBetweenNodes: Gets maximum transfer speed to device to which this interface is attached.
GetSpeedToNode: Gets maximum transfer speed to device to which this interface is attached.
InterfaceIsInited: Determines whether interface has been properly inited.
NotificationIsOn: Determines whether callback notifications for this interface are currently active.
Open: Opens the connected device for exclusive access.
OpenWithSessionRef: Gives this interface access to a device that is already open.
PrintDCLProgram: Walks a DCL program linked list and prints its contents.
Read: Performs synchronous block read.
ReadQuadlet: Performs synchronous quadlet read.
ReleaseIRMBandwidthInGeneration: Attempt to release some isochronous bandwidth from the IRM
ReleaseIRMChannelInGeneration: Attempt to release an isochronous channel from the IRM
RemoveCallbackDispatcherFromRunLoop: Reverses the effects of AddCallbackDispatcherToRunLoop().
RemoveIsochCallbackDispatcherFromRunLoop: Removes an IOFireWireLib-added run loop event source.
Seize: Seizes control of device/unit.
SetBusResetDoneHandler: Sets the callback that should be called after a bus reset has occurred and reconfiguration of the bus has been completed.
SetBusResetHandler: Sets the callback that should be called when a bus reset occurs.
SetRefCon: Sets user reference value on this interface.
TurnOffNotification: Deactivates and callbacks specified for this device interface.
TurnOnNotification: Activates any callbacks specified for this device interface.
Write: Performs synchronous block write.
WriteQuadlet: Perform synchronous quadlet write

AddCallbackDispatcherToRunLoop

Installs the proper run loop event source to allow callbacks to function.

const IOReturn (*AddCallbackDispatcherToRunLoop)(IOFireWireLibDeviceRef self, CFRunLoopRef inRunLoop);

Parameters

self: The device interface to use.
inRunLoop: The run loop on which to install the event source.

Discussion

This method must be called before callback notifications for this interface, or any interfaces created using this interface, can function.

AddCallbackDispatcherToRunLoopForMode

Adds a run loop event source to allow IOFireWireLib callbacks to function.

IOReturn ( *AddCallbackDispatcherToRunLoopForMode)( 
    IOFireWireLibDeviceRef self, 
    CFRunLoopRef inRunLoop, 
    CFStringRef inRunLoopMode );

Parameters

self: The device interface to use.
inRunLoop: The run loop on which to install the event source.
inRunLoopMode: The run loop mode(s) for which to install the event source.

Return Value

Returns an IOReturn error code.

Discussion

Installs the proper run loop event source to allow callbacks to function. This method must be called before callback notifications for this interface or any interfaces created using this interface can function. With this function, you can additionally specify for which run loop modes this source should be added.

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

AddIsochCallbackDispatcherToRunLoop

Adds an event source for the isochronous callback dispatcher to the specified CFRunLoop.

IOReturn ( *AddIsochCallbackDispatcherToRunLoop)( 
    IOFireWireLibDeviceRef self, 
    CFRunLoopRef inRunLoop);

Parameters

self: The device interface to use.
inRunLoop: A CFRunLoopRef for the run loop to which the event loop source should be added.

Return Value

Returns an IOReturn error code.

Discussion

Isochronous related callbacks will not function before this function is called. This function is similar to AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different from that passed to AddCallbackDispatcherToRunLoop.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

AddIsochCallbackDispatcherToRunLoopForMode

Add a run loop event source to allow IOFireWireLib isoch callbacks to function.

IOReturn ( *AddIsochCallbackDispatcherToRunLoopForMode)( 
    IOFireWireLibDeviceRef self, 
    CFRunLoopRef inRunLoop, 
    CFStringRef inRunLoopMode );

Parameters

self: The device interface to use.
inRunLoop: A CFRunLoopRef for the run loop to which the event loop source should be added.
inRunLoopMode: The run loop mode(s) for which to install the event source.

Return Value

Returns an IOReturn error code.

Discussion

This function adds an event source for the isochronous callback dispatcher to the specified CFRunLoop. Isochronous related callbacks will not be called unless this function has been called. This function is similar to AddCallbackDispatcherToRunLoop. The passed CFRunLoop can be different from that passed to AddCallbackDispatcherToRunLoop.

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

AllocateIRMBandwidthInGeneration

Attempt to allocate some isochronous bandwidth from the IRM

IOReturn ( *AllocateIRMBandwidthInGeneration)(
    IOFireWireLibDeviceRef self,
    UInt32 bandwidthUnits,
    UInt32 generation);

Parameters

bandwidthUnits: The number of bandwidth units to allocate
generation: The bus generation that this allocation attempt is to take place in.

Return Value

Returns kIOReturnSuccess if bandwidth allocation was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed)

Discussion

Attempts to allocates some isochronous bandwidth from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

AllocateIRMChannelInGeneration

Attempt to allocate an isochronous channel from the IRM

IOReturn ( *AllocateIRMChannelInGeneration)(
    IOFireWireLibDeviceRef self,
    UInt8 isochChannel,
    UInt32 generation);

Parameters

isochChannel: The isochronous channel to allocate
generation: The bus generation that this allocation attempt is to take place in.

Return Value

Returns kIOReturnSuccess if channel allocation was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed)

Discussion

Attempts to allocates an isochronous channel from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

BusReset

Cause a bus reset

IOReturn ( *BusReset)(
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

ClientCommandIsComplete

void ( *ClientCommandIsComplete)(
    IOFireWireLibDeviceRef self,
    FWClientCommandID commandID,
    IOReturn status);

Parameters

commandID: The command ID passed to the callback function when it was called.
status: An IOReturn value indicating the completion status of the callback function.

Discussion

This function must be called from callback routines once they have completed processing a callback. This function only applies to callbacks which take an IOFireWireLibDeviceRef (i.e. bus reset) parameter.

Close

Releases exclusive access to the device.

void ( *Close)(
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

CompareSwap

Perform synchronous lock operation

IOReturn ( *CompareSwap)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress* addr,
    UInt32 cmpVal,
    UInt32 newVal,
    Boolean failOnReset,
    UInt32 generation);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr: Command target address
cmpVal: The check/compare value
newVal: Value to set
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOReturn error code

CompareSwap64

Performs synchronous lock operation.

IOReturn ( *CompareSwap64)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress* addr, 
    UInt32* expectedVal,
    UInt32* newVal,
    UInt32* oldVal,
    IOByteCount size, 
    Boolean failOnReset,
    UInt32 generation);

Parameters

self

The device interface to use.

device

The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.

If the quadlets stored at 'oldVal' match those passed to 'expectedVal', the lock operation was successful.

addr

Command target address.

expectedVal

Pointer to quadlets expected at target.

newVal

Pointer to quadlets to atomically set at target if compare is successful.

oldVal

Pointer to quadlets to hold value found at target address after transaction if completed.

size

Size in bytes of compare swap transaction to perform. Value values are 4 and 8.

failOnReset

Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration().

generation

The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.

Return Value

Returns an IOReturn error code.

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

CreateAsyncStreamCommand

Create a command object for sending Async Stream packets

IOFireWireLibCommandRef ( *CreateAsyncStreamCommand)(
    IOFireWireLibDeviceRef self, 
    UInt32 channel, 
    UInt32 sync, 
    UInt32 tag, 
    void *buf, 
    UInt32 size, 
    IOFireWireLibCommandCallback callback, 
    Boolean failOnReset, 
    UInt32 generation, 
    void *inRefCon, 
    REFIID iid);

Parameters

self: The device interface to use.
channel: The channel number to use.
buf: A pointer to the buffer containing the data to be written
size: Number of bytes to write
callback: Command completion callback.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
inRefCon: A user specified reference value. This will be passed to all callback functions.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created phy packet listener object.

Return Value

An IOReturn error code

CreateAsyncStreamListener

Creates a async stream listener object and returns an interface to it.

IOFWAsyncStreamListenerInterfaceRef ( *CreateAsyncStreamListener)(
    IOFireWireLibDeviceRef self, 
    UInt32 channel, 
    IOFWAsyncStreamListenerHandler callback, 
    void *inRefCon, 
    UInt32 inQueueBufferSize, 
    REFIID iid);

Parameters

self: The device interface to use.
channel: The channel to allocate.
inRefCon: A user specified reference value. This will be passed to all callback functions.
inQueueBufferSize: The size of the queue which receives packets from the bus before they are handed to the client. A larger queue can help eliminate dropped packets when receiving large bursts of data. When a packet is received which can not fit into the queue, the packet dropped callback will be called.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created ayns stream listener object.

Return Value

An IOFWAsyncStreamListenerInterfaceRef. Returns 0 upon failure

CreateCompareSwapCommand

Create a quadlet compare/swap command object.

IOFireWireLibCommandRef ( *CreateCompareSwapCommand)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress * addr,
    UInt32 cmpVal,
    UInt32 newVal,
    IOFireWireLibCommandCallback callback,
    Boolean failOnReset,
    UInt32 generation,
    void* inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported. Setting the callback value to nil defaults to synchronous execution.
addr: Command target address
cmpVal: 32-bit value expected at target address
newVal: 32-bit value to be set at target address
callback: Command completion callback.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

CreateCompareSwapCommand64

Creates a quadlet compare/swap command object and initializes it with 64-bit values.

IOFireWireLibCommandRef ( *CreateCompareSwapCommand64)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress* addr, 
    UInt64 cmpVal,
    UInt64 newVal,
    IOFireWireLibCommandCallback callback, 
    Boolean failOnReset,
    UInt32 generation,
    void* inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported. Setting the callback value to nil defaults to synchronous execution.
addr: Command target address.
cmpVal: 64-bit value expected at target address.
newVal: 64-bit value to be set at target address.
callback: Command completion callback.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration().
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.

Return Value

Returns an IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

CreateConfigDirectoryWithIOObject

This function can be used to create a config directory object and a corresponding interface from an opaque IOObject reference. Some configuration directory interface methods may return an io_object_t instead of an IOFireWireLibConfigDirectoryRef. Use this function to obtain an IOFireWireLibConfigDirectoryRef from an io_object_t.

IOFireWireLibConfigDirectoryRef ( *CreateConfigDirectoryWithIOObject)(
    IOFireWireLibDeviceRef self,
    io_object_t inObject,
    REFIID iid);

Parameters

self: The device interface to use.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created config directory object.

Return Value

An IOFireWireLibConfigDirectoryRef. Returns 0 upon failure

CreateDCLCommandPool

Creates a command pool object and returns an interface to it.

IOFireWireLibDCLCommandPoolRef ( *CreateDCLCommandPool)( 
    IOFireWireLibDeviceRef self, 
    IOByteCount size, 
    REFIID iid );

Parameters

self: The device interface to use.
size: Starting size of command pool.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created object.

Return Value

Returns an IOFireWireLibDCLCommandPoolRef, 0 upon failure.

Discussion

The command pool can be used to build DCL programs.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

CreateInitialUnitsPseudoAddressSpace

Creates a pseudo address space in initial units space.

IOFireWireLibPseudoAddressSpaceRef ( *CreateInitialUnitsPseudoAddressSpace)( 
    IOFireWireLibDeviceRef self, 
    UInt32 inAddressLo, 
    UInt32 inSize, 
    void *inRefCon, 
    UInt32 inQueueBufferSize, 
    void *inBackingStore, 
    UInt32 inFlags, 
    REFIID iid);

Parameters

self

The device interface to use.

inAddressLo

The lower 32 bits of the base address of the address space to be created. The address is always in initial units space.

inSize

The size in bytes of this address space.

inRefCon

A user specified reference value. This will be passed to all callback functions.

inQueueBufferSize

The size of the queue which receives packets from the bus before they are handed to the client and/or put in the backing store. A larger queue can help eliminate dropped packets when receiving large bursts of data. When a packet is received which cannot fit into the queue, the packet dropped callback will be called.

inBackingStore

An optional block of allocated memory representing the contents of the address space.

inFlags

A UInt32 with bits set corresponding to the flags that should be set for this address space.

kFWAddressSpaceNoFlags -- All flags off
kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed. Setting this flag also disables compare/swap transactions on this address space.
kFWAddressSpaceNoReadAccess -- Read access to this address space will be disallowed. Setting this flag also disables compare/swap transactions on this address space.
kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents of the backing store. The user process will not be notified of writes.
kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automatically using the contents of the backing store. The user process will not be notified of reads.
kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly to the backing store at the same time the user process is notified of a write. Clients will only be notified of a write if kFWAddressSpaceAutoWriteReply is not set.
kFWAddressSpaceShareIfExists -- Allows creation of this address space even if another client already has an address space at the requested address. All clients will be notified of writes to covered addresses.
kFWAddressSpaceExclusive -- Ensures that the allocation of this address space will fail if any portion of this address range is already allocated. If the allocation is successful this flag ensures that any future allocations overlapping this range will fail even if allocted with kFWAddressSpaceShareIfExists.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created pseudo address space object.

Return Value

Returns an IOFireWireLibPseudoAddressSpaceRef, 0 upon failure.

Discussion

Creates a pseudo address space object in initial units space and returns an interface to it. This will create a pseudo address space (software-backed) on the local machine.

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

CreateIRMAllocation

Attempt to create an IRM allocation that persists accross bus-resets.

IOFireWireLibIRMAllocationRef ( *CreateIRMAllocation)(
    IOFireWireLibDeviceRef self, 
    Boolean releaseIRMResourcesOnFree, 
    IOFireWireLibIRMAllocationLostNotificationProc callback, 
    void *pLostNotificationProcRefCon, 
    REFIID iid);

Parameters

releaseIRMResourcesOnFree: Specify whether or not the IRM resources shall be released when the IOFireWireLibIRMAllocation is destroyed. Can be overrided later.
callback: The handler to notify clients of failure to reclaim IRM resources after bus-reset.
pLostNotificationProcRefCon: The refCon passed with the callback.

Return Value

Returns a pointer to the newly created IRM allocation object, if successful, NULL otherwise.

Discussion

Create an IOFireWireIRMAllocation object, which can be used to allocate IRM resources, and will reallocate automatically after bus-resets (if possible).

Availability: IOFireWireDeviceInterface_v9 and newer

CreateIsochChannel

Creates an isochronous channel object and returns an interface to it.

IOFireWireLibIsochChannelRef ( *CreateIsochChannel)( 
    IOFireWireLibDeviceRef self, 
    Boolean doIrm, 
    UInt32 packetSize, 
    IOFWSpeed prefSpeed, 
    REFIID iid );

Parameters

self: The device interface to use.
doIRM: Controls whether the channel automatically performs IRM operations. Pass true if the channel should allocate its channel and bandwidth with the IRM. Pass false to ignore the IRM.
packetSize: Size in bytes of packets being sent or received with this channel. This is automatically translated into a bandwidth allocation appropriate for the speed passed in prefSpeed.
prefSpeed: The preferred bus speed of this channel.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created object.

Return Value

Returns an IOFireWireLibIsochChannelRef, 0 upon failure.

Discussion

An isochronous channel object is an abstract entity used to represent a FireWire isochronous channel.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

CreateLocalIsochPort

Creates a local isochronous port object and returns an interface to it.

IOFireWireLibLocalIsochPortRef ( *CreateLocalIsochPort)( 
    IOFireWireLibDeviceRef self, 
    Boolean inTalking, 
    DCLCommand *inDCLProgram, 
    UInt32 inStartEvent, 
    UInt32 inStartState, 
    UInt32 inStartMask, 
    IOVirtualRange inDCLProgramRanges[], // optional optimization parameters 
    UInt32 inDCLProgramRangeCount, 
    IOVirtualRange inBufferRanges[], 
    UInt32 inBufferRangeCount, 
    REFIID iid);

Parameters

self: The device interface to use.
inTalking: Pass true if this port represents an isochronous talker. Pass false if this port represents an isochronous listener.
inDCLProgram: A pointer to the first DCL command struct of the DCL program to be compiled and used to send or receive data on this port.
inStartEvent: Start event: 0 or kFWDCLCycleEvent or kFWDCLSyBitsEvent.
inStartState: Start state bits. For kFWDCLCycleEvent specifies the cycle to start the DMA on. For kFWDCLSyBitsEvent specifies the packet sync field value for the first packet to receive.
inStartMask: Start mask bits. For kFWDCLCycleEvent specifies a mask for the start cycle: the DMA will start when currentCycle & inStartMask == inStartEvent & inStartMask. For kFWDCLSyBitsEvent specifies a mask for the sync field: the DMA will start when packet sync == inStartEvent & inStartMask.
inDCLProgramRanges: This is an optional optimization parameter which can be used to decrease the time the local port object spends determining which set of virtual ranges the passed DCL program occupies. Pass a pointer to an array of IOVirtualRange structs or nil to ignore this parameter.
inDCLProgramRangeCount: The number of virtual ranges passed to inDCLProgramRanges. Pass 0 for none.
inBufferRanges: This is an optional optimization parameter which can be used to decrease the time the local port object spends determining which set of virtual ranges the data buffers referenced by the passed DCL program occupy. Pass a pointer to an array of IOVirtualRange structs or nil to ignore this parameter.
inBufferRangeCount: The number of virtual ranges passed to inBufferRanges. Pass 0 for none.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created object.

Return Value

Returns an IOFireWireLibLocalIsochPortRef, 0 upon failure.

Discussion

A local isochronous port object is an abstract entity used to represent a talking or listening endpoint in the local machine.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

CreateLocalIsochPortWithOptions

Creates a local isoch port

IOFireWireLibLocalIsochPortRef ( *CreateLocalIsochPortWithOptions)( 
    IOFireWireLibDeviceRef self, 
    Boolean inTalking, 
    DCLCommand *dclProgram, 
    UInt32 startEvent, 
    UInt32 startState, 
    UInt32 startMask, 
    IOVirtualRange dclProgramRanges[], // optional optimization parameters 
    UInt32 dclProgramRangeCount, 
    IOVirtualRange bufferRanges[], 
    UInt32 bufferRangeCount, 
    IOFWIsochPortOptions options, 
    REFIID iid);

Parameters

options: Currently supported options are 'kFWIsochPortUseSeparateKernelThread'. If this option is used, a separate kernel thread will be created to handle interrupt processing for this port only. Pass 'kFWIsochPortDefaultOptions' for no options.

Return Value

Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.

Discussion

Same as CreateLocalIsochPort(), above, but allows additional options to be passed.

Availability: This function is available in IOFireWireDeviceInterface_v8 and later.

CreateLocalUnitDirectory

Creates a local unit directory object and returns an interface to it. An instance of a unit directory object corresponds to an instance of a unit directory in the local machine's configuration ROM.

IOFireWireLibLocalUnitDirectoryRef ( *CreateLocalUnitDirectory)(
    IOFireWireLibDeviceRef self,
    REFIID iid);

Parameters

self: The device interface to use.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created unit directory object.

Return Value

An IOFireWireLibLocalUnitDirectoryRef. Returns 0 upon failure

CreatePHYCommand

Create a command object for sending a PHY packet

IOFireWireLibCommandRef ( *CreatePHYCommand)(
    IOFireWireLibDeviceRef self, 
    UInt32 data1, 
    UInt32 data2, 
    IOFireWireLibCommandCallback callback, 
    Boolean failOnReset, 
    UInt32 generation, 
    void *inRefCon, 
    REFIID iid );

Parameters

self: The device interface to use.
data1: phy packet quadlet 1
data2: phy packet quadlet 1
callback: completion callback
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration()
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created phy command object.

Return Value

An IOReturn error code

CreatePHYPacketListener

Create a listener object for receiving PHY packets

IOFireWireLibPHYPacketListenerRef ( *CreatePHYPacketListener)(
    IOFireWireLibDeviceRef self, 
    UInt32 queueCount, 
    REFIID iid );

Parameters

self: The device interface to use.
queueCount: The maximum queue size to use to buffer phy packets between kernel and user space
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created phy packet listener object.

Return Value

An IOReturn error code

CreatePhysicalAddressSpace

Creates a physical address space object and returns an interface to it.

IOFireWireLibPhysicalAddressSpaceRef ( *CreatePhysicalAddressSpace)(
    IOFireWireLibDeviceRef self,
    UInt32 inSize,
    void *inBackingStore,
    UInt32 inFlags,
    REFIID iid);

Parameters

self: The device interface to use.
inBackingStore: A block of allocated memory representing the contents of the address space.
inSize: The size in bytes of this address space.
inFlags: A UInt32 with bits set corresponding to the flags that should be set for this address space. For future use -- always pass 0.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created physical address space object.

Return Value

Returns an IOFireWireLibPhysicalAddressSpaceRef, 0 upon failure.

Discussion

This will create a physical address space on the local machine.

CreatePseudoAddressSpace

Creates a pseudo address space object and returns an interface to it. This will create a pseudo address space (software-backed) on the local machine.

IOFireWireLibPseudoAddressSpaceRef ( *CreatePseudoAddressSpace)( 
    IOFireWireLibDeviceRef self, 
    UInt32 inSize, 
    void *inRefCon, 
    UInt32 inQueueBufferSize, 
    void *inBackingStore, 
    UInt32 inFlags, 
    REFIID iid);

Parameters

self

The device interface to use.

inSize

The size in bytes of this address space

inRefCon

A user specified reference value. This will be passed to all callback functions.

inQueueBufferSize

The size of the queue which receives packets from the bus before they are handed to the client and/or put in the backing store. A larger queue can help eliminate dropped packets when receiving large bursts of data. When a packet is received which can not fit into the queue, the packet dropped callback will be called.

inBackingStore

An optional block of allocated memory representing the contents of the address space.

inFlags

A UInt32 with bits set corresponding to the flags that should be set for this address space.

kFWAddressSpaceNoFlags -- All flags off
kFWAddressSpaceNoWriteAccess -- Write access to this address space will be disallowed. Setting this flag also disables compare/swap transactions on this address space.
kFWAddressSpaceNoReadAccess -- Read access access to this address space will be disallowed. Setting this flag also disables compare/swap transactions on this address space.
kFWAddressSpaceAutoWriteReply -- Writes will be made automatically, directly modifying the contents of the backing store. The user process will not be notified of writes.
kFWAddressSpaceAutoReadReply -- Reads to this address space will be answered automagically using the contents of the backing store. The user process will not be notified of reads.
kFWAddressSpaceAutoCopyOnWrite -- Writes to this address space will be made directly to the backing store at the same time the user process is notified of a write.

iid

An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created pseudo address space object.

Return Value

An IOFireWireLibPseudoAddressSpaceRef. Returns 0 upon failure

CreateReadCommand

Create a block read command object.

IOFireWireLibCommandRef ( *CreateReadCommand)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress * addr,
    void* buf,
    UInt32 size,
    IOFireWireLibCommandCallback callback,
    Boolean failOnReset,
    UInt32 generation,
    void* inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported. Setting the callback value to nil defaults to synchronous execution.
addr: Command target address
buf: A pointer to a buffer where the results will be stored
size: Number of bytes to read
callback: Command completion callback.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

CreateReadQuadletCommand

Create a quadlet read command object.

IOFireWireLibCommandRef ( *CreateReadQuadletCommand)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress * addr,
    UInt32 quads[],
    UInt32 numQuads,
    IOFireWireLibCommandCallback callback,
    Boolean failOnReset,
    UInt32 generation,
    void* inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported. Setting the callback value to nil defaults to synchronous execution.
addr: Command target address
quads: An array of quadlets where results should be stored
numQuads: Number of quadlets to read
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

CreateRemoteIsochPort

Creates a remote isochronous port object and returns an interface to it.

IOFireWireLibRemoteIsochPortRef ( *CreateRemoteIsochPort)( 
    IOFireWireLibDeviceRef self, 
    Boolean inTalking, 
    REFIID iid);

Parameters

self: The device interface to use.
inTalking: Pass true if this port represents an isochronous talker. Pass false if this port represents an isochronous listener.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created remote isochronous port object.

Return Value

Returns an IOFireWireLibRemoteIsochPortRef, 0 upon failure.

Discussion

A remote isochronous port object is an abstract entity used to represent a remote talker or listener device on an isochronous channel.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

CreateVectorCommand

Create a vector command object.

IOFireWireLibVectorCommandRef ( *CreateVectorCommand)(
    IOFireWireLibDeviceRef self,
    IOFireWireLibCommandCallback callback,
    void *inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
callback: Command completion callback. Setting the callback value to nil defaults to synchronous execution.
refcon: Reference constant for 3rd party use.

Return Value

An IOFireWireLibVectorCommandRef interface

CreateWriteCommand

Create a block write command object.

IOFireWireLibCommandRef ( *CreateWriteCommand)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress * addr,
    void* buf,
    UInt32 size,
    IOFireWireLibCommandCallback callback,
    Boolean failOnReset,
    UInt32 generation,
    void* inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported. Setting the callback value to nil defaults to synchronous execution.
addr: Command target address
buf: A pointer to the buffer containing the data to be written
size: Number of bytes to write
callback: Command completion callback.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

CreateWriteQuadletCommand

Create a quadlet write command object.

IOFireWireLibCommandRef ( *CreateWriteQuadletCommand)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress * addr,
    UInt32 quads[],
    UInt32 numQuads,
    IOFireWireLibCommandCallback callback,
    Boolean failOnReset,
    UInt32 generation,
    void* inRefCon,
    REFIID iid);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported. Setting the callback value to nil defaults to synchronous execution.
addr: Command target address
quads: An array of quadlets containing quadlets to be written
numQuads: Number of quadlets to write
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOFireWireLibCommandRef interface. See IOFireWireLibCommandRef.

FireLog

Logs string to in-kernel debug buffer.

IOReturn ( *FireLog)( 
    IOFireWireLibDeviceRef self, 
    const char* format, 
    ... );

Parameters

self: The device interface to use.

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

GetBusCycleTime

Gets bus and cycle time.

IOReturn ( *GetBusCycleTime)(
    IOFireWireLibDeviceRef self,
    UInt32 *outBusTime,
    UInt32 *outCycleTime);

Parameters

self: The device interface to use.
outBusTime: A pointer to a UInt32 to hold the bus time.
outCycleTime: A pointer to a UInt32 to hold the cycle time.

Return Value

Returns an IOReturn error code.

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

GetBusGeneration

Gets bus generation number.

IOReturn ( *GetBusGeneration)(
    IOFireWireLibDeviceRef self,
    UInt32 *outGeneration );

Parameters

self: The device interface to use.
outGeneration: A pointer to a UInt32 to hold the bus generation number.

Return Value

Returns kIOReturnSuccess if a valid bus generation has been returned in 'outGeneration'.

Discussion

The bus generation number stays constant between bus resets and can be used in combination with a FireWire node ID to uniquely identify nodes on the bus. Pass the generation number to functions that take or return FireWire node IDs.

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

GetConfigDirectory

Creates a config directory object and returns an interface to it. The created config directory object represents the config directory in the remote device or unit to which the creating device interface is attached.

IOFireWireLibConfigDirectoryRef ( *GetConfigDirectory)(
    IOFireWireLibDeviceRef self,
    REFIID iid);

Parameters

self: The device interface to use.
iid: An ID number, of type CFUUIDBytes (see CFUUID.h), identifying the type of interface to be returned for the created config directory object.

Return Value

An IOFireWireLibConfigDirectoryRef which should be released using Release(). Returns 0 upon failure.

GetCycleTime

Get bus cycle time.

IOReturn ( *GetCycleTime)(
    IOFireWireLibDeviceRef self,
    UInt32 *outCycleTime);

Parameters

self: The device interface to use.
outCycleTime: A pointer to a UInt32 to hold the result

Return Value

An IOReturn error code.

GetCycleTimeAndUpTime

Get bus cycle time and cpu uptime.

IOReturn ( *GetCycleTimeAndUpTime)(
    IOFireWireLibDeviceRef self,
    UInt32 *outCycleTime,
    UInt64 *outUpTime);

Parameters

self: The device interface to use.
outCycleTime: A pointer to a UInt32 to hold the result
outUpTime: A pointer to a UInt64 to hold the result

Return Value

An IOReturn error code.

GetDevice

Gets the I/O Kit service to which this interface is connected.

io_object_t ( *GetDevice)(
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Return Value

Returns an io_object_t corresponding to the device the interface is using.

GetGenerationAndNodeID

(Obsolete) Get bus generation and remote device node ID.

IOReturn ( *GetGenerationAndNodeID)(
    IOFireWireLibDeviceRef self,
    UInt32 *outGeneration,
    UInt16 *outNodeID);

Parameters

self: The device interface to use.
outGeneration: A pointer to a UInt32 to hold the generation result
outNodeID: A pointer to a UInt16 to hold the remote device node ID

Return Value

An IOReturn error code.

Discussion

Obsolete -- Please use GetBusGeneration() and/or GetRemoteNodeID() in interface v4.

GetIsochAsyncPort

Returns the notification port used for async and isoch callbacks

mach_port_t ( *GetIsochAsyncPort)(
    IOFireWireLibDeviceRef self );

Parameters

self: The device interface to use.

Return Value

Returns the mach_port used for notifications

Discussion

If necessary GetIsochAsyncPort will allocate the port.

Availability: IOFireWireDeviceInterface_v9 and newer

GetLocalNodeID

(Obsolete) Get local node ID.

IOReturn ( *GetLocalNodeID)(
    IOFireWireLibDeviceRef self,
    UInt16 *outLocalNodeID);

Parameters

self: The device interface to use.
outNodeID: A pointer to a UInt16 to hold the local device node ID

Return Value

An IOReturn error code.

Discussion

Obsolete -- Please use GetBusGeneration() and GetLocalNodeIDWithGeneration() in interface v4.

GetLocalNodeIDWithGeneration

Gets node ID of local machine.

IOReturn ( *GetLocalNodeIDWithGeneration)(
    IOFireWireLibDeviceRef self,
    UInt32 checkGeneration,
    UInt16 *outLocalNodeID );

Parameters

self: The device interface to use.
checkGeneration: A bus generation number obtained from GetBusGeneration().
outLocalNodeID: A pointer to a UInt16 to hold the node ID of the local machine.

Return Value

Returns kIOReturnSuccess if a valid nodeID has been returned in 'outLocalNodeID'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.

Discussion

Use this function instead of GetLocalNodeID().

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

GetRefCon

Gets user reference value set on this interface.

void* ( *GetRefCon)( 
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Return Value

Returns the user's reference value set on this interface.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

GetRemoteNodeID

Gets node ID of device to which this interface is attached.

IOReturn ( *GetRemoteNodeID)(
    IOFireWireLibDeviceRef self,
    UInt32 checkGeneration,
    UInt16 *outRemoteNodeID );

Parameters

self: The device interface to use.
checkGeneration: A bus generation number obtained from GetBusGeneration().
outRemoteNodeID: A pointer to a UInt16 to hold the node ID of the remote device.

Return Value

Returns kIOReturnSuccess if a valid nodeID has been returned in 'outRemoteNodeID'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

GetResetTime

Get time since last bus reset.

IOReturn ( *GetResetTime)( 
    IOFireWireLibDeviceRef self, 
    AbsoluteTime *outResetTime);

Parameters

self: The device interface to use.
outResetTime: A pointer to an AbsolutTime to hold the result.

Return Value

An IOReturn error code.

GetSpeedBetweenNodes

Gets maximum transfer speed to device to which this interface is attached.

IOReturn ( *GetSpeedBetweenNodes)(
    IOFireWireLibDeviceRef self,
    UInt32 checkGeneration,
    UInt16 srcNodeID,
    UInt16 destNodeID,
    IOFWSpeed *outSpeed);

Parameters

self: The device interface to use.
checkGeneration: A bus generation number obtained from GetBusGeneration().
srcNodeID: A FireWire node ID.
destNodeID: A FireWire node ID.
outSpeed: A pointer to an IOFWSpeed to hold the maximum transfer speed between node 'srcNodeID' and 'destNodeID'.

Return Value

Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

GetSpeedToNode

Gets maximum transfer speed to device to which this interface is attached.

IOReturn ( *GetSpeedToNode)(
    IOFireWireLibDeviceRef self,
    UInt32 checkGeneration,
    IOFWSpeed *outSpeed);

Parameters

self: The device interface to use.
checkGeneration: A bus generation number obtained from GetBusGeneration().
outSpeed: A pointer to an IOFWSpeed to hold the maximum speed to the remote device.

Return Value

Returns kIOReturnSuccess if a valid speed has been returned in 'outSpeed'. Returns kIOFireWireBusReset if 'checkGeneration' does not match the current bus generation number.

Availability: This function is available in IOFireWireDeviceInterface_v4 and later.

InterfaceIsInited

Determines whether interface has been properly inited.

Boolean ( *InterfaceIsInited)(
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Return Value

Returns true if interface is inited and false if is it not.

NotificationIsOn

Determines whether callback notifications for this interface are currently active.

const Boolean (*NotificationIsOn)(IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Return Value

Returns a Boolean value where true indicates notifications are active.

Open

Opens the connected device for exclusive access.

IOReturn ( *Open)(
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Return Value

Returns an IOReturn error code.

Discussion

When you have the device open using this method, all accesses by other clients of this device will be denied until Close() is called.

OpenWithSessionRef

Gives this interface access to a device that is already open.

IOReturn ( *OpenWithSessionRef)(
    IOFireWireLibDeviceRef self,
    IOFireWireSessionRef sessionRef);

Parameters

self: The device interface to use.
IOFireWireSessionRef: The sessionRef returned from the client who has the device open.

Return Value

Returns an IOReturn error code.

Discussion

This is an open function which allows this interface to have access to the device when already opened. The service which has already opened the device must be able to provide an IOFireWireSessionRef.

PrintDCLProgram

Walks a DCL program linked list and prints its contents.

void ( *PrintDCLProgram)( 
    IOFireWireLibDeviceRef self, 
    const DCLCommand* inProgram, 
    UInt32 inLength);

Parameters

self: The device interface to use.
inProgram: A pointer to the first DCL of the program to print.
inLength: Number of DCLs expected in the program. PrintDCLProgram() will report an error if this number does not match the number of DCLs found in the program.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

Read

Performs synchronous block read.

IOReturn ( *Read)(
    IOFireWireLibDeviceRef self, 
    io_object_t device, 
    const FWAddress* addr, 
    void* buf, 
    UInt32* size, 
    Boolean failOnReset, 
    UInt32 generation);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to read. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr: Command target address.
buf: A pointer to a buffer where the results will be stored.
size: Number of bytes to read.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in generation. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration().
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.

Return Value

Returns an IOReturn error code.

ReadQuadlet

Performs synchronous quadlet read.

IOReturn ( *ReadQuadlet)(
    IOFireWireLibDeviceRef self, 
    io_object_t device, 
    const FWAddress* addr, 
    UInt32* val, 
    Boolean failOnReset, 
    UInt32 generation);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to read. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr: Command target address.
value: A pointer to where to data should be stored.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in generation. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration().
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.

Return Value

Returns an IOReturn error code.

ReleaseIRMBandwidthInGeneration

Attempt to release some isochronous bandwidth from the IRM

IOReturn ( *ReleaseIRMBandwidthInGeneration)(
    IOFireWireLibDeviceRef self,
    UInt32 bandwidthUnits,
    UInt32 generation);

Parameters

bandwidthUnits: The number of bandwidth units to release
generation: The bus generation that this release attempt is to take place in.

Return Value

Returns kIOReturnSuccess if bandwidth release was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed)

Discussion

Attempts to release some isochronous bandwidth from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

ReleaseIRMChannelInGeneration

Attempt to release an isochronous channel from the IRM

IOReturn ( *ReleaseIRMChannelInGeneration)(
    IOFireWireLibDeviceRef self,
    UInt8 isochChannel,
    UInt32 generation);

Parameters

isochChannel: The isochronous channel to release
generation: The bus generation that this release attempt is to take place in.

Return Value

Returns kIOReturnSuccess if channel relase was successful. Returns kIOFireWireBusReset if 'generation' does not match the current bus generation number. Returns kIOReturnError for any other error (such as the allocation failed)

Discussion

Attempts to release an isochronous channel from the IRM, if the generation matches the current generation. Availability: IOFireWireDeviceInterface_v9 and newer

RemoveCallbackDispatcherFromRunLoop

Reverses the effects of AddCallbackDispatcherToRunLoop().

const void (*RemoveCallbackDispatcherFromRunLoop)(IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Discussion

This method removes the run loop event source that was added to the specified run loop preventing any future callbacks from being called.

RemoveIsochCallbackDispatcherFromRunLoop

Removes an IOFireWireLib-added run loop event source.

void ( *RemoveIsochCallbackDispatcherFromRunLoop)( 
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Discussion

Reverses the effects of AddIsochCallbackDispatcherToRunLoop(). This method removes the run loop event source that was added to the specified run loop preventing any future callbacks from being called.

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

Seize

Seizes control of device/unit.

IOReturn ( *Seize)( 
    IOFireWireLibDeviceRef self, 
    IOOptionBits inFlags, 
    ... );

Parameters

self: The device interface to use.
reserved: Reserved for future use. Set to NULL.

Discussion

Allows a user space client to seize control of an in-kernel service even if that service has been Opened() by another client or in-kernel driver. This function should be used with care. Admin rights are required to use this function.

Calling this method makes it appear to all other drivers that the device has been unplugged. Open() should be called after this method has been invoked.

When access is complete, Close() and then IOServiceRequestProbe() should be called to restore normal operation. Calling IOServiceRequestProbe() makes it appear that the device has been "re-plugged."

Availability: This function is available in IOFireWireDeviceInterface_v3 and later.

SetBusResetDoneHandler

Sets the callback that should be called after a bus reset has occurred and reconfiguration of the bus has been completed.

const IOFireWireBusResetDoneHandler (*SetBusResetDoneHandler)(IOFireWireLibDeviceRef self, IOFireWireBusResetDoneHandler handler);

Parameters

self: The device interface to use.
handler: Function pointer to the handler to install.

Return Value

Returns an IOFireWireBusResetDoneHandler function pointer to the previously installed bus reset handler. Returns 0 if none was set.

Discussion

This function will only be called once per bus reset.

SetBusResetHandler

Sets the callback that should be called when a bus reset occurs.

const IOFireWireBusResetHandler (*SetBusResetHandler)(IOFireWireLibDeviceRef self, IOFireWireBusResetHandler handler);

Parameters

self: The device interface to use.
handler: Function pointer to the handler to install.

Return Value

Returns an IOFireWireBusResetHandler function pointer to the previously installed bus reset handler. Returns 0 if none was set.

Discussion

Note that this callback can be called multiple times before the bus reset done handler is called. For example, multiple bus resets might occur before bus reconfiguration has completed.

SetRefCon

Sets user reference value on this interface.

void ( *SetRefCon)( 
    IOFireWireLibDeviceRef self, 
    const void* refCon);

Parameters

self: The device interface to use.
refCon: The reference value to set.

Availability: This function is available in IOFireWireDeviceInterface_v2 and later.

TurnOffNotification

Deactivates and callbacks specified for this device interface.

void ( *TurnOffNotification)(
    IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Discussion

This function reverses the effects of TurnOnNotification().

TurnOnNotification

Activates any callbacks specified for this device interface.

const Boolean (*TurnOnNotification)(IOFireWireLibDeviceRef self);

Parameters

self: The device interface to use.

Return Value

Returns a Boolean value. Returns true on success.

Discussion

This function only works after AddCallbackDispatcherToRunLoop has been called. See also AddIsochCallbackDispatcherToRunLoop.

Write

Performs synchronous block write.

IOReturn ( *Write)(
    IOFireWireLibDeviceRef self, 
    io_object_t device, 
    const FWAddress* addr, 
    const void* buf, 
    UInt32* size, 
    Boolean failOnReset, 
    UInt32 generation);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr: Command target address.
buf: A pointer to a buffer where the results will be stored.
size: Number of bytes to read.
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration().
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false.

Return Value

Returns an IOReturn error code.

WriteQuadlet

Perform synchronous quadlet write

IOReturn ( *WriteQuadlet)(
    IOFireWireLibDeviceRef self,
    io_object_t device,
    const FWAddress* addr,
    const UInt32 val,
    Boolean failOnReset,
    UInt32 generation);

Parameters

self: The device interface to use.
device: The service (representing an attached FireWire device) to which to write. For 48-bit, device relative addressing, pass the service used to create the device interface. This can be obtained by calling GetDevice(). For 64-bit absolute addressing, pass 0. Other values are unsupported.
addr: Command target address
val: The value to write
failOnReset: Pass true if the command should only be executed during the FireWire bus generation specified in 'generation'. Pass false to ignore the generation parameter. The generation can be obtained by calling GetBusGeneration(). Must be 'true' when using 64-bit addressing.
generation: The FireWire bus generation during which the command should be executed. Ignored if failOnReset is false. Must be a valid generation number when using 64-bit absolute addressing.

Return Value

An IOReturn error code

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