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_ALLOC 9F 16.Os 17.Sh NAME 18.Nm vmem_alloc , 19.Nm vmem_xalloc , 20.Nm vmem_free , 21.Nm vmem_xfree 22.Nd allocate and free segments from a vmem arena 23.Sh SYNOPSIS 24.In sys/vmem.h 25.Ft void * 26.Fo vmem_alloc 27.Fa "vmem_t *vmp" 28.Fa "size_t size" 29.Fa "int vmflag" 30.Fc 31.Ft void * 32.Fo vmem_xalloc 33.Fa "vmem_t *vmp" 34.Fa "size_t size" 35.Fa "size_t align_arg" 36.Fa "size_t phase" 37.Fa "size_t nocross" 38.Fa "void *minaddr" 39.Fa "void *maxaddr" 40.Fa "int vmflag" 41.Fc 42.Ft void 43.Fo vmem_free 44.Fa "vmem_t *vmp" 45.Fa "void *vaddr" 46.Fa "size_t size" 47.Fc 48.Ft void 49.Fo vmem_xfree 50.Fa "vmem_t *vmp" 51.Fa "void *vaddr" 52.Fa "size_t size" 53.Fc 54.Sh INTERFACE LEVEL 55illumos DDI specific 56.Sh PARAMETERS 57.Bl -tag -width Ds 58.It Fa vmp 59The vmem arena from which to allocate or free. 60.It Fa size 61The size of the segment to allocate or free. 62.It Fa vmflag 63A bitmask of flags controlling the behaviour of the allocation. 64There are two meaningful groups of flags. 65.Dv VM_SLEEP 66or 67.Dv VM_NOSLEEP 68must be specified, and indicate whether the allocation may block. 69A 70.Dv VM_SLEEP 71allocation can never fail but may block indefinitely. 72.Pp 73The allocation policy may be specified by one of the following flags: 74.Bl -tag -width Ds 75.It Dv VM_BESTFIT 76Take the segment from the smallest free segment that could satisfy this 77allocation. 78.It Dv VM_FIRSTFIT 79Take the segment from the first free segment found that could satisfy this 80allocation. 81.It Dv VM_NEXTFIT 82Take the segment from the segment after the one previously allocated. 83This 84provides sequential behaviour useful when allocating identifiers from a 85.Dv VMC_IDENTIFIER 86arena. 87.It Dv VM_ENDALLOC 88May be specified in combination with 89.Dv VM_BESTFIT , 90.Dv VM_FIRSTFIT 91or the default policy to indicate that the higher addresses should be 92preferred. 93.El 94.Pp 95The default (unnamed) allocation policy is 96.Dq "instant fit" , 97an approximation of 98.Dv VM_BESTFIT 99in guaranteed constant time. 100.It Fa align_arg 101The minimum alignment of the allocation. 102If 0, the allocated segment will be aligned as the arena's quantum. 103.It Fa phase 104The allocated segment must be 105.Fa phase 106bytes from the alignment boundary. 107.It Fa nocross 108The allocated segment may not straddle a 109.Fa nocross 110alignment boundary. 111.It Fa minaddr 112The minimum address at which the segment may be allocated. 113.It Fa maxaddr 114The maximum address which may be included in the segment. 115.It Fa vaddr 116The address of the segment which 117.Fn vmem_free 118or 119.Fn vmem_xfree 120should free. 121.El 122.Sh DESCRIPTION 123The 124.Fn vmem_alloc 125and 126.Fn vmem_xalloc 127functions allocate a segment of 128.Fa size 129length from the vmem arena 130.Fa vmp . 131.Pp 132The 133.Fa vmflag 134argument controls the behaviour of the allocation, as described in 135.Sx PARAMETERS . 136.Pp 137For allocations with complex requirements, such as those used for DMA 138.Fn vmem_xalloc 139takes additional arguments allowing those requirements to be expressed. 140.Pp 141Segments allocated with 142.Fn vmem_xalloc 143must always be freed with 144.Fn vmem_xfree , 145since these allocations are uncached. 146.Sh CONTEXT 147This function can be called from either user or kernel context. 148If the 149.Dv VM_NOSLEEP 150flag is specified, it may also be called from interrupt context. 151.Sh RETURN VALUES 152Upon successful completion the 153.Fn vmem_alloc 154and 155.Fn vmem_xalloc 156functions return a pointer to the beginning of the allocated segment. 157In the case of a 158.Dv VMC_IDENTIFIER 159arena, the address of this pointer is the meaningful component, not the value 160to which it points. 161.Pp 162On failure, 163.Dv NULL 164is returned. 165When the 166.Dv VM_SLEEP 167flag is specified, these functions can never fail (but may block forever). 168.Sh SEE ALSO 169.Xr vmem 9 , 170.Xr vmem_contains 9F , 171.Xr vmem_create 9F 172