# OS_InitArena

## Syntax

      #include <nitro/os.h>

      void OS_InitArena( void );

## Arguments

None.

## Return Values

None.

## Description

Sets the upper and lower boundaries.

This function only needs to be called once before the `Alloc` functions or other `Arena` functions. This function is called internally by the `OS_Init` function, so there is normally no need for the application to call it again. Subsequent calls of this function do nothing.

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

The TWL-SDK allows you to define nine different arenas: main memory (one for ARM9 and one for ARM7), extended main memory, ITCM, DTCM, shared memory for the SDK, 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 | ARM9-dedicated main memory for the game program | From ARM9
OS_ARENA_MAIN_SUBPRIV | ARM7-dedicated main memory | From ARM7
OS_ARENA_MAINEX | Extended main memory for development debugging only | From ARM9
OS_ARENA_ITCM | ITCM | From ARM9
OS_ARENA_DTCM | DTCM | From ARM9
OS_ARENA_SHARED | Shared memory for the SDK | From ARM9
OS_ARENA_WRAM_MAIN | ARM9-shared Work RAM | From ARM9
OS_ARENA_WRAM_SUB | ARM7-shared Work RAM | From ARM7
OS_ARENA_WRAM_SUBPRIV | ARM7-dedicated Work RAM | From ARM7

Of the nine arenas, `OS_InitArena` for ARM7 sets up six the same as `OS_InitArena` for ARM9. The three exceptions are ARM7-dedicated main memory, ARM7-dedicated Work RAM, and ARM7-shared Work RAM.

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

Arena | Bottom | Top
--- | --- | ---
ARM9-dedicated main memory | `SDK_MAIN_ARENA_LO` (obtained from the LCF file) | `HW_MAIN_MEM_MAIN_END( 0x023e0000 )`
ARM7-dedicated main memory | `SDK_SUBPRIV_ARENA_LO` (obtained from the LCF file) | Beginning of ARM7-dedicated main memory
Extended main memory | 0 or `SDK_SECTION_ARENA_EX_START` (obtained from the LCF file) (*1) | 0 or Before the debugger region (*1)
ITCM | `SDK_SECTION_ARENA_ITCM_START` (obtained from the LCF file) | Highest order ITCM (`0x02000000`)
DTCM | `SDK_SECTION_ARENA_DTCM_START` (obtained from the LCF file) (*2) | Before system mode stack (*2)
Shared memory for the SDK | Bottom of shared memory | Before shared memory region
ARM9-shared Work RAM | Bottom of shared Work RAM (*3) | Bottom of shared Work RAM (*3)
ARM7-shared Work RAM | *4 | Top of shared Work RAM
ARM7-dedicated Work RAM | *5 | Before system mode stack

*1 To use the extended main memory arena, you must declare it with the `OS_EnableMainExArena` function. The upper and lower addresses of the extended main memory arena are 0 when it cannot be used. The commercial version of the Nintendo DS system has no extended main memory, so the extended main memory arena cannot be used for it. In this case, the upper and lower addresses are 0.

*2 The region cannot be allocated for the DTCM arena if the stack is full. 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. (See `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 shared Work, the empty region becomes the ARM7-shared Work RAM arena. If it does not fit, both the start address and end address become the top address of 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

2009/05/19 Revised description related to `OS_Init` in Description.
2005/08/27 Changed the initial addresses of DTCM, ITCM, and the main memory expanded arena.
2004/10/26 Corrected error in number of initialized arenas.
2004/10/01 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