1.\" 2.\" This file and its contents are supplied under the terms of the 3.\" Common Development and Distribution License ("CDDL"), version 1.0. 4.\" You may only use this file in accordance with the terms of version 5.\" 1.0 of the CDDL. 6.\" 7.\" A full copy of the text of the CDDL should have accompanied this 8.\" source. A copy of the CDDL is also available via the Internet at 9.\" http://www.illumos.org/license/CDDL. 10.\" 11.\" 12.\" Copyright 2017, Richard Lowe. 13.\" 14.Dd Jan 18, 2017 15.Dt VMEM_CREATE 9F 16.Os 17.Sh NAME 18.Nm vmem_create , 19.Nm vmem_xcreate , 20.Nm vmem_destroy 21.Nd create and destroy vmem arenas 22.Sh SYNOPSIS 23.In sys/vmem.h 24.Vt "typedef struct vmem vmem_t;" 25.Vt "typedef void *(vmem_alloc_t)(vmem_t *, size_t, int);" 26.Vt "typedef void (vmem_free_t)(vmem_t *, void *, size_t);" 27.Vt "typedef void *(vmem_ximport_t)(vmem_t *, size_t *, size_t, int);" 28.Ft vmem_t * 29.Fo vmem_create 30.Fa "const char *name" 31.Fa "void *base" 32.Fa "size_t size" 33.Fa "size_t quantum" 34.Fa "vmem_alloc_t *afunc" 35.Fa "vmem_free_t *ffunc" 36.Fa "vmem_t *source" 37.Fa "size_t qcache_max" 38.Fa "int vmflag" 39.Fc 40.Ft vmem_t * 41.Fo vmem_xcreate 42.Fa "const char *name" 43.Fa "void *base" 44.Fa "size_t size" 45.Fa "size_t quantum" 46.Fa "vmem_ximport_t *afunc" 47.Fa "vmem_free_t *ffunc" 48.Fa "vmem_t *source" 49.Fa "size_t qcache_max" 50.Fa "int vmflag" 51.Fc 52.Ft void 53.Fo vmem_destroy 54.Fa "vmem_t *vmp" 55.Fc 56.Sh INTERFACE LEVEL 57illumos DDI specific 58.Sh PARAMETERS 59.Bl -tag -width Ds 60.It Fa name 61A character string giving a name to the vmem 62arena to be created. 63.It Fa base 64An address indicating the lowest possible value in the arena. 65.It Fa size 66The size of the arena to create. 67.It Fa quantum 68The arena's 69.Dq quantum . 70The granularity of the arena. 71The amount allocated at minimum by each request. 72Must be a power of 2. 73.It Fa afunc 74A function which is called to import new spans from 75.Fa source , 76which may be 77.Dv NULL 78if this arena does not import from another. 79When calling 80.Fn vmem_create , 81.Fa afunc 82is a 83.Vt vmem_alloc_t , 84a function taking three parameters and returning a pointer to 85.Vt void 86(the imported space): 87.Bl -tag -width Ds 88.It Fa "vmem_t *" 89The source arena from which we'll import. 90The 91.Fa source 92argument to 93.Fn vmem_create . 94.It Fa size_t 95The size to import. 96.It Fa int 97The 98.Fa vmflag 99argument used for the import. 100.El 101.Pp 102When calling 103.Fn vmem_xcreate , 104.Fa afunc 105is a 106.Vt vmem_ximport_t , 107a function taking four parameters and returning a pointer to 108.Vt void 109(the imported space): 110.Bl -tag -width Ds 111.It Fa "vmem_t *" 112The source arena from which we'll import. 113The 114.Fa source 115argument to 116.Fn vmem_xcreate . 117.It Fa "size_t *" 118The size of the import. 119.Fa afunc 120may 121.Em increase 122this size if that is desirable, but must never decrease it. 123.It Fa size_t 124The desired alignment of the imported space. 125.It Fa int 126The 127.Fa vmflag 128argument used for the import. 129.El 130.It Fa ffunc 131A function which is called to return spans to 132.Fa source , 133which may be 134.Dv NULL 135if this arena does not import from another. 136This is a 137.Vt vmem_free_t , 138a function taking three parameters and returning void: 139.Bl -tag -width Ds 140.It Fa "vmem_t" 141The arena to which space is being returned. 142The 143.Fa source 144argument to 145.Fn vmem_create 146or 147.Fn vmem_xcreate . 148.It Fa "void *" 149The span being returned to the source arena. 150.It Fa "size_t" 151The size of the span being returned to the source arena. 152.El 153.It Fa source 154An arena from which this arena will import, 155which may be 156.Dv NULL 157if this arena does not import from another. 158.It Fa qcache_max 159Each arena offers caching of integer multiples of 160.Fa quantum 161up to 162.Fa qcache_max , 163which may be 0. 164.It Fa vmflag 165A bitmask of flags indicating the characteristics of this arena. 166.Bl -tag -width Ds 167.It Dv VMC_IDENTIFIER 168The arena represents arbitrary integer identifiers, rather than virtual 169memory. 170.El 171.It Fa vmp 172A pointer to the vmem arena to be destroyed. 173.El 174.Sh DESCRIPTION 175A 176.Em vmem arena 177is a section of an arbitrary address space (a range of integer addresses). 178This commonly represents virtual memory, but can in fact be an arbitrary set 179of integers. 180The 181.Dv VMC_IDENTIFIER 182flag set at arena creation time differentiates between these two cases. 183.Pp 184The 185.Fa afunc , 186.Fa ffunc , and 187.Fa source 188arguments combine to support a hierarchical structure of arenas, each 189importing from a single parent (the 190.Fa source ) . 191The 192.Fn vmem_create 193and 194.Fn vmem_xcreate 195functions differ in that the latter provides an interface for 196.Fa afunc 197to alter the size of the span imported from 198.Fa source . 199It is only legal to 200.Em increase 201this size. 202.Sh CONTEXT 203These functions can be called from user or kernel context. 204.Sh RETURN VALUES 205Upon successful completion the 206.Fn vmem_create 207and 208.Fn vmem_xcreate 209functions return a pointer to a vmem arena. 210Otherwise, 211.Dv NULL 212is returned to indicate the arena could not be created. 213.Sh SEE ALSO 214.Xr vmem 9 , 215.Xr vmem_add 9F , 216.Xr vmem_alloc 9F 217