1/*
2 * Copyright (c) 2003-2004 Apple Computer, Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28
29#ifndef LIBKERN_OSMALLOC_h
30#define LIBKERN_OSMALLOC_h
31
32#include <sys/cdefs.h>
33
34__BEGIN_DECLS
35
36#include <stdint.h>
37#ifdef MACH_KERNEL_PRIVATE
38#include <kern/queue.h>
39#endif
40
41/*!
42 * @header
43 *
44 * @abstract
45 * This header declares the OSMalloc memory-allocation KPI.
46 *
47 * @discussion
48 * Kernel extensions can use these functions to allocate and deallocate
49 * memory blocks that are tracked under named tags.
50 * A kernel extension can create whatever tags it needs,
51 * but typically just creates one with its bundle identifier.
52 *
53 * Tags are required; attempting to use these functions without one
54 * will result in a panic.
55 *
56 * <b>Use Restrictions</b>
57 *
58 * None of the OSMalloc functions are safe to call
59 * in a primary interrupt handler.
60 */
61
62#ifdef MACH_KERNEL_PRIVATE
63
64#define OSMT_MAX_NAME (64)
65
66typedef struct _OSMallocTag_ {
67 queue_chain_t OSMT_link;
68 uint32_t OSMT_refcnt;
69 uint32_t OSMT_state;
70 uint32_t OSMT_attr;
71 char OSMT_name[OSMT_MAX_NAME];
72} * OSMallocTag;
73
74#define OSMT_VALID_MASK 0xFFFF0000
75#define OSMT_VALID 0xDEAB0000
76#define OSMT_RELEASED 0x00000001
77
78/*! @parseOnly */
79#define OSMT_ATTR_PAGEABLE 0x01
80
81#else
82/*!
83 * @typedef OSMallocTag
84 *
85 * @abstract
86 * An opaque type used to track memory allocations.
87 */
88typedef struct __OSMallocTag__ * OSMallocTag;
89
90
91/*!
92 * @typedef OSMallocTag_t
93 *
94 * @abstract
95 * See <code>@link OSMallocTag OSMallocTag@/link</code>.
96 */
97typedef struct __OSMallocTag__ * OSMallocTag_t;
98#endif
99
100/*!
101 * @define OSMT_DEFAULT
102 *
103 * @abstract
104 * Indicates that an <code>@link OSMallocTag OSMallocTag@/link</code>
105 * be created with default attributes.
106 *
107 * @discussion
108 * An <code>@link OSMallocTag OSMallocTag@/link</code> created
109 * with this attribute allocates all blocks in wired memory.
110 */
111#define OSMT_DEFAULT 0x00
112
113
114/*!
115 * @define OSMT_PAGEABLE
116 *
117 * @abstract
118 * Indicates that an <code>@link OSMallocTag OSMallocTag@/link</code>
119 * should allocate pageable memory when possible.
120 *
121 * @discussion
122 * An <code>@link OSMallocTag OSMallocTag@/link</code> created
123 * with this attribute allocates blocks of a full page size or larger
124 * in pageable memory,
125 * and blocks smaller than a full page size in wired memory.
126 */
127#define OSMT_PAGEABLE 0x01
128
129
130/*!
131 * @function OSMalloc_Tagalloc
132 *
133 * @abstract
134 * Creates a tag for use with OSMalloc functions.
135 *
136 * @param name The name of the tag to create.
137 * @param flags A bitmask that controls allocation behavior; see description.
138 *
139 * @result
140 * An opaque tag to be used with OSMalloc functions for tracking memory usage.
141 *
142 * @discussion
143 * OSMalloc tags can have arbitrary names of a length up to 63 characters.
144 * Calling this function twice with the same name
145 * creates two tags, which share that name.
146 *
147 * <code>flags</code> can be the bitwise OR of the following flags:
148 * <ul>
149 * <li><code>@link OSMT_DEFAULT OSMT_DEFAULT@/link</code> -
150 * allocations are wired. This is the 'zero' bitmask value and
151 * is overridden by any other flag specified.</li>
152 * <li><code>@link OSMT_PAGEABLE OSMT_PAGEABLE@/link</code> -
153 * allocations of a full page size or greater are pageable;
154 * allocations smaller than a page are wired.</li>
155 * </ul>
156 */
157extern OSMallocTag OSMalloc_Tagalloc(
158 const char * name,
159 uint32_t flags);
160
161
162/*!
163 * @function OSMalloc_Tagfree
164 *
165 * @abstract
166 * Frees a tag used with OSMalloc functions.
167 *
168 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code> to free.
169 *
170 * @discussion
171 * OSMalloc tags must not be freed
172 * while any memory blocks allocated
173 * with them still exist.
174 * Any OSMalloc function called on those blocks
175 * will result in a panic.
176 */
177extern void OSMalloc_Tagfree(OSMallocTag tag);
178
179
180/*!
181 * @function OSMalloc
182 *
183 * @abstract
184 * Allocates a block of memory associated
185 * with a given <code>@link OSMallocTag OSMallocTag@/link</code>.
186 *
187 * @param size The size of the memory block to allocate.
188 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code>
189 * under which to allocate the memory.
190 *
191 * @result
192 * A pointer to the memory on success, <code>NULL</code> on failure.
193 *
194 * @discussion
195 * If <code>tag</code> was created with the
196 * <code>@link OSMT_PAGEABLE OSMT_PAGEABLE@/link</code>
197 * attribute <i>and</i> <code>size</code>
198 * is a full page or larger, the allocated memory is pageable;
199 * otherwise it is wired.
200 */
201extern void * OSMalloc(
202 uint32_t size,
203 OSMallocTag tag) __attribute__((alloc_size(1)));
204
205
206/*!
207 * @function OSMalloc_nowait
208 *
209 * @abstract
210 * Equivalent to <code>@link OSMalloc_noblock OSMalloc_noblock@/link</code>.
211 */
212extern void * OSMalloc_nowait(
213 uint32_t size,
214 OSMallocTag tag) __attribute__((alloc_size(1)));
215
216
217/*!
218 * @function OSMalloc_noblock
219 *
220 * @abstract
221 * Allocates a block of memory associated
222 * with a given <code>@link OSMallocTag OSMallocTag@/link</code>,
223 * returning <code>NULL</code> if it would block.
224 *
225 * @param size The size of the memory block to allocate.
226 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code>
227 * under which to allocate the memory.
228 *
229 * @result
230 * A pointer to the memory on success, <code>NULL</code> on failure
231 * or if allocation would block.
232 *
233 * @discussion
234 * If <code>tag</code> was created with the
235 * <code>@link OSMT_PAGEABLE OSMT_PAGEABLE@/link</code>
236 * attribute <i>and</i> <code>size</code>
237 * is a full page or larger, the allocated memory is pageable;
238 * otherwise it is wired.
239 *
240 * This function is guaranteed not to block.
241 */
242extern void * OSMalloc_noblock(
243 uint32_t size,
244 OSMallocTag tag) __attribute__((alloc_size(1)));
245
246
247/*!
248 * @function OSFree
249 *
250 * @abstract
251 * Frees a block of memory allocated by <code>@link OSMalloc OSMalloc@/link</code>.
252 *
253 * @param addr A pointer to the memory block to free.
254 * @param size The size of the memory block to free.
255 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code>
256 * with which <code>addr</code> was originally allocated.
257 */
258extern void OSFree(
259 void * addr,
260 uint32_t size,
261 OSMallocTag tag);
262
263#ifdef XNU_KERNEL_PRIVATE
264/*!
265 * @function OSMalloc_size
266 *
267 * @abstract
268 * Returns the size of a block of memory allocated by <code>@link OSMalloc OSMalloc@/link</code>.
269 *
270 * @param addr A pointer to the memory block allocated via OSMalloc.
271 */
272extern uint32_t OSMalloc_size(
273 void * addr);
274#endif /* XNU_KERNEL_PRIVATE */
275
276__END_DECLS
277
278#endif /* LIBKERN_OSMALLOC_h */
279