Memory Allocation (Overview)

Introduction


(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.)

Initialization

The 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, calling 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. Using the OS_InitiAlloc() return value, the arena's boundary address, ArenaLo, only needs to move by the size of the information block.

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. The reason for this necessity is that this maximum number of heap descriptors is created in advance in the block information of the heap. 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.


To clear memory allocation system information, call OS_ClearAlloc().


Heap Creation

Call OS_CreateHeap() to create a new heap. Specify the region to use for the heap using the start and end arguments. The specified region must be within the range from topAddr to bottomAddr in the diagram.

The heap information is stored in the heap descriptor.


Releasing and Reinitializing Heaps

Call OS_DestroyHeap() to destroy created heaps. This does not change the pointers ArenaLo and ArenaHi.

Call OS_ClearHeap() to reinitialize a heap.


Current Heap

You can set current heap for each arena. By setting the current heap, it is no longer necessary to specify heap handlers using several macro functions. It also becomes possible to specify heap with OS_CURRENT_HEAP_HANDLE, even though it is a tool for specifying heap handles.

OS_SetCurrentHeap() sets the current heap.


Extending Heaps

After creating a heap, it is possible to extend the heap region. Call OS_AddToHeap() using the heap argument to specify the heap you want extended.

Do not use the extended heap region for another purpose until you release the heap.

When using OS_AddToHeap(), heap "enclaves" may occur as illustrated below.


Allocating Memory Block

The OS_AllocFromHeap() function allows you to allocate memory blocks from the specified heap. For this function, you must also specify the arena.
For the sake of simplicity, a macro is provided that includes the arena name in the function name. For details, refer to OS_AllocFromHeap().

Also, the OS_AllocFixed() function allows you to allocate memory blocks from a specified region. A memory block allocated with this function is excluded from heap control. Therefore, it is alright to take a memory block allocated with this function as an argument and extend another heap with OS_AddToHeap().


Releasing Memory Block

The OS_FreeToHeap() function allows you to release allocated memory blocks. For this function, you must also specify the arena.
For the sake of simplicity, a macro is provided that includes the arena name in the function name. For details regarding this macro, see the reference materials for OS_FreeToHeap().

Also, the OS_FreeAllToHeap() function allows you to release all memory blocks. Here too a macro is provided that includes arena name in function name. For details regarding this macro, see OS_FreeAllToHeap().


Memory Block Management

Within heaps both free memory and used memory are controlled in block units. These block units are linked with a bidirectional list. After creating a heap, all regions for heap are considered free blocks.

The size of the data area includes the region allocated for heap. With normal use, this value does not change. However, calling OS_AllocFixed() reduces the size of that block amount in heaps that include the specified region. Also, the size of that block amount increases when you add memory blocks that were not originally included in this heap by calling OS_AddToHeap().

The following diagram shows the heap and heap descriptor state at a point in time. In this example, when FreeBlockList reaches addr1 and then follows the next link, it becomes clear that addr1 and the block that starts from addr5 and addr3 are empty regions. In the same way, by following Allocated Block List, it becomes clear that the block that starts from addr2, addr4, and addr6 is in use.


Memory Block Size Information

The following functions are available:

OS_GetTotalAllocSize() gets the total size of the memory block (not including the header size) being used

OS_GetTotalOccupiedSize() gets the total size of the memory block (including the header size) being used

OS_GetTotalFreeSize() gets the total size of the free memory block

OS_GetMaxFreeSize() gets the size of the largest free memory block

OS_ReferentSize() specifies a memory block and then gets the size of that block

These functions only take into account parts where memory block data is stored. In other words, the size of the part that controls memory is not included. Even though these are functions that get the totals, that total is only the data region part.


Debugging Functions

OS_DumpHeap() displays heap contents using OS_Printf(). This function is used for debugging.

Also, OS_CheckHeap() checks the validity of the heap contents.

See Also

OS function list (Arena), OS function list (Alloc)

Revision History

2005/10/07 Added OS_GetTotalOccupiedSize()
03/14/2005 Corrected link destination error
03/03/2005 Corrected link destination error
12/13/2004 Corrected Wording
10/26/2004 Initial version