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