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)