# OS_InitArena

## C Specification

      #include <nitro/os.h>

      void OS_InitArena( void );

## Arguments

None.

## Return Values

None.

## 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.

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

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.

Arena ID | Arena | Initialization
--- | --- | ---
OS_ARENA_MAIN | Main Memory Arena (ARM9 dedicated) | From ARM9
OS_ARENA_MAIN_SUBPRIV | Main Memory Arena (ARM7 dedicated) | From ARM7
OS_ARENA_MAINEX | Main Memory Expanded Arena | From ARM9
OS_ARENA_ITCM | ITCM Arena | From ARM9
OS_ARENA_DTCM | DTCM Arena | From ARM9
OS_ARENA_SHARED | Shared Memory Arena | From ARM9
OS_ARENA_WRAM_MAIN | Shared work RAM arena (for ARM9) | From ARM9
OS_ARENA_WRAM_SUB | Shared work RAM arena (for ARM7) | From ARM7
OS_ARENA_WRAM_SUBPRIV | Work RAM arena (ARM7 dedicated) | From ARM7

`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`) | `HW_MAIN_MEM_MAIN_END( 0x023e0000 )`
Main Memory Arena (ARM7 dedicated) | `SDK_SUBPRIV_ARENA_LO` (acquired from `lcf`) | Beginning of ARM7 dedicated main memory
Main Memory Expanded Arena | 0 or SDK_SECTION_ARENA_EX_START (obtained from lcf )*1 | 0 or Before the debugger region *1
ITCM Arena | SDK_SECTION_ARENA_ITCM_START (obtained from lcf) | Highest order ITCM (0x02000000)
DTCM Arena | SDK_SECTION_ARENA_DTCM_START (obtained from lcf) | Before system mode stack *2
Shared Memory Arena (user region) | Bottom of shared memory | Before shared memory system region
Shared work RAM arena (for ARM9) | Bottom of Shared work RAM | Bottom of Shared work RAM *3
Shared work RAM arena (for ARM7) | *4 | Top of Shared work RAM
Work RAM arena (ARM7 dedicated) | *5 | Before system mode stack

*1 Use `OS_EnableMainEx()` to declare the main memory expanded arena; it cannot be used without declaring it. The upper and lower addresses of the main memory expanded arena are 0 when it cannot be used. Furthermore, there is no extended main memory in the the production version of the Nintendo DS system, so there will be no expanded arena in the main memory. Also in this case, the upper and lower addresses are 0.

*2 The region cannot be allocated for the DTCM arena when using the entire stack. When this happens, the upper and lower addresses of the DTCM arena have the same value.

*3 The top and bottom of the shared work RAM arena (for ARM9) have the same address. By default the size is 0.

*4 This is the lower address of the final address of the ARM7 static module and the highest address of the shared work region. 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.

*5 This is the higher end of the address of the ARM7 static module and the restart address of the ARM7 dedicated work RAM region. 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.

## See Also

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

## Revision History

08/27/2005 Changed the initial addresses of DTCM, ITCM and the main memory expanded arena.
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.

CONFIDENTIAL