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
  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
  66 typedef 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  */
  88 typedef struct __OSMallocTag__ * OSMallocTag;
  89
  90
  91 /*!
  92  * @typedef OSMallocTag_t
  93  *
  94  * @abstract
  95  * See <code>@link OSMallocTag OSMallocTag@/link</code>.
  96  */
  97 typedef 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  */
 157 extern 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  */
 177 extern 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  */
 201 extern 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  */
 212 extern 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  */
 242 extern 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  */
 258 extern 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  */
 272 extern uint32_t OSMalloc_size(
 273         void    * addr);
 274 #endif /* XNU_KERNEL_PRIVATE */
 275
 276 __END_DECLS
 277
 278 #endif  /* LIBKERN_OSMALLOC_h */