IOFireWireAVCLibUnitInterface

Overview

Initial interface discovered for all AVC Unit drivers.

Discussion

The IOFireWireAVCLibUnitInterface is the initial interface discovered by most drivers. It supplies the methods that control the operation of the AVC unit as a whole. Finally, the Unit can supply a reference to the IOFireWireUnit. This can be useful if a driver wishes to access the standard FireWire APIs.

Functions

addCallbackDispatcherToRunLoop

Adds a dispatcher for kernel callbacks to the specified runloop.

AVCAsynchronousCommandCancel

AVCAsynchronousCommandReinit

AVCAsynchronousCommandReinitWithCommandBytes

AVCAsynchronousCommandRelease

AVCAsynchronousCommandSubmit

AVCCommand

Sends an AVC command to the device and returns the response.

AVCCommandInGeneration

Sends an AVC command to the device and returns the response.

breakLocalP2PInputConnection

Decrements the point-to-point connection count of a unit input plug.

breakLocalP2POutputConnection

Decrements the point-to-point connection count of a unit output plug.

breakP2PInputConnection

Decrements the point-to-point connection count of a unit input plug.

breakP2POutputConnection

Decrements the point-to-point connection count of a unit output plug.

close

Closes an exclusive access to the device.

createAVCAsynchronousCommand

getAncestorInterface

Creates a plug-in object for an ancestor (in the I/O Registry) of the AVC unit and returns an interface to it.

getBusProtocolInterface

Creates a plug-in object for a protocol driver for the FireWire bus the AVC unit is connected to and returns an interface to it.

getProtocolInterface

Creates a plug-in object for a protocol driver for the FireWire bus the AVC unit is connected to and returns an interface to it.

getSessionRef

Opens a connection to a device that is not already open.

makeLocalP2POutputConnection

Increments the point-to-point connection count of a unit output plug.

makeP2PInputConnection

Increments the point-to-point connection count of a unit input plug.

makeP2POutputConnection

Increments the point-to-point connection count of a unit output plug.

open

Exclusively opens a connection to the in-kernel device.

openWithSessionRef(void *)

Opens a connection to a device that is not already open.

openWithSessionRef(void *, IOFireWireSessionRef)

Opens a connection to a device that is not already open.

removeCallbackDispatcherFromRunLoop

Removes a dispatcher for kernel callbacks to the specified run loop.

setMessageCallback

Sets callback for user space message routine.

updateAVCCommandTimeout

Updates an AVCCommand's timeout back to 10 seconds.

Adds a dispatcher for kernel callbacks to the specified runloop.

IOReturn ( *addCallbackDispatcherToRunLoop)(
    void *self,
    CFRunLoopRef cfRunLoopRef );  

Parameters

Return Value

Returns kIOReturnSuccess on success.

Discussion

The user space portions of the AVC API communicate with the in-kernel services by messaging the kernel. Similarly, the kernel messages the user space services in response. These responses need to be picked up by a piece of code. This call adds that code to the specified run loop. Most drivers will call this method on the run loop that was created when your task was created. To avoid deadlock you must avoid sleeping (or spin waiting) the run loop to wait for AVC response. If you do this the dispatcher will never get to run and you will wait forever.

IOReturn ( *AVCAsynchronousCommandCancel)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);  

IOReturn ( *AVCAsynchronousCommandReinit)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);  

IOReturn ( *AVCAsynchronousCommandReinitWithCommandBytes)(
    void *self, 
    IOFireWireAVCLibAsynchronousCommand *pCommandObject, 
    const UInt8 * command, 
    UInt32 cmdLen);  

IOReturn ( *AVCAsynchronousCommandRelease)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);  

IOReturn ( *AVCAsynchronousCommandSubmit)(
    void *self,
    IOFireWireAVCLibAsynchronousCommand *pCommandObject);  

Sends an AVC command to the device and returns the response.

IOReturn ( *AVCCommand)(
    void *self, 
    const UInt8 * command,
    UInt32 cmdLen,
    UInt8 * response,
    UInt32 *responseLen);  

Parameters

Discussion

This function will block until the device returns a response or the kernel driver times out.

Sends an AVC command to the device and returns the response.

IOReturn ( *AVCCommandInGeneration)(
    void *self,
    UInt32 busGeneration, 
    const UInt8 * command,
    UInt32 cmdLen,
    UInt8 * response,
    UInt32 *responseLen);  

Parameters

Discussion

Sends an AVC command to the device and returns the response. The command must complete in the specified bus generation. This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?). This function will block until the device returns a response or the kernel driver times out.

Decrements the point-to-point connection count of a unit input plug.

IOReturn ( *breakP2PInputConnection)(
    void *self,
    UInt32 inputPlug);  

Discussion

This function is only available if the interface version is > 3.

Decrements the point-to-point connection count of a unit output plug.

IOReturn ( *breakP2POutputConnection)(
    void *self,
    UInt32 outputPlug);  

Discussion

This function is only available if the interface version is > 3.

Decrements the point-to-point connection count of a unit input plug.

IOReturn ( *breakP2PInputConnection)(
    void *self,
    UInt32 inputPlug);  

Discussion

This function is only available if the interface version is > 3.

Decrements the point-to-point connection count of a unit output plug.

IOReturn ( *breakP2POutputConnection)(
    void *self,
    UInt32 outputPlug);  

Discussion

This function is only available if the interface version is > 3.

Closes an exclusive access to the device.

void ( *close)(
    void *self );  

Parameters

Discussion

Closes an exclusive access to the device. When a device is closed it may be unloaded by the kernel. If it is unloaded and then later reappears it will be represented by a different object. You won't be able to use this user client on the new object. The new object will have to be looked up in the I/O Registry and a new user client will have to be opened on it.

IOReturn ( *createAVCAsynchronousCommand)(
    void *self, 
    const UInt8 * command, 
    UInt32 cmdLen, 
    IOFireWireAVCLibAsynchronousCommandCallback completionCallback, 
    void *pRefCon, 
    IOFireWireAVCLibAsynchronousCommand **ppCommandObject);  

Creates a plug-in object for an ancestor (in the I/O Registry) of the AVC unit and returns an interface to it.

void * ( *getAncestorInterface)(
    void *self,
    char *object_class,
    REFIID pluginType,
    REFIID iid);  

Parameters

Return Value

Returns a COM-style interface pointer. Returns 0 upon failure.

Discussion

This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?).

Creates a plug-in object for a protocol driver for the FireWire bus the AVC unit is connected to and returns an interface to it.

void * ( *getProtocolInterface)(
    void *self,
    REFIID pluginType,
    REFIID iid);  

Parameters

Return Value

Returns a COM-style interface pointer. Returns 0 upon failure.

Discussion

This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?).

Creates a plug-in object for a protocol driver for the FireWire bus the AVC unit is connected to and returns an interface to it.

void * ( *getProtocolInterface)(
    void *self,
    REFIID pluginType,
    REFIID iid);  

Parameters

Return Value

Returns a COM-style interface pointer. Returns 0 upon failure.

Discussion

This function is only available if the interface version is > 1 (MacOSX 10.2.0 or later?).

Opens a connection to a device that is not already open.

IOFireWireSessionRef ( *getSessionRef)(
    void *self);  

Parameters

Return Value

Returns a sessionRef on success.

Discussion

Sometimes it is desirable to open multiple user clients on a device. In the case of FireWire sometimes we wish to have both the FireWire User Client and the AVC User Client open at the same time. The technique to arbitrate this is as follows:
First open normally the device furthest from the root in the IORegistry.
Second, get its sessionRef with the with a call to this method.
Third, open the device further up the chain by calling openWithSessionRef and passing the sessionRef returned from this call.

Increments the point-to-point connection count of a unit output plug.

IOReturn ( *makeP2POutputConnection)(
    void *self,
    UInt32 outputPlug,
    UInt32 chan,
    IOFWSpeed speed);  

Discussion

This function is only available if the interface version is > 3.

Increments the point-to-point connection count of a unit input plug.

IOReturn ( *makeP2PInputConnection)(
    void *self,
    UInt32 inputPlug,
    UInt32 chan);  

Discussion

This function is only available if the interface version is > 3.

Increments the point-to-point connection count of a unit output plug.

IOReturn ( *makeP2POutputConnection)(
    void *self,
    UInt32 outputPlug,
    UInt32 chan,
    IOFWSpeed speed);  

Discussion

This function is only available if the interface version is > 3.

Exclusively opens a connection to the in-kernel device.

IOReturn ( *open)(
    void *self );  

Parameters

Return Value

Returns kIOReturnSuccess on success.

Discussion

Exclusively opens a connection to the in-kernel device. As long as the in-kernel device object is open, no other drivers will be able to open a connection to the device. When open, the device on the bus may disappear, but the in-kernel object representing it will stay instantiated and can begin communicating with the device again if it ever reappears.

Opens a connection to a device that is not already open.

IOFireWireSessionRef ( *getSessionRef)(
    void *self);  

Parameters

Return Value

Returns a sessionRef on success.

Discussion

Sometimes it is desirable to open multiple user clients on a device. In the case of FireWire sometimes we wish to have both the FireWire User Client and the AVC User Client open at the same time. The technique to arbitrate this is as follows:
First open normally the device furthest from the root in the IORegistry.
Second, get its sessionRef with the with a call to this method.
Third, open the device further up the chain by calling openWithSessionRef and passing the sessionRef returned from this call.

Opens a connection to a device that is not already open.

IOReturn ( *openWithSessionRef)(
    void *self,
    IOFireWireSessionRef sessionRef );  

Parameters

Return Value

Returns kIOReturnSuccess on success.

Discussion

Sometimes it is desirable to open multiple user clients on a device. In the case of FireWire sometimes we wish to have both the FireWire User Client and the AVC User Client open at the same time. The technique to arbitrate this is as follows:
First open normally the device furthest from the root in the I/O Registry.
Second, get its sessionRef with the getSessionRef call.
Third, open the device further up the chain by calling this method and passing the sessionRef returned from the call in step 2.

Removes a dispatcher for kernel callbacks to the specified run loop.

void ( *removeCallbackDispatcherFromRunLoop)(
    void *self );  

Parameters

Discussion

Undoes the work of addCallbackDispatcherToRunLoop.

Sets callback for user space message routine.

void ( *setMessageCallback)(
    void *self,
    void *refCon,
    IOFWAVCMessageCallback callback);  

Parameters

Discussion

In FireWire and AVC, bus status messages are delivered via IOKit's message routine. This routine is emulated in user space for AVC and FireWire messages via this callback. You should register here for bus reset and reconnect messages.

Updates an AVCCommand's timeout back to 10 seconds.

IOReturn ( *updateAVCCommandTimeout)(
    void *self);  

Discussion

AVCCommands will time out after 10 seconds unless this function is called (from another thread) to update the command's timeout back to 10 seconds. This function is only available if the interface version is > 2.

Last Updated: 2009-10-15