| blob | 28b84b6cd1c8ab1ed48bdfd5409dd5187574819b |
1 '\" te
2 .\" Copyright 2014 Garrett D'Amore <garrett@damore.org>
3 .\" Copyright (c) 2006, Sun Microsystems, Inc., All Rights Reserved
4 .\" 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.
5 .\" 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.
6 .\" 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]
7 .TH SCSI_INIT_PKT 9F "May 24, 2014"
8 .SH NAME
9 scsi_init_pkt \- prepare a complete SCSI packet
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <sys/scsi/scsi.h>
17 \fBstruct scsi_pkt *\fR\fBscsi_init_pkt\fR(\fBstruct scsi_address *\fR\fIap\fR,
18 \fBstruct scsi_pkt *\fR\fIpktp\fR, \fBstruct buf *\fR\fIbp\fR, \fBint\fR \fIcmdlen\fR, \fBint\fR \fIstatuslen\fR,
19 \fBint\fR \fIprivatelen\fR, \fBint\fR \fIflags\fR, \fBint\fR \fB(*\fRcallback\fB)(caddr_t)\fR, \fBcaddr_t\fR \fIarg\fR);
20 .fi
22 .SH INTERFACE LEVEL
23 .sp
24 .LP
25 Solaris DDI specific (Solaris DDI).
26 .SH PARAMETERS
27 .sp
28 .ne 2
29 .na
30 \fB\fIap\fR\fR
31 .ad
32 .sp .6
33 .RS 4n
34 Pointer to a \fBscsi_address\fR(9S) structure.
35 .RE
37 .sp
38 .ne 2
39 .na
40 \fB\fIpktp\fR\fR
41 .ad
42 .sp .6
43 .RS 4n
44 A pointer to a \fBscsi_pkt\fR(9S) structure.
45 .RE
47 .sp
48 .ne 2
49 .na
50 \fB\fIbp\fR\fR
51 .ad
52 .sp .6
53 .RS 4n
54 Pointer to a \fBbuf\fR(9S) structure.
55 .RE
57 .sp
58 .ne 2
59 .na
60 \fB\fIcmdlen\fR\fR
61 .ad
62 .sp .6
63 .RS 4n
64 The required length for the \fBSCSI \fRcommand descriptor block (\fBCDB\fR) in
65 bytes.
66 .RE
68 .sp
69 .ne 2
70 .na
71 \fB\fIstatuslen\fR\fR
72 .ad
73 .sp .6
74 .RS 4n
75 The required length for the \fBSCSI \fRstatus completion block (\fBSCB\fR) in
76 bytes. Valid values are:
77 .sp
78 .ne 2
79 .na
80 \fB\fB0\fR\fR
81 .ad
82 .sp .6
83 .RS 4n
84 No status back.
85 .RE
87 .sp
88 .ne 2
89 .na
90 \fB\fB1\fR\fR
91 .ad
92 .sp .6
93 .RS 4n
94 Return SCSI status byte.
95 .RE
97 .sp
98 .ne 2
99 .na
100 \fB\fBsizeof(scsi_arq_status)\fR\fR
101 .ad
102 .sp .6
103 .RS 4n
104 Return status information in a \fBscsi_arq_status\fR structure. This will
105 include up to 20 bytes of sense data. Please refer to \fBscsi_arq_status\fR(9S)
106 for more information.
107 .sp
108 For extra sense packets (\fBPKT_XARQ\fR flag asserted), set \fIstatuslen\fR to
109 be a greater number like, (\fIN\fR + \fBsizeof(struct scsi_arq_status)\fR)
110 where \fIN\fR is the number of extra bytes beyond the default 20. For example,
111 \fIN\fR=1 requests 21 bytes of sense, \fIN\fR=235 asks for 255 bytes.
112 .RE
114 .RE
116 .sp
117 .ne 2
118 .na
119 \fB\fIprivatelen\fR\fR
120 .ad
121 .sp .6
122 .RS 4n
123 The required length for the \fIpkt_private\fR area.
124 .RE
126 .sp
127 .ne 2
128 .na
129 \fB\fIflags\fR\fR
130 .ad
131 .sp .6
132 .RS 4n
133 Flags modifier.
134 .RE
136 .sp
137 .ne 2
138 .na
139 \fB\fIcallback\fR\fR
140 .ad
141 .sp .6
142 .RS 4n
143 A pointer to a callback function, \fBNULL_FUNC\fR, or \fBSLEEP_FUNC\fR.
144 .RE
146 .sp
147 .ne 2
148 .na
149 \fB\fIarg\fR\fR
150 .ad
151 .sp .6
152 .RS 4n
153 The \fIcallback\fR function argument.
154 .RE
156 .SH DESCRIPTION
157 .sp
158 .LP
159 Target drivers use \fBscsi_init_pkt()\fR to request the transport layer to
160 allocate and initialize a packet for a \fBSCSI\fR command which possibly
161 includes a data transfer. If \fIpktp\fR is \fINULL,\fR a new \fBscsi_pkt\fR(9S)
162 is allocated using the \fBHBA\fR driver's packet allocator. The \fIbp\fR is a
163 pointer to a \fBbuf\fR(9S) structure. If \fIbp\fR is non-\fINULL\fR and
164 contains a valid byte count, the \fBbuf\fR(9S) structure is also set up for
165 \fBDMA \fRtransfer using the \fBHBA\fR driver \fBDMA\fR resources allocator.
166 When \fIbp\fR is allocated by \fBscsi_alloc_consistent_buf\fR(9F), the
167 \fBPKT_CONSISTENT\fR bit must be set in the \fIflags\fR argument to ensure
168 proper operation. If \fIprivatelen\fR is non-zero then additional space is
169 allocated for the \fIpkt_private\fR area of the \fBscsi_pkt\fR(9S). On return
170 \fIpkt_private\fR points to this additional space. Otherwise \fIpkt_private\fR
171 is a pointer that is typically used to store the \fIbp\fR during execution of
172 the command. In this case \fIpkt_private\fR is \fINULL\fR on return.
173 .sp
174 .LP
175 The \fIflags\fR argument is a set of bit flags. Possible bits include:
176 .sp
177 .ne 2
178 .na
179 \fB\fBPKT_CONSISTENT\fR\fR
180 .ad
181 .sp .6
182 .RS 4n
183 This must be set if the \fBDMA\fR buffer was allocated using
184 \fBscsi_alloc_consistent_buf\fR(9F). In this case, the \fBHBA\fR driver will
185 guarantee that the data transfer is properly synchronized before performing the
186 target driver's command completion callback.
187 .RE
189 .sp
190 .ne 2
191 .na
192 \fB\fBPKT_DMA_PARTIAL\fR\fR
193 .ad
194 .sp .6
195 .RS 4n
196 This may be set if the driver can accept a partial \fBDMA\fR mapping. If set,
197 \fBscsi_init_pkt()\fR will allocate \fBDMA\fR resources with the
198 \fBDDI_DMA_PARTIAL\fR bit set in the DMA flags.
199 The \fBpkt_resid\fR field of the
200 \fBscsi_pkt\fR(9S) structure may be returned with a non-zero value, which
201 indicates the number of bytes for which \fBscsi_init_pkt()\fR was unable to
202 allocate DMA resources. In this case, a subsequent call to
203 \fBscsi_init_pkt()\fR may be made for the same \fIpktp\fR and \fIbp\fR to
204 adjust the DMA resources to the next portion of the transfer. This sequence
205 should be repeated until the \fBpkt_resid\fR field is returned with a zero
206 value, which indicates that with transport of this final portion the entire
207 original request will have been satisfied.
208 .RE
210 .sp
211 .ne 2
212 .na
213 \fB\fBPKT_XARQ\fR\fR
214 .ad
215 .sp .6
216 .RS 4n
217 Setting this flag requests that the \fBHBA\fR return extra sense data for this
218 \fBscsi_pkt\fR(9S). The default auto request sense mechanism returns up to 20
219 bytes. More than 20 bytes of sense data can be requested by setting this flag
220 and setting the \fIstatuslen\fR correctly. Set the \fIstatuslen\fR to be the
221 \fBsizeof(struct scsi_arq_status)\fR plus the number of sense bytes needed
222 beyond 20. For example, set statuslen to be \fB(sizeof(struct scsi_arq_status)
223 + 5)\fR for 25 bytes of sense.
224 .RE
226 .sp
227 .LP
228 When calling \fBscsi_init_pkt()\fR to move already-allocated \fBDMA\fR
229 resources, the \fIcmdlen\fR, \fIstatuslen\fR, and \fIprivatelen\fR fields are
230 ignored.
231 .sp
232 .LP
233 The last argument \fIarg\fR is supplied to the \fIcallback\fR function when it
234 is invoked.
235 .sp
236 .LP
237 \fIcallback\fR indicates what the allocator routines should do when resources
238 are not available:
239 .sp
240 .ne 2
241 .na
242 \fB\fBNULL_FUNC\fR\fR
243 .ad
244 .RS 16n
245 Do not wait for resources. Return a \fINULL\fR pointer.
246 .RE
248 .sp
249 .ne 2
250 .na
251 \fB\fBSLEEP_FUNC\fR\fR
252 .ad
253 .RS 16n
254 Wait indefinitely for resources.
255 .RE
257 .sp
258 .ne 2
259 .na
260 \fBOther Values\fR
261 .ad
262 .RS 16n
263 \fIcallback\fR points to a function which is called when resources may have
264 become available. \fIcallback\fR must return either \fB0\fR (indicating that it
265 attempted to allocate resources but again failed to do so), in which case it is
266 put back on a list to be called again later, or \fB1\fR indicating either
267 success in allocating resources or indicating that it no longer cares for a
268 retry.
269 .RE
271 .sp
272 .LP
273 When allocating \fBDMA\fR resources, \fBscsi_init_pkt()\fR returns the
274 \fBscsi_pkt\fR field \fBpkt_resid\fR as the number of residual bytes for which
275 the system was unable to allocate \fBDMA\fR resources. A \fBpkt_resid\fR of
276 \fB0\fR means that all necessary \fBDMA\fR resources were allocated.
277 .SH RETURN VALUES
278 .sp
279 .LP
280 The \fBscsi_init_pkt()\fR function returns \fINULL\fR if the packet or
281 \fBDMA\fR resources could not be allocated. Otherwise, it returns a pointer to
282 an initialized \fBscsi_pkt\fR(9S). If \fIpktp\fR was not \fINULL\fR the return
283 value will be \fIpktp\fR on successful initialization of the packet.
284 .SH CONTEXT
285 .sp
286 .LP
287 If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine can be called only
288 from user-level code. Otherwise, it can be called from user, interrupt, or
289 kernel context. The \fIcallback\fR function may not block or call routines that
290 block.
291 .SH EXAMPLES
292 .LP
293 \fBExample 1 \fRAllocating a Packet Without \fBDMA\fR Resources Attached
294 .sp
295 .LP
296 To allocate a packet without \fBDMA\fR resources attached, use:
298 .sp
299 .in +2
300 .nf
301 pkt = scsi_init_pkt(&devp->sd_address, NULL, NULL, CDB_GROUP1,
302 1, sizeof (struct my_pkt_private *), 0,
303 sd_runout, sd_unit);
304 .fi
305 .in -2
307 .LP
308 \fBExample 2 \fRAllocating a Packet With \fBDMA\fR Resources Attached
309 .sp
310 .LP
311 To allocate a packet with \fBDMA\fR resources attached use:
313 .sp
314 .in +2
315 .nf
316 pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP1,
317 sizeof(struct scsi_arq_status), 0, 0, NULL_FUNC, NULL);
318 .fi
319 .in -2
321 .LP
322 \fBExample 3 \fRAttaching \fBDMA\fR Resources to a Preallocated Packet
323 .sp
324 .LP
325 To attach \fBDMA\fR resources to a preallocated packet, use:
327 .sp
328 .in +2
329 .nf
330 pkt = scsi_init_pkt(&devp->sd_address, old_pkt, bp, 0,
331 0, 0, 0, sd_runout, (caddr_t) sd_unit);
332 .fi
333 .in -2
335 .LP
336 \fBExample 4 \fRAllocating a Packet with Consistent \fBDMA\fR Resources
337 Attached
338 .sp
339 .LP
340 Since the packet is already allocated, the \fIcmdlen\fR, \fIstatuslen\fR and
341 \fIprivatelen\fR are \fB0\fR. To allocate a packet with consistent \fBDMA\fR
342 resources attached, use:
344 .sp
345 .in +2
346 .nf
347 bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL,
348 SENSE_LENGTH, B_READ, SLEEP_FUNC, NULL);
349 pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP0,
350 sizeof(struct scsi_arq_status), sizeof (struct my_pkt_private *),
351 PKT_CONSISTENT, SLEEP_FUNC, NULL);
352 .fi
353 .in -2
355 .LP
356 \fBExample 5 \fRAllocating a Packet with Partial \fBDMA\fR Resources Attached
357 .sp
358 .LP
359 To allocate a packet with partial \fBDMA\fR resources attached, use:
361 .sp
362 .in +2
363 .nf
364 my_pkt = scsi_init_pkt(&devp->sd_address, NULL, bp, CDB_GROUP0,
365 1, sizeof (struct buf *), PKT_DMA_PARTIAL,
366 SLEEP_FUNC, NULL);
367 .fi
368 .in -2
370 .SH SEE ALSO
371 .sp
372 .LP
373 \fBscsi_alloc_consistent_buf\fR(9F), \fBscsi_destroy_pkt\fR(9F),
374 \fBscsi_dmaget\fR(9F), \fBscsi_pktalloc\fR(9F), \fBbuf\fR(9S),
375 \fBscsi_address\fR(9S), \fBscsi_pkt\fR(9S)
376 .sp
377 .LP
378 \fIWriting Device Drivers\fR
379 .SH NOTES
380 .sp
381 .LP
382 If a \fBDMA\fR allocation request fails with \fBDDI_DMA_NOMAPPING\fR, the
383 \fBB_ERROR\fR flag will be set in \fIbp\fR, and the \fBb_error\fR field will be
384 set to \fBEFAULT\fR.
385 .sp
386 .LP
387 If a \fBDMA\fR allocation request fails with \fBDDI_DMA_TOOBIG\fR, the
388 \fBB_ERROR\fR flag will be set in \fIbp\fR, and the \fBb_error\fR field will be
389 set to \fBEINVAL\fR.