Mac Dev Center Right arrow

Mac OS X Reference Library Right arrow

Drivers, Kernel, & Hardware: Kernel Device Drivers Right arrow

Kernel Framework Reference

OSMalloc.h

Includes:

Overview

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.

Functions

OSFree: Frees a block of memory allocated by OSMalloc.
OSMalloc: Allocates a block of memory associated with a given OSMallocTag.
OSMalloc_noblock: Allocates a block of memory associated with a given OSMallocTag, returning NULL if it would block.
OSMalloc_nowait: Equivalent to OSMalloc_noblock.
OSMalloc_Tagalloc: Creates a tag for use with OSMalloc functions.
OSMalloc_Tagfree: Frees a tag used with OSMalloc functions.

OSFree

Frees a block of memory allocated by OSMalloc.

extern void OSFree( 
    void *addr, 
    uint32_t size, 
    OSMallocTag tag);

Parameters

addr: A pointer to the memory block to free.
size: The size of the memory block to free.
tag: The OSMallocTag with which addr was originally allocated.

OSMalloc

Allocates a block of memory associated with a given OSMallocTag.

extern void * OSMalloc( 
    uint32_t size, 
    OSMallocTag tag);

Parameters

size: The size of the memory block to allocate.
tag: The OSMallocTag under which to allocate the memory.

Return Value

A pointer to the memory on success, NULL on failure.

Discussion

If tag was created with the OSMT_PAGEABLE attribute and size is a full page or larger, the allocated memory is pageable; otherwise it is wired.

OSMalloc_noblock

Allocates a block of memory associated with a given OSMallocTag, returning NULL if it would block.

extern void * OSMalloc_noblock( 
    uint32_t size, 
    OSMallocTag tag);

Parameters

size: The size of the memory block to allocate.
tag: The OSMallocTag under which to allocate the memory.

Return Value

A pointer to the memory on success, NULL on failure or if allocation would block.

Discussion

If tag was created with the OSMT_PAGEABLE 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.

OSMalloc_nowait

Equivalent to OSMalloc_noblock.

extern void * OSMalloc_nowait( 
    uint32_t size, 
    OSMallocTag tag);

OSMalloc_Tagalloc

Creates a tag for use with OSMalloc functions.

extern OSMallocTag OSMalloc_Tagalloc( 
    const char * name, 
    uint32_t flags);

Parameters

name: The name of the tag to create.
flags: A bitmask that controls allocation behavior; see description.

Return Value

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:

OSMT_DEFAULT - allocations are wired. This is the 'zero' bitmask value and is overridden by any other flag specified.
OSMT_PAGEABLE - allocations of a full page size or greater are pageable; allocations smaller than a page are wired.

OSMalloc_Tagfree

Frees a tag used with OSMalloc functions.

extern void OSMalloc_Tagfree(
    OSMallocTag tag);

Parameters

tag: The OSMallocTag 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.

Typedefs

OSMallocTag: An opaque type used to track memory allocations.
OSMallocTag_t: See OSMallocTag.

OSMallocTag

An opaque type used to track memory allocations.

typedef struct __OSMallocTag__ * OSMallocTag;

OSMallocTag_t

See OSMallocTag.

typedef struct __OSMallocTag__ * OSMallocTag_t;

Macro Definitions

OSMT_DEFAULT: Indicates that an OSMallocTag be created with default attributes.
OSMT_PAGEABLE: Indicates that an OSMallocTag should allocate pageable memory when possible.

OSMT_DEFAULT

Indicates that an OSMallocTag be created with default attributes.

#define OSMT_DEFAULT 0x00

Discussion

An OSMallocTag created with this attribute allocates all blocks in wired memory.

OSMT_PAGEABLE

Indicates that an OSMallocTag should allocate pageable memory when possible.

#define OSMT_PAGEABLE 0x01

Discussion

An OSMallocTag 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.

Last Updated: 2009-10-14