#include <nitro/os.h>OSHeapHandle OS_CreateExtraHeap( OSArenaId id ); | id | Arena ID of an arena in which you are going to create a heap |
In the case that it was possible to create a heap, the handle to the heap is returned. This is a value greater than or equal to 0.
When a heap could not be created, -1 is returned.
Creates a heap in the specified arena.
This function has special uses. (The heap region is fixed at 16 KB of the bottom of the main memory that is possible when a hybrid ROM is running in NITRO mode.) The heap creation function for ordinary use is OS_CreateHeap.
With TWL ROM (both hybrid and limited ROM), a system reserved region of 16 KB is created at the bottom of the main memory. However, this region can be used only when running in TWL mode. In other words, when a hybrid ROM is running in NITRO mode on NITRO hardware, this 16 KB is not used at all.
This function allocates the empty 16-KB region to the heap of the specified arena. This function cannot be called for NITRO ROM and TWL limited ROM.(It exists only with hybrid ROM, so a compile error will be generated. Also, a heap is not created even if this function is called while a hybrid ROM is running on TWL hardware and in TWL mode, so -1 is returned to indicate an error.
The arena is specified with the arena ID (id). For more information on this value, see the OS_InitArena function. The arena must have memory allocated with the OS_InitAlloc function and have been initialized in advance. The region for the heap is 16 KB from 0x02000000 to 0x02003FFF at the top of the main memory.
Call the OS_DestroyHeap function to destroy created heaps.
Call the OS_ClearExtraHeap function to reinitialize a heap.( Do not call the OS_ClearHeap function.)
(Ex.)
#define HEAP_NUM 2
#define HEAP_SIZE 0x10000
OSHeapHandle mainHeapHandle = -1;
void NitroMain(void)
{
OS_Init();
//---- Declare to use main memory heaps
OS_InitAlloc( OS_ARENA_MAIN, OS_GetMainArenaLo(), OS_GetMainArenaHi(), HEAP_NUM );
//---- Create main heap
heapArea = OS_AllocFromArenaLo( OS_ARENA_MAIN, HEAP_SIZE, 32 );
mainHeapHandle = OS_CreateHeap( OS_ARENA_MAIN, heapArea, (void*)((u32)heapArea + HEAP_SIZE) );
//---- If NITRO MODE, create extra heap
if ( OS_IsRunOnTwl() == FALSE )
{
extraHeapHandle = OS_CreateExtraHeap( OS_ARENA_MAIN );
}
}
In this example, the OS_CreateExtraHeap function is called only when running in NITRO mode. This program presumes that a hybrid ROM will be built. A compile error is generated when a NITRO ROM or TWL limited ROM is built because the OS_CreateExtraHeap function is not defined.
This function adds the 16-KB region as one heap.When a heap enclave region has already been added, see the OS_AddExtraAreaToHeap function. Note that if a 16-KB region is created as a heap, it cannot be used as an added enclave region. If used as an added enclave region, it cannot be created as one heap.
OS_InitArena
OS_InitAlloc
OS_DestroyHeap
OS_ClearHeap
OS_ClearExtraHeap
OS_CreateHeap
OS_AddExtraAreaToHeap
2009/04/03 Added information on OS_AddExtraAreaToHeap.
2009/02/17 Initial version.
CONFIDENTIAL