# OS_InitArena

## Syntax

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

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

Arena ID | Arena | Initialization
--- | --- | ---
OS_ARENA_MAIN | Arena in main memory (ARM9-dedicated) | From ARM9
OS_ARENA_MAIN_SUBPRIV | Arena in main memory (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 (user region) | 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
--- | --- | ---
Arena in main memory (ARM9-dedicated) | `SDK_MAIN_ARENA_LO` (acquired from `lcf`) | `HW_MAIN_MEM_MAIN_END( 0x023e0000 )`
Arena in main memory (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 the .lcf file) (*1) | 0 or Before the debugger region *1
ITCM Arena | SDK_SECTION_ARENA_ITCM_START (Obtained from the .lcf file) | Highest order ITCM (0x02000000)
Arena in DTCM | SDK_SECTION_ARENA_DTCM_START (Obtained from the .lcf file) (*2) | Before system mode stack *2
User information arena in shared memory | Bottom of shared memory | Before shared memory system region
Arena for ARM9 in shared work RAM | Bottom of shared work RAM (*3) | Bottom of shared work RAM (*3)
Arena for ARM7 in shared work RAM | *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. To allocate a region for the DTCM arena, you must prepare an empty region by adjusting the stack size in the `.lsf` file. (Refer to `tools/makelcf` and `tools/makelcf.TWL` for more about `.lsf` and `.lcf` files.) The stack for system mode is described here, but normally this is the stack for the launcher thread.

*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 larger of either (1) the ending address of the ARM7 static module or (2) the lowest 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
tools/makelcf
Arena Overview
`

## Revision History

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

CONFIDENTIAL