1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<HTML> 3<HEAD> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 7.0.1.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<TITLE>OS_CreateExtraHeap</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">OS_CreateExtraHeap<IMG src="../../image/TWL.gif" align="middle"></H1> 12<H2>Syntax</H2> 13<DL> 14 <DD> 15 <PRE><CODE>#include <nitro/os.h></CODE></PRE> 16 <PRE><CODE>OSHeapHandle OS_CreateExtraHeap( OSArenaId id ); </CODE></PRE> 17</DL> 18<H2>Arguments</H2> 19<TABLE border="1" width="100%"> 20 <TBODY> 21 <TR> 22<TD width="13%"><EM><STRONG>id</STRONG></EM></TD> 23<TD width="87%">Arena ID of an arena in which you are going to create a heap</TD> 24 </TR> 25 </TBODY> 26</TABLE> 27<H2>Return Values</H2> 28<P>In the case that it was possible to create a heap, the handle to the heap is returned. This is a value greater than or equal to 0.<BR>When a heap could not be created, -1 is returned.</P> 29<H2>Description</H2> 30<P>Creates a heap in the specified arena. </P> 31<P>This function has special uses. (The heap region is fixed at 16 KB of the bottom of the main memory that is possible when a hybrid ROM is running in NITRO mode.) The heap creation function for ordinary use is <A href="OS_CreateHeap.html"><CODE>OS_CreateHeap</CODE></A>.</P> 32<P>With TWL ROM (both hybrid and limited ROM), a system reserved region of 16 KB is created at the bottom of the main memory. However, this region can be used only when running in TWL mode. In other words, when a hybrid ROM is running in NITRO mode on NITRO hardware, this 16 KB is not used at all.</P> 33<P>This function allocates the empty 16-KB region to the heap of the specified arena. <FONT color="#ff0000">This function cannot be called for NITRO ROM and TWL limited ROM.</FONT>(It exists only with hybrid ROM, so a compile error will be generated. Also, <FONT color="#ff0000">a heap is not created even if this function is called while a hybrid ROM is running on TWL hardware and in TWL mode, so -1 is returned to indicate an error.</FONT></P> 34<P>The arena is specified with the arena ID (<SPAN class="argument">id</SPAN>). For more information on this value, see the <a href="../arena/OS_InitArena.html"><code>OS_InitArena</code></a> function. The arena must have memory allocated with the <CODE>OS_InitAlloc</CODE> function and have been initialized in advance. The region for the heap is 16 KB from <CODE>0x02000000</CODE> to <CODE>0x02003FFF</CODE> at the top of the main memory.</P> 35<P>Call the <a href="OS_DestroyHeap.html"><code>OS_DestroyHeap</code></a> function to destroy created heaps.</P> 36<P>Call the <A href="OS_ClearExtraHeap.html"><CODE>OS_ClearExtraHeap</CODE></A> function to reinitialize a heap.( Do not call the <A href="OS_ClearHeap.html"><CODE>OS_ClearHeap</CODE></A> function.)</P> 37<BLOCKQUOTE style="background-color:#ffffcc"> 38<CODE><B>(Ex.)</B><BR> <BR> #define HEAP_NUM 2<BR> #define HEAP_SIZE 0x10000<BR> OSHeapHandle mainHeapHandle = -1;<BR> <BR> void NitroMain(void)<BR> {<BR> OS_Init();<BR> <BR> //---- Declare to use main memory heaps<BR> OS_InitAlloc( OS_ARENA_MAIN, OS_GetMainArenaLo(), OS_GetMainArenaHi(), HEAP_NUM );<BR> <BR> //---- Create main heap<BR> heapArea = OS_AllocFromArenaLo( OS_ARENA_MAIN, HEAP_SIZE, 32 );<BR> mainHeapHandle = OS_CreateHeap( OS_ARENA_MAIN, heapArea, (void*)((u32)heapArea + HEAP_SIZE) );<BR> <BR> //---- If NITRO MODE, create extra heap<BR> <FONT color="#ff0000"> if ( OS_IsRunOnTwl() == FALSE )<BR> {<BR> extraHeapHandle = OS_CreateExtraHeap( OS_ARENA_MAIN );<BR> }</FONT><BR> <BR> }</CODE></BLOCKQUOTE> 39<P>In this example, the <CODE>OS_CreateExtraHeap</CODE> function is called only when running in NITRO mode. This program presumes that a hybrid ROM will be built. A compile error is generated when a NITRO ROM or TWL limited ROM is built because the <CODE>OS_CreateExtraHeap</CODE> function is not defined.</P> 40<P>This function <FONT color="#ff0000">adds the 16-KB region as one heap.</FONT>When a heap enclave region has already been added, see the <A href="OS_AddExtraAreaToHeap.html"><CODE>OS_AddExtraAreaToHeap</CODE></A> function. Note that if a 16-KB region is created as a heap, it cannot be used as an added enclave region. If used as an added enclave region, it cannot be created as one heap.</P> 41<H2>See Also</H2> 42<P><A href="../arena/OS_InitArena.html"><CODE>OS_InitArena</CODE></A><BR> <A href="OS_InitAlloc.html"><CODE>OS_InitAlloc</CODE></A><BR> <A href="OS_DestroyHeap.html"><CODE>OS_DestroyHeap</CODE></A><BR> <A href="OS_ClearHeap.html"><CODE>OS_ClearHeap</CODE></A><BR> <A href="OS_ClearExtraHeap.html"><CODE>OS_ClearExtraHeap</CODE></A><BR> <A href="OS_CreateHeap.html"><CODE>OS_CreateHeap</CODE></A><BR> <A href="OS_AddExtraAreaToHeap.html"><CODE>OS_AddExtraAreaToHeap</CODE></A> 43</P> 44<H2>Revision History</H2> 45<P>2009/04/03 Added information on <A href="OS_AddExtraAreaToHeap.html"><CODE>OS_AddExtraAreaToHeap</CODE></A>.<BR> 2009/02/17 Initial version.</P> 46<hr><p>CONFIDENTIAL</p></body> 47</HTML>
