Execute SCSI I/O Command
Prototype: DWORD SendASPI32Command(lpSRB)
Declaration: LPSRB lpSRB;
The SendASPI32Command function with command code SC_EXEC_SCSI_CMD is used to execute a SCSI I/O command. Once an ASPI client has initialized, virtually all I/O is performed with this command.
| Parameter |
Description |
| lpSRB |
Points to the following SCSI request block |
typedef struct {
BYTE SRB_Cmd; // ASPI command code = SC_EXEC_SCSI_CMD
BYTE SRB_Status; // ASPI command status byte
BYTE SRB_HaId; // ASPI host adapter number
BYTE SRB_Flags; // ASPI request flags
DWORD SRB_Hdr_Rsvd; // Reserved
BYTE SRB_Target; // Target's SCSI ID
BYTE SRB_Lun; // Target's LUN number
WORD SRB_Rsvd1; // Reserved for Alignment
DWORD SRB_BufLen; // Data Allocation Length
BYTE *SRB_BufPointer; // Data Buffer Point
BYTE SRB_SenseLen; // Sense Allocation Length
BYTE SRB_CDBLen; // CDB Length
BYTE SRB_HaStat; // Host Adapter Status
BYTE SRB_TargStat; // Target Status
void (*SRB_PostProc)(); // Post routine
void *SRB_Rsvd2; // Reserved
BYTE SRB_Rsvd3[16]; // Reserved for expansion
BYTE CDBByte[16]; // SCSI CDB
BYTE SenseArea[SENSE_LEN+2]; // Request Sense buffer
} SRB_ExecSCSICmd, *PSRB_ExecSCSICmd;
Table 4-6. Execute SCSI I/O Command
| Member |
Description |
| SRB_Cmd |
[IN] This field must contain SC_EXEC_SCSI_CMD. |
| SRB_Status |
[OUT]This field returns one of the following statuses: |
| SS_PENDING |
SCSI request is in progress. |
| SS_COMP |
SCSI/ASPI request has completed without error. |
| SS_ABORTED |
SCSI command has been aborted. |
| SS_ABORT_FAIL |
SCSI command abort failed. |
| SS_ERR |
SCSI command completed with an error. |
| SS_INVALID_SRB |
One or more parameters in the SCSI Request Block (SRB) are set incorrectly. |
| SS_INVALID_PATH_ID |
SCSI ID and LUN are invalid. |
| SS_BUFFER_TO_BIG |
The ASPI manager cannot handle the given transfer size. |
| SS_BUFFER_ALIGN |
The ASPI manager cannot handle the alignment on this buffer. You must force the buffer into the alignment specified by the alignment mask returned as part of the SC_HA_INQUIRY command. |
| SS_SECURITY_VIOLATION |
The application does not have the security privileges needed to perform the operation for the device. |
| SRB_HaId |
[IN] This field specifies which installed host adapter the request is intended for. Host adapter numbers are always assigned by the SCSI manager layer beginning with zero. |
| SRB_Flags |
[IN] The SRB flags field is defined as follows: |
| SRB_DIR_IN |
Data transfer from SCSI target to host. Mutually exclusive with SRB_DIR_OUT. |
| SRB_DIR_OUT |
Transfer from host to SCSI target. Mutually exclusive with SRB_DIR_IN. |
| SRB_EVENT_NOTIFY |
Enable ASPI command event notification. This flag and the SRB_POSTING flag are mutually exclusive. |
| SRB_POSTING |
Enable ASPI command completion posting. This flag and the SRB_EVENT_NOTIFY flag are mutually exclusive. |
| SRB_ENABLE_RESIDUAL COUNT |
Enables reporting of residual byte count. This bit is only significant if the host adapter reports support for residual byte count from the SC_HA_INQUIRY command. Whenever a data underrun occurs, the SRB_BufLen field is updated to reflect the remaining bytes to transfer. |
| SRB_Hdr_Rsvd |
Reserved = 0 |
| SRB_Target |
[IN] SCSI ID of target device. |
| SRB_Lun |
[IN] Logical Unit Number (LUN) of device. |
| SRB_BufLen |
[IN] This field indicates the number of bytes to be transferred. If the SCSI command to be executed does not transfer data (for example, Test Unit Ready, Rewind, etc.), this field must be set to zero. If residual byte length is supported and selected, this field is returned with the residual number of bytes (usually 0). |
| SRB_BufPointer |
[IN] This field is a pointer to the data buffer. |
| SRB_SenseLen |
[IN] This field indicates the number of bytes allocated at the end of the SRB for sense data. A request sense is automatically generated if a check condition is presented at the end of a SCSI command. |
| SRB_CDBLen |
[IN] This field establishes the length, in bytes, of the SCSI Command Descriptor Block (CDB). This value is typically 6 or 10. |
| SRB_HaStat |
[OUT] Upon completion of the SCSI command, the ASPI manager sets this field with the host adapter status as follows: |
| HASTAT_OK |
Host adapter did not detect an error. |
| HASTAT_TIMEOUT |
The time allocated for the transaction ran out. |
| HASTAT_COMMAND_TIMEOUT |
SRB expired while waiting to be processed. |
| HASTAT_SEL_TO |
Selection of target timed out. |
| HASTAT_MESSAGE_REJECT |
While processing SRB, the adapter received a MESSAGE REJECT. |
| HASTAT_BUS_RESET |
A bus reset was detected. |
| HASTAT_PARITY_ERROR |
A parity error was detected. |
| HASTAT_REQUEST_SENSE_FAILED |
The adapter failed in issuing a Request Sense after a check condition was reported by the target device. |
| HASTAT_DO_DU |
Data overrun/underrun. |
| HASTAT_BUS_FREE |
Unexpected Bus Free. |
| HASTAT_PHASE_ERR |
Target Bus phase sequence failure. |
| SRB_TargStat |
[OUT] Upon completion of the SCSI command, the ASPI manager will record the specific status returned by the SCSI target: |
| STATUS_GOOD |
No target status. |
| STATUS_CHKCOND |
Check status (sense data is in SenseArea). |
| STATUS_BUSY |
Specified Target/LUN is busy. |
| STATUS_RESCONF |
Reservation conflict. |
| SRB_PostProc |
[IN] If posting is enabled (SRB_POSTING flag), this field contains a pointer to a function. ASPI for Win32 calls this function upon completion of an ASPI request. If event notification is enabled (SRB_EVENT_NOTIFY flag), this field contains a handle to an event. ASPI for Win32 signals this event upon completion of an ASPI request. |
| CDBByte[..] |
[IN] This field contains the CDB as defined by the target's SCSI command set. The length of the SCSI CDB is specified in the SRB_CDBLen field. |
| SenseArea[..] |
[OUT] The SenseArea is filled with the sense data on a check condition. The maximum length of this field is specified in the SRB_SenseLen field. Note that the target can return fewer than the number of sense bytes requested. |
Table 4-7. Return Values from Execute SCSI I/O Command
| Value |
Meaning |
| SS_PENDING |
SCSI request is in progress. |
Example
This example sends a SCSI Inquiry command to host adapter #0, target #0, LUN #0.
SRB_ExecSCSICmd MySRB;
DWORD ASPIStatus;
char InquiryBuffer[32];
.
.
.
MySRB.SRB_Header = SC_EXEC_SCSI_CMD;
MySRB.SRB_HaId = 0;
MySRB.SRB_Flags = SRB_DIR_IN | SRB_POSTING;
MySRB.SRB_Hdr_Rsvd = 0;
MySRB.SRB_Target = 0;
MySRB.SRB_Lun = 0;
MySRB.SRB_BufLen = 32;
MySRB.SRB_SenseLen = SENSE_LEN;
MySRB.SRB_BufPointer = InquiryBuffer;
MySRB.SRB_CDBLen = 6;
MySRB.RB_PostProc = PostProcedure;
MySRB.CDBByte[0] = SCSI_INQUIRY;
MySRB.CDBByte[1] = 0;
MySRB.CDBByte[2] = 0;
MySRB.CDBByte[3] = 0;
MySRB.CDBByte[4] = 32;
MySRB.CDBByte[5] = 0;
.
/***************************************************/
/* Make sure all other reserved fields are zeroed
/* before passing the SRB to ASPI for Win32
/***************************************************/
.
ASPIStatus = SendASPI32Command ( (LPSRB) &MySRB );
.
.