In the image of the memory map shown on this page, the lower address is at the top of the image and the upper address is at the bottom.
NitroSDK allows you to build a heap system in the Arena in which you can allocate and release memory blocks for use in the game. When the OS_InitArena() function initializes the Arena, the ArenaLo pointer is inserted at the front end of the region and the ArenaHi pointer is inserted at the tail end of the region.
A memory allocation system can be built for each of multiple Arenas. In addition, multiple heap regions can be configured for a single Arena.
For an Arena in the state shown in the preceding figure, executing the OS_InitAlloc() function to initialize the memory allocation system results in the creation of a heap information block at the bottom of the memory region, as shown in the figure below. Up to this point, this memory block was an unallocated Arena region. The maximum number of heaps that can be created in a single Arena must be specified as an argument of the OS_InitAlloc() function because heap descriptors equal to this maximum number are created in the heap information block as part of the initialization process. As shown in the figure, the heap descriptors store information about the size of the heap regions, the start of free blocks, and the starting addresses of blocks in use.
The ArenaLo address, which is the Arena boundary address, is shifted by the size of the information block.
To destroy the memory allocation system information, call OS_ClearAlloc().
To create a heap, call OS_CreateHeap(). Specify a region to use for the heap. The region must be within the range of topAddr and bottomAddr as shown in the following figure.
When the heap is created, the heap information is stored in heap descriptor.
To destroy the created heap, call OS_DestroyHeap(). However, pointers to ArenaLo or ArenaHi will not change because of this.
To reinitialize the heap, call OS_ClearHeap().
Current heap can be set for each arena. If the current heap is set in advance, there is no need for specifying heap handles for some of the macro functions. Also, even with the function that specifies heap handle, OS_CURRENT_HEAP_HANDLE can be used to specify the heap.
The function that sets the current heap is OS_SetCurrentHeap().
Once the heap was created, the heap region can be extended. Specify the area to be extended and call OS_AddToHeap().
Do not use the heap region that was once extended for other purpose until the heap is destroyed.
The figure below illustrates that an isolated heap can occur with OS_AddToHeap().
The OS_AllocFromHeap() function is provided to allocate memory blocks in the heap. The arena must be specified with this function, but there is a macro that contains the arena name in the function name to simplify the procedure. For details, refer to OS_AllocFromHeap().
Also, the function OS_AllocFixed() is provided to allocate memory blocks by specifying the region. The memory block allocated with this function is excluded from the heap management. Therefore, it is possible to use the memory block allocated with this function as an argument to extend other heaps with OS_AddToHeap().
The OS_FreeToHeap() function is provided to release the allocated memory block. The arena must be specified with this function, but there is a macro that contains the arena name in the function name to simplify the procedure. For details on the macro, refer to OS_FreeToHeap().
Also, the function OS_FreeAllToHeap() is provided to release all memory blocks. A macro that contains the arena name in the function name is also provided. For more information on the macro, refer to OS_FreeAllToHeap().
Both free heap memory and in-use heap memory are managed in units of blocks, and they are linked on the bidirectional list. Immediately after the heap is created, all of the regions for heap are assumed to be free blocks.
Data area size is the size of the area allocated for heap. With normal usage this value will not change. However, when OS_AllocFixed() is used, the heap that contains the specified region is reduced by the size of that block. Also, when using OS_AddToHeap() to add a memory block that was not originally contained, the heap increases by the size of this block.
The next figure shows the state of the heap and heap descriptor at a certain point. In this example, Free Block List indicates B1. From that point, by following the next link you will find that B5 and B3 are empty regions, and by following the Allocated Block List you will find that B2 and B4 are in use.
The following functions are provided:
OS_GetTotalAllocSize() obtains the total size of the memory blocks being used.
OS_GetTotalAllocSize() obtains the total size of the free memory blocks.
OS_GetMaxFreeSize() obtains the size of the largest free memory block.
OS_ReferentSize() specifies the memory block and obtains the size of that block.
These functions only consider the portion that stores the memory block data. In other words, the size of the portion that manages the memory is not included. Even with a function that obtains the total, it will be the total for only the data region portions.

The function OS_DumpHeap() displays the contents of the heap by using OS_Printf(). This is a function for debugging.
OS_CheckHeap() checks the validity of the heap contents.
OS function list (Arena), OS function list (Alloc)
10/26/2004 Initial version