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); 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); 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); 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__END_DECLS 264 265#endif /* LIBKERN_OSMALLOC_h */ 266