# OS_InitArena

## C Specification

      #include <nitro/os.h>

      void OS_InitArena( void );

## Description

This function sets the upper and lower boundaries.

Call this function once before the `Alloc` functions or other Arena functions. But because this function is also called from within `OS_Init()`, calling this function has no meaning when `OS_Init()` is called. Second and subsequent calls of this function will be ignored. The arena boundaries can be changed after `OS_InitArena()` has been called.

It is possible to change the arena boundaries with `OS_SetArenaLo()` and `OS_SetArenaHi()` after calling `OS_InitArena()`.

In the NITRO SDK, it is possible to set boundaries for 9 arenas: main memory (for ARM9, for ARM7), main memory expanded region, ITCM, DTCM, shared memory (user portion), shared work RAM (for ARM9 and for ARM7), and ARM7 dedicated work RAM. Each region has an ID and is defined in `OSArenaId` array format as follows:

`OS_ARENA_MAIN` | Main Memory Arena (ARM9 dedicated)
`OS_ARENA_MAIN_SUBPRIV` | Main Memory Arena (ARM7 dedicated)
`OS_ARENA_MAINEX` | Expansion Main Memory Arena
`OS_ARENA_ITCM` | ITCM Arena
`OS_ARENA_DTCM` | DTCM Arena
`OS_ARENA_SHARED` | Shared Memory Arena
`OS_ARENA_WRAM_MAIN` | Shared work RAM arena (for ARM9)
`OS_ARENA_WRAM_SUB` | Shared work RAM arena (for ARM7)
`OS_ARENA_WRAM_SUBPRIV` | Work RAM arena (ARM7 dedicated)

`OS_InitArena()` for ARM7 sets up six of the nine arenas of `OS_InitArena()` for ARM9. The three exceptions are the arena on the ARM7-dedicated main memory, the arena on the ARM7 shared work RAM, and ARM7 dedicated work RAM arena.

Calling `OS_InitArena()` from both processors sets each arena's upper and lower boundary as shown below:

Arena | Bottom | Top
Main Memory Arena (ARM9 dedicated) | `SDK_MAIN_ARENA_LO` (acquired from lcf) `SDK_SUBPRIV_ARENA_LO` (acquired from lcf) | Before ARM7 dedicated main memory region.
Main Memory Arena (ARM7 dedicated) | Beginning of ARM7 dedicated main memory | Top of ARM7 dedicated main memory region.
Expansion Main Memory Arena | Beginning of expanded main memory region | Before the debugger region
ITCM Arena | SDK_AUTOLOAD_ITCM_BSS_END | Top of ITCM
DTCM Arena | SDK_AUTOLOAD_DTCM_BSS_END | Before system mode stack
Shared Memory Arena(user region) | Bottom of shared memory | Before shared memory system region
Shared work RAM arena (for ARM9) | *1 | Bottom of Shared work RAM
Shared work RAM arena (for ARM7) | *2 | Top of Shared work RAM
Work RAM arena (ARM7 dedicated) | Bottom of ARM7 dedicated Work RAM | Before system mode stack

There is no main memory expansion area in the the production version of the Nintendo DS system, so there will be no arena for the main memory expansion area. The top and bottom of the shared work RAM arena (for ARM9) have the same address, that is, by default the size is 0.

*1 is the smaller of the end address of the ARM7 static module and address of the top of the shared work. In other words, if the ARM7 static module fits in the shared work the empty region becomes the arena on the ARM7 shared work RAM. If it does not fit, both the start address and end address become the top address of the shared work and the size of the arena is 0.

*2 is the larger of the end address of the ARM7 static module and the restart address of the ARM7 dedicated work RAM. In other words, if the ARM7 static module will amount to the ARM7 dedicated work RAM, the empty region excluding this is the ARM7 dedicated work RAM arena. If the module is not that big and will not amount to the ARM7 dedicated work RAM, the arena is from the top of the ARM7 dedicated work RAM.

For more details, see the Arena Overview.

## Arguments

None

## Return Values

None

## See Also

`OS_SetArenaHi`, `OS_SetArenaLo`, `OS_GetArenaHi`, `OS_GetArenaLo`

## Revision History

11/02/2004 Corrected error in number of initialized arenas.
10/26/2004 Separated the graphical explanation of arenas.
10/01/2004 Described by associating overlay
09/29/2004 Described the arena regions with charts
05/28/2004 Changed description of ARM7 arenas.
02/19/2004 Changed the number of arenas from 6 to 9. Added support for both processors
01/16/2004 Added `MainEx`
01/06/2004 Initial version