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

IOFireWireSBP2LibLUNInterface

Declared In:

Overview

Initial interface disovered for all drivers.

Discussion

The IOFireWireSBP2LibLUNInterface is the initial interface discovered by most drivers. It supplies the methods that control the operation of the LUN as a whole. Methods that control the behavior and execution of an SBP2 login session are supplied in a separate IOFireWireSBP2LibLoginInterface object. The LUN can be used to create one of these login objects. The LUN can also create IOFireWireSBP2LibManagementORBInterface objects for configuring and appending non-login related management functions. Login related management functions (ie. Login, Logout, Reconnect) are supplied by the IOFireWireSBP2LibLoginInterface. Finally the LUN 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 run loop.
close: Opens a connection to a device that is not already open.
createLogin: Creates a new IOFireWireSBP2LibLoginInterface object.
createMgmtORB: Creates a new IOFireWireSBP2LibMgmntORBInterface object.
getRefCon: Returns the refCon set with setRefCon.
getSessionRef: Returns the session reference to an already open device.
open: Exclusively opens a connection to the in-kernel device.
openWithSessionRef: Opens a connection to a device that is already open.
removeCallbackDispatcherFromRunLoop: Removes a dispatcher for kernel callbacks from the specified run loop.
setMessageCallback: Set callback for user space message routine.
setRefCon: Sets the ORB refCon.

addCallbackDispatcherToRunLoop

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

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

Parameters

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

Return Value

Returns kIOReturnSuccess on success.

Discussion

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

close

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

void ( *close)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.

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 IORegistry and a new user client will have to be opened on it.

createLogin

Creates a new IOFireWireSBP2LibLoginInterface object.

IUnknownVTbl** ( *createLogin)(
    void *self,
    REFIID iid );

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.
iid: UUID for desired type of IOFireWireSBP2LibLoginInterface.

Return Value

Returns a pointer to a new IOFireWireSBP2LibLoginInterface.

Discussion

Creates a new IOFireWireSBP2LibLoginInterface object for the LUN. Login objects supply most of the SBP2 APIs related to login maintenance and Normal Command ORB execution.

createMgmtORB

Creates a new IOFireWireSBP2LibMgmntORBInterface object.

IUnknownVTbl** ( *createMgmtORB)(
    void *self,
    REFIID iid );

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.
iid: UUID for desired type of IOFireWireSBP2LibMgmtORBInterface.

Return Value

Returns a pointer to a new IOFireWireSBP2Login.

Discussion

Creates a new IOFireWireSBP2LibMgmtORBInterface object. Management objects let you execute commands like QueryLogins, LogicalUnitReset, and AbortTask. These commands are configured after they are created here. When they are done executing (after a call to submit) the supplied completion routine will be called with the supplied refcon. Usually this refCon is the "this" pointer of completion method's object.

getRefCon

Returns the refCon set with setRefCon.

void * ( *getRefCon)(
    void *self);

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.

Return Value

Returns the previously stored user defined value.

Discussion

Returns the user defined value previously stored in the ORB with setRefCon.

getSessionRef

Returns the session reference to an already open device.

IOFireWireSessionRef ( *getSessionRef)(
    void *self);

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.

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 SBP2 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 a call to this method.

Third open the device further up the chain by calling openWithSessionRef and passing the sessionRef returned from this call.

open

Exclusively opens a connection to the in-kernel device.

IOReturn ( *open)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.

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.

openWithSessionRef

Opens a connection to a device that is already open.

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

Parameters

sessionRef: SessionRef returned from getSessionRef call.
self: Pointer to IOFireWireSBP2LibLUNInterface.

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 SBP2 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 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.

removeCallbackDispatcherFromRunLoop

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

void ( *removeCallbackDispatcherFromRunLoop)(
    void *self );

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.

Discussion

Undoes the work of addCallbackDispatcherToRunLoop.

setMessageCallback

Set callback for user space message routine.

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

Parameters

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

Discussion

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

setRefCon

Sets the ORB refCon.

void ( *setRefCon)(
    void *self,
    void *refCon );

Parameters

self: Pointer to IOFireWireSBP2LibLUNInterface.
refCon: a user defined value.

Discussion

Sets a user defined value on the ORB that can be retrieved later with the method getRefCon.

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