| blob | 2cf6e7629e6e07836a934dc1ca2ec0f9e1dccdc2 |
1 '\" te
2 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH SCSI_PKT 9S "Jan 11, 2009"
7 .SH NAME
8 scsi_pkt \- SCSI packet structure
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <sys/scsi/scsi.h>
13 .fi
15 .SH INTERFACE LEVEL
16 .sp
17 .LP
18 Solaris DDI specific (Solaris DDI).
19 .SH DESCRIPTION
20 .sp
21 .LP
22 A \fBscsi_pkt\fR structure defines the packet that is allocated by
23 \fBscsi_init_pkt\fR(9F). The target driver fills in some information and passes
24 it to \fBscsi_transport\fR(9F) for execution on the target. The host bus
25 adapter (\fBHBA\fR) fills in other information as the command is processed.
26 When the command completes or can be taken no further, the completion function
27 specified in the packet is called with a pointer to the packet as its argument.
28 From fields within the packet, the target driver can determine the success or
29 failure of the command.
30 .SH STRUCTURE MEMBERS
31 .sp
32 .in +2
33 .nf
34 opaque_t pkt_ha_private; /* private data for
35 host adapter */
36 struct scsi_address pkt_address; /* destination packet */
37 opaque_t pkt_private; /* private data
38 for target driver */
39 void (*pkt_comp)(struct scsi_pkt *); /* callback */
40 uint_t pkt_flags; /* flags */
41 int pkt_time; /* time allotted to
42 complete command */
43 uchar_t *pkt_scbp; /* pointer to
44 status block */
45 uchar_t *pkt_cdbp; /* pointer to
46 command block */
47 ssize_t pkt_resid; /* number of bytes
48 not transferred */
49 uint_t pkt_state; /* state of command */
50 uint_t pkt_statistics; /* statistics */
51 uchar_t pkt_reason; /* reason completion
52 called */
53 uint_t pkt_cdblen; /* length of pkt_cdbp */
54 uint_t pkt_scdblen; /* length of pkt_scbp */
55 uint_t pkt_tgtlen; /* length of pkt_private */
56 uint_t pkt_numcookies; /* number of DMA cookies */
57 ddi_dma_cookie_t *pkt_cookies; /* array of DMA cookies */
58 uint_t pkt_dma_flags; /* DMA flags */
59 .fi
60 .in -2
62 .sp
63 .ne 2
64 .na
65 \fB\fBpkt_ha_private\fR\fR
66 .ad
67 .RS 18n
68 Opaque pointer that the HBA uses to reference a private data structure that
69 transfers \fBscsi_pkt\fR requests.
70 .RE
72 .sp
73 .ne 2
74 .na
75 \fB\fBpkt_address\fR\fR
76 .ad
77 .RS 18n
78 Initialized by \fBscsi_init_pkt\fR(9F), \fBpkt_address\fR records the intended
79 route and the recipient of a request.
80 .RE
82 .sp
83 .ne 2
84 .na
85 \fB\fBpkt_private\fR\fR
86 .ad
87 .RS 18n
88 Reserved for the use of the target driver, \fBpkt_private\fR is not changed by
89 the HBA driver.
90 .RE
92 .sp
93 .ne 2
94 .na
95 \fB\fBpkt_comp\fR\fR
96 .ad
97 .RS 18n
98 Specifies the command completion callback routine. When the host adapter driver
99 has gone as far as it can in transporting a command to a \fBSCSI\fR target, and
100 the command has either run to completion or can go no further for some other
101 reason, the host adapter driver calls the function pointed to by this field and
102 passes a pointer to the packet as argument. The callback routine itself is
103 called from interrupt context and must not sleep or call any function that
104 might sleep.
105 .RE
107 .sp
108 .ne 2
109 .na
110 \fB\fBpkt_flags\fR\fR
111 .ad
112 .RS 18n
113 Provides additional information about how the target driver expects the command
114 to be executed. See \fBpkt_flag Definitions\fR.
115 .RE
117 .sp
118 .ne 2
119 .na
120 \fB\fBpkt_time\fR\fR
121 .ad
122 .RS 18n
123 Set by the target driver to represent the maximum time allowed in seconds for
124 this command to complete. Timeout starts when the command is transmitted on the
125 \fBSCSI\fR bus. The \fBpkt_time\fR may be \fB0\fR if no timeout is required.
126 .RE
128 .sp
129 .ne 2
130 .na
131 \fB\fBpkt_scbp\fR\fR
132 .ad
133 .RS 18n
134 Points to either a struct \fBscsi_status\fR(9S) or, if \fBauto-rqsense\fR is
135 enabled and \fBpkt_state\fR includes \fBSTATE_ARQ_DONE\fR, a struct
136 \fBscsi_arq_status\fR. If \fBscsi_status\fR is returned, the \fBSCSI\fR status
137 byte resulting from the requested command is available. If
138 \fBscsi_arq_status\fR(9S) is returned, the sense information is also available.
139 .RE
141 .sp
142 .ne 2
143 .na
144 \fB\fBpkt_cdbp\fR\fR
145 .ad
146 .RS 18n
147 Points to a kernel-addressable buffer with a length specified by a call to the
148 proper resource allocation routine, \fBscsi_init_pkt\fR(9F).
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fBpkt_resid\fR\fR
155 .ad
156 .RS 18n
157 Contains a residual count, either the number of data bytes that have not been
158 transferred (\fBscsi_transport\fR(9F)) or the number of data bytes for which
159 DMA resources could not be allocated \fBscsi_init_pkt\fR(9F). In the latter
160 case, partial DMA resources can be allocated only if \fBscsi_init_pkt\fR(9F) is
161 called with the \fBPKT_DMA_PARTIAL\fR flag.
162 .RE
164 .sp
165 .ne 2
166 .na
167 \fB\fBpkt_state\fR\fR
168 .ad
169 .RS 18n
170 Has bit positions that represent the six most important states that a
171 \fBSCSI\fR command can go through. See \fBpkt_state Definitions\fR.
172 .RE
174 .sp
175 .ne 2
176 .na
177 \fB\fBpkt_statistics\fR\fR
178 .ad
179 .RS 18n
180 Maintains some transport-related statistics. See \fBpkt_statistics
181 Definitions\fR.
182 .RE
184 .sp
185 .ne 2
186 .na
187 \fB\fBpkt_reason\fR\fR
188 .ad
189 .RS 18n
190 Contains a completion code that indicates why the \fBpkt_comp\fR function was
191 called. See \fBpkt_reason Definitions\fR.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBpkt_cdblen\fR\fR
198 .ad
199 .RS 18n
200 Length of buffer pointed to by \fBpkt_cdbp\fR. See \fBtran_setup_pkt\fR.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fBpkt_scblen\fR\fR
207 .ad
208 .RS 18n
209 Length of buffer pointed to by \fBpkt_scbp\fR. See \fBtran_setup_pkt\fR.
210 .RE
212 .sp
213 .ne 2
214 .na
215 \fB\fBpkt_tgtlen\fR\fR
216 .ad
217 .RS 18n
218 Length of buffer pointed to by \fBpkt_private\fR. See \fBtran_setup_pkt\fR.
219 .RE
221 .sp
222 .ne 2
223 .na
224 \fB\fBpkt_numcookies\fR\fR
225 .ad
226 .RS 18n
227 Length \fBpkt_cookies\fR array. See \fBtran_setup_pkt\fR.
228 .RE
230 .sp
231 .ne 2
232 .na
233 \fB\fBpkt_cookies\fR\fR
234 .ad
235 .RS 18n
236 Array of DMA cookies. See \fBtran_setup_pkt\fR.
237 .RE
239 .sp
240 .ne 2
241 .na
242 \fB\fBpkt_dma_flags\fR\fR
243 .ad
244 .RS 18n
245 DMA flags used, such as \fBDDI_DMA_READ\fR and \fBDDI_DMA_WRITE\fR. See
246 \fBtran_setup_pkt\fR.
247 .RE
249 .sp
250 .LP
251 The host adapter driver will update the \fBpkt_resid\fR, \fBpkt_reason\fR,
252 \fBpkt_state\fR, and \fBpkt_statistics\fR fields.
253 .SS "\fBpkt_flags\fR Definitions"
254 .sp
255 .LP
256 The appropriate definitions for the structure member \fBpkt_flags\fR are:
257 .sp
258 .ne 2
259 .na
260 \fB\fBFLAG_NOINTR\fR\fR
261 .ad
262 .RS 30n
263 Run command with no command completion callback. Command is complete upon
264 return from \fBscsi_transport\fR(9F).
265 .RE
267 .sp
268 .ne 2
269 .na
270 \fB\fBFLAG_NODISCON\fR\fR
271 .ad
272 .RS 30n
273 Run command without disconnects.
274 .RE
276 .sp
277 .ne 2
278 .na
279 \fB\fBFLAG_NOPARITY\fR\fR
280 .ad
281 .RS 30n
282 Run command without parity checking.
283 .RE
285 .sp
286 .ne 2
287 .na
288 \fB\fBFLAG_HTAG\fR\fR
289 .ad
290 .RS 30n
291 Run command as the head-of-queue-tagged command.
292 .RE
294 .sp
295 .ne 2
296 .na
297 \fB\fBFLAG_OTAG\fR\fR
298 .ad
299 .RS 30n
300 Run command as an ordered-queue-tagged command.
301 .RE
303 .sp
304 .ne 2
305 .na
306 \fB\fBFLAG_STAG\fR\fR
307 .ad
308 .RS 30n
309 Run command as a simple-queue-tagged command.
310 .RE
312 .sp
313 .ne 2
314 .na
315 \fB\fBFLAG_SENSING\fR\fR
316 .ad
317 .RS 30n
318 Indicates a request sense command.
319 .RE
321 .sp
322 .ne 2
323 .na
324 \fB\fBFLAG_HEAD\fR\fR
325 .ad
326 .RS 30n
327 Place command at the head of the queue.
328 .RE
330 .sp
331 .ne 2
332 .na
333 \fB\fBFLAG_RENEGOTIATE_WIDE_SYNC\fR\fR
334 .ad
335 .RS 30n
336 Before transporting this command, the host adapter should initiate the
337 renegotiation of wide mode and synchronous transfer speed. Normally, the HBA
338 driver manages negotiations but under certain conditions forcing a
339 renegotiation is appropriate. Renegotiation is recommended before Request Sense
340 and Inquiry commands. Refer to the SCSI 2 standard, sections 6.6.21 and 6.6.23.
341 .sp
342 This flag should not be set for every packet as this will severely impact
343 performance.
344 .RE
346 .SS "\fBpkt_reason\fR Definitions"
347 .sp
348 .LP
349 The appropriate definitions for the structure member \fBpkt_reason\fR are:
350 .sp
351 .ne 2
352 .na
353 \fB\fBCMD_CMPLT\fR\fR
354 .ad
355 .RS 20n
356 No transport errors; normal completion.
357 .RE
359 .sp
360 .ne 2
361 .na
362 \fB\fBCMD_INCOMPLETE\fR\fR
363 .ad
364 .RS 20n
365 Transport stopped with abnormal state.
366 .RE
368 .sp
369 .ne 2
370 .na
371 \fB\fBCMD_DMA_DERR\fR\fR
372 .ad
373 .RS 20n
374 \fBDMA\fRd irection error.
375 .RE
377 .sp
378 .ne 2
379 .na
380 \fB\fBCMD_TRAN_ERR\fR\fR
381 .ad
382 .RS 20n
383 Unspecified transport error.
384 .RE
386 .sp
387 .ne 2
388 .na
389 \fB\fBCMD_RESET\fR\fR
390 .ad
391 .RS 20n
392 \fBSCSI\fR bus reset destroyed command.
393 .RE
395 .sp
396 .ne 2
397 .na
398 \fB\fBCMD_ABORTED\fR\fR
399 .ad
400 .RS 20n
401 Command transport aborted on request.
402 .RE
404 .sp
405 .ne 2
406 .na
407 \fB\fBCMD_TIMEOUT\fR\fR
408 .ad
409 .RS 20n
410 Command timed out.
411 .RE
413 .sp
414 .ne 2
415 .na
416 \fB\fBCMD_DATA_OVR\fR\fR
417 .ad
418 .RS 20n
419 Data overrun.
420 .RE
422 .sp
423 .ne 2
424 .na
425 \fB\fBCMD_CMD_OVR\fR\fR
426 .ad
427 .RS 20n
428 Command overrun.
429 .RE
431 .sp
432 .ne 2
433 .na
434 \fB\fBCMD_STS_OVR\fR\fR
435 .ad
436 .RS 20n
437 Status overrun.
438 .RE
440 .sp
441 .ne 2
442 .na
443 \fB\fBCMD_BADMSG\fR\fR
444 .ad
445 .RS 20n
446 Message not command complete.
447 .RE
449 .sp
450 .ne 2
451 .na
452 \fB\fBCMD_NOMSGOUT\fR\fR
453 .ad
454 .RS 20n
455 Target refused to go to message out phase.
456 .RE
458 .sp
459 .ne 2
460 .na
461 \fB\fBCMD_XID_FAIL\fR\fR
462 .ad
463 .RS 20n
464 Extended identify message rejected.
465 .RE
467 .sp
468 .ne 2
469 .na
470 \fB\fBCMD_IDE_FAIL\fR\fR
471 .ad
472 .RS 20n
473 "Initiator Detected Error" message rejected.
474 .RE
476 .sp
477 .ne 2
478 .na
479 \fB\fBCMD_ABORT_FAIL\fR\fR
480 .ad
481 .RS 20n
482 Abort message rejected.
483 .RE
485 .sp
486 .ne 2
487 .na
488 \fB\fBCMD_REJECT_FAIL\fR\fR
489 .ad
490 .RS 20n
491 Reject message rejected.
492 .RE
494 .sp
495 .ne 2
496 .na
497 \fB\fBCMD_NOP_FAIL\fR\fR
498 .ad
499 .RS 20n
500 "No Operation" message rejected.
501 .RE
503 .sp
504 .ne 2
505 .na
506 \fB\fBCMD_PER_FAIL\fR\fR
507 .ad
508 .RS 20n
509 "Message Parity Error" message rejected.
510 .RE
512 .sp
513 .ne 2
514 .na
515 \fB\fBCMD_BDR_FAIL\fR\fR
516 .ad
517 .RS 20n
518 "Bus Device Reset" message rejected.
519 .RE
521 .sp
522 .ne 2
523 .na
524 \fB\fBCMD_ID_FAIL\fR\fR
525 .ad
526 .RS 20n
527 Identify message rejected.
528 .RE
530 .sp
531 .ne 2
532 .na
533 \fB\fBCMD_UNX_BUS_FREE\fR\fR
534 .ad
535 .RS 20n
536 Unexpected bus free phase.
537 .RE
539 .sp
540 .ne 2
541 .na
542 \fB\fBCMD_TAG_REJECT\fR\fR
543 .ad
544 .RS 20n
545 Target rejected the tag message.
546 .RE
548 .sp
549 .ne 2
550 .na
551 \fB\fBCMD_DEV_GONE\fR\fR
552 .ad
553 .RS 20n
554 The device has been removed.
555 .RE
557 .SS "pkt_state Definitions"
558 .sp
559 .LP
560 The appropriate definitions for the structure member \fBpkt_state\fR are:
561 .sp
562 .ne 2
563 .na
564 \fB\fBSTATE_GOT_BUS\fR\fR
565 .ad
566 .RS 22n
567 Bus arbitration succeeded.
568 .RE
570 .sp
571 .ne 2
572 .na
573 \fB\fBSTATE_GOT_TARGET\fR\fR
574 .ad
575 .RS 22n
576 Target successfully selected.
577 .RE
579 .sp
580 .ne 2
581 .na
582 \fB\fBSTATE_SENT_CMD\fR\fR
583 .ad
584 .RS 22n
585 Command successfully sent.
586 .RE
588 .sp
589 .ne 2
590 .na
591 \fB\fBSTATE_XFERRED_DATA\fR\fR
592 .ad
593 .RS 22n
594 Data transfer took place.
595 .RE
597 .sp
598 .ne 2
599 .na
600 \fB\fBSTATE_GOT_STATUS\fR\fR
601 .ad
602 .RS 22n
603 Status received.
604 .RE
606 .sp
607 .ne 2
608 .na
609 \fB\fBSTATE_ARQ_DONE\fR\fR
610 .ad
611 .RS 22n
612 The command resulted in a check condition and the host adapter driver executed
613 an automatic request sense command.
614 .RE
616 .sp
617 .ne 2
618 .na
619 \fB\fBSTATE_XARQ_DONE\fR\fR
620 .ad
621 .RS 22n
622 The command requested in extra sense data using a \fBPKT_XARQ\fR flag got a
623 check condition. The host adapter driver was able to successfully request and
624 return this. The \fBscsi_pkt.pkt_scbp->sts_rqpkt_resid\fR returns the sense
625 data residual based on the \fIstatuslen\fR parameter of the
626 \fBscsi_init_pkt\fR(9F) call. The sense data begins at
627 \fBscsi_pkt.pkt_scbp->sts_sensedata\fR.
628 .RE
630 .SS "pkt_statistics Definitions"
631 .sp
632 .LP
633 The definitions that are appropriate for the structure member
634 \fBpkt_statistics\fR are:
635 .sp
636 .ne 2
637 .na
638 \fB\fBSTAT_DISCON\fR\fR
639 .ad
640 .RS 18n
641 Device disconnect.
642 .RE
644 .sp
645 .ne 2
646 .na
647 \fB\fBSTAT_SYNC\fR\fR
648 .ad
649 .RS 18n
650 Command did a synchronous data transfer.
651 .RE
653 .sp
654 .ne 2
655 .na
656 \fB\fBSTAT_PERR\fR\fR
657 .ad
658 .RS 18n
659 \fBSCSI\fR parity error.
660 .RE
662 .sp
663 .ne 2
664 .na
665 \fB\fBSTAT_BUS_RESET\fR\fR
666 .ad
667 .RS 18n
668 Bus reset.
669 .RE
671 .sp
672 .ne 2
673 .na
674 \fB\fBSTAT_DEV_RESET\fR\fR
675 .ad
676 .RS 18n
677 Device reset.
678 .RE
680 .sp
681 .ne 2
682 .na
683 \fB\fBSTAT_ABORTED\fR\fR
684 .ad
685 .RS 18n
686 Command was aborted.
687 .RE
689 .sp
690 .ne 2
691 .na
692 \fB\fBSTAT_TIMEOUT\fR\fR
693 .ad
694 .RS 18n
695 Command timed out.
696 .RE
698 .SH SEE ALSO
699 .sp
700 .LP
701 \fBtran_init_pkt\fR(9E), \fBtran_setup_pkt\fR(9E), \fBscsi_arq_status\fR(9S),
702 \fBscsi_init_pkt\fR(9F), \fBscsi_transport\fR(9F), \fBscsi_status\fR(9S),
703 \fBscsi_hba_pkt_comp\fR(9F)
704 .sp
705 .LP
706 \fIWriting Device Drivers\fR
707 .SH NOTES
708 .sp
709 .LP
710 HBA drivers should signal \fBscsi_pkt\fR completion by calling
711 \fBscsi_hba_pkt_comp\fR(9F). This is mandatory for HBA drivers that implement
712 \fBtran_setup_pkt\fR(9E). Failure to comply results in undefined behavior.