'\" te
.\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH SCSI_PKT 9S "Jan 11, 2009"
.SH NAME
scsi_pkt \- SCSI packet structure
.SH SYNOPSIS
.nf
#include <sys/scsi/scsi.h>
.fi

.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH DESCRIPTION
A \fBscsi_pkt\fR structure defines the packet that is allocated by
\fBscsi_init_pkt\fR(9F). The target driver fills in some information and passes
it to \fBscsi_transport\fR(9F) for execution on the target. The host bus
adapter (\fBHBA\fR) fills in 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.
.SH STRUCTURE MEMBERS
.in +2
.nf
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 */
uint_t               pkt_cdblen;               /* length of pkt_cdbp */
uint_t               pkt_scdblen;              /* length of pkt_scbp */
uint_t               pkt_tgtlen;               /* length of pkt_private */
uint_t               pkt_numcookies;           /* number of DMA cookies */
ddi_dma_cookie_t     *pkt_cookies;             /* array of DMA cookies */
uint_t               pkt_dma_flags;            /* DMA flags */
.fi
.in -2

.sp
.ne 2
.na
\fB\fBpkt_ha_private\fR\fR
.ad
.RS 18n
Opaque pointer that the HBA uses to reference a private data structure that
transfers \fBscsi_pkt\fR requests.
.RE

.sp
.ne 2
.na
\fB\fBpkt_address\fR\fR
.ad
.RS 18n
Initialized by \fBscsi_init_pkt\fR(9F), \fBpkt_address\fR records the intended
route and the recipient of a request.
.RE

.sp
.ne 2
.na
\fB\fBpkt_private\fR\fR
.ad
.RS 18n
Reserved for the use of the target driver, \fBpkt_private\fR is not changed by
the HBA driver.
.RE

.sp
.ne 2
.na
\fB\fBpkt_comp\fR\fR
.ad
.RS 18n
Specifies the command completion callback routine. When the host adapter driver
has gone as far as it can in transporting a command to a \fBSCSI\fR target, and
the command has either run to completion or can go no further for some other
reason, the host adapter driver calls the function pointed to by this field and
passes 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.
.RE

.sp
.ne 2
.na
\fB\fBpkt_flags\fR\fR
.ad
.RS 18n
Provides additional information about how the target driver expects the command
to be executed. See \fBpkt_flag Definitions\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_time\fR\fR
.ad
.RS 18n
Set by the target driver to represent the maximum time allowed in seconds for
this command to complete. Timeout starts when the command is transmitted on the
\fBSCSI\fR bus. The \fBpkt_time\fR may be \fB0\fR if no timeout is required.
.RE

.sp
.ne 2
.na
\fB\fBpkt_scbp\fR\fR
.ad
.RS 18n
Points to either a struct \fBscsi_status\fR(9S) or, if \fBauto-rqsense\fR is
enabled and \fBpkt_state\fR includes \fBSTATE_ARQ_DONE\fR, a struct
\fBscsi_arq_status\fR. If \fBscsi_status\fR is returned, the \fBSCSI\fR status
byte resulting from the requested command is available. If
\fBscsi_arq_status\fR(9S) is returned, the sense information is also available.
.RE

.sp
.ne 2
.na
\fB\fBpkt_cdbp\fR\fR
.ad
.RS 18n
Points to a kernel-addressable buffer with a length specified by a call to the
proper resource allocation routine, \fBscsi_init_pkt\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fBpkt_resid\fR\fR
.ad
.RS 18n
Contains a residual count, either the number of data bytes that have not been
transferred (\fBscsi_transport\fR(9F)) or the number of data bytes for which
DMA resources could not be allocated \fBscsi_init_pkt\fR(9F). In the latter
case, partial DMA resources can be allocated only if \fBscsi_init_pkt\fR(9F) is
called with the \fBPKT_DMA_PARTIAL\fR flag.
.RE

.sp
.ne 2
.na
\fB\fBpkt_state\fR\fR
.ad
.RS 18n
Has bit positions that represent the six most important states that a
\fBSCSI\fR command can go through. See \fBpkt_state Definitions\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_statistics\fR\fR
.ad
.RS 18n
Maintains some transport-related statistics. See \fBpkt_statistics
Definitions\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_reason\fR\fR
.ad
.RS 18n
Contains a completion code that indicates why the \fBpkt_comp\fR function was
called. See \fBpkt_reason Definitions\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_cdblen\fR\fR
.ad
.RS 18n
Length of buffer pointed to by \fBpkt_cdbp\fR. See \fBtran_setup_pkt\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_scblen\fR\fR
.ad
.RS 18n
Length of buffer pointed to by \fBpkt_scbp\fR. See \fBtran_setup_pkt\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_tgtlen\fR\fR
.ad
.RS 18n
Length of buffer pointed to by \fBpkt_private\fR. See \fBtran_setup_pkt\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_numcookies\fR\fR
.ad
.RS 18n
Length \fBpkt_cookies\fR array. See \fBtran_setup_pkt\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_cookies\fR\fR
.ad
.RS 18n
Array of DMA cookies. See \fBtran_setup_pkt\fR.
.RE

.sp
.ne 2
.na
\fB\fBpkt_dma_flags\fR\fR
.ad
.RS 18n
DMA flags used, such as \fBDDI_DMA_READ\fR and \fBDDI_DMA_WRITE\fR. See
\fBtran_setup_pkt\fR.
.RE

.sp
.LP
The host adapter driver will update the \fBpkt_resid\fR, \fBpkt_reason\fR,
\fBpkt_state\fR, and \fBpkt_statistics\fR fields.
.SS "\fBpkt_flags\fR Definitions"
The appropriate definitions for the structure member \fBpkt_flags\fR are:
.sp
.ne 2
.na
\fB\fBFLAG_NOINTR\fR\fR
.ad
.RS 30n
Run command with no command completion callback. Command is complete upon
return from \fBscsi_transport\fR(9F).
.RE

.sp
.ne 2
.na
\fB\fBFLAG_NODISCON\fR\fR
.ad
.RS 30n
Run command without disconnects.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_NOPARITY\fR\fR
.ad
.RS 30n
Run command without parity checking.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_HTAG\fR\fR
.ad
.RS 30n
Run command as the head-of-queue-tagged command.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_OTAG\fR\fR
.ad
.RS 30n
Run command as an ordered-queue-tagged command.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_STAG\fR\fR
.ad
.RS 30n
Run command as a simple-queue-tagged command.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_SENSING\fR\fR
.ad
.RS 30n
Indicates a request sense command.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_HEAD\fR\fR
.ad
.RS 30n
Place command at the head of the queue.
.RE

.sp
.ne 2
.na
\fB\fBFLAG_RENEGOTIATE_WIDE_SYNC\fR\fR
.ad
.RS 30n
Before transporting this command, the host adapter should initiate the
renegotiation of wide mode and synchronous transfer speed. Normally, the HBA
driver manages negotiations but under certain conditions forcing a
renegotiation is appropriate. Renegotiation is recommended before Request Sense
and Inquiry commands. Refer to the SCSI 2 standard, sections 6.6.21 and 6.6.23.
.sp
This flag should not be set for every packet as this will severely impact
performance.
.RE

.SS "\fBpkt_reason\fR Definitions"
The appropriate definitions for the structure member \fBpkt_reason\fR are:
.sp
.ne 2
.na
\fB\fBCMD_CMPLT\fR\fR
.ad
.RS 20n
No transport errors; normal completion.
.RE

.sp
.ne 2
.na
\fB\fBCMD_INCOMPLETE\fR\fR
.ad
.RS 20n
Transport stopped with abnormal state.
.RE

.sp
.ne 2
.na
\fB\fBCMD_DMA_DERR\fR\fR
.ad
.RS 20n
\fBDMA\fRd irection error.
.RE

.sp
.ne 2
.na
\fB\fBCMD_TRAN_ERR\fR\fR
.ad
.RS 20n
Unspecified transport error.
.RE

.sp
.ne 2
.na
\fB\fBCMD_RESET\fR\fR
.ad
.RS 20n
\fBSCSI\fR bus reset destroyed command.
.RE

.sp
.ne 2
.na
\fB\fBCMD_ABORTED\fR\fR
.ad
.RS 20n
Command transport aborted on request.
.RE

.sp
.ne 2
.na
\fB\fBCMD_TIMEOUT\fR\fR
.ad
.RS 20n
Command timed out.
.RE

.sp
.ne 2
.na
\fB\fBCMD_DATA_OVR\fR\fR
.ad
.RS 20n
Data overrun.
.RE

.sp
.ne 2
.na
\fB\fBCMD_CMD_OVR\fR\fR
.ad
.RS 20n
Command overrun.
.RE

.sp
.ne 2
.na
\fB\fBCMD_STS_OVR\fR\fR
.ad
.RS 20n
Status overrun.
.RE

.sp
.ne 2
.na
\fB\fBCMD_BADMSG\fR\fR
.ad
.RS 20n
Message not command complete.
.RE

.sp
.ne 2
.na
\fB\fBCMD_NOMSGOUT\fR\fR
.ad
.RS 20n
Target refused to go to message out phase.
.RE

.sp
.ne 2
.na
\fB\fBCMD_XID_FAIL\fR\fR
.ad
.RS 20n
Extended identify message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_IDE_FAIL\fR\fR
.ad
.RS 20n
"Initiator Detected Error" message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_ABORT_FAIL\fR\fR
.ad
.RS 20n
Abort message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_REJECT_FAIL\fR\fR
.ad
.RS 20n
Reject message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_NOP_FAIL\fR\fR
.ad
.RS 20n
"No Operation" message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_PER_FAIL\fR\fR
.ad
.RS 20n
"Message Parity Error" message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_BDR_FAIL\fR\fR
.ad
.RS 20n
"Bus Device Reset" message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_ID_FAIL\fR\fR
.ad
.RS 20n
Identify message rejected.
.RE

.sp
.ne 2
.na
\fB\fBCMD_UNX_BUS_FREE\fR\fR
.ad
.RS 20n
Unexpected bus free phase.
.RE

.sp
.ne 2
.na
\fB\fBCMD_TAG_REJECT\fR\fR
.ad
.RS 20n
Target rejected the tag message.
.RE

.sp
.ne 2
.na
\fB\fBCMD_DEV_GONE\fR\fR
.ad
.RS 20n
The device has been removed.
.RE

.SS "pkt_state Definitions"
The appropriate definitions for the structure member \fBpkt_state\fR are:
.sp
.ne 2
.na
\fB\fBSTATE_GOT_BUS\fR\fR
.ad
.RS 22n
Bus arbitration succeeded.
.RE

.sp
.ne 2
.na
\fB\fBSTATE_GOT_TARGET\fR\fR
.ad
.RS 22n
Target successfully selected.
.RE

.sp
.ne 2
.na
\fB\fBSTATE_SENT_CMD\fR\fR
.ad
.RS 22n
Command successfully sent.
.RE

.sp
.ne 2
.na
\fB\fBSTATE_XFERRED_DATA\fR\fR
.ad
.RS 22n
Data transfer took place.
.RE

.sp
.ne 2
.na
\fB\fBSTATE_GOT_STATUS\fR\fR
.ad
.RS 22n
Status received.
.RE

.sp
.ne 2
.na
\fB\fBSTATE_ARQ_DONE\fR\fR
.ad
.RS 22n
The command resulted in a check condition and the host adapter driver executed
an automatic request sense command.
.RE

.sp
.ne 2
.na
\fB\fBSTATE_XARQ_DONE\fR\fR
.ad
.RS 22n
The command requested in extra sense data using a \fBPKT_XARQ\fR flag got a
check condition. The host adapter driver was able to successfully request and
return this. The \fBscsi_pkt.pkt_scbp->sts_rqpkt_resid\fR returns the sense
data residual based on the \fIstatuslen\fR parameter of the
\fBscsi_init_pkt\fR(9F) call. The sense data begins at
\fBscsi_pkt.pkt_scbp->sts_sensedata\fR.
.RE

.SS "pkt_statistics Definitions"
The definitions that are appropriate for the structure member
\fBpkt_statistics\fR are:
.sp
.ne 2
.na
\fB\fBSTAT_DISCON\fR\fR
.ad
.RS 18n
Device disconnect.
.RE

.sp
.ne 2
.na
\fB\fBSTAT_SYNC\fR\fR
.ad
.RS 18n
Command did a synchronous data transfer.
.RE

.sp
.ne 2
.na
\fB\fBSTAT_PERR\fR\fR
.ad
.RS 18n
\fBSCSI\fR parity error.
.RE

.sp
.ne 2
.na
\fB\fBSTAT_BUS_RESET\fR\fR
.ad
.RS 18n
Bus reset.
.RE

.sp
.ne 2
.na
\fB\fBSTAT_DEV_RESET\fR\fR
.ad
.RS 18n
Device reset.
.RE

.sp
.ne 2
.na
\fB\fBSTAT_ABORTED\fR\fR
.ad
.RS 18n
Command was aborted.
.RE

.sp
.ne 2
.na
\fB\fBSTAT_TIMEOUT\fR\fR
.ad
.RS 18n
Command timed out.
.RE

.SH SEE ALSO
\fBtran_init_pkt\fR(9E), \fBtran_setup_pkt\fR(9E), \fBscsi_arq_status\fR(9S),
\fBscsi_init_pkt\fR(9F), \fBscsi_transport\fR(9F), \fBscsi_status\fR(9S),
\fBscsi_hba_pkt_comp\fR(9F)
.sp
.LP
\fIWriting Device Drivers\fR
.SH NOTES
HBA drivers should signal \fBscsi_pkt\fR completion by calling
\fBscsi_hba_pkt_comp\fR(9F). This is mandatory for HBA drivers that implement
\fBtran_setup_pkt\fR(9E). Failure to comply results in undefined behavior.