1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
|
'\" te
.\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" 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.
.\" 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.
.\" 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]
.TH SCSI_ALLOC_CONSISTENT_BUF 9F "Jan 16, 2006"
.SH NAME
scsi_alloc_consistent_buf \- allocate an I/O buffer for SCSI DMA
.SH SYNOPSIS
.nf
#include <sys/scsi/scsi.h>
\fBstruct buf *\fR\fBscsi_alloc_consistent_buf\fR(\fBstructscsi_address*\fR\fIap\fR,
\fBstruct buf *\fR\fIbp\fR, \fBsize_t\fR \fIdatalen\fR, \fBuint_t\fR \fIbflags\fR,
\fBint (*\fR\fIcallback\fR)(caddr_t), \fBcaddr_t\fR \fIarg\fR);
.fi
.SH INTERFACE LEVEL
illumos DDI specific (illumos DDI).
.SH PARAMETERS
.ne 2
.na
\fB\fIap\fR\fR
.ad
.RS 12n
Pointer to the \fBscsi_address\fR(9S) structure.
.RE
.sp
.ne 2
.na
\fB\fIbp\fR\fR
.ad
.RS 12n
Pointer to the \fBbuf\fR(9S) structure.
.RE
.sp
.ne 2
.na
\fB\fIdatalen\fR\fR
.ad
.RS 12n
Number of bytes for the data buffer.
.RE
.sp
.ne 2
.na
\fB\fIbflags\fR\fR
.ad
.RS 12n
Flags setting for the allocated buffer header. This should either be
\fBB_READ\fR or \fBB_WRITE\fR.
.RE
.sp
.ne 2
.na
\fB\fIcallback\fR\fR
.ad
.RS 12n
A pointer to a callback function, \fBNULL_FUNC\fR or \fBSLEEP_FUNC\fR.
.RE
.sp
.ne 2
.na
\fB\fIarg\fR\fR
.ad
.RS 12n
The callback function argument.
.RE
.SH DESCRIPTION
The \fBscsi_alloc_consistent_buf()\fR function returns allocates a buffer
header and the associated data buffer for direct memory access (DMA) transfer.
This buffer is allocated from the \fBiobp\fR space, which is considered
consistent memory. For more details, see \fBddi_dma_mem_alloc\fR(9F) and
\fBddi_dma_sync\fR(9F).
.sp
.LP
For buffers allocated via \fBscsi_alloc_consistent_buf()\fR, and marked with
the \fBPKT_CONSISTENT\fR flag via \fBscsi_init_pkt\fR(9F), the HBA driver must
ensure that the data transfer for the command is correctly synchronized before
the target driver's command completion callback is performed.
.sp
.LP
If \fIbp\fR is \fINULL\fR, a new buffer header will be allocated using
\fBgetrbuf\fR(9F). In addition, if \fIdatalen\fR is non-zero, a new buffer will
be allocated using \fBddi_dma_mem_alloc\fR(9F).
.sp
.LP
\fIcallback\fR indicates what the allocator routines should do when direct
memory access \fB(DMA)\fR resources are not available; the valid values are:
.sp
.ne 2
.na
\fB\fBNULL_FUNC\fR\fR
.ad
.RS 16n
Do not wait for resources. Return a \fINULL\fR pointer.
.RE
.sp
.ne 2
.na
\fB\fBSLEEP_FUNC\fR\fR
.ad
.RS 16n
Wait indefinitely for resources.
.RE
.sp
.ne 2
.na
\fBOther Values\fR
.ad
.RS 16n
\fIcallback\fR points to a function that is called when resources may become
available. \fIcallback\fR must return either \fB0\fR (indicating that it
attempted to allocate resources but failed to do so), in which case it is put
back on a list to be called again later, or \fB1\fR indicating either success
in allocating resources or indicating that it no longer cares for a retry. The
last argument \fIarg\fR is supplied to the \fIcallback\fR function when it is
invoked.
.RE
.SH RETURN VALUES
The \fBscsi_alloc_consistent_buf()\fR function returns a pointer to a
\fBbuf\fR(9S) structure on success. It returns \fBNULL\fR if resources are not
available even if \fIwaitfunc\fR was not \fBSLEEP_FUNC\fR.
.SH CONTEXT
If \fIcallback\fR is \fBSLEEP_FUNC\fR, then this routine may be called only
from user-level code. Otherwise, it may be called fromuser, interrupt, or
kernel context. The \fIcallback\fR function may not block or call routines that
block.
.SH EXAMPLES
\fBExample 1 \fRAllocate a request sense packet with consistent DMA resources
attached.
.sp
.in +2
.nf
bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL,
SENSE_LENGTH, B_READ, SLEEP_FUNC, NULL);
rqpkt = scsi_init_pkt(&devp->sd_address,
NULL, bp, CDB_GROUP0, 1, 0,
PKT_CONSISTENT, SLEEP_FUNC, NULL);
.fi
.in -2
.LP
\fBExample 2 \fRAllocate an inquiry packet with consistent DMA resources
attached.
.sp
.in +2
.nf
bp = scsi_alloc_consistent_buf(&devp->sd_address, NULL,
SUN_INQSIZE, B_READ, canwait, NULL);
if (bp) {
pkt = scsi_init_pkt(&devp->sd_address, NULL, bp,
CDB_GROUP0, 1, PP_LEN, PKT_CONSISTENT,
canwait, NULL);
}
.fi
.in -2
.SH SEE ALSO
.BR ddi_dma_mem_alloc (9F),
.BR ddi_dma_sync (9F),
.BR getrbuf (9F),
.BR scsi_destroy_pkt (9F),
.BR scsi_free_consistent_buf (9F),
.BR scsi_init_pkt (9F),
.BR buf (9S),
.BR scsi_address (9S)
.sp
.LP
\fIWriting Device Drivers\fR
|
