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
57 illumos DDI specific
58 .Sh PARAMETERS
59 .Bl -tag -width Ds
60 .It Fa name
61 A character string giving a name to the vmem
62 arena to be created.
63 .It Fa base
64 An address indicating the lowest possible value in the arena.
65 .It Fa size
66 The size of the arena to create
67 .It Fa quantum
68 The arena's
69 .Dq quantum .
70 The granularity of the arena. The amount allocated at minimum by each request.
71 .It Fa afunc
72 A function which is called to import new spans from
73 .Fa source .
74 Which may be
75 .Dv NULL
76 if this arena does not import from another.
77 .It Fa ffunc
78 A function which is called to return spans to
79 .Fa source .
80 Which may be
81 .Dv NULL
82 if this arena does not import from another.
83 .It Fa source
84 An arena from which this arena will import.
85 Which may be
86 .Dv NULL
87 if this arena does not import from another.
88 .It Fa qcache_max
89 Each arena offers caching of integer multiples of
90 .Fa quantum
91 up to
92 .Fa qcache_max .
93 .It Fa vmflag
94 A bitmask of flags indicating the characteristics of this arena.
95 .Bl -tag -width Ds
96 .It Dv VMC_IDENTIFIER
97 The arena represents arbitrary integer identifiers, rather than virtual
98 memory.
99 .El
100 .It Fa vmp
101 A pointer to the vmem arena to be destroyed.
102 .El
103 .Sh DESCRIPTION
104 A
105 .Em vmem arena
106 is a section of an arbitrary address space (a range of integer addresses).
107 This commonly represents virtual memory, but can in fact be an arbitrary set
108 of integers. The
109 .Dv VMC_IDENTIFIER
110 flag set at arena creation time differentiates between these two cases.
111 .Pp
112 The
113 .Fa afunc ,
114 .Fa ffunc , and
115 .Fa source
116 arguments combine to support a hierarchical structure of arenas, each
117 importing from a single parent (the
118 .Fa source ) .
119 The
120 .Fn vmem_create
121 and
122 .Fn vmem_xcreate
123 functions differ in that the latter provides an interface for
124 .Fa afunc
125 to alter the size of the span imported from
126 .Fa source .
127 It is only legal to
128 .Em increase
129 thise size.
130 .Sh CONTEXT
131 These functions can be called from user or kernel context.
132 .Sh RETURN VALUES
133 Upon successful completion the
134 .Fn vmem_create and
135 .Fn vmem_xcreate
136 functions return a pointer to a vmem arena. Otherwise,
137 .Dv NULL
138 is returned to indicate the arena could not be created.
139 .Sh SEE ALSO
140 .Xr vmem 9 ,
141 .Xr vmem_add 9F ,
142 .Xr vmem_alloc 9F