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

IOFireWireAVCLibProtocolInterface

Declared In:

IOFireWireAVCLib.h

Overview

Initial interface discovered for all AV/C protocol drivers.

Discussion

The IOFireWireAVCLibProtocolInterface is used to set up local plug control registers and to receive AV/C requests.

Functions

addCallbackDispatcherToRunLoop: Adds a dispatcher for kernel callbacks to the specified run loop.
addSubunit: Installs a virtual AV/C subunit.
allocateInputPlug: Allocates an input plug.
allocateOutputPlug: Allocates an output plug.
connectTargetPlugs: Establishes an internal AV/C plug connection between subunit/unit plugs.
disconnectTargetPlugs: Breaks an internal AV/C plug connection between subunit/unit plugs.
freeInputPlug: Deallocates an input plug.
freeOutputPlug: Deallocates an output plug.
getSubunitPlugSignalFormat: Gets the signal format of the specifed plug.
getTargetPlugConnection: Gets the connection details for a specific plug.
installAVCCommandHandler: Installs a command handler for handling specific incoming AV/C commands.
publishAVCUnitDirectory: Publishes an AV/C unit directory in the config ROM.
readInputMasterPlug: Returns the current value of the input master plug.
readInputPlug: Returns the current value of an input plug.
readOutputMasterPlug: Returns the current value of the output master plug.
readOutputPlug: Returns the current value of an output plug.
removeCallbackDispatcherFromRunLoop: Removes a dispatcher for kernel callbacks to the specified run loop.
sendAVCResponse: Sends an AV/C response packet.
setAVCRequestCallback: This function has been deprecated. Use installAVCCommandHandler instead.
setMessageCallback: Sets callback for user space message routine.
setSubunitPlugSignalFormat: Sets the signal format of the specifed plug.
updateInputMasterPlug: Updates the value of the master input plug (simulating a lock transaction).
updateInputPlug: Updates the value of an input plug (simulating a lock transaction).
updateOutputMasterPlug: Updates the value of the master output plug (simulating a lock transaction).
updateOutputPlug: Updates the value of an output plug (simulating a lock transaction).

addCallbackDispatcherToRunLoop

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

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

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
cfRunLoopRef: Reference to a run loop.

Return Value

Returns kIOReturnSuccess on success.

Discussion

The user space portions of the AV/C 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 AV/C response. If you do this the dispatcher will never get to run and you will wait forever.

addSubunit

Installs a virtual AV/C subunit.

IOReturn ( *addSubunit)(
    void *self, 
    UInt32 subunitType, 
    UInt32 numSourcePlugs, 
    UInt32 numDestPlugs, 
    void *refCon, 
    IOFWAVCSubunitPlugHandlerCallback callback, 
    UInt32 *pSubunitTypeAndID);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
subunitType: The type of subunit to create.
numSourcePlugs: The number of source plugs for this subunit.
numDestPlugs: The number of destination plugs for this subunit.
refcon: Arbitrary value passed back as first argument of callback.
callback: A pointer to the callback to receive plug management messages.
pSubunitTypeAndID: A pointer to a byte to hold the returned subunit address for the new subunit.

allocateInputPlug

Allocates an input plug.

IOReturn ( *allocateInputPlug)(
    void *self,
    void *refcon,
    IOFWAVCPCRCallback func,
    UInt32 *plug);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
refcon: Arbitrary value passed back as first argument of callback.
func: Callback function when a successful lock transaction to the plug has been performed.
plug: Set to the plug number if a plug is successfully allocated.

allocateOutputPlug

Allocates an output plug.

IOReturn ( *allocateOutputPlug)(
    void *self,
    void *refcon,
    IOFWAVCPCRCallback func,
    UInt32 *plug);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
refcon: Arbitrary value passed back as first argument of callback.
func: Callback function when a successful lock transaction to the plug has been performed.
plug: Set to the plug number if a plug is successfully allocated.

connectTargetPlugs

Establishes an internal AV/C plug connection between subunit/unit plugs.

IOReturn ( *connectTargetPlugs)(
    void *self, 
    UInt32 sourceSubunitTypeAndID, 
    IOFWAVCPlugTypes sourcePlugType, 
    UInt32 *pSourcePlugNum, 
    UInt32 destSubunitTypeAndID, 
    IOFWAVCPlugTypes destPlugType, 
    UInt32 *pDestPlugNum, 
    bool lockConnection, 
    bool permConnection);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
sourceSubunitTypeAndID: The subunit type and ID for the source plug
sourcePlugType: The source plug type.
pSourcePlugNum: A pointer to the source plug number. Will return the actual source plug number here.
destSubunitTypeAndID: The subunit type and ID for the destination plug.
destPlugType: The destination plug type.
pDestPlugNum: A pointer to the destination plug number. Will return the actual destination plug number here.
lockConnection: A flag to specify if this connection should be locked.
permConnection: A flag to specify if this connection is permanent.

disconnectTargetPlugs

Breaks an internal AV/C plug connection between subunit/unit plugs.

IOReturn ( *disconnectTargetPlugs)(
    void *self, 
    UInt32 sourceSubunitTypeAndID, 
    IOFWAVCPlugTypes sourcePlugType, 
    UInt32 sourcePlugNum, 
    UInt32 destSubunitTypeAndID, 
    IOFWAVCPlugTypes destPlugType, 
    UInt32 destPlugNum);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
sourceSubunitTypeAndID: The subunit type and ID for the source plug.
sourcePlugType: The source plug type.
pSourcePlugNum: The source plug number.
destSubunitTypeAndID: The subunit type and ID for the destination plug.
destPlugType: The destination plug type.
pDestPlugNum: The destination plug number.

freeInputPlug

Deallocates an input plug.

void ( *freeInputPlug)(
    void *self,
    UInt32 plug);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
plug: Value returned by allocateInputPlug.

freeOutputPlug

Deallocates an output plug.

void ( *freeOutputPlug)(
    void *self,
    UInt32 plug);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
plug: Value returned by allocateOutputPlug.

getSubunitPlugSignalFormat

Gets the signal format of the specifed plug.

IOReturn ( *getSubunitPlugSignalFormat)(
    void *self, 
    UInt32 subunitTypeAndID, 
    IOFWAVCPlugTypes plugType, 
    UInt32 plugNum, 
    UInt32 *pSignalFormat);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
subunitTypeAndID: The subunit type and ID of the plug.
plugType: The plug type.
plugNum: The plug number.
pSignalFormat: A pointer to the location to return the signal format value.

getTargetPlugConnection

Gets the connection details for a specific plug.

IOReturn ( *getTargetPlugConnection)(
    void *self, 
    UInt32 subunitTypeAndID, 
    IOFWAVCPlugTypes plugType, 
    UInt32 plugNum, 
    UInt32 *pConnectedSubunitTypeAndID, 
    IOFWAVCPlugTypes *pConnectedPlugType, 
    UInt32 *pConnectedPlugNum, 
    bool *pLockConnection, 
    bool *pPermConnection);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
subunitTypeAndID: The subunit type and ID of the plug.
plugType: The plug type.
plugNum: The plug number.
pConnectedSubunitTypeAndID: The subunit type and ID of the connected plug.
pConnectedPlugType: The type of the connected plug.
pConnectedPlugNum: The number of the connected plug.
pLockConnection: A pointer for returning the lock status of the connection.
pPermConnection: A pointer for returning the perm status of the connection.

installAVCCommandHandler

Installs a command handler for handling specific incoming AV/C commands.

IOReturn ( *installAVCCommandHandler)(
    void *self, 
    UInt32 subUnitTypeAndID, 
    UInt32 opCode, 
    void *refCon, 
    IOFWAVCCommandHandlerCallback callback);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
subUnitTypeAndID: The subunit type and ID for this command handler.
opCode: The opcode for this command handler.
refcon: Arbitrary value passed back as first argument of callback.
callback: A pointer to the callback function

publishAVCUnitDirectory

Publishes an AV/C unit directory in the config ROM.

IOReturn ( *publishAVCUnitDirectory)(
    void *self);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.

readInputMasterPlug

Returns the current value of the input master plug.

UInt32 ( *readInputMasterPlug)(
    void *self);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.

readInputPlug

Returns the current value of an input plug.

UInt32 ( *readInputPlug)(
    void *self,
    UInt32 plug);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
plug: Value returned by allocateInputPlug.

readOutputMasterPlug

Returns the current value of the output master plug.

UInt32 ( *readOutputMasterPlug)(
    void *self);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.

readOutputPlug

Returns the current value of an output plug.

UInt32 ( *readOutputPlug)(
    void *self,
    UInt32 plug);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
plug: Value returned by allocateOutputPlug.

removeCallbackDispatcherFromRunLoop

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

void ( *removeCallbackDispatcherFromRunLoop)(
    void *self );

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.

Discussion

Undoes the work of addCallbackDispatcherToRunLoop.

sendAVCResponse

Sends an AV/C response packet.

IOReturn ( *sendAVCResponse)(
    void *self, 
    UInt32 generation, 
    UInt16 nodeID, 
    const char *response, 
    UInt32 responseLen);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
generation: The FireWire bus generation that this response should be sent in.
nodeID: The node ID of the device we are sending this response to.
response: A pointer to the response bytes.
responseLen: The number of response bytes.

setAVCRequestCallback

This function has been deprecated. Use installAVCCommandHandler instead.

IOReturn ( *setAVCRequestCallback)(
    void *self,
    UInt32 subUnitType,
    UInt32 subUnitID, 
    void *refCon,
    IOFWAVCRequestCallback callback);

setMessageCallback

Sets callback for user space message routine.

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

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
refCon: RefCon to be returned as first argument of completion routine.
callback: Address of completion routine.

Discussion

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

setSubunitPlugSignalFormat

Sets the signal format of the specifed plug.

IOReturn ( *setSubunitPlugSignalFormat)(
    void *self, 
    UInt32 subunitTypeAndID, 
    IOFWAVCPlugTypes plugType, 
    UInt32 plugNum, 
    UInt32 signalFormat);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
subunitTypeAndID: The subunit type and ID of the plug.
plugType: The plug type.
plugNum: The plug number.
signalFormat: The 32-bit signal format value.

updateInputMasterPlug

Updates the value of the master input plug (simulating a lock transaction).

IOReturn ( *updateInputMasterPlug)(
    void *self,
    UInt32 oldVal,
    UInt32 newVal);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
oldVal: Value returned by readInputMasterPlug.
newVal: New value to store in plug if its current value is oldVal.

updateInputPlug

Updates the value of an input plug (simulating a lock transaction).

IOReturn ( *updateInputPlug)(
    void *self,
    UInt32 plug,
    UInt32 oldVal,
    UInt32 newVal);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
plug: Value returned by allocateInputPlug.
oldVal: Value returned by readInputPlug.
newVal: New value to store in plug if its current value is oldVal.

updateOutputMasterPlug

Updates the value of the master output plug (simulating a lock transaction).

IOReturn ( *updateOutputMasterPlug)(
    void *self,
    UInt32 oldVal,
    UInt32 newVal);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
oldVal: Value returned by readOutputMasterPlug.
newVal: New value to store in plug if its current value is oldVal.

updateOutputPlug

Updates the value of an output plug (simulating a lock transaction).

IOReturn ( *updateOutputPlug)(
    void *self,
    UInt32 plug,
    UInt32 oldVal,
    UInt32 newVal);

Parameters

self: Pointer to IOFireWireAVCLibProtocolInterface.
plug: Value returned by allocateOutputPlug.
oldVal: Value returned by readOutputPlug.
newVal: New value to store in plug if its current value is oldVal.

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