OS_AddExtraAreaToHeap

Syntax

#include <nitro/os.h>

void OS_AddExtraAreaToHeap( OSArenaId id, OSHeapHandle heap );

Arguments

id	Arena ID of the arena for a heap to which the 16-KB region of the top of the main memory will be added.
*heap*	Handle of a heap to which the 16-KB region of the top of the main memory will be added.

Return Values

None.

Description

A 16-KB region memory block from the top of main memory is added to the existing heap region.

This function has special uses. (The added region is fixed at 16 KB of the bottom of main memory that is possible when a hybrid ROM is running in NITRO mode.) The function that adds the main memory block to the existing heap, for ordinary purposes, is the OS_AddToHeap function. Note that the OS_AddExtraAreaToHeap function is an inline function that internally calls the OS_AddToHeap function

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, This function does nothing even if called while a hybrid ROM is running on TWL hardware in TWL mode.

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.

This function adds the 16-KB region to the existing heap.See the OS_CreateExtraHeap function for more information on creating a heap using a 16-KB region Note that both cannot be run simultaneously.

Revision History

2009/04/03 Initial version.