Using scsi_command()

Tip: When debugging a driver using a debugging kernel (see "Preparing the System for Debugging"), you can display the contents of a scsi_request structure using symmon or idbg (see "Commands to Display I/O Status").

Input to scsi_command()

Input Fields of the scsi_request Structure

Field Name	Contents
sr_ctlr	The adapter number.
sr_target	The target number.
sr_lun	The logical unit number.
sr_tag	If this target supports the SCSI-2 tagged-queue feature, and this command is directed to a queue, this field contains the queue tag message. Constant names for queue messages are in sys/scsi.h: SC_TAG_SIMPLE and two others.
sr_command	Address of the bytes of the SCSI command to issue.
sr_cmdlen	The length of the string at *sr_command. Constants for the common lengths are in sys/scsi.h: SC_CLASS0_SZ (6), SC_CLASS1_SZ (10), and SC_CLASS2_SZ (12).
sr_flags	Flags for data direction and DMA mapping, see Table 15-4.
sr_timeout	Number of ticks (HZ units) to wait for a response before timing out. The host adapter driver supplies a minimum value if this field is zero or too small.
sr_buffer	Address of first byte of data. Must be zero when sr_bp is supplied and SRF_MAPBP is specified in sr_flags.
sr_buflen	Length of data or buffer space.
sr_sense	Address of space for sense data, in case the command ends in a check condition.
sr_senselen	Length of the sense area.
sr_notify	Address of the callback function, called when the command is complete. A callback address is required on all commands.
sr_bp	Address of a buf_t object, when the command is called from a block driver's pfxstrategy() entry point and buffer mapping is requested in sr_flags.
sr_dev	Address of additional information that could be useful in the callback routine *sr_notify.

The callback function address in sr_notify must be specified. (Device drivers for versions of IRIX previous to 5.x may set a NULL in this field; that is no longer permitted.)

The possible flag bits that can be set in sr_flags are listed in Table 15-4.

Values for the sr_flags Field of a scsi_request

Flag Constant	Purpose
SRF_DIR_IN	Data will be received in memory. If this flag is absent, the command sends data from memory to the device.
SRF_FLUSH	The data cache for the buffer area should be flushed (for output) or marked invalid (for input) prior to the command. This flag should be used whenever the buffer is local to the driver, not mapped by a buf_t object. It causes no extra overhead in systems that do not require cache flushing.
SRF_MAPUSER	Set this flag when doing I/O based on a buf_t and the B_MAPUSER bit is set in b_flags.
SRF_MAP	Set this flag when doing I/O based on a buf_t and the BP_ISMAPPED macro returns nonzero.
SRF_MAPBP	The sr_bp field points to a buf_t in which BP_ISMAPPED returns false. The host adapter driver maps in the buffer.
SRF_AEN_ACK	This request is an acknowledgment of an AEN (Asynchronous Event Notification) message from the target. Following an AEN, any command without this flag is rejected with status SC_ATTN.
SRF_NEG_SYNC	Attempt to negotiate synchronous transfer mode for this command. Ignored by some host adapter drivers. Overrides SCSIALLOC_NOSYNC (see "Using scsi_alloc()").
SRF_NEG_ASYNC	Attempt to negotiate asynchronous mode for this command. Ignored unless the device is currently using synchronous mode.

When none of the three flag values beginning SR_MAP are supplied, the sr_buffer address must be a physical memory address. The SR_MAPUSER and SR_MAPBP flags are normally used when the command is issued from a pfxstrategy() entry point in order to read or write a buffer controlled from a buf_t object.

Command Execution

In any event, the sr_notify function is called when the command is complete. This function can be called from the host adapter interrupt handler, so it must assume that it is called in interrupt state.

The device driver should wait for the notify function to be called. The usual way is to share a semaphore (see "Semaphores"), as follows:

• Prior to calling scsi_command(), initialize the semaphore to 0 (the semaphore is being used to wait for an event).

• Immediately after the call to scsi_command(), call psema() for the semaphore.

• In the notify function, call vsema() for the function.

When the device driver holds an exclusive lock prior to issuing the command, a synchronization variable provides an appropriate way to wait for command completion (see "Using Synchronization Variables").

Values Returned in a scsi_request Structure

Values Returned From a SCSI Command

Field Name	Purpose
sr_status	Software status flags, see Table 15-6.
sr_scsi_status	SCSI status byte, see Table 15-7.
sr_ha_flags	Host adapter status flags, see Table 15-8.
sr_sensegotten	When no sense command was issued, 0. When a sense command was issued following an error, the number of bytes of sense data received. When an error occurred during a sense command, -1
sr_resid	The difference between sr_buflen and the number of bytes actually transferred.

The sr_status field should be tested first. It contains an integer value; the possible values are summarized in Table 15-6.

Software Status Values From a SCSI Request

Constant Name	Meaning
SC_GOOD	The request was valid and the command was executed. The command might still have failed; see sr_scsi_status.
SC_TIMEOUT	The device did not respond to selection within 250 milliseconds.
SC_HARDERR	A hardware error occurred; inspect sr_senselen to see how much sense data was received, if any.
SC_PARITY	SCSI bus parity error detected.
SC_MEMERR	System memory parity or ECC error detected.
SC_CMDTIME	The device responded to selection but the command did not complete before sr_timeout expired.
SC_ALIGN	The buffer address was not aligned as required by the adapter hardware. Most Silicon Graphics adapters require word (4-byte) alignment.
SC_ATTN	Either a unit attention was received, or this command follows an AEN and did not contain the SR_AEN_ACK flag (see Table 15-4).
SC_REQUEST	An error was detected in the input values; the command was not attempted. The error could be that scsi_alloc() has not been called; or it could be due to missing or incorrect values.

One or more bits are set in the sc_scsi_status field. This field represents the status following the requested command, when the requested command executes correctly. When the requested command ends with Check Condition status, a sense command is issued and the SCSI status following the sense is placed in sc_scsi_status. In other words, the true indication of successful execution of the requested command is a zero in sr_sensegotten, because this indicates that no sense command was attempted.

Possible values of sc_scsi_status are summarized in Table 15-7.

SCSI Status Bytes

Constant Name	Meaning
ST_GOOD	The target has successfully completed the SCSI command. If a check condition was returned, a sense command was issued. The sr_sensegotten field is nonzero when this was the case.
ST_CHECK	This bit is only set for the special case when a check condition occurred on a sense command following a check condition on the requested command. The sr_sensegotten field contains -1.
ST_COND_MET	Search condition was met.
ST_BUSY	The target is busy. The driver will normally delay and then request the command again.
ST_INT_GOOD	This status is reported for every command in a series of linked commands. Linked commands are not supported by Silicon Graphics host adapters.
ST_RES_CONF	A conflict with a reserved logical unit or reserved extent.

One or more bits can be set in sr_ha_flags to document a host adapter state or problem. These flags are summarized in Table 15-8.

Host Adapter Status After a SCSI Request

Constant Name	Meaning
SRH_CANTSYNC	Unable to negotiate synchronous mode.
SRH_SYNCXFR	Synchronous mode was used. If not set, asynchronous mode was used.
SRH_TRIEDSYNC	Synchronous mode negotiation was attempted; see the SHR_CANTSYNC bit for the result.
SRH_BADSYNC	When SRH_CANTSYNC is set, this bit indicates that the negotiation failed because the device cannot negotiate.
SRH_NOADAPSYNC	When SRH_CANTSYNC is set, this bit indicates that the host adapter does not support synchronous negotiation, or that the system has been configured to not use synchronous mode for this device.
SRH_WIDE	This adapter supports Wide mode.
SRH_DISC	This adapter supports Disconnect mode and is configured to use it.
SRH_TAGQ	This adapter supports tagged queueing and is configured to use it.
SRH_MAPUSER	This host adapter driver can map user addresses.