]> git.saurik.com Git - apple/xnu.git/blob - libkern/libkern/OSMalloc.h
projects / apple / xnu.git / blob
? search:


b7aecdd521cfc880eb6a00df4766583be6de3be6
[apple/xnu.git] / libkern / libkern / OSMalloc.h
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 #if defined(XNU_KERNEL_PRIVATE)
41 #include <kern/kalloc.h>
42 #ifndef OSMallocDeprecated
43 #define OSMallocDeprecated __deprecated_msg("Use kalloc heaps")
44 #endif
45 #endif /* XNU_KERNEL_PRIVATE */
46
47 /*!
48 * @header
49 *
50 * @abstract
51 * This header declares the OSMalloc memory-allocation KPI.
52 *
53 * @discussion
54 * Kernel extensions can use these functions to allocate and deallocate
55 * memory blocks that are tracked under named tags.
56 * A kernel extension can create whatever tags it needs,
57 * but typically just creates one with its bundle identifier.
58 *
59 * Tags are required; attempting to use these functions without one
60 * will result in a panic.
61 *
62 * <b>Use Restrictions</b>
63 *
64 * None of the OSMalloc functions are safe to call
65 * in a primary interrupt handler.
66 */
67
68 #ifdef MACH_KERNEL_PRIVATE
69
70 #define OSMT_MAX_NAME (64)
71
72 typedef struct _OSMallocTag_ {
73 queue_chain_t OSMT_link;
74 uint32_t OSMT_refcnt;
75 uint32_t OSMT_state;
76 uint32_t OSMT_attr;
77 char OSMT_name[OSMT_MAX_NAME];
78 } * OSMallocTag;
79
80 #define OSMT_VALID_MASK 0xFFFF0000
81 #define OSMT_VALID 0xDEAB0000
82 #define OSMT_RELEASED 0x00000001
83
84 /*! @parseOnly */
85 #define OSMT_ATTR_PAGEABLE 0x01
86
87 #else
88 /*!
89 * @typedef OSMallocTag
90 *
91 * @abstract
92 * An opaque type used to track memory allocations.
93 */
94 typedef struct __OSMallocTag__ * OSMallocTag;
95
96
97 /*!
98 * @typedef OSMallocTag_t
99 *
100 * @abstract
101 * See <code>@link OSMallocTag OSMallocTag@/link</code>.
102 */
103 typedef struct __OSMallocTag__ * OSMallocTag_t;
104 #endif
105
106 /*!
107 * @define OSMT_DEFAULT
108 *
109 * @abstract
110 * Indicates that an <code>@link OSMallocTag OSMallocTag@/link</code>
111 * be created with default attributes.
112 *
113 * @discussion
114 * An <code>@link OSMallocTag OSMallocTag@/link</code> created
115 * with this attribute allocates all blocks in wired memory.
116 */
117 #define OSMT_DEFAULT 0x00
118
119
120 /*!
121 * @define OSMT_PAGEABLE
122 *
123 * @abstract
124 * Indicates that an <code>@link OSMallocTag OSMallocTag@/link</code>
125 * should allocate pageable memory when possible.
126 *
127 * @discussion
128 * An <code>@link OSMallocTag OSMallocTag@/link</code> created
129 * with this attribute allocates blocks of a full page size or larger
130 * in pageable memory,
131 * and blocks smaller than a full page size in wired memory.
132 */
133 #define OSMT_PAGEABLE 0x01
134
135
136 /*!
137 * @function OSMalloc_Tagalloc
138 *
139 * @abstract
140 * Creates a tag for use with OSMalloc functions.
141 *
142 * @param name The name of the tag to create.
143 * @param flags A bitmask that controls allocation behavior; see description.
144 *
145 * @result
146 * An opaque tag to be used with OSMalloc functions for tracking memory usage.
147 *
148 * @discussion
149 * OSMalloc tags can have arbitrary names of a length up to 63 characters.
150 * Calling this function twice with the same name
151 * creates two tags, which share that name.
152 *
153 * <code>flags</code> can be the bitwise OR of the following flags:
154 * <ul>
155 * <li><code>@link OSMT_DEFAULT OSMT_DEFAULT@/link</code> -
156 * allocations are wired. This is the 'zero' bitmask value and
157 * is overridden by any other flag specified.</li>
158 * <li><code>@link OSMT_PAGEABLE OSMT_PAGEABLE@/link</code> -
159 * allocations of a full page size or greater are pageable;
160 * allocations smaller than a page are wired.</li>
161 * </ul>
162 */
163 #if XNU_KERNEL_PRIVATE
164 OSMallocDeprecated
165 #endif
166 extern OSMallocTag OSMalloc_Tagalloc(
167 const char * name,
168 uint32_t flags);
169
170
171 /*!
172 * @function OSMalloc_Tagfree
173 *
174 * @abstract
175 * Frees a tag used with OSMalloc functions.
176 *
177 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code> to free.
178 *
179 * @discussion
180 * OSMalloc tags must not be freed
181 * while any memory blocks allocated
182 * with them still exist.
183 * Any OSMalloc function called on those blocks
184 * will result in a panic.
185 */
186 #if XNU_KERNEL_PRIVATE
187 OSMallocDeprecated
188 #endif
189 extern void OSMalloc_Tagfree(OSMallocTag tag);
190
191
192 /*!
193 * @function OSMalloc
194 *
195 * @abstract
196 * Allocates a block of memory associated
197 * with a given <code>@link OSMallocTag OSMallocTag@/link</code>.
198 *
199 * @param size The size of the memory block to allocate.
200 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code>
201 * under which to allocate the memory.
202 *
203 * @result
204 * A pointer to the memory on success, <code>NULL</code> on failure.
205 *
206 * @discussion
207 * If <code>tag</code> was created with the
208 * <code>@link OSMT_PAGEABLE OSMT_PAGEABLE@/link</code>
209 * attribute <i>and</i> <code>size</code>
210 * is a full page or larger, the allocated memory is pageable;
211 * otherwise it is wired.
212 */
213 #if XNU_KERNEL_PRIVATE
214 OSMallocDeprecated
215 #endif
216 extern void * OSMalloc(
217 uint32_t size,
218 OSMallocTag tag) __attribute__((alloc_size(1)));
219
220 /*!
221 * @function OSMalloc_nowait
222 *
223 * @abstract
224 * Equivalent to <code>@link OSMalloc_noblock OSMalloc_noblock@/link</code>.
225 */
226 #if XNU_KERNEL_PRIVATE
227 OSMallocDeprecated
228 #endif
229 extern void * OSMalloc_nowait(
230 uint32_t size,
231 OSMallocTag tag) __attribute__((alloc_size(1)));
232
233 /*!
234 * @function OSMalloc_noblock
235 *
236 * @abstract
237 * Allocates a block of memory associated
238 * with a given <code>@link OSMallocTag OSMallocTag@/link</code>,
239 * returning <code>NULL</code> if it would block.
240 *
241 * @param size The size of the memory block to allocate.
242 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code>
243 * under which to allocate the memory.
244 *
245 * @result
246 * A pointer to the memory on success, <code>NULL</code> on failure
247 * or if allocation would block.
248 *
249 * @discussion
250 * If <code>tag</code> was created with the
251 * <code>@link OSMT_PAGEABLE OSMT_PAGEABLE@/link</code>
252 * attribute <i>and</i> <code>size</code>
253 * is a full page or larger, the allocated memory is pageable;
254 * otherwise it is wired.
255 *
256 * This function is guaranteed not to block.
257 */
258 #if XNU_KERNEL_PRIVATE
259 OSMallocDeprecated
260 #endif
261 extern void * OSMalloc_noblock(
262 uint32_t size,
263 OSMallocTag tag) __attribute__((alloc_size(1)));
264
265 /*!
266 * @function OSFree
267 *
268 * @abstract
269 * Frees a block of memory allocated by <code>@link OSMalloc OSMalloc@/link</code>.
270 *
271 * @param addr A pointer to the memory block to free.
272 * @param size The size of the memory block to free.
273 * @param tag The <code>@link OSMallocTag OSMallocTag@/link</code>
274 * with which <code>addr</code> was originally allocated.
275 */
276 #if XNU_KERNEL_PRIVATE
277 OSMallocDeprecated
278 #endif
279 extern void OSFree(
280 void * addr,
281 uint32_t size,
282 OSMallocTag tag);
283
284 __END_DECLS
285
286 #endif /* LIBKERN_OSMALLOC_h */
mirror of XNU