# Memory Allocation System (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

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

### Create Heap

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.

### Destroy/Reinitialize Heap

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

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

### Extend the Heap

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

### Allocate Memory Block

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

### Release Memory Block

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

### Method of Memory Block Management

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.

### Information Regarding the Memory Block Size

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.

### Function for Debugging

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.

## See Also

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

## Revision History

10/26/2004 Initial version