15a342f14SRichard Lowe.\" 25a342f14SRichard Lowe.\" This file and its contents are supplied under the terms of the 35a342f14SRichard Lowe.\" Common Development and Distribution License ("CDDL"), version 1.0. 45a342f14SRichard Lowe.\" You may only use this file in accordance with the terms of version 55a342f14SRichard Lowe.\" 1.0 of the CDDL. 65a342f14SRichard Lowe.\" 75a342f14SRichard Lowe.\" A full copy of the text of the CDDL should have accompanied this 85a342f14SRichard Lowe.\" source. A copy of the CDDL is also available via the Internet at 95a342f14SRichard Lowe.\" http://www.illumos.org/license/CDDL. 105a342f14SRichard Lowe.\" 115a342f14SRichard Lowe.\" 125a342f14SRichard Lowe.\" Copyright 2017, Richard Lowe. 135a342f14SRichard Lowe.\" 145a342f14SRichard Lowe.Dd Jan 18, 2017 155a342f14SRichard Lowe.Dt VMEM_CREATE 9F 165a342f14SRichard Lowe.Os 175a342f14SRichard Lowe.Sh NAME 185a342f14SRichard Lowe.Nm vmem_create , 195a342f14SRichard Lowe.Nm vmem_xcreate , 205a342f14SRichard Lowe.Nm vmem_destroy 215a342f14SRichard Lowe.Nd create and destroy vmem arenas 225a342f14SRichard Lowe.Sh SYNOPSIS 235a342f14SRichard Lowe.In sys/vmem.h 245a342f14SRichard Lowe.Vt "typedef struct vmem vmem_t;" 255a342f14SRichard Lowe.Vt "typedef void *(vmem_alloc_t)(vmem_t *, size_t, int);" 265a342f14SRichard Lowe.Vt "typedef void (vmem_free_t)(vmem_t *, void *, size_t);" 275a342f14SRichard Lowe.Vt "typedef void *(vmem_ximport_t)(vmem_t *, size_t *, size_t, int);" 285a342f14SRichard Lowe.Ft vmem_t * 295a342f14SRichard Lowe.Fo vmem_create 305a342f14SRichard Lowe.Fa "const char *name" 315a342f14SRichard Lowe.Fa "void *base" 325a342f14SRichard Lowe.Fa "size_t size" 335a342f14SRichard Lowe.Fa "size_t quantum" 345a342f14SRichard Lowe.Fa "vmem_alloc_t *afunc" 355a342f14SRichard Lowe.Fa "vmem_free_t *ffunc" 365a342f14SRichard Lowe.Fa "vmem_t *source" 375a342f14SRichard Lowe.Fa "size_t qcache_max" 385a342f14SRichard Lowe.Fa "int vmflag" 395a342f14SRichard Lowe.Fc 405a342f14SRichard Lowe.Ft vmem_t * 415a342f14SRichard Lowe.Fo vmem_xcreate 425a342f14SRichard Lowe.Fa "const char *name" 435a342f14SRichard Lowe.Fa "void *base" 445a342f14SRichard Lowe.Fa "size_t size" 455a342f14SRichard Lowe.Fa "size_t quantum" 465a342f14SRichard Lowe.Fa "vmem_ximport_t *afunc" 475a342f14SRichard Lowe.Fa "vmem_free_t *ffunc" 485a342f14SRichard Lowe.Fa "vmem_t *source" 495a342f14SRichard Lowe.Fa "size_t qcache_max" 505a342f14SRichard Lowe.Fa "int vmflag" 515a342f14SRichard Lowe.Fc 525a342f14SRichard Lowe.Ft void 535a342f14SRichard Lowe.Fo vmem_destroy 545a342f14SRichard Lowe.Fa "vmem_t *vmp" 555a342f14SRichard Lowe.Fc 565a342f14SRichard Lowe.Sh INTERFACE LEVEL 575a342f14SRichard Loweillumos DDI specific 585a342f14SRichard Lowe.Sh PARAMETERS 595a342f14SRichard Lowe.Bl -tag -width Ds 605a342f14SRichard Lowe.It Fa name 615a342f14SRichard LoweA character string giving a name to the vmem 625a342f14SRichard Lowearena to be created. 635a342f14SRichard Lowe.It Fa base 645a342f14SRichard LoweAn address indicating the lowest possible value in the arena. 655a342f14SRichard Lowe.It Fa size 665a342f14SRichard LoweThe size of the arena to create. 675a342f14SRichard Lowe.It Fa quantum 685a342f14SRichard LoweThe arena's 695a342f14SRichard Lowe.Dq quantum . 70*72d3dbb9SYuri PankovThe granularity of the arena. 71*72d3dbb9SYuri PankovThe amount allocated at minimum by each request. 72*72d3dbb9SYuri PankovMust be a power of 2. 735a342f14SRichard Lowe.It Fa afunc 745a342f14SRichard LoweA function which is called to import new spans from 755a342f14SRichard Lowe.Fa source , 765a342f14SRichard Lowewhich may be 775a342f14SRichard Lowe.Dv NULL 785a342f14SRichard Loweif this arena does not import from another. 795a342f14SRichard LoweWhen calling 805a342f14SRichard Lowe.Fn vmem_create , 815a342f14SRichard Lowe.Fa afunc 825a342f14SRichard Loweis a 835a342f14SRichard Lowe.Vt vmem_alloc_t , 845a342f14SRichard Lowea function taking three parameters and returning a pointer to 855a342f14SRichard Lowe.Vt void 865a342f14SRichard Lowe(the imported space): 875a342f14SRichard Lowe.Bl -tag -width Ds 885a342f14SRichard Lowe.It Fa "vmem_t *" 89*72d3dbb9SYuri PankovThe source arena from which we'll import. 90*72d3dbb9SYuri PankovThe 915a342f14SRichard Lowe.Fa source 925a342f14SRichard Loweargument to 935a342f14SRichard Lowe.Fn vmem_create . 945a342f14SRichard Lowe.It Fa size_t 955a342f14SRichard LoweThe size to import. 965a342f14SRichard Lowe.It Fa int 975a342f14SRichard LoweThe 985a342f14SRichard Lowe.Fa vmflag 995a342f14SRichard Loweargument used for the import. 1005a342f14SRichard Lowe.El 1015a342f14SRichard Lowe.Pp 1025a342f14SRichard LoweWhen calling 1035a342f14SRichard Lowe.Fn vmem_xcreate , 1045a342f14SRichard Lowe.Fa afunc 1055a342f14SRichard Loweis a 1065a342f14SRichard Lowe.Vt vmem_ximport_t , 1075a342f14SRichard Lowea function taking four parameters and returning a pointer to 1085a342f14SRichard Lowe.Vt void 1095a342f14SRichard Lowe(the imported space): 1105a342f14SRichard Lowe.Bl -tag -width Ds 1115a342f14SRichard Lowe.It Fa "vmem_t *" 112*72d3dbb9SYuri PankovThe source arena from which we'll import. 113*72d3dbb9SYuri PankovThe 1145a342f14SRichard Lowe.Fa source 1155a342f14SRichard Loweargument to 1165a342f14SRichard Lowe.Fn vmem_xcreate . 1175a342f14SRichard Lowe.It Fa "size_t *" 1185a342f14SRichard LoweThe size of the import. 1195a342f14SRichard Lowe.Fa afunc 1205a342f14SRichard Lowemay 1215a342f14SRichard Lowe.Em increase 1225a342f14SRichard Lowethis size if that is desirable, but must never decrease it. 1235a342f14SRichard Lowe.It Fa size_t 1245a342f14SRichard LoweThe desired alignment of the imported space. 1255a342f14SRichard Lowe.It Fa int 1265a342f14SRichard LoweThe 1275a342f14SRichard Lowe.Fa vmflag 1285a342f14SRichard Loweargument used for the import. 1295a342f14SRichard Lowe.El 1305a342f14SRichard Lowe.It Fa ffunc 1315a342f14SRichard LoweA function which is called to return spans to 1325a342f14SRichard Lowe.Fa source , 1335a342f14SRichard Lowewhich may be 1345a342f14SRichard Lowe.Dv NULL 1355a342f14SRichard Loweif this arena does not import from another. 1365a342f14SRichard LoweThis is a 1375a342f14SRichard Lowe.Vt vmem_free_t , 1385a342f14SRichard Lowea function taking three parameters and returning void: 1395a342f14SRichard Lowe.Bl -tag -width Ds 1405a342f14SRichard Lowe.It Fa "vmem_t" 141*72d3dbb9SYuri PankovThe arena to which space is being returned. 142*72d3dbb9SYuri PankovThe 1435a342f14SRichard Lowe.Fa source 1445a342f14SRichard Loweargument to 1455a342f14SRichard Lowe.Fn vmem_create 1465a342f14SRichard Loweor 1475a342f14SRichard Lowe.Fn vmem_xcreate . 1485a342f14SRichard Lowe.It Fa "void *" 1495a342f14SRichard LoweThe span being returned to the source arena. 1505a342f14SRichard Lowe.It Fa "size_t" 1515a342f14SRichard LoweThe size of the span being returned to the source arena. 1525a342f14SRichard Lowe.El 1535a342f14SRichard Lowe.It Fa source 1545a342f14SRichard LoweAn arena from which this arena will import, 1555a342f14SRichard Lowewhich may be 1565a342f14SRichard Lowe.Dv NULL 1575a342f14SRichard Loweif this arena does not import from another. 1585a342f14SRichard Lowe.It Fa qcache_max 1595a342f14SRichard LoweEach arena offers caching of integer multiples of 1605a342f14SRichard Lowe.Fa quantum 1615a342f14SRichard Loweup to 1625a342f14SRichard Lowe.Fa qcache_max , 1635a342f14SRichard Lowewhich may be 0. 1645a342f14SRichard Lowe.It Fa vmflag 1655a342f14SRichard LoweA bitmask of flags indicating the characteristics of this arena. 1665a342f14SRichard Lowe.Bl -tag -width Ds 1675a342f14SRichard Lowe.It Dv VMC_IDENTIFIER 1685a342f14SRichard LoweThe arena represents arbitrary integer identifiers, rather than virtual 1695a342f14SRichard Lowememory. 1705a342f14SRichard Lowe.El 1715a342f14SRichard Lowe.It Fa vmp 1725a342f14SRichard LoweA pointer to the vmem arena to be destroyed. 1735a342f14SRichard Lowe.El 1745a342f14SRichard Lowe.Sh DESCRIPTION 1755a342f14SRichard LoweA 1765a342f14SRichard Lowe.Em vmem arena 1775a342f14SRichard Loweis a section of an arbitrary address space (a range of integer addresses). 1785a342f14SRichard LoweThis commonly represents virtual memory, but can in fact be an arbitrary set 179*72d3dbb9SYuri Pankovof integers. 180*72d3dbb9SYuri PankovThe 1815a342f14SRichard Lowe.Dv VMC_IDENTIFIER 1825a342f14SRichard Loweflag set at arena creation time differentiates between these two cases. 1835a342f14SRichard Lowe.Pp 1845a342f14SRichard LoweThe 1855a342f14SRichard Lowe.Fa afunc , 1865a342f14SRichard Lowe.Fa ffunc , and 1875a342f14SRichard Lowe.Fa source 1885a342f14SRichard Lowearguments combine to support a hierarchical structure of arenas, each 1895a342f14SRichard Loweimporting from a single parent (the 1905a342f14SRichard Lowe.Fa source ) . 1915a342f14SRichard LoweThe 1925a342f14SRichard Lowe.Fn vmem_create 1935a342f14SRichard Loweand 1945a342f14SRichard Lowe.Fn vmem_xcreate 1955a342f14SRichard Lowefunctions differ in that the latter provides an interface for 1965a342f14SRichard Lowe.Fa afunc 1975a342f14SRichard Loweto alter the size of the span imported from 1985a342f14SRichard Lowe.Fa source . 1995a342f14SRichard LoweIt is only legal to 2005a342f14SRichard Lowe.Em increase 2015a342f14SRichard Lowethis size. 2025a342f14SRichard Lowe.Sh CONTEXT 2035a342f14SRichard LoweThese functions can be called from user or kernel context. 2045a342f14SRichard Lowe.Sh RETURN VALUES 2055a342f14SRichard LoweUpon successful completion the 2065a342f14SRichard Lowe.Fn vmem_create 2075a342f14SRichard Loweand 2085a342f14SRichard Lowe.Fn vmem_xcreate 209*72d3dbb9SYuri Pankovfunctions return a pointer to a vmem arena. 210*72d3dbb9SYuri PankovOtherwise, 2115a342f14SRichard Lowe.Dv NULL 2125a342f14SRichard Loweis returned to indicate the arena could not be created. 2135a342f14SRichard Lowe.Sh SEE ALSO 2145a342f14SRichard Lowe.Xr vmem 9 , 2155a342f14SRichard Lowe.Xr vmem_add 9F , 2165a342f14SRichard Lowe.Xr vmem_alloc 9F 217