1tran_start(9E) Driver Entry Points tran_start(9E)
2
6 tran_start - request to transport a SCSI command
7
9 #include <sys/scsi/scsi.h>
10 int prefixtran_start(struct scsi_address *ap,
14 struct scsi_pkt *pkt);
15
18 Solaris architecture specific (Solaris DDI).
19
21 pkt Pointer to the scsi_pkt(9S) structure that is about to be
22 transferred.
23 ap Pointer to a scsi_address(9S) structure.
26
29 The tran_start() vector in the scsi_hba_tran(9S) structure must be
30 initialized during the HBA driver's attach(9E) to point to an HBA entry
31 point to be called when a target driver calls scsi_transport(9F).
32 tran_start() must perform the necessary operations on the HBA hardware
35 to transport the SCSI command in the pkt structure to the target/logi‐
36 cal unit device specified in the ap structure.
37 If the flag FLAG_NOINTR is set in pkt_flags in pkt, tran_start()
40 should not return until the command has been completed. The command
41 completion callback pkt_comp in pkt must not be called for commands
42 with FLAG_NOINTR set, since the return is made directly to the func‐
43 tion invoking scsi_transport(9F).
44 When the flag FLAG_NOINTR is not set, tran_start() must queue the
47 command for execution on the hardware and return immediately. The mem‐
48 ber pkt_comp in pkt indicates a callback routine to be called upon
49 command completion.
50 Refer to scsi_pkt(9S) for other bits in pkt_flags for which the HBA
53 driver may need to adjust how the command is managed.
54 If the auto_rqsense capability has been set, and the status length
57 allocated in tran_init_pkt(9E) is greater than or equal to
58 sizeof(struct scsi_arq_status), automatic request sense is enabled for
59 this pkt. If the command terminates with a Check Condition, the HBA
60 driver must arrange for a Request Sense command to be transported to
61 that target/logical unit, and the members of the scsi_arq_status
62 structure pointed to by pkt_scbp updated with the results of this
63 Request Sense command before the HBA driver completes the command
64 pointed by pkt.
65 The member pkt_time in pkt is the maximum number of seconds in which
68 the command should complete. Timeout starts when the command is trans‐
69 mitted on the SCSI bus. A pkt_time of 0 means no timeout should be
70 performed.
71 For a command which has timed out, the HBA driver must perform some
74 recovery operation to clear the command in the target, typically an
75 Abort message, or a Device or Bus Reset. The pkt_reason member of the
76 timed out pkt should be set to CMD_TIMEOUT, and pkt_statistics OR'ed
77 with STAT_TIMEOUT. If the HBA driver can successfully recover from the
78 timeout, pkt_statistics must also be OR'ed with one of STAT_ABORTED,
79 STAT_BUS_RESET, or STAT_DEV_RESET, as appropriate. This informs the
80 target driver that timeout recovery has already been successfully
81 accomplished for the timed out command. The pkt_comp completion call‐
82 back, if not NULL, must also be called at the conclusion of the time‐
83 out recovery.
84 If the timeout recovery was accomplished with an Abort Tag message,
87 only the timed out packet is affected, and the packet must be returned
88 with pkt_statistics OR'ed with STAT_ABORTED and STAT_TIMEOUT.
89 If the timeout recovery was accomplished with an Abort message, all
92 commands active in that target are affected. All corresponding packets
93 must be returned with pkt_reason, CMD_TIMEOUT, and pkt_statistics
94 OR'ed with STAT_TIMEOUT and STAT_ABORTED.
95 If the timeout recovery was accomplished with a Device Reset, all pack‐
98 ets corresponding to commands active in the target must be returned in
99 the transport layer for this target. Packets corresponding to commands
100 active in the target must be returned returned with pkt_reason set to
101 CMD_TIMEOUT, and pkt_statistics OR'ed with STAT_DEV_RESET and
102 STAT_TIMEOUT. Currently inactive packets queued for the device should
103 be returned with pkt_reason set to CMD_RESET and pkt_statistics OR'ed
104 with STAT_ABORTED.
105 If the timeout recovery was accomplished with a Bus Reset, all packets
108 corresponding to commands active in the target must be returned in the
109 transport layer. Packets corresponding to commands active in the target
110 must be returned with pkt_reason set to CMD_TIMEOUT and pkt_statistics
111 OR'ed with STAT_TIMEOUT and STAT_BUS_RESET. All queued packets for
112 other targets on this bus must be returned with pkt_reason set to
113 CMD_RESET and pkt_statistics OR'ed with STAT_ABORTED.
114 Note that after either a Device Reset or a Bus Reset, the HBA driver
117 must enforce a reset delay time of 'scsi-reset-delay' milliseconds,
118 during which time no commands should be sent to that device, or any
119 device on the bus, respectively.
120 tran_start() should initialize the following members in pkt to 0.
123 Upon command completion, the HBA driver should ensure that the values
124 in these members are updated to accurately reflect the states through
125 which the command transitioned while in the transport layer.
126 pkt_resid For commands with data transfer, this member must be
128 updated to indicate the residual of the data trans‐
129 ferred.
130 pkt_reason The reason for the command completion. This field
133 should be set to CMD_CMPLT at the beginning of
134 tran_start(), then updated if the command ever tran‐
135 sitions to an abnormal termination state. To avoid
136 losing information, do not set pkt_reason to any
137 other error state unless it still has its original
138 CMD_CMPLT value.
139 pkt_statistics Bit field of transport-related statistics.
142 pkt_state Bit field with the major states through which a SCSI
145 command can transition. Note: The members listed
146 above, and pkt_hba_private member, are the only
147 fields in the scsi_pkt(9S) structure which may be
148 modified by the transport layer.
149
152 tran_start() must return:
153 TRAN_ACCEPT The packet was accepted by the transport layer.
155 TRAN_BUSY The packet could not be accepted because there was
158 already a packet in progress for this target/logi‐
159 cal unit, the HBA queue was full, or the target
160 device queue was full.
161 TRAN_BADPKT The DMA count in the packet exceeded the DMA
164 engine's maximum DMA size, or the packet could not
165 be accepted for other reasons.
166 TRAN_FATAL_ERROR A fatal error has occurred in the HBA.
169
172 The tran_start() function can be called from user or interupt context.
173 This requirement comes from scsi_transport().
174
176 attach(9E), tran_init_pkt(9E), scsi_hba_attach(9F), scsi_transport(9F),
177 scsi_address(9S), scsi_arq_status(9S), scsi_hba_tran(9S), scsi_pkt(9S)
178 Writing Device Drivers
181SunOS 5.11 17 Aug 2005 tran_start(9E)