# Arena (Overview)

## Introduction

NitroSDK allows you to define nine different Arena regions: main memory (one for ARM9 & one for ARM7), expanded main memory, ITCM, DTCM, shared memory users, shared work RAM (one for ARM9 & one for ARM7), and dedicated work RAM for ARM7. Each region gets an ID and is defined as an `OSArenaId` enumerated type, as shown below.

`OS_ARENA_MAIN` | Arena in main memory for ARM9
`OS_ARENA_MAIN_SUBPRIV` | Arena in main memory for ARM7
`OS_ARENA_MAINEX` | Arena in expanded main memory
`OS_ARENA_ITCM` | Arena in ICTM
`OS_ARENA_DTCM` | Arena in DTCM
`OS_ARENA_SHARED` | User information Arena in shared memory
`OS_ARENA_WRAM_MAIN` | Arena for ARM9 in shared work RAM
`OS_ARENA_WRAM_SUB` | Arena for ARM7 in shared work RAM
`OS_ARENA_WRAM_SUBPRIV` | Arena in ARM7 work RAM

These Arenas are initialized by `OS_InitArena()`. ARM7 configures Arena regions in the following locations: main memory, shared work RAM, and ARM7 work RAM. The rest of the Arenas are configured by ARM9.
The figure below illustrates the standard memory maps during development.

Back to top...

### Arena in ITCM

The figure below shows the Arena in ITCM.
The program code is placed in the lower part of ITCM, and the rest becomes the Arena.

`SDK_AUTOLOAD_ITCM_BSS_END` is determined automatically in the `lcf` file, taking the location in ITCM into consideration.

The code located in ITCM is specified in the SDK and is part of the interrupt handler and the DMA function. This part is transferred to ITCM by the autoload feature before `NitroMain()` runs. This transferred part can be specified by a user addition.

Warning: The determination of `SDK_AUTOLOAD_ITCM_BSS_END` takes the location of the autoload part in ITCM into consideration, but the value may not be set correctly if an overlay is constructed in ITCM.

Back to top...

### Arenas in main memory, expanded memory, DTCM and shared regions

The following figure shows the Arenas in main memory, expanded memory, DTCM and shared regions

Symbols that start with `SDK_` are determined automatically in the lcf file.

The lower address in DTCM is secured for the data region used for interrupt processes. The region can also be secured by a user addition. (Program code cannot be placed in DTCM.)

Warning: The determination of `SDK_AUTOLOAD_DTCM_BSS_END` takes the location of the autoload part in DTCM into consideration, but the value may not be set correctly if an overlay is constructed in ITCM.

`HW_MAIN_ARENA_LO` is discussed below.

`SDK_MAIN_ARENA_LO` is positioned furthest back, behind the static part of main memory, the program loaded by overlay, and that overlay part of the BSS region. This positioning allows the main memory Arena to be used regardless of the overlay read status.

Back to top...

### Arenas in work RAM

The standard practice is to allocate all of work RAM to ARM7, so it is assumed that this Arena also will be used by ARM7.

Shared work RAM and dedicated ARM7 work RAM are allocated to contiguous regions. Whether or not a work RAM Arena can be secured will vary depending on the size of the program code stored here.

The examples below show cases where the program is so big it spills into dedicated ARM7 work RAM, and where it is contained in shared work RAM.

In the first example, there is no Arena in shared work RAM for either ARM7 or ARM9. In the second example, there is no Arena in shared work RAM for ARM9.

Back to top...

### Managing Arenas and securing memory

The Arena region depends on the pointers that indicate the start and the end of the region.

The system stores only these two pointers and information regarding whether or not the Arena has been initialized. In other words, there is no information regarding the extent to which the Arena can be used, the initial locations of the pointers, or the content of the Arena.

For each Arena, there are pointers for the start and end of the Arena region and the information about initialization. This data is collected together and placed in a System shared region.

When memory blocks are secured from an Arena, they can be secured from either the start or the end of the region. The memory region boundary moves on accordingly its own. For example, to secure a block of `SIZE1` bytes from the start of the Arena (i.e., from the low-order end), `OS_GetArenaLo()` is called and then `OS_SetArenaLo()` in order to set the boundary with the returned value.

In the following figure, a block of `SIZE2` bytes is secured from the tail end of the Arena (i.e., from the high-order end).

Arenas are not something you access frequently during the game in terms of securing and releasing memory. They are most often used for general assignments like securing lump regions for various purposes at the time of initialization. The OS has a memory allocation system with functions like `OS_AllocFromHeap()` for repeatedly securing and releasing memory during the game.

## See Also

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

## Revision History

10/25/2004 Initial version. Spun off of `OS_InitArena()`.