# OS_CreateExtraHeap

## 構文

      #include <nitro/os.h>

      OSHeapHandle OS_CreateExtraHeap( OSArenaId id );

## 引数

id | ヒープを作成するアリーナのアリーナID

## 返り値

ヒープを作成することが出来た場合、ヒープへのハンドル値を返します。これは0以上の値です。
ヒープを作成することが出来なかった場合、-1を返します。

## 説明

指定のアリーナにヒープを作成します。

この関数は特殊な用途 ( ヒープの領域は、HYBRID ROM を NITRO モードで動作させた際に出来るメインメモリ最下位 16KB の領域で固定 ) で用いられます。通常の用途で用いられるヒープ作成関数は `OS_CreateHeap()` です。

TWL ROM (HYBRID ROM、LIMITED ROM ともに) では、メインメモリの最下位 16KB にシステムの予約領域が作成されます。ただしこの領域は TWL モードで動作している場合にしか使用されません。すなわち、HYBRID ROM を NITRO ハードウェア上で NITRO モードで動作させている時には、この 16KB は全く使用されていません。

本関数は、この空いた 16KB の領域を指定のアリーナのヒープとして割り当てるための関数です。NITRO ROM や、TWL LIMITED ROM では、本関数を呼ぶことは出来ません。(HYBRID ROM ビルドでしか存在しませんのでコンパイルエラーとなります。) また、HYBRID ROM を TWL ハードウェア上で TWL モードで動作させているときには、本関数を呼んでもヒープは作成されませんのでエラーを表す -1 を返します。

アリーナはアリーナID id で指定します。この値については `OS_InitArena()` を参照してください。アリーナはあらかじめ `OS_InitAlloc()` でメモリ割り当てシステムの初期化を行なっておく必要があります。ヒープのための領域はメインメモリ先頭 0x02000000 から 0x02003FFF までの16KB となります。

作成したヒープを破壊するときは `OS_DestoryHeap()` を呼んでください。

ヒープを再初期化するときは `OS_ClearExtraHeap()` を呼んでください。( `OS_ClearHeap()` ではありません。)

> `(例)
> #define HEAP_NUM 2
> #define HEAP_SIZE 0x10000
> OSHeapHandle mainHeapHandle = -1;
> void NitroMain(void)
> {
> OS_Init();
> //---- Declare to use main memory heaps
> OS_InitAlloc( OS_ARENA_MAIN, OS_GetMainArenaLo(), OS_GetMainArenaHi(), HEAP_NUM );
> //---- Create main heap
> heapArea = OS_AllocFromArenaLo( OS_ARENA_MAIN, HEAP_SIZE, 32 );
> mainHeapHandle = OS_CreateHeap( OS_ARENA_MAIN, heapArea, (void*)((u32)heapArea + HEAP_SIZE) );
> //---- If NITRO MODE,　create extra heap
> if ( OS_IsRunOnTwl() == FALSE )
> {
> extraHeapHandle = OS_CreateExtraHeap( OS_ARENA_MAIN );
> }
> }`

この例では、NITRO モードで動作している場合のみ、`OS_CreateExtraHeap()` を呼ぶようにしています。このプログラムは HYBRID ROM ビルドされることが想定されています。NITRO ROM ビルドや、TWL LIMITED ROM ビルドを行うと、`OS_CreateExtraHeap()` が定義されていないため、コンパイルエラーとなります。

本関数は、16KB の領域を一つのヒープとして作成する関数です。すでにあるヒープの飛び地領域として追加する場合は、`OS_AddExtraAreaToHeap()` を参照してください。なお、16KB領域をヒープとして作成すれば、飛び地の追加領域としては使用できませんし、飛び地の追加領域として使用した場合は、1つのヒープとして作成することはできません。

## 参照

`OS_InitArena, OS_InitAlloc, OS_DestroyHeap
OS_ClearHeap, OS_ClearExtraHeap, OS_CreateHeap
OS_AddExtraAreaToHeap`

## 履歴

2009/04/03 `OS_AddExtraAreaToHeap` について追加
2009/02/17 初版