The sc_buf structure is used for communication between the SCSI device driver and the SCSI adapter device driver during an initiator I/O request. This structure is passed to and from the strategy routine in the same way a standard driver uses a struct buf structure.
The sc_buf structure contains certain fields used to pass a SCSI command and associated parameters to the SCSI adapter device driver. Other fields within this structure are used to pass returned status back to the SCSI device driver. The sc_buf structure is defined in the /usr/include/sys/scsi.h file.
Fields in the sc_buf structure are used as follows:
SC_NODISC | Do not allow the target to disconnect during this command. |
SC_ASYNC | Do not allow the adapter to negotiate for synchronous transfer to the SCSI device. |
Also during normal use, the SC_ASYNC bit must not be set. It should be set only in cases where a previous command to the device ended in an unexpected SCSI bus free condition. This condition is noted as SC_SCSI_BUS_FAULT in the general_card_status field of the sc_cmd structure. Since other errors may also result in the SC_SCSI_BUS_FAULT flag being set, the SC_ASYNC bit should only be set on the last retry of the failed command.
The contents of the resvd1 field, if non-null, must be a pointer to the uio structure that is passed to the SCSI device driver. The SCSI adapter device driver treats the resvd1 field as a pointer to a uio structure that accesses the iovec structures containing pointers to the data. There are no address-alignment restrictions on the data in the iovec structures. The only restriction is that the total transfer length of all the data must not exceed the maximum transfer length for the adapter device driver.
The sc_buf.bufstruct.b_un.b_addr field, which normally contains the starting system-buffer address, is ignored and can be altered by the SCSI adapter device driver when the sc_buf is returned. The sc_buf.bufstruct.b_bcount field should be set by the caller to the total transfer length for the data.
SC_SCSI_ERROR | The scsi_status field is valid. |
SC_ADAPTER_ERROR | The general_card_status field is valid. |
If an error is detected during execution of a SCSI command, and the error prevented the SCSI command from actually being sent to the SCSI bus by the adapter, then the error should be processed or recovered, or both, by the SCSI adapter device driver.
If it is recovered successfully by the SCSI adapter device driver, the error is logged, as appropriate, but is not reflected in the general_card_status byte. If the error cannot be recovered by the SCSI adapter device driver, the appropriate general_card_status bit is set and the sc_buf structure is returned to the SCSI device driver for further processing.
If an error is detected after the command was actually sent to the SCSI device, then it should be processed or recovered, or both, by the SCSI device driver.
For error logging, the SCSI adapter device driver logs SCSI bus- and adapter-related conditions, while the SCSI device driver logs SCSI device-related errors. In the following description, a capital letter "A" after the error name indicates that the SCSI adapter device driver handles error logging. A capital letter "H" indicates that the SCSI device driver handles error logging.
Some of the following error conditions indicate a SCSI device failure. Others are SCSI bus- or adapter-related.
Logical Unit Numbers (LUNs) | ||
lun Fields | LUN 0 - 7 | LUN 8 - 31 |
sc_buf.lun | LUN Value | LUN Value |
sc_buf.scsi_command.scsi_cmd.lun | LUN Value | 0 |
Note: LUN value is the current value of LUN.
Note: Commands with the value of SC_NO_Q for the q_tag_msg field (except for request sense commands) should not be queued to a device whose queue contains a command with another value for q_tag_msg . If commands with the SC_NO_Q value (except for request sense) are sent to the device, then the SCSI device driver must make sure that no active commands are using different values for q_tag_msg . Similarly, the SCSI device driver must also make sure that a command with a q_tag_msg value of SC_ORDERED_Q, SC_HEAD_Q, or SC_SIMPLE_Q is not sent to a device that has a command with the q_tag_msg field of SC_NO_Q.
SC_RESUME | When set, means the SCSI adapter device driver should resume transaction queuing for this ID/LUN. Error recovery is complete after a SCIOHALT operation, check condition, or severe SCSI bus error. This flag is used to restart the SCSI adapter device driver following a reported error. |
SC_DELAY_CMD | When set, means the SCSI adapter device driver should delay sending this command (following a SCSI reset or BDR to this device) by at least the number of seconds specified to the SCSI adapter device driver in its configuration information. For SCSI devices that do not require this function, this flag should not be set. |
SC_Q_CLR | When set, means the SCSI adapter driver should clear its transaction queue for this ID/LUN. The transaction containing this flag setting does not require an actual SCSI command in the sc_buf
because it is flushed back to the SCSI device driver with the rest of the transactions for this ID/LUN. However, this transaction must have the SCSI ID field (sc_buf.scsi_command.scsi_id)
and the LUN fields (sc_buf.scsi_command.scsi_cmd.lun
and sc_buf.lun
) filled in with the device's SCSI ID and logical unit number (LUN). This flag is valid only during error recovery of a check condition or command terminated at a command tag queuing device when the SC_DID_NOT_CLR_Q flag is set in the sc_buf.adap_q_status
field.
Note: When addressing LUN's 8 - 31, be sure to see the description of the sc_buf.lun field within the sc_buf structure. |
SC_Q_RESUME | When set, means that the SCSI adapter driver should resume its halted transaction queue for this ID/LUN. The transaction containing this flag setting does not require an actual SCSI command to be sent to the SCSI adapter driver. However, this transaction must have the sc_buf.scsi_command.scsi_id
and sc_buf.scsi_command.scsi_cmd.lun
fields filled in with the device's SCSI ID and logical unit number. If the transaction containing this flag setting is the first issued by the SCSI device driver after it receives an error (indicating that the adapter driver's queue is halted), then the SC_RESUME flag must be set also.
Note: When addressing LUN's 8 - 31, be sure to see the description of the sc_buf.lun field within the sc_buf structure. |
Understanding the Execution of Initiator I/O Requests.
Understanding the tm_buf Structure.