OS_AllocFromHeap


C Specification

#include <nitro/os.h>

void* OS_AllocFromHeap( 
                OSArenaId       id , 
                OSHeapHandle    heap , 
                u32             size );

void* OS_AllocFromMain( u32 size );
void* OS_AllocFromITCM( u32 size );
void* OS_AllocFromDTCM( u32 size );
void* OS_AllocFromShared( u32 size );
void* OS_AllocFromWram( u32 size );
void* OS_AllocFromMainEx( u32 size );

void* OS_Alloc( u32 size );

Description

Allocates a memory block from a heap

In OS_AllocFromHeap, you must specify the handle of the allocating heap and the arena ID of the arena that is associated with that heap. The arena is specified with an arena ID, id.
For more information, see OS_InitArena.

If OS_CURRENT_HEAP_HANDLE is specified as the heap handle, it will be assumed that the arena's current heap is being specified.

OS_AllocFromMain is the inline function for OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... ).
OS_AllocFromICTM is the inline function for OS_AllocFromHeap( OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE, ... ).
OS_AllocFromDTCM is the inline function for OS_AllocFromHeap( OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE, ... ).
OS_AllocFromShared is the inline function for OS_AllocFromHeap( OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE, ... ).
OS_AllocFromWram is the inline function for OS_AllocFromHeap( OS_ARENA_WRAM, OS_CURRENT_HEAP_HANDLE, ... ).
OS_AllocFromMainEx is the inline function for OS_AllocFromHeap( OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE, ... ).

OS_Alloc is the inline of OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... ).

For ARM9, OS_Alloc is the inline of OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... );
For ARM7, OS_Alloc is the inline of OS_AllocFromHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... ).

Caution

When try to allocate a 0–byte region, DEBUG build stops at ASSERT. In other builds, the operation is indefinite.

Arguments

id Arena ID of the arena associated with the heap from which a region will be reserved
heap Handle of the heap from which a region will be reserved
size Size of the region you want to reserve (bytes)

Return Values

If a region was allocated, the region's start address is returned.
If it was not possible to allocate a region, NULL is returned.

See Also

OS_InitArena, OS_InitAlloc, OS_CreateHeap, OS_FreeToHeap, OS_FreeAllToHeap

Revision History

07/07/2004 Added caution regarding 0&ndashbyte regions
03/08/2004 Added difference in behavior when called in ARM7 and ARM9
02/25/2004 Changed the number of arenas from 6 to 9
01/06/2004 Initial Version