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. A 69.Dv VM_SLEEP 70allocation can never fail but may block indefinitely. 71.Pp 72The allocation policy may be specified by one of the following flags: 73.Bl -tag -width Ds 74.It Dv VM_BESTFIT 75Take the segment from the smallest free segment that could satisfy this allocation. 76.It Dv VM_FIRSTFIT 77Take the segment from the first free segment found that could satisfy this 78allocation. 79.It Dv VM_NEXTFIT 80Take the segment from the segment after the one previously allocated. This 81provides sequential behaviour useful when allocating identifiers from a 82.Dv VMC_IDENTIFIER 83arena. 84.It Dv VM_ENDALLOC 85May be specified in combination with 86.Dv VM_BESTFIT , 87.Dv VM_FIRSTFIT 88or the default policy to indicate that the higher addresses should be 89preferred. 90.El 91.Pp 92The default (unnamed) allocation policy is 93.Dq "instant fit" , 94an approximation of 95.Dv VM_BESTFIT 96in guaranteed constant time. 97.It Fa align_arg 98The minimum alignment of the allocation. If 0, 99the allocated segment will be aligned as the arena's quantum. 100.It Fa phase 101The allocated segment must be 102.Fa phase 103bytes from the alignment boundary. 104.It Fa nocross 105The allocated segment may not straddle a 106.Fa nocross 107alignment boundary. 108.It Fa minaddr 109The minimum address at which the segment may be allocated. 110.It Fa maxaddr 111The maximum address which may be included in the segment. 112.It Fa vaddr 113The address of the segment which 114.Fn vmem_free 115or 116.Fn vmem_xfree 117should free. 118.El 119.Sh DESCRIPTION 120The 121.Fn vmem_alloc 122and 123.Fn vmem_xalloc 124functions allocate a segment of 125.Fa size 126length from the vmem arena 127.Fa vmp . 128.Pp 129The 130.Fa vmflag 131argument controls the behaviour of the allocation, as described in 132.Sx PARAMETERS . 133.Pp 134For allocations with complex requirements, such as those used for DMA 135.Fn vmem_xalloc 136takes additional arguments allowing those requirements to be expressed. 137.Pp 138Segments allocated with 139.Fn vmem_xalloc 140must always be freed with 141.Fn vmem_xfree , 142since these allocations are uncached. 143.Sh CONTEXT 144This function can be called from either user or kernel context. 145If the 146.Dv VM_NOSLEEP 147flag is specified, it may also be called from interrupt context. 148.Sh RETURN VALUES 149Upon successful completion the 150.Fn vmem_alloc 151and 152.Fn vmem_xalloc 153functions return a pointer to the beginning of the allocated segment. In the 154case of a 155.Dv VMC_IDENTIFIER 156arena, the address of this pointer is the meaningful component, not the value 157to which it points. 158.Pp 159On failure, 160.Dv NULL 161is returned. 162When the 163.Dv VM_SLEEP 164flag is specified, these functions can never fail (but may block forever). 165.Sh SEE ALSO 166.Xr vmem 9 , 167.Xr vmem_contains 9F , 168.Xr vmem_create 9F 169