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
|
'\" te
.\" Copyright 1989 AT&T
.\" Copyright (C) 2006, Sun Microsystems, Inc. All Rights Reserved
.\" Copyright 2021 Tintri by DDN, 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 ESBALLOC 9F "Apr 24, 2021"
.SH NAME
esballoc, desballoc esballoca, desballoca \-
allocate a message block using a caller-supplied buffer
.SH SYNOPSIS
.nf
#include <sys/stream.h>
\fBmblk_t *\fR\fBesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
\fBfrtn_t *\fR\fIfr_rtnp\fR);
.fi
.LP
.nf
\fBmblk_t *\fR\fBdesballoc\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
\fBfrtn_t *\fR\fIfr_rtnp\fR);
.fi
.LP
.nf
#include <sys/strsubr.h>
.fi
.LP
.nf
\fBmblk_t *\fR\fBesballoca\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
\fBfrtn_t *\fR\fIfr_rtnp\fR);
.fi
.LP
.nf
\fBmblk_t *\fR\fBdesballoca\fR(\fBuchar_t *\fR\fIbase\fR, \fBsize_t\fR \fIsize\fR, \fBuint_t\fR \fIpri\fR,
\fBfrtn_t *\fR\fIfr_rtnp\fR);
.fi
.SH INTERFACE LEVEL
\fBesballoc()\fR: Architecture independent level 1 (DDI/DKI)
.sp
.LP
.nf
\fBesballoca()\fR: illumos DDI specific (illumos DDI)
\fBdesballoc()\fR: illumos DDI specific (illumos DDI)
\fBdesballoca()\fR: illumos DDI specific (illumos DDI)
.fi
.SH PARAMETERS
.ne 2
.na
\fB\fIbase\fR\fR
.ad
.RS 11n
Address of caller-supplied data buffer.
.RE
.sp
.ne 2
.na
\fB\fIsize\fR\fR
.ad
.RS 11n
Number of bytes in data buffer.
.RE
.sp
.ne 2
.na
\fB\fIpri\fR\fR
.ad
.RS 11n
Priority of the request (no longer used).
.RE
.sp
.ne 2
.na
\fB\fIfr_rtnp\fR\fR
.ad
.RS 11n
Free routine data structure.
.RE
.SH DESCRIPTION
The \fBesballoc()\fR, \fBesballoca()\fR, \fBdesballoc()\fR and
\fBdesballoca()\fR functions operate identically to \fBallocb\fR(9F),
except that the data buffer to associate with the message is specified
by the caller. The allocated message will have both the \fBb_wptr\fR
and \fBb_rptr\fR set to the supplied data buffer starting at \fIbase\fR. Only
the buffer itself can be specified by the caller. The message block and data
block header are allocated as if by \fBallocb\fR(9F).
.sp
.LP
When \fBfreeb\fR(9F) is called to free the message, the driver's
message-freeing routine, referenced through the \fBfree_rtn\fR(9S) structure,
is called with appropriate arguments to free the data buffer.
.sp
.LP
The \fBfree_rtn\fR(9S) structure includes the following members:
.sp
.in +2
.nf
void (*free_func)(); /* caller's freeing routine */
caddr_t free_arg; /* argument to free_func() */
.fi
.in -2
.sp
.LP
Instead of requiring a specific number of arguments, the \fBfree_arg\fR field
is defined of type \fBcaddr_t\fR. This way, the driver can pass a pointer to a
structure if more than one argument is needed. Note that the address of the
\fBfree_rtn\fR(9S) structure passed to \fBesballoc()\fR is used when the
returned mblk/dblk pair is freed, and must remain valid until then.
.sp
.LP
If \fBesballoc()\fR or \fBesballoca()\fR was used, then \fBfree_func\fR will
be called asynchronously at some point after the message is no longer
referenced. If \fBdesballoc()\fR or \fBdesballoca()\fR was used, then
\fBfree_func\fR will be called synchronously by the thread releasing
the final reference. See \fBfreeb\fR(9F).
.sp
.LP
The \fBfree_func\fR routine must not sleep, and must not access any dynamically
allocated data structures that could be freed before or during its execution.
In addition, because messages allocated with \fBdesballoc()\fR or
\fBdesballoca()\fR are freed in the context of the caller, \fBfree_func\fR
must not call another module's \fBput\fR procedure, or attempt to acquire a
private module lock which might be held by another thread across a call to a
STREAMS utility routine that could free a message block. Finally,
\fBfree_func\fR routines specified using \fBdesballoc()\fR or
\fBdesballoca()\fR may run in interrupt context and thus must only use
synchronization primitives that include an interrupt priority returned from
\fBddi_intr_get_pri\fR(9F) or \fBddi_intr_get_softint_pri\fR(9F). If any of
these restrictions are not followed, the possibility of lock recursion or
deadlock exists.
.SH RETURN VALUES
On success, a pointer to the newly allocated message block is returned. On
failure, \fBNULL\fR is returned.
.SH CONTEXT
The \fBesballoc()\fR, \fBesballoca()\fR, \fBdesballoc()\fR and
\fBdesballoca()\fR functions can be called from user,
interrupt, or kernel context.
.SH ATTRIBUTES
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp
.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE ATTRIBUTE VALUE
_
Interface Stability Committed
.TE
.SH SEE ALSO
\fBallocb\fR(9F), \fBddi_intr_get_pri\fR(9F),
\fBddi_intr_get_softint_pri\fR(9F), \fBfreeb\fR(9F), \fBdatab\fR(9S),
\fBfree_rtn\fR(9S)
.sp
.LP
\fIWriting Device Drivers\fR
.sp
.LP
\fISTREAMS Programming Guide\fR
|
