1scsi_pkt(9S) Data Structures for Drivers scsi_pkt(9S)
2
6 scsi_pkt - SCSI packet structure
7
9 #include <sys/scsi/scsi.h>
10
13 Solaris DDI specific (Solaris DDI).
14
16 A scsi_pkt structure defines the packet that is allocated by
17 scsi_init_pkt(9F). The target driver fills in some information and
18 passes it to scsi_transport(9F) for execution on the target. The host
19 bus adapter (HBA) fills in other information as the command is pro‐
20 cessed. When the command completes or can be taken no further, the com‐
21 pletion function specified in the packet is called with a pointer to
22 the packet as its argument. From fields within the packet, the target
23 driver can determine the success or failure of the command.
24
26 opaque_t pkt_ha_private; /* private data for
27 host adapter */
28 struct scsi_address pkt_address; /* destination packet */
29 opaque_t pkt_private; /* private data
30 for target driver */
31 void (*pkt_comp)(struct scsi_pkt *); /* callback */
32 uint_t pkt_flags; /* flags */
33 int pkt_time; /* time allotted to
34 complete command */
35 uchar_t *pkt_scbp; /* pointer to
36 status block */
37 uchar_t *pkt_cdbp; /* pointer to
38 command block */
39 ssize_t pkt_resid; /* number of bytes
40 not transferred */
41 uint_t pkt_state; /* state of command */
42 uint_t pkt_statistics; /* statistics */
43 uchar_t pkt_reason; /* reason completion
44 called */
45 uint_t pkt_cdblen; /* length of pkt_cdbp */
46 uint_t pkt_scdblen; /* length of pkt_scbp */
47 uint_t pkt_tgtlen; /* length of pkt_private */
48 uint_t pkt_numcookies; /* number of DMA cookies */
49 ddi_dma_cookie_t *pkt_cookies; /* array of DMA cookies */
50 uint_t pkt_dma_flags; /* DMA flags */
51 pkt_ha_private Opaque pointer that the HBA uses to reference a pri‐
54 vate data structure that transfers scsi_pkt requests.
55 pkt_address Initialized by scsi_init_pkt(9F), pkt_address records
58 the intended route and the recipient of a request.
59 pkt_private Reserved for the use of the target driver, pkt_pri‐
62 vate is not changed by the HBA driver.
63 pkt_comp Specifies the command completion callback routine.
66 When the host adapter driver has gone as far as it
67 can in transporting a command to a SCSI target, and
68 the command has either run to completion or can go no
69 further for some other reason, the host adapter
70 driver calls the function pointed to by this field
71 and passes a pointer to the packet as argument. The
72 callback routine itself is called from interrupt con‐
73 text and must not sleep or call any function that
74 might sleep.
75 pkt_flags Provides additional information about how the target
78 driver expects the command to be executed. See
79 pkt_flag Definitions.
80 pkt_time Set by the target driver to represent the maximum
83 time allowed in seconds for this command to complete.
84 Timeout starts when the command is transmitted on the
85 SCSI bus. The pkt_time may be 0 if no timeout is
86 required.
87 pkt_scbp Points to either a struct scsi_status(9S) or, if
90 auto-rqsense is enabled and pkt_state includes
91 STATE_ARQ_DONE, a struct scsi_arq_status. If
92 scsi_status is returned, the SCSI status byte result‐
93 ing from the requested command is available. If
94 scsi_arq_status(9S) is returned, the sense informa‐
95 tion is also available.
96 pkt_cdbp Points to a kernel-addressable buffer with a length
99 specified by a call to the proper resource allocation
100 routine, scsi_init_pkt(9F).
101 pkt_resid Contains a residual count, either the number of data
104 bytes that have not been transferred (scsi_trans‐
105 port(9F)) or the number of data bytes for which DMA
106 resources could not be allocated scsi_init_pkt(9F).
107 In the latter case, partial DMA resources can be
108 allocated only if scsi_init_pkt(9F) is called with
109 the PKT_DMA_PARTIAL flag.
110 pkt_state Has bit positions that represent the six most impor‐
113 tant states that a SCSI command can go through. See
114 pkt_state Definitions.
115 pkt_statistics Maintains some transport-related statistics. See
118 pkt_statistics Definitions.
119 pkt_reason Contains a completion code that indicates why the
122 pkt_comp function was called. See pkt_reason Defini‐
123 tions.
124 pkt_cdblen Length of buffer pointed to by pkt_cdbp. See
127 tran_setup_pkt.
128 pkt_scblen Length of buffer pointed to by pkt_scbp. See
131 tran_setup_pkt.
132 pkt_tgtlen Length of buffer pointed to by pkt_private. See
135 tran_setup_pkt.
136 pkt_numcookies Length pkt_cookies array. See tran_setup_pkt.
139 pkt_cookies Array of DMA cookies. See tran_setup_pkt.
142 pkt_dma_flags DMA flags used, such as DDI_DMA_READ and
145 DDI_DMA_WRITE. See tran_setup_pkt.
146 The host adapter driver will update the pkt_resid, pkt_reason,
150 pkt_state, and pkt_statistics fields.
151 pkt_flags Definitions
153 The appropriate definitions for the structure member pkt_flags are:
154 FLAG_NOINTR Run command with no command completion
156 callback. Command is complete upon return
157 from scsi_transport(9F).
158 FLAG_NODISCON Run command without disconnects.
161 FLAG_NOPARITY Run command without parity checking.
164 FLAG_HTAG Run command as the head-of-queue-tagged
167 command.
168 FLAG_OTAG Run command as an ordered-queue-tagged
171 command.
172 FLAG_STAG Run command as a simple-queue-tagged com‐
175 mand.
176 FLAG_SENSING Indicates a request sense command.
179 FLAG_HEAD Place command at the head of the queue.
182 FLAG_RENEGOTIATE_WIDE_SYNC Before transporting this command, the
185 host adapter should initiate the renego‐
186 tiation of wide mode and synchronous
187 transfer speed. Normally, the HBA driver
188 manages negotiations but under certain
189 conditions forcing a renegotiation is
190 appropriate. Renegotiation is recommended
191 before Request Sense and Inquiry com‐
192 mands. Refer to the SCSI 2 standard, sec‐
193 tions 6.6.21 and 6.6.23.
194 This flag should not be set for every
196 packet as this will severely impact per‐
197 formance.
198 pkt_reason Definitions
201 The appropriate definitions for the structure member pkt_reason are:
202 CMD_CMPLT No transport errors; normal completion.
204 CMD_INCOMPLETE Transport stopped with abnormal state.
207 CMD_DMA_DERR DMAd irection error.
210 CMD_TRAN_ERR Unspecified transport error.
213 CMD_RESET SCSI bus reset destroyed command.
216 CMD_ABORTED Command transport aborted on request.
219 CMD_TIMEOUT Command timed out.
222 CMD_DATA_OVR Data overrun.
225 CMD_CMD_OVR Command overrun.
228 CMD_STS_OVR Status overrun.
231 CMD_BADMSG Message not command complete.
234 CMD_NOMSGOUT Target refused to go to message out phase.
237 CMD_XID_FAIL Extended identify message rejected.
240 CMD_IDE_FAIL "Initiator Detected Error" message rejected.
243 CMD_ABORT_FAIL Abort message rejected.
246 CMD_REJECT_FAIL Reject message rejected.
249 CMD_NOP_FAIL "No Operation" message rejected.
252 CMD_PER_FAIL "Message Parity Error" message rejected.
255 CMD_BDR_FAIL "Bus Device Reset" message rejected.
258 CMD_ID_FAIL Identify message rejected.
261 CMD_UNX_BUS_FREE Unexpected bus free phase.
264 CMD_TAG_REJECT Target rejected the tag message.
267 CMD_DEV_GONE The device has been removed.
270 pkt_state Definitions
273 The appropriate definitions for the structure member pkt_state are:
274 STATE_GOT_BUS Bus arbitration succeeded.
276 STATE_GOT_TARGET Target successfully selected.
279 STATE_SENT_CMD Command successfully sent.
282 STATE_XFERRED_DATA Data transfer took place.
285 STATE_GOT_STATUS Status received.
288 STATE_ARQ_DONE The command resulted in a check condition and the
291 host adapter driver executed an automatic request
292 sense command.
293 STATE_XARQ_DONE The command requested in extra sense data using a
296 PKT_XARQ flag got a check condition. The host
297 adapter driver was able to successfully request
298 and return this. The
299 scsi_pkt.pkt_scbp->sts_rqpkt_resid returns the
300 sense data residual based on the statuslen param‐
301 eter of the scsi_init_pkt(9F) call. The sense
302 data begins at scsi_pkt.pkt_scbp->sts_sensedata.
303 pkt_statistics Definitions
306 The definitions that are appropriate for the structure member pkt_sta‐
307 tistics are:
308 STAT_DISCON Device disconnect.
310 STAT_SYNC Command did a synchronous data transfer.
313 STAT_PERR SCSI parity error.
316 STAT_BUS_RESET Bus reset.
319 STAT_DEV_RESET Device reset.
322 STAT_ABORTED Command was aborted.
325 STAT_TIMEOUT Command timed out.
328
331 tran_init_pkt(9E), tran_setup_pkt(9E), scsi_arq_status(9S),
332 scsi_init_pkt(9F), scsi_transport(9F), scsi_status(9S),
333 scsi_hba_pkt_comp(9F)
334 Writing Device Drivers
337
339 HBA drivers should signal scsi_pkt completion by calling
340 scsi_hba_pkt_comp(9F). This is mandatory for HBA drivers that implement
341 tran_setup_pkt(9E). Failure to comply results in undefined behavior.
342SunOS 5.11 11 Jan 2009 scsi_pkt(9S)