Mac Developer Library

Developer

IOFireWireSBP2Login Class Reference

Options
Deployment Target:

On This Page
Language:

IOFireWireSBP2Login

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.

Supplies the login maintenance and Normal Command ORB execution portions of the API.

Supplies APIs for login maintenance and command execution. Drivers can use this object to create IOFireWireSBP2ORB objects and execute them. Solicited and unsolicited status callback routines can be registered and the SBP2 services will notify the driver when the appropriate status arrives. This class also handles login maintenance. Supplies APIs for logging in and logging out and attempts to reconnect to the LUN after bus resets. The base FireWire services deliver bus reset notification via the IOKit message routine. The SBP2 services build on this behavior and deliver reconnectFailed and reconnectComplete through the message routine as well.

  • Creates a new IOFireWireSBP2ORB for this login.

    Declaration

    C++

    virtual IOFireWireSBP2ORB * createORB( void );

    Return Value

    Returns a pointer to the new ORB object.

    Discussion

    Create a new IOFireWireSBP2ORB for this login. It can be configured with it's accessors and executed with submitORB below.

  • Enables unsolicited status.

    Declaration

    C++

    virtual IOReturn enableUnsolicitedStatus( void );

    Return Value

    Returns kIOReturnSuccess if the status enable write started successfully.

    Discussion

    After unsolicited is sent the device will not send any additional unsolicited status until a specific register is written. This serves as a sort of flow-control for unsolicited status. After unsolicited status is recieved and processed drivers will want to reenable the delivery of unsolicted status by a call to this method.

  • Returns the currently set login flags.

    Declaration

    C++

    virtual UInt32 getLoginFlags( void );

    Return Value

    Returns a UInt32 containing the currently set login flags.

    Discussion

    Returns the current state of the login flags. Currently there is only one flag defined for this API. kFWSBP2ExclusiveLogin indicates that the exclusive login bit should be set in the login ORB.

  • Returns the current login ID.

    Declaration

    C++

    virtual UInt32 getLoginID( void );

    Return Value

    Returns a UInt32 containing the current login ID.

    Discussion

    When we successfully login to a device. The device gives us a unique login id. This is used internally for reconnecting to the device after bus resets and for certain other management ORBs. Most drivers are probably not interested in this value.

  • Returns the maximum command block size.

    Declaration

    C++

    virtual UInt32 getMaxCommandBlockSize( void );

    Return Value

    Returns a UInt32 containing the maximum command block size.

    Discussion

    The device publishes an upper limit on the size of command block that it can accept. That value can be accessed via this method.

  • Returns the currently set maximum payload size.

    Declaration

    C++

    virtual UInt32 getMaxPayloadSize( void );

    Return Value

    Returns a UInt32 containing the currently set maximum payload size.

    Discussion

    Returns the currently global maximum payload size in bytes.

  • Returns the currently set reconnect time.

    Declaration

    C++

    virtual UInt32 getReconnectTime( void );

    Return Value

    Returns a UInt32 containing the currently set reconnect time.

    Discussion

    Returns the currently desired initiator reconnect time encoded as 2^time seconds.

  • Returns the refCon set with setRefCon.

    Declaration

    C++

    virtual void * getRefCon( void );

    Return Value

    Returns the previously stored user defined value.

    Discussion

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

  • Returns the callback to be called on normal command status.

    Declaration

    C++

    virtual void getStatusNotifyProc( void **refCon, FWSBP2NotifyCallback *callback );

    Parameters

    refCon

    output parameter returning the refCon to be passed to the callback.

    callback

    output parameter returning the address of the callback.

    Discussion

    Returns the refCon and callback address of the status notify callback.

  • Returns the callback to be called on unsolicited status.

    Declaration

    C++

    virtual void getUnsolicitedStatusNotifyProc( void **refCon, FWSBP2NotifyCallback *callback );

    Parameters

    refCon

    output parameter returning the refCon to be passed to the callback.

    callback

    output parameter returning the address of the callback.

    Discussion

    Returns the refCon and callback address of the unsolicited status notify callback.

  • Primary implementation of the release mechanism.

    Declaration

    C++

    virtual void release() const;

    Discussion

    See OSObject.h for more information. When retainCount == when then call free().

  • Rings the doorbell on the LUN.

    Declaration

    C++

    virtual IOReturn ringDoorbell( void );

    Return Value

    Returns kIOReturnSuccess if the ring started successfully.

    Discussion

    Non-immediate appends to the ORB chain may require the fetch agent state machine to be notified of the new ORB's presence. This is accomplished by writing to the so called doorbell register. This method begins one of those writes.

  • Sets the value to be written to the BUSY_TIMEOUT register.

    Declaration

    C++

    virtual void setBusyTimeoutRegisterValue( UInt32timeout );

    Parameters

    timeout

    desired value of the BUSY_TIMEOUT register.

    Discussion

    1394-1995 defines a register known as the BUSY_TIMEOUT register. This register controls the busy retry behavior of your device. The initial value for this register is 0x00000000. Which means busied transactions will not be retried. Since most devices want their transactions retired on busy acks, the SBP2 service automatically updates the BUSY_TIMEOUT register with the value specified here whenever necessary. Most drivers should set this value to 0x0000000f.

  • Sets the callback to be called when a fetch agent reset completes.

    Declaration

    C++

    virtual void setFetchAgentResetCompletion( void *refCon, FWSBP2StatusCallbackcallback );

    Parameters

    refCon

    refCon passed to callback.

    callback

    address of callback method of type FWSBP2FetchAgentWriteCallback.

    Discussion

    The fetch agent state machine on the device can be reset by a write to a specific register. The SBP2 services offer a utility method to reset the fetch agent. You can register a callback routine here to be notified when this rest write completes.

  • Sets the callback to be called when the fetch agent write completes.

    Declaration

    C++

    virtual void setFetchAgentWriteCompletion( void *refCon, FWSBP2FetchAgentWriteCallbackcallback );

    Parameters

    refCon

    refCon passed to callback.

    callback

    address of callback method of type FWSBP2FetchAgentWriteCallback.

    Discussion

    When an immediate orb is executed with submitORB, it's address is written to a specific address on the device. This address is called the fetch agent. The device the reads that orb from the Mac's memory and executes it. With this call you can register to be called back when this write to the fetch agent completes. The SBP2 services guarantee that the fetch agent write will be complete before status is reported for an ORB, so for most drivers this notification is not required.

  • Sets the callback to be called when a login attempt is complete.

    Declaration

    C++

    virtual void setLoginCompletion( void *refCon, FWSBP2LoginCallbackcallback );

    Parameters

    refCon

    refCon passed to callback.

    callback

    address of callback method of type FWSBP2LoginCallback.

    Discussion

    The supplied callback is called when a login attempt has completed. "status" in the callback's params should be checked to determine the success or failure of the login attempt. If "statusBlock" is non-null then login status was written and it has been supplied here. If the login attempt was successful then the login response will be supplied in the "loginResponse" buffer. Note: all buffers supplied to callbacks are only valid for the duration of the callback. Also, you are not to modify the contents of any supplied buffer.

  • Sets login configuration flags.

    Declaration

    C++

    virtual void setLoginFlags( UInt32loginFlags );

    Parameters

    loginFlags

    the login configuration flags.

    Discussion

    Configures the login behavior according to the provided flags. Currently two flags are defined for this API. kFWSBP2ExclusiveLogin sets the exclusive login bit in the login ORB. kFWSBP2DontSynchronizeMgmtAgent allows simultaneous logins or reconnects to LUNs with a common management agent (ie LUNs in the same unit directory).

  • Sets login retry behavior.

    Declaration

    C++

    virtual void setLoginRetryCountAndDelayTime( UInt32retryCount, UInt32uSecs );

    Parameters

    retryCount

    number of times to retry logins

    uSecs

    delay time in microseconds between login retries

    Discussion

    Sets login retry behavior.

  • Sets the callback to be called when a logout attempt is complete.

    Declaration

    C++

    virtual void setLogoutCompletion( void *refCon, FWSBP2LogoutCallbackcallback );

    Parameters

    refCon

    refCon passed to callback.

    callback

    address of callback method of type FWSBP2LogoutCallback.

    Discussion

    The supplied callback is called when a logout attempt has completed. "status" in the callback's params should be checked to determine the success or failure of the logout attempt. If "statusBlock" is non-null then logout status was written and it has been supplied here. Note: all buffers supplied to callbacks are only valid for the duration of the callback. Also, you are not to modify the contents of any supplied buffer.

  • Sets the maximum data transfer length for a normal command ORB.

    Declaration

    C++

    virtual void setMaxPayloadSize( UInt32reconnectTime );

    Parameters

    reconnectTime

    The desired maximum payload size in bytes.

    Discussion

    Sets the maximum data transfer length for a normal command ORB. This value is the maximum for all ORBs sent to this LUN. This can be trimmed further on an ORB by ORB basis, by a similar call in the IOFireWireSBP2ORB itself.

  • Sets the login password.

    Declaration

    C++

    virtual IOReturn setPassword( IOMemoryDescriptor *memory );

    Parameters

    memory

    an IOMemoryDescriptor referencing the password.

    Return Value

    Returns kIOReturnSuccess on success.

    Discussion

    Sets the login password using an IOMemoryDescriptor. An alternate version exists that accepts a buffer and a length. If the password length is 8 or less the password is copied directly into the login orb. If the length is greater than 8 the buffer is referenced by address in the login ORB.

  • Sets the login password.

    Declaration

    C++

    virtual IOReturn setPassword( void *buf, UInt32len );

    Parameters

    buf

    a pointer to the password buffer.

    len

    the length in bytes of the password buffer.

    Return Value

    Returns kIOReturnSuccess on success.

    Discussion

    Sets the login password using a buffer and a length. An alternate version exists that accepts an IOMemoryDescriptor. If the password length is 8 or less the password is copied directly into the login orb. If the length is greater than 8 the buffer is referenced by address in the login ORB. In this case the buffer is not copied and should remain allocated for the duration of the login attempt.

  • Sets the desired reconnect duration.

    Declaration

    C++

    virtual void setReconnectTime( UInt32reconnectTime );

    Parameters

    reconnectTime

    The desired reconnect timeout encoded as 2^reconnectTime seconds.

    Discussion

    The target and initiator arbitrate the duration of the reconnect timeout. Here the initiator specifies its desired timeout time in 2^reconnectTime seconds. After a successful login the device returns the actual timeout value it wishes to use. This value may be less than the reconnect timeout that the intiator specified if this is all that the device can support.

  • Sets the login refCon.

    Declaration

    C++

    virtual void setRefCon( void *refCon );

    Parameters

    refCon

    a user defined value.

    Discussion

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

  • Sets the callback to be called on normal command status.

    Declaration

    C++

    virtual void setStatusNotifyProc( void *refCon, FWSBP2NotifyCallbackcallback );

    Parameters

    refCon

    refCon passed to callback.

    callback

    address of callback method of type FWSBP2NotifyCallback.

    Discussion

    The supplied callback is called when normal command status is recieved, when a normal command times out, or when a normal command is aborted. "notificationEvent" in the callback's params will indicate what happened. It will be set to one of the following values: kFWSBP2NormalCommandReset, kFWSBP2NormalCommandStatus, or kFWSBP2NormalCommandTimeout. If the event type is kFWSBP2NormalCommandTimeout and "len" is non-zero then "message" contains the data written to the status block.

  • Sets the callback to be called on normal command status.

    Declaration

    C++

    virtual void setUnsolicitedStatusNotifyProc( void *refCon, FWSBP2NotifyCallbackcallback );

    Parameters

    refCon

    refCon passed to callback.

    callback

    address of callback method of type FWSBP2NotifyCallback.

    Discussion

    The supplied callback is called when unsolicited status is recieved. "notificationEvent" in the callback's params will indicate what happened. In this case it will be set to kFWSBP2UnsolicitedStatus. If "len" is non-zero then "message" contains the data written to the status block. Note: any buffers returned by callbacks are only valid for the duration of the login and should not have their contents modified.

  • Resets the LUN's fetch agent.

    Declaration

    C++

    virtual IOReturn submitFetchAgentReset( void );

    Return Value

    Returns kIOReturnSuccess if the reset started successfully.

    Discussion

    The fetch agent state machine on the device can be reset by a write to a specific register. This reset can be intiated by a call to this method. Notification of the completion of this write can be had by registering a callback with the setFetchAgentResetCompletion method.

  • Attempts to login to the LUN.

    Declaration

    C++

    virtual IOReturn submitLogin( void );

    Return Value

    Returns kIOReturnSuccess login has successlly begun.

    Discussion

    This call begins the login process. The login object should be configured prior to this call. If kIOReturnSuccess is returned from this call then the loginCompletion routine will be called when the login completes (successfully or unsuccesfully).

  • Attempts to logout of the LUN.

    Declaration

    C++

    virtual IOReturn submitLogout( void );

    Return Value

    Returns kIOReturnSuccess if logout has successfully begun.

    Discussion

    This call begins the logout process. If kIOReturnSuccess is returned from this call then the logoutCompletion routine will be called when the logout completes (successfully or unsuccesfully).

  • Submits the given orb

    Declaration

    C++

    virtual IOReturn submitORB( IOFireWireSBP2ORB *orb );

    Parameters

    orb

    The orb to be executed.

    Return Value

    Returns kIOReturnSuccess if the ORB has been started successfully.

    Discussion

    Starts execution of the given ORB. If the ORB is an immediate ORB it's addresss is written to the fetch agent. If it is a non immediate orb its address is appended to the last orb of the currently processing chain. The doorbell is not rung automatically it must be run manually with the ringDoorbell command described below.