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.

Frees a block of memory allocated by OSMalloc.

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

Parameters

Allocates a block of memory associated with a given OSMallocTag.

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

Parameters

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.

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

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.

Equivalent to OSMalloc_noblock.

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

Creates a tag for use with OSMalloc functions.

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

Parameters

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.

Frees a tag used with OSMalloc functions.

extern void OSMalloc_Tagfree(
    OSMallocTag tag);  

Parameters

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.

An opaque type used to track memory allocations.

typedef struct __OSMallocTag__ * OSMallocTag;  

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.

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.

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: 2010-07-29