/* * Copyright (c) 2003-2004 Apple Computer, Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. The rights granted to you under the License * may not be used to create, or enable the creation or redistribution of, * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ #ifndef LIBKERN_OSMALLOC_h #define LIBKERN_OSMALLOC_h #include __BEGIN_DECLS #include /*! * @header * * @abstract * This header declares the OSMalloc memory-allocation KPI. * * @discussion * Kernel extensions can use these functions to allocate and deallocate * memory blocks that are tracked under named tags. * A kernel extension can create whatever tags it needs, * but typically just creates one with its bundle identifier. * * Tags are required; attempting to use these functions without one * will result in a panic. * * Use Restrictions * * None of the OSMalloc functions are safe to call * in a primary interrupt handler. */ /*! * @typedef OSMallocTag * * @abstract * An opaque type used to track memory allocations. */ typedef struct __OSMallocTag__ * OSMallocTag; /*! * @typedef OSMallocTag_t * * @abstract * See @link OSMallocTag OSMallocTag@/link. */ typedef struct __OSMallocTag__ * OSMallocTag_t; /*! * @define OSMT_DEFAULT * * @abstract * Indicates that an @link OSMallocTag OSMallocTag@/link * be created with default attributes. * * @discussion * An @link OSMallocTag OSMallocTag@/link created * with this attribute allocates all blocks in wired memory. */ #define OSMT_DEFAULT 0x00 /*! * @define OSMT_PAGEABLE * * @abstract * Indicates that an @link OSMallocTag OSMallocTag@/link * should allocate pageable memory when possible. * * @discussion * An @link OSMallocTag OSMallocTag@/link created * with this attribute allocates blocks of a full page size or larger * in pageable memory, * and blocks smaller than a full page size in wired memory. */ #define OSMT_PAGEABLE 0x01 /*! * @function OSMalloc_Tagalloc * * @abstract * Creates a tag for use with OSMalloc functions. * * @param name The name of the tag to create. * @param flags A bitmask that controls allocation behavior; see description. * * @result * An opaque tag to be used with OSMalloc functions for tracking memory usage. * * @discussion * OSMalloc tags can have arbitrary names of a length up to 63 characters. * Calling this function twice with the same name * creates two tags, which share that name. * * flags can be the bitwise OR of the following flags: * */ extern OSMallocTag OSMalloc_Tagalloc( const char * name, uint32_t flags); /*! * @function OSMalloc_Tagfree * * @abstract * Frees a tag used with OSMalloc functions. * * @param tag The @link OSMallocTag OSMallocTag@/link to free. * * @discussion * OSMalloc tags must not be freed * while any memory blocks allocated * with them still exist. * Any OSMalloc function called on those blocks * will result in a panic. */ extern void OSMalloc_Tagfree(OSMallocTag tag); /*! * @function OSMalloc * * @abstract * Allocates a block of memory associated * with a given @link OSMallocTag OSMallocTag@/link. * * @param size The size of the memory block to allocate. * @param tag The @link OSMallocTag OSMallocTag@/link * under which to allocate the memory. * * @result * A pointer to the memory on success, NULL on failure. * * @discussion * If tag was created with the * @link OSMT_PAGEABLE OSMT_PAGEABLE@/link * attribute and size * is a full page or larger, the allocated memory is pageable; * otherwise it is wired. */ extern void * OSMalloc( uint32_t size, OSMallocTag tag); /*! * @function OSMalloc_nowait * * @abstract * Equivalent to @link OSMalloc_noblock OSMalloc_noblock@/link. */ extern void * OSMalloc_nowait( uint32_t size, OSMallocTag tag); /*! * @function OSMalloc_noblock * * @abstract * Allocates a block of memory associated * with a given @link OSMallocTag OSMallocTag@/link, * returning NULL if it would block. * * @param size The size of the memory block to allocate. * @param tag The @link OSMallocTag OSMallocTag@/link * under which to allocate the memory. * * @result * A pointer to the memory on success, NULL on failure * or if allocation would block. * * @discussion * If tag was created with the * @link OSMT_PAGEABLE OSMT_PAGEABLE@/link * attribute and size * is a full page or larger, the allocated memory is pageable; * otherwise it is wired. * * This function is guaranteed not to block. */ extern void * OSMalloc_noblock( uint32_t size, OSMallocTag tag); /*! * @function OSFree * * @abstract * Frees a block of memory allocated by @link OSMalloc OSMalloc@/link. * * @param addr A pointer to the memory block to free. * @param size The size of the memory block to free. * @param tag The @link OSMallocTag OSMallocTag@/link * with which addr was originally allocated. */ extern void OSFree( void * addr, uint32_t size, OSMallocTag tag); __END_DECLS #endif /* LIBKERN_OSMALLOC_h */