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