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 */ 287