.\" Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
.\" Copyright 2022 Garrett D'Amore
.\" 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]
.Dd June 21, 2022
.Dt SCSI_PKT 9S
.Os
.Sh NAME
.Nm scsi_pkt
.Nd SCSI packet structure
.Sh SYNOPSIS
.In sys/scsi/scsi.h
.Sh INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.Sh DESCRIPTION
A
.Nm
structure defines the packet that is allocated by
.Xr scsi_init_pkt 9F .
The target driver fills in some information and passes it to
.Xr scsi_transport 9F
for execution on the target.
The host bus adapter
.Pq HBA
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
.Bd -literal -offset indent
opaque_t             pkt_ha_private;
struct scsi_address  pkt_address;
opaque_t             pkt_private;
void                 (*pkt_comp)(struct scsi_pkt *);
uint_t               pkt_flags;
int                  pkt_time;
uchar_t              *pkt_scbp;
uchar_t              *pkt_cdbp;
ssize_t              pkt_resid;
uint_t               pkt_state;
uint_t               pkt_statistics;
uchar_t              pkt_reason;
uint_t               pkt_cdblen;
uint_t               pkt_scblen;
uint_t               pkt_tgtlen;
uint_t               pkt_numcookies;
ddi_dma_cookie_t     *pkt_cookies;
uint_t               pkt_dma_flags;
.Ed
.Pp
These members are described here:
.Bl -tag -width indent
.It Fa pkt_ha_private
Opaque pointer that the HBA uses to reference a private data structure that
transfers
.Nm
requests.
.It Fa pkt_address
Initialized by
.Xr scsi_init_pkt 9F ,
.Fa pkt_address
records the intended route and the recipient of a request.
.It Fa pkt_private
Reserved for the use of the target driver,
.Fa pkt_private
is not changed by the HBA driver.
.It Fa pkt_comp
Specifies the command completion callback routine.
When the host adapter driver has gone as far as it can in transporting 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 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.
.It Fa pkt_flags
Provides additional information about how the target driver expects the command
to be executed.
See
.Sx pkt_flags Definitions .
.It Fa pkt_time
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 SCSI bus.
The
.Fa pkt_time
may be zero if no timeout is required.
.It Fa pkt_scbp
Points to either a struct
.Xr scsi_status 9S
or, if
.Fa auto-rqsense
is enabled and
.Fa pkt_state
includes
.Dv STATE_ARQ_DONE ,
a struct
.Xr scsi_arq_status 9S .
If
.Xr scsi_status 9S
is returned, the SCSI status byte resulting from the requested command is
available.
If
.Xr scsi_arq_status 9S
is returned, the sense information is also available.
.It Fa pkt_cdbp
Points to a kernel-addressable buffer with a length specified by a call to the
proper resource allocation routine,
.Xr scsi_init_pkt 9F .
.It Fa pkt_resid
Contains a residual count, either the number of data bytes that have not been
transferred by
.Xr scsi_transport 9F
or the number of data bytes for which
DMA resources could not be allocated by
.Xr scsi_init_pkt 9F .
In the latter case, partial DMA resources can be allocated only if
.Xr scsi_init_pkt 9F
is called with the
.Dv PKT_DMA_PARTIAL
flag.
.It Fa pkt_state
Has bit positions that represent the six most important states that a
SCSI command can go through.
See
.Sx pkt_state Definitions .
.It Fa pkt_statistics
Maintains some transport-related statistics.
See
.Sx pkt_statistics Definitions .
.It Fa pkt_reason
Contains a completion code that indicates why the
.Fa pkt_comp
function was called.
See
.Sx pkt_reason Definitions .
.It Fa pkt_cdblen
Length of buffer pointed to by
.Fa pkt_cdbp .
Se
.Xr  tran_setup_pkt 9E .
.It Fa pkt_scblen
Length of buffer pointed to by
.Fa pkt_scbp .
See
.Xr tran_setup_pkt 9E .
.It Fa pkt_tgtlen
Length of buffer pointed to by
.Fa pkt_private .
See
.Xr tran_setup_pkt 9E .
.It Fa pkt_numcookies
Length of
.Fa pkt_cookies
array.
See
.Xr tran_setup_pkt 9E .
.It Fa pkt_cookies
Array of DMA cookies.
See
.Xr tran_setup_pkt 9E .
.It Fa pkt_dma_flags
DMA flags used, such as
.Dv DDI_DMA_READ
and
.Dv DDI_DMA_WRITE .
See
.Xr tran_setup_pkt 9E .
.El
.Pp
The host adapter driver will update the
.Fa pkt_resid ,
.Fa pkt_reason ,
.Fa pkt_state ,
and
.Fa pkt_statistics
fields.
.Ss "pkt_flags Definitions"
The appropriate definitions for the structure member
.Fa pkt_flags
are:
.Bl -tag -width indent
.It Dv FLAG_NOINTR
Run command with no command completion callback.
Command is complete upon return from
.Xr scsi_transport 9F .
.It Dv FLAG_NODISCON
Run command without disconnects.
.It Dv FLAG_NOPARITY
Run command without parity checking.
.It Dv FLAG_HTAG
Run command as the head-of-queue-tagged command.
.It Dv FLAG_OTAG
Run command as an ordered-queue-tagged command.
.It Dv FLAG_STAG
Run command as a simple-queue-tagged command.
.It Dv FLAG_SENSING
Indicates a request sense command.
.It Dv FLAG_HEAD
Place command at the head of the queue.
.It Dv FLAG_RENEGOTIATE_WIDE_SYNC
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
.Ql "Request Sense"
and
.Ql Inquiry
commands.
Refer to the SCSI 2 standard, sections 6.6.21 and 6.6.23.
.Pp
This flag should not be set for every packet as this will severely impact
performance.
.El
.Ss "pkt_reason Definitions"
The appropriate definitions for the structure member
.Fa pkt_reason
are:
.Bl -tag -width indent
.It Dv CMD_CMPLT
No transport errors; normal completion.
.It Dv CMD_INCOMPLETE
Transport stopped with abnormal state.
.It Dv CMD_DMA_DERR
DMA direction error.
.It Dv CMD_TRAN_ERR
Unspecified transport error.
.It Dv CMD_RESET
SCSI bus reset destroyed command.
.It Dv CMD_ABORTED
Command transport aborted on request.
.It Dv CMD_TIMEOUT
Command timed out.
.It Dv CMD_DATA_OVR
Data overrun.
.It Dv CMD_CMD_OVR
Command overrun.
.It Dv CMD_STS_OVR
Status overrun.
.It Dv CMD_BADMSG
Message not command complete.
.It Dv CMD_NOMSGOUT
Target refused to go to message out phase.
.It Dv CMD_XID_FAIL
Extended identify message rejected.
.It Dv CMD_IDE_FAIL
"Initiator Detected Error" message rejected.
.It Dv CMD_ABORT_FAIL
Abort message rejected.
.It Dv CMD_REJECT_FAIL
Reject message rejected.
.It Dv CMD_NOP_FAIL
"No Operation" message rejected.
.It Dv CMD_PER_FAIL
"Message Parity Error" message rejected.
.It Dv CMD_BDR_FAIL
"Bus Device Reset" message rejected.
.It Dv CMD_ID_FAIL
Identify message rejected.
.It Dv CMD_UNX_BUS_FREE
Unexpected bus free phase.
.It Dv CMD_TAG_REJECT
Target rejected the tag message.
.It Dv CMD_DEV_GONE
The device has been removed.
.El
.Ss "pkt_state Definitions"
The appropriate definitions for the structure member
.Fa pkt_state
are:
.Bl -tag -width indent
.It Dv STATE_GOT_BUS
Bus arbitration succeeded.
.It Dv STATE_GOT_TARGET
Target successfully selected.
.It Dv STATE_SENT_CMD
Command successfully sent.
.It Dv STATE_XFERRED_DATA
Data transfer took place.
.It Dv STATE_GOT_STATUS
Status received.
.It Dv STATE_ARQ_DONE
The command resulted in a check condition and the host adapter driver executed
an automatic request sense command.
.It Dv STATE_XARQ_DONE
The command requested in extra sense data using a
.Dv PKT_XARQ
flag got a check condition.
The host adapter driver was able to successfully request and return this.
The
.Sy scsi_pkt.pkt_scbp->sts_rqpkt_resid
returns the sense data residual based on the
.Fa statuslen
parameter of the
.Xr scsi_init_pkt 9F
call.
The sense data begins at
.Sy scsi_pkt.pkt_scbp->sts_sensedata .
.El
.Ss "pkt_statistics Definitions"
The definitions that are appropriate for the structure member
.Fa pkt_statistics
are:
.Bl -tag -width indent
.It Dv STAT_DISCON
Device disconnect.
.It Dv STAT_SYNC
Command did a synchronous data transfer.
.It Dv STAT_PERR
SCSI parity error.
.It Dv STAT_BUS_RESET
Bus reset.
.It Dv STAT_DEV_RESET
Device reset.
.It Dv STAT_ABORTED
Command was aborted.
.It Dv STAT_TIMEOUT
Command timed out.
.El
.Sh SEE ALSO
.Xr tran_init_pkt 9E ,
.Xr tran_setup_pkt 9E ,
.Xr scsi_hba_pkt_comp 9F ,
.Xr scsi_init_pkt 9F ,
.Xr scsi_transport 9F ,
.Xr scsi_arq_status 9S ,
.Xr scsi_status 9S
.Pp
.Rs
.%T "Writing Device Drivers"
.Re
.Sh NOTES
HBA drivers should signal
.Nm
completion by calling
.Xr scsi_hba_pkt_comp 9F .
This is mandatory for HBA drivers that implement
.Xr tran_setup_pkt 9E .
Failure to comply results in undefined behavior.
.Pp
Drivers must not make assumptions about the size of the
.Nm
structure.
In particular, this structure must not be directly
inlined into other driver structures nor allocated
except by one of the specialized allocation functions
such as
.Xr scsi_init_pkt 9F .