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_ALLOC 9F 165a342f14SRichard Lowe.Os 175a342f14SRichard Lowe.Sh NAME 185a342f14SRichard Lowe.Nm vmem_alloc , 195a342f14SRichard Lowe.Nm vmem_xalloc , 205a342f14SRichard Lowe.Nm vmem_free , 215a342f14SRichard Lowe.Nm vmem_xfree 225a342f14SRichard Lowe.Nd allocate and free segments from a vmem arena 235a342f14SRichard Lowe.Sh SYNOPSIS 245a342f14SRichard Lowe.In sys/vmem.h 255a342f14SRichard Lowe.Ft void * 265a342f14SRichard Lowe.Fo vmem_alloc 275a342f14SRichard Lowe.Fa "vmem_t *vmp" 285a342f14SRichard Lowe.Fa "size_t size" 295a342f14SRichard Lowe.Fa "int vmflag" 305a342f14SRichard Lowe.Fc 315a342f14SRichard Lowe.Ft void * 325a342f14SRichard Lowe.Fo vmem_xalloc 335a342f14SRichard Lowe.Fa "vmem_t *vmp" 345a342f14SRichard Lowe.Fa "size_t size" 355a342f14SRichard Lowe.Fa "size_t align_arg" 365a342f14SRichard Lowe.Fa "size_t phase" 375a342f14SRichard Lowe.Fa "size_t nocross" 385a342f14SRichard Lowe.Fa "void *minaddr" 395a342f14SRichard Lowe.Fa "void *maxaddr" 405a342f14SRichard Lowe.Fa "int vmflag" 415a342f14SRichard Lowe.Fc 425a342f14SRichard Lowe.Ft void 435a342f14SRichard Lowe.Fo vmem_free 445a342f14SRichard Lowe.Fa "vmem_t *vmp" 455a342f14SRichard Lowe.Fa "void *vaddr" 465a342f14SRichard Lowe.Fa "size_t size" 475a342f14SRichard Lowe.Fc 485a342f14SRichard Lowe.Ft void 495a342f14SRichard Lowe.Fo vmem_xfree 505a342f14SRichard Lowe.Fa "vmem_t *vmp" 515a342f14SRichard Lowe.Fa "void *vaddr" 525a342f14SRichard Lowe.Fa "size_t size" 535a342f14SRichard Lowe.Fc 545a342f14SRichard Lowe.Sh INTERFACE LEVEL 555a342f14SRichard Loweillumos DDI specific 565a342f14SRichard Lowe.Sh PARAMETERS 575a342f14SRichard Lowe.Bl -tag -width Ds 585a342f14SRichard Lowe.It Fa vmp 595a342f14SRichard LoweThe vmem arena from which to allocate or free. 605a342f14SRichard Lowe.It Fa size 615a342f14SRichard LoweThe size of the segment to allocate or free. 625a342f14SRichard Lowe.It Fa vmflag 635a342f14SRichard LoweA bitmask of flags controlling the behaviour of the allocation. 645a342f14SRichard LoweThere are two meaningful groups of flags. 655a342f14SRichard Lowe.Dv VM_SLEEP 665a342f14SRichard Loweor 675a342f14SRichard Lowe.Dv VM_NOSLEEP 68*72d3dbb9SYuri Pankovmust be specified, and indicate whether the allocation may block. 69*72d3dbb9SYuri PankovA 705a342f14SRichard Lowe.Dv VM_SLEEP 715a342f14SRichard Loweallocation can never fail but may block indefinitely. 725a342f14SRichard Lowe.Pp 735a342f14SRichard LoweThe allocation policy may be specified by one of the following flags: 745a342f14SRichard Lowe.Bl -tag -width Ds 755a342f14SRichard Lowe.It Dv VM_BESTFIT 76*72d3dbb9SYuri PankovTake the segment from the smallest free segment that could satisfy this 77*72d3dbb9SYuri Pankovallocation. 785a342f14SRichard Lowe.It Dv VM_FIRSTFIT 795a342f14SRichard LoweTake the segment from the first free segment found that could satisfy this 805a342f14SRichard Loweallocation. 815a342f14SRichard Lowe.It Dv VM_NEXTFIT 82*72d3dbb9SYuri PankovTake the segment from the segment after the one previously allocated. 83*72d3dbb9SYuri PankovThis 845a342f14SRichard Loweprovides sequential behaviour useful when allocating identifiers from a 855a342f14SRichard Lowe.Dv VMC_IDENTIFIER 865a342f14SRichard Lowearena. 875a342f14SRichard Lowe.It Dv VM_ENDALLOC 885a342f14SRichard LoweMay be specified in combination with 895a342f14SRichard Lowe.Dv VM_BESTFIT , 905a342f14SRichard Lowe.Dv VM_FIRSTFIT 915a342f14SRichard Loweor the default policy to indicate that the higher addresses should be 925a342f14SRichard Lowepreferred. 935a342f14SRichard Lowe.El 945a342f14SRichard Lowe.Pp 955a342f14SRichard LoweThe default (unnamed) allocation policy is 965a342f14SRichard Lowe.Dq "instant fit" , 975a342f14SRichard Lowean approximation of 985a342f14SRichard Lowe.Dv VM_BESTFIT 995a342f14SRichard Lowein guaranteed constant time. 1005a342f14SRichard Lowe.It Fa align_arg 101*72d3dbb9SYuri PankovThe minimum alignment of the allocation. 102*72d3dbb9SYuri PankovIf 0, the allocated segment will be aligned as the arena's quantum. 1035a342f14SRichard Lowe.It Fa phase 1045a342f14SRichard LoweThe allocated segment must be 1055a342f14SRichard Lowe.Fa phase 1065a342f14SRichard Lowebytes from the alignment boundary. 1075a342f14SRichard Lowe.It Fa nocross 1085a342f14SRichard LoweThe allocated segment may not straddle a 1095a342f14SRichard Lowe.Fa nocross 1105a342f14SRichard Lowealignment boundary. 1115a342f14SRichard Lowe.It Fa minaddr 1125a342f14SRichard LoweThe minimum address at which the segment may be allocated. 1135a342f14SRichard Lowe.It Fa maxaddr 1145a342f14SRichard LoweThe maximum address which may be included in the segment. 1155a342f14SRichard Lowe.It Fa vaddr 1165a342f14SRichard LoweThe address of the segment which 1175a342f14SRichard Lowe.Fn vmem_free 1185a342f14SRichard Loweor 1195a342f14SRichard Lowe.Fn vmem_xfree 1205a342f14SRichard Loweshould free. 1215a342f14SRichard Lowe.El 1225a342f14SRichard Lowe.Sh DESCRIPTION 1235a342f14SRichard LoweThe 1245a342f14SRichard Lowe.Fn vmem_alloc 1255a342f14SRichard Loweand 1265a342f14SRichard Lowe.Fn vmem_xalloc 1275a342f14SRichard Lowefunctions allocate a segment of 1285a342f14SRichard Lowe.Fa size 1295a342f14SRichard Lowelength from the vmem arena 1305a342f14SRichard Lowe.Fa vmp . 1315a342f14SRichard Lowe.Pp 1325a342f14SRichard LoweThe 1335a342f14SRichard Lowe.Fa vmflag 1345a342f14SRichard Loweargument controls the behaviour of the allocation, as described in 1355a342f14SRichard Lowe.Sx PARAMETERS . 1365a342f14SRichard Lowe.Pp 1375a342f14SRichard LoweFor allocations with complex requirements, such as those used for DMA 1385a342f14SRichard Lowe.Fn vmem_xalloc 1395a342f14SRichard Lowetakes additional arguments allowing those requirements to be expressed. 1405a342f14SRichard Lowe.Pp 1415a342f14SRichard LoweSegments allocated with 1425a342f14SRichard Lowe.Fn vmem_xalloc 1435a342f14SRichard Lowemust always be freed with 1445a342f14SRichard Lowe.Fn vmem_xfree , 1455a342f14SRichard Lowesince these allocations are uncached. 1465a342f14SRichard Lowe.Sh CONTEXT 1475a342f14SRichard LoweThis function can be called from either user or kernel context. 1485a342f14SRichard LoweIf the 1495a342f14SRichard Lowe.Dv VM_NOSLEEP 1505a342f14SRichard Loweflag is specified, it may also be called from interrupt context. 1515a342f14SRichard Lowe.Sh RETURN VALUES 1525a342f14SRichard LoweUpon successful completion the 1535a342f14SRichard Lowe.Fn vmem_alloc 1545a342f14SRichard Loweand 1555a342f14SRichard Lowe.Fn vmem_xalloc 156*72d3dbb9SYuri Pankovfunctions return a pointer to the beginning of the allocated segment. 157*72d3dbb9SYuri PankovIn the case of a 1585a342f14SRichard Lowe.Dv VMC_IDENTIFIER 1595a342f14SRichard Lowearena, the address of this pointer is the meaningful component, not the value 1605a342f14SRichard Loweto which it points. 1615a342f14SRichard Lowe.Pp 1625a342f14SRichard LoweOn failure, 1635a342f14SRichard Lowe.Dv NULL 1645a342f14SRichard Loweis returned. 1655a342f14SRichard LoweWhen the 1665a342f14SRichard Lowe.Dv VM_SLEEP 1675a342f14SRichard Loweflag is specified, these functions can never fail (but may block forever). 1685a342f14SRichard Lowe.Sh SEE ALSO 1695a342f14SRichard Lowe.Xr vmem 9 , 1705a342f14SRichard Lowe.Xr vmem_contains 9F , 1715a342f14SRichard Lowe.Xr vmem_create 9F 172