1 NVLIST_ALLOC(9F) Kernel Functions for Drivers NVLIST_ALLOC(9F)
2
3
4
5 NAME
6 nvlist_alloc, nvlist_free, nvlist_size, nvlist_pack, nvlist_unpack,
7 nvlist_dup, nv_alloc_init, nv_alloc_fini, nvlist_xalloc, nvlist_xpack,
8 nvlist_xunpack, nvlist_xdup, nvlist_merge - Manage a name-value pair
9 list
10
11 SYNOPSIS
12 #include <sys/nvpair.h>
13
14 List Manipulation:
15
16 int nvlist_alloc(nvlist_t **nvlp, uint_t nvflag,
17 int kmflag);
18
19
20 int nvlist_xalloc(nvlist_t **nvlp, uint_t nvflag, nv_alloc_t *nva);
21
22
23 void nvlist_free(nvlist_t *nvl);
24
25
26 int nvlist_size(nvlist_t *nvl, size_t *size, int encoding);
27
28
29 int nvlist_pack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
30 int flag);
31
32
33 int nvlist_xpack(nvlist_t *nvl, char **bufp, size_t *buflen, int encoding,
34 nv_alloc_t *nva);
35
36
37 int nvlist_unpack(char *buf, size_t buflen, nvlist_t **nvlp, int flag);
38
39
40 int nvlist_xunpack(char *buf, size_t buflen, nvlist_t **nvlp,
41 nv_alloc_t *nva);
42
43
44 int nvlist_dup(nvlist_t *nvl, nvlist_t **nvlp, int flag);
45
46
47 int nvlist_xdup(nvlist_t *nvl, nvlist_t **nvlp, nv_alloc_t *nva);
48
49
50 int nvlist_merge(nvlist_t *dst, nvlist_t *nvl, int flag);
51
52
53 Pluggable Allocator Configuration:
54
55 nv_alloc_t *nvlist_lookup_nv_alloc(nvlist_t *);
56
57
58 int nv_alloc_init(nv_alloc_t *nva,
59 const nv_alloc_ops_t * nvo,/* args */ ...);
60
61
62 void nv_alloc_reset(nv_alloc_t *nva);
63
64
65 void nv_alloc_fini(nv_alloc_t *nva);
66
67
68 Pluggable Allocation Initialization with Fixed Allocator:
69
70 int nv_alloc_init(nv_alloc_t *nva,
71 nv_fixed_ops, void * bufptr, size_t sz);
72
73
74 INTERFACE LEVEL
75 Solaris DDI specific (Solaris DDI)
76
77 PARAMETERS
78 nvlp
79 Address of a pointer to list of name-value pairs
80 (nvlist_t).
81
82
83 nvflag
84 Specify bit fields defining nvlist_t properties:
85
86 NV_UNIQUE_NAME
87 nvpair names are unique.
88
89
90 NV_UNIQUE_NAME_TYPE
91 Name-data type combination is unique
92
93
94
95 kmflag
96 Kernel memory allocation policy, either KM_SLEEP or
97 KM_NOSLEEP.
98
99
100 nvl
101 nvlist_t to be processed.
102
103
104 dst
105 Destination nvlist_t.
106
107
108 size
109 Pointer to buffer to contain the encoded size.
110
111
112 bufp
113 Address of buffer to pack nvlist into. Must be 8-byte
114 aligned. If NULL, library will allocate memory.
115
116
117 buf
118 Buffer containing packed nvlist_t.
119
120
121 buflen
122 Size of buffer bufp or buf points to.
123
124
125 encoding
126 Encoding method for packing.
127
128
129 nvo
130 Pluggable allocator operations pointer (nv_alloc_ops_t).
131
132
133 nva
134 Points to a nv_alloc_t structure to be used for the
135 specified nvlist_t.
136
137
138 DESCRIPTION
139 List Manipulation:
140
141
142 The nvlist_alloc() function allocates a new name-value pair list and
143 updates nvlp to point to the handle. The argument nvflag specifies
144 nvlist_t properties to remain persistent across packing, unpacking, and
145 duplication.
146
147
148 If NV_UNIQUE_NAME is specified for nvflag, existing nvpairs with
149 matching names are removed before the new nvpair is added. If
150 NV_UNIQUE_NAME_TYPE is specified for nvflag, existing nvpairs with
151 matching names and data types are removed before the new nvpair is
152 added. See nvlist_add_byte(9F) for more details.
153
154
155 The nvlist_xalloc() function differs from nvlist_alloc() in that
156 nvlist_xalloc() can use a different allocator, as described in the
157 Pluggable Allocators section.
158
159
160 The nvlist_free() function frees a name-value pair list. If nvl is a
161 null pointer, no action occurs.
162
163
164 The nvlist_size() function returns the minimum size of a contiguous
165 buffer large enough to pack nvl. The encoding parameter specifies the
166 method of encoding when packing nvl. Supported encoding methods are:
167
168 NV_ENCODE_NATIVE
169 Straight bcopy() as described in bcopy(9F).
170
171
172 NV_ENCODE_XDR
173 Use XDR encoding, suitable for sending to another
174 host.
175
176
177
178 The nvlist_pack() function packs nvl into contiguous memory starting at
179 *bufp. The encoding parameter specifies the method of encoding (see
180 above).
181
182 o If *bufp is not NULL, *bufp is expected to be a caller-
183 allocated buffer of size *buflen. The kmflag argument is
184 ignored.
185
186 o If *bufp is NULL, the library allocates memory and updates
187 *bufp to point to the memory and updates *buflen to contain
188 the size of the allocated memory. The value of kmflag
189 indicates the memory allocation policy
190
191
192 The nvlist_xpack() function differs from nvlist_pack() in that
193 nvlist_xpack() can use a different allocator.
194
195
196 The nvlist_unpack() function takes a buffer with a packed nvlist_t and
197 unpacks it into a searchable nvlist_t. The library allocates memory for
198 nvlist_t. The caller is responsible for freeing the memory by calling
199 nvlist_free().
200
201
202 The nvlist_xunpack() function differs from nvlist_unpack() in that
203 nvlist_xunpack() can use a different allocator.
204
205
206 The nvlist_dup() function makes a copy of nvl and updates nvlp to point
207 to the copy.
208
209
210 The nvlist_xdup() function differs from nvlist_dup() in that
211 nvlist_xdup() can use a different allocator.
212
213
214 The nvlist_merge() function adds copies of all name-value pairs from
215 nvlist_t nvl to nvlist_t dst. Name-value pairs in dst are replaced with
216 name-value pairs from nvl which have identical names (if dst has the
217 type NV_UNIQUE_NAME), or identical names and types (if dst has the type
218 NV_UNIQUE_NAME_TYPE).
219
220
221 The nvlist_lookup_nv_alloc() function retrieves the pointer to the
222 allocator used when manipulating a name-value pair list.
223
224 PLUGGABLE ALLOCATORS
225 Using Pluggable Allocators:
226
227
228 The nv_alloc_init(), nv_alloc_reset() and nv_alloc_fini() functions
229 provide an interface that specifies the allocator to be used when
230 manipulating a name-value pair list.
231
232
233 The nv_alloc_init() determines allocator properties and puts them into
234 the nva argument. You need to specify the nv_arg argument, the nvo
235 argument and an optional variable argument list. The optional
236 arguments are passed to the (*nv_ao_init()) function.
237
238
239 The nva argument must be passed to nvlist_xalloc(), nvlist_xpack(),
240 nvlist_xunpack() and nvlist_xdup().
241
242
243 The nv_alloc_reset() function resets the allocator properties to the
244 data specified by nv_alloc_init(). When no (*nv_ao_reset()) function is
245 specified, nv_alloc_reset() is without effect.
246
247
248 The nv_alloc_fini() destroys the allocator properties determined by
249 nv_alloc_init(). When a (*nv_ao_fini()) routine is specified, it is
250 called from nv_alloc_fini().
251
252
253 The disposition of the allocated objects and the memory used to store
254 them is left to the allocator implementation.
255
256
257 The `nv_alloc_sleep' and `nv_alloc_nosleep' nv_alloc_t pointers may be
258 used with nvlist_xalloc to mimic the behavior of nvlist_alloc with
259 KM_SLEEP and KM_NOSLEEP, respectively.
260
261 o nv_alloc_nosleep
262 o nv_alloc_sleep
263
264
265
266 The nvpair framework provides a fixed-buffer allocator, accessible via
267 nv_fixed_ops.
268
269 o nv_fixed_ops
270
271
272
273 Given a buffer size and address, the fixed-buffer allocator allows for
274 the creation of nvlists in contexts where malloc or kmem_alloc services
275 may not be available. The fixed-buffer allocator is designed primarily
276 to support the creation of nvlists.
277
278
279 Memory freed using nvlist_free(), pair-removal, or similar routines is
280 not reclaimed.
281
282
283 When used to initialize the fixed-buffer allocator, nv_alloc_init
284 should be called as follows:
285
286 int nv_alloc_init(nv_alloc_t *nva, const nv_alloc_ops_t *nvo,
287 void *bufptr, size_t sz);
288
289
290
291 When invoked on a fixed-buffer, the nv_alloc_reset() function resets
292 the fixed buffer and prepares it for re-use. The framework consumer is
293 responsible for freeing the buffer passed to nv_alloc_init().
294
295 CREATING PLUGGABLE ALLOCATORS
296 Any producer of name-value pairs may possibily specify his own
297 allocator routines. You must provide the following pluggable allocator
298 operations in the allocator implementation.
299
300 int (*nv_ao_init)(nv_alloc_t *nva, va_list nv_valist);
301 void (*nv_ao_fini)(nv_alloc_t *nva);
302 void *(*nv_ao_alloc)(nv_alloc_t *nva, size_t sz);
303 void (*nv_ao_reset)(nv_alloc_t *nva);
304 void (*nv_ao_free)(nv_alloc_t *nva, void *buf, size_t sz);
305
306
307
308 The nva argument of the allocator implementation is always the first
309 argument.
310
311
312 The optional (*nv_ao_init() ) function is responsible for filling the
313 data specified by nv_alloc_init() into the nva_arg() argument. The
314 (*nv_ao_init()) function is called only when nv_alloc_init() is
315 executed.
316
317
318 The optional (*nv_ao_fini()) function is responsible for the cleanup of
319 the allocator implementation. It is called by nv_alloc_fini().
320
321
322 The required (*nv_ao_alloc()) function is used in the nvpair allocation
323 framework for memory allocation. The sz argument specifies the size of
324 the requested buffer.
325
326
327 The optional (*nv_ao_reset()) function is responsible for resetting the
328 nva_arg argument to the data specified by nv_alloc_init().
329
330
331 The required (*nv_ao_free()) function is used in the nvpair allocator
332 framework for memory de-allocation. The argument buf is a pointer to a
333 block previously allocated by (*nv_ao_alloc()) function. The size
334 argument sz must exactly match the original allocation.
335
336
337 The disposition of the allocated objects and the memory used to store
338 them is left to the allocator implementation.
339
340 RETURN VALUES
341 For nvlist_alloc(), nvlist_dup(), nvlist_xalloc(), and nvlist_xdup():
342
343 0
344 success
345
346
347 EINVAL
348 invalid argument
349
350
351 ENOMEM
352 insufficient memory
353
354
355
356 For nvlist_pack(), nvlist_unpack(), nvlist_xpack(), and
357 nvlist_xunpack():
358
359 0
360 success
361
362
363 EINVAL
364 invalid argument
365
366
367 ENOMEM
368 insufficient memory
369
370
371 EFAULT
372 encode/decode error
373
374
375 ENOTSUP
376 encode/decode method not supported
377
378
379
380 For nvlist_size():
381
382 0
383 success
384
385
386 EINVAL
387 invalid argument
388
389
390
391 For nvlist_lookup_nv_alloc():
392
393
394 pointer to the allocator
395
396 USAGE
397 The fixed-buffer allocator is very simple allocator. It uses a pre-
398 allocated buffer for memory allocations and it can be used in interrupt
399 context. You are responsible for allocation and de-allocation for the
400 pre-allocated buffer.
401
402 EXAMPLES
403 /*
404 * using the fixed-buffer allocator.
405 */
406 #include <sys/nvpair.h>
407
408 /* initialize the nvpair allocator framework */
409 static nv_alloc_t *
410 init(char *buf, size_t size)
411 {
412 nv_alloc_t *nvap;
413
414 if ((nvap = kmem_alloc(sizeof(nv_alloc_t), KM_SLEEP)) == NULL)
415 return (NULL);
416
417 if (nv_alloc_init(nvap, nv_fixed_ops, buf, size) == 0)
418 return (nvap);
419
420 return (NULL);
421 }
422
423 static void
424 fini(nv_alloc_t *nvap)
425 {
426 nv_alloc_fini(nvap);
427 kmem_free(nvap, sizeof(nv_alloc_t));
428 }
429 static int
430 interrupt_context(nv_alloc_t *nva)
431 {
432 nvlist_t *nvl;
433 int error;
434
435 if ((error = nvlist_xalloc(&nvl, NV_UNIQUE_NAME, nva)) != 0)
436 return (-1);
437
438 if ((error = nvlist_add_int32(nvl, "name", 1234)) == 0)
439 error = send_nvl(nvl);
440
441 nvlist_free(nvl);
442 return (error);
443 }
444
445
446 CONTEXT
447 The nvlist_alloc(), nvlist_pack(), nvlist_unpack(), and nvlist_dup()
448 functions can be called from interrupt context only if the KM_NOSLEEP
449 flag is set. They can be called from user context with any valid flag.
450
451
452 The nvlist_xalloc(), nvlist_xpack(), nvlist_xunpack(), and
453 nvlist_xdup() functions can be called from interrupt context only if
454 (1) the default allocator is used and the KM_NOSLEEP flag is set or (2)
455 the specified allocator did not sleep for free memory (for example, it
456 uses a pre-allocated buffer for memory allocations).
457
458
459 These functions can be called from user or kernel context with any
460 valid flag.
461
462
463
464 February 15, 2016 NVLIST_ALLOC(9F)