[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, Volume 2

SCIORESET (Reset) SCSI Adapter Device Driver ioctl Operation

Purpose

Allows the caller to force a SCSI device to release all current reservations, clear all current commands, and return to an initial state.

Description

The SCIORESET operation allows the caller to force a SCSI device to release all current reservations, clear all current commands, and return to an initial state. This operation is used by system management routines to force a SCSI controller to release a competing SCSI initiator's reservation in a multi-initiator environment.

This operation actually executes a SCSI bus device reset (BDR) message to the selected SCSI controller on the selected adapter. The BDR message is directed to a SCSI ID. Therefore, all logical unit numbers (LUNs) associated with that SCSI ID are affected by the execution of the BDR.

For the operation to work effectively, a SCSI Reserve command should be issued after the SCIORESET operation through the appropriate SCSI device driver. Typically, the SCSI device driver open logic issues a SCSI Reserve command. This prevents another initiator from claiming the device.

There is a finite amount of time between the release of all reservations (by a SCIORESET operation) and the time the device is again reserved (by a SCSI Reserve command from the host). During this interval, another SCSI initiator can reserve the device instead. If this occurs, the SCSI Reserve command from this host fails and the device remains reserved by a competing initiator. The capability needed to prevent or recover from this event is beyond the SCSI adapter device driver and SCSI device driver components.

The arg parameter to the SCIORESET operation allows the caller to specify the SCSI ID of the device to be reset. The least significant byte in the arg parameter is the LUN ID of the LUN on the SCSI controller. The device indicated by the LUN ID should have been successfully started by a call to the SCIOSTART operation. The next least significant byte is the SCSI ID. The remaining two bytes are reserved and must be set to a value of 0.

Examples

  1. The following example demonstrates actual use of this command. A SCSI ID of 1 is assumed, and an LUN of 0 exists on this SCSI controller. 
    open SCSI adapter device driver
SCIOSTART SCSI ID=1, LUN=0
SCIORESET SCSI ID=1, LUN=0 (to free any reservations)
SCIOSTOP SCSI ID=1, LUN=0
close SCSI adapter device driver
open SCSI device driver (normal open) for SCSI ID=1, LUN=0
...
Use device as normal
...
  2. To make use of the SC_FORCED_OPEN flag of the SCSI device driver: 
    open SCSI device driver (with SC_FORCED_OPEN flag) 
for SCSI ID=1, LUN=0
...
    Use the device as normal.

Both examples assume that the SCSI device driver open call executes a SCSI Reserve command on the selected device.

The SCSI adapter device driver performs normal error-recovery procedures during execution of this command. For example, if the BDR message causes the SCSI bus to hang, a SCSI bus reset will be initiated to clear the condition.

Return Values

When completed successfully, this operation returns a value of 0. Otherwise, a value of -1 is returned and the errno global variable is set to one of the following values:

EINVAL Indicates an SCIOSTART command was not issued prior to this command.
EIO Indicates an unrecoverable I/O error occurred. In this case, the adapter error-status information is logged in the system error log.
EIO Indicates either the device is already stopping or the device driver is unable to pin code.
ENOCONNECT Indicates that a bus fault has occurred. The caller should respond by retrying with the SC_ASYNC flag set in the flag byte of the passed parameters. If more than one retry is attempted, only the last retry should be made with the SC_ASYNC flag set. Generally, the SCSI adapter device driver cannot determine which device caused the bus fault, so this error is not logged in the system error log.
ENODEV Indicates the target SCSI ID could not be selected or is not responding. This condition is not necessarily an error and is not logged.
ENOMEM Indicates insufficient memory is available to complete the command.
ETIMEDOUT Indicates the adapter did not respond with status before the internal command time-out value expired. This error is logged.

Files

/dev/scsi0, /dev/scsi1, ..., /dev/scsin Provide an interface to allow SCSI device drivers to access SCSI devices or adapters.
/dev/vscsi0, /dev/vscsi1,..., /dev/vscsin Provide an interface to allow SCSI-2 Fast/Wide Adapter/A and SCSI-2 Differential Fast/Wide Adapter/A device drivers to access SCSI devices or adapters.

Related Information

The rmt SCSI device driver, scdisk SCSI device driver, SCSI Adapter device driver.

[ Previous | Next | Contents | Home | Search ]