scsi_pkt(9S) Data Structures for Drivers scsi_pkt(9S)
NAME
scsi_pkt - SCSI packet structure
SYNOPSIS
#include <sys/scsi/scsi.h>
INTERFACE LEVEL
Solaris DDI specific (Solaris DDI).
DESCRIPTION
A scsi_pkt structure defines the packet that is allocated by scsi_init_pkt(9F). The target driver fills in some information, and passes it
to scsi_transport(9F) for execution on the target. The host bus adapter (HBA) fills in some other information as the command is processed.
When the command completes (or can be taken no further) the completion function specified in the packet is called, with a pointer to the
packet as its argument. From fields within the packet, the target driver can determine the success or failure of the command.
STRUCTURE MEMBERS
opaque_t pkt_ha_private;
/* private data for host adapter */
struct scsi_address pkt_address;
/* destination packet */
opaque_t pkt_private;
/* private data for target driver */
void (*pkt_comp)(struct scsi_pkt *);
/* callback */
uint_t pkt_flags;
/* flags */
int pkt_time;
/* time allotted to complete command */
uchar_t *pkt_scbp;
/* pointer to status block */
uchar_t *pkt_cdbp;
/* pointer to command block */
ssize_t pkt_resid;
/* number of bytes not transferred */
uint_t pkt_state;
/* state of command */
uint_t pkt_statistics;
/* statistics */
uchar_t pkt_reason;
/* reason completion called */
pkt_ha_private An opaque pointer that the Host Bus Adapter uses to reference a private data structure used to transfer scsi_pkt
requests.
pkt_address Initialized by scsi_init_pkt(9F); pkt_address records the intended route and recipient of a request.
pkt_private Reserved for the use of the target driver; pkt_private is not changed by the HBA driver.
pkt_comp Specifies the command completion callback routine. When the host adapter driver has gone as far as it can in trans-
porting a command to a SCSI target, and the command has either run to completion or can go no further for some
other reason, the host adapter driver will call the function pointed to by this field and pass a pointer to the
packet as argument. The callback routine itself is called from interrupt context and must not sleep or call any
function that might sleep.
pkt_flags Provides additional information about how the target driver expects the command to be executed. See pkt_flag Defi-
nitions.
pkt_time Will be set by the target driver to represent the maximum time in seconds that this command is allowed to take to
complete. Timeout starts when the command is transmitted on the SCSI bus. pkt_time may be 0 if no timeout is
required.
pkt_scbp Points to either a struct scsi_status(9S) or, if auto-rqsense is enabled, and pkt_state includes STATE_ARQ_DONE, a
struct scsi_arq_status. If scsi_status is returned, the SCSI status byte resulting from the requested command is
available; if scsi_arq_status(9S) is returned, the sense information is also available.
pkt_cdbp Points to a kernel-addressable buffer whose length was specified by a call to the proper resource allocation rou-
tine, scsi_init_pkt(9F).
pkt_resid Contains a residual count, either the number of data bytes that have not been transferred ( scsi_transport(9F)) or
the number of data bytes for which DMA resources could not be allocated scsi_init_pkt(9F). In the latter case, par-
tial DMA resources may only be allocated if scsi_init_pkt(9F) is called with the PKT_DMA_PARTIAL flag.
pkt_state Has bit positions that represent the six most important states that a SCSI command can go through (see pkt_state
Definitions).
pkt_statistics Maintains some transport-related statistics. (see pkt_statistics Definitions).
pkt_reason Contains a completion code that indicates why the pkt_comp function was called. See pkt_reason Definitions, below.
The host adapter driver will update the pkt_resid, pkt_reason, pkt_state, and pkt_statistics fields.
pkt_flags Definitions:
The appropriate definitions for the structure member pkt_flags are:
FLAG_NOINTR
Run command with no command completion callback; command is complete upon return from scsi_transport(9F).
FLAG_NODISCON
Run command without disconnects.
FLAG_NOPARITY
Run command without parity checking.
FLAG_HTAG
Run command as the head-of-queue-tagged command.
FLAG_OTAG
Run command as an ordered-queue-tagged command.
FLAG_STAG
Run command as a simple-queue --tagged command.
FLAG_SENSING
Indicates command is a request sense command.
FLAG_HEAD
Place command at the head of the queue.
FLAG_RENEGOTIATE_WIDE_SYNC
Before transporting this command, the host adapter should initiate the renegotiation of wide mode and synchronous transfer speed. Nor-
mally the HBA driver manages negotiations but under certain conditions forcing a renegotiation is appropriate. Renegotiation is recom-
mended before Request Sense and Inquiry commands. (Refer to the SCSI 2 standard, sections 6.6.21 and 6.6.23.) This flag should not be
set for every packet as this will severely impact performance.
pkt_reason Definitions:
The appropriate definitions for the structure member pkt_reason are:
CMD_CMPLT No transport errors; normal completion.
CMD_INCOMPLETE Transport stopped with abnormal state.
CMD_DMA_DERR DMA direction error.
CMD_TRAN_ERR Unspecified transport error.
CMD_RESET SCSI bus reset destroyed command.
CMD_ABORTED Command transport aborted on request.
CMD_TIMEOUT Command timed out.
CMD_DATA_OVR Data overrun.
CMD_CMD_OVR Command overrun.
CMD_STS_OVR Status overrun.
CMD_BADMSG Message not command complete.
CMD_NOMSGOUT Target refused to go to message out phase.
CMD_XID_FAIL Extended identify message rejected.
CMD_IDE_FAIL "Initiator Detected Error" message rejected.
CMD_ABORT_FAIL Abort message rejected.
CMD_REJECT_FAIL Reject message rejected.
CMD_NOP_FAIL "No Operation" message rejected.
CMD_PER_FAIL "Message Parity Error" message rejected.
CMD_BDR_FAIL "Bus Device Reset" message rejected.
CMD_ID_FAIL Identify message rejected.
CMD_UNX_BUS_FREE Unexpected bus free phase.
CMD_TAG_REJECT Target rejected the tag message.
CMD_DEV_GONE The device has been removed.
pkt_state Definitions:
The appropriate definitions for the structure member pkt_state are:
STATE_GOT_BUS Bus arbitration succeeded.
STATE_GOT_TARGET Target successfully selected.
STATE_SENT_CMD Command successfully sent.
STATE_XFERRED_DATA Data transfer took place.
STATE_GOT_STATUS Status received.
STATE_ARQ_DONE The command resulted in a check condition and the host adapter driver executed an automatic request sense command.
pkt_statistics Definitions:
The definitions that are appropriate for the structure member pkt_statistics are:
STAT_DISCON Device disconnect.
STAT_SYNC Command did a synchronous data transfer.
STAT_PERR SCSI parity error.
STAT_BUS_RESET Bus reset.
STAT_DEV_RESET Device reset.
STAT_ABORTED Command was aborted.
STAT_TIMEOUT Command timed out.
SEE ALSO
tran_init_pkt(9E), scsi_arq_status(9S), scsi_init_pkt(9F), scsi_transport(9F), scsi_status(9S)
Writing Device Drivers
SunOS 5.10 30 June 2004 scsi_pkt(9S)