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_AddExtraAreaToHeap</TITLE>
8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css">
9</HEAD>
10<BODY>
11<H1 align="left">OS_AddExtraAreaToHeap<IMG src="../../image/TWL.gif" align="middle"></H1>
12<H2>Syntax</H2>
13<DL>
14  <DD>
15  <PRE><CODE>#include &lt;nitro/os.h&gt;</CODE></PRE>
16  <PRE><CODE>void OS_AddExtraAreaToHeap( OSArenaId id, OSHeapHandle heap );</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 the arena for a heap to which the 16-KB region of the top of the main memory will be added.</TD>
24    </TR>
25    <TR>
26<TD><B><I>heap</I></B></TD>
27<TD>Handle of a heap to which the 16-KB region of the top of the main memory will be added.</TD>
28    </TR>
29  </TBODY>
30</TABLE>
31<H2>Return Values</H2>
32<P>None.</P>
33<H2>Description</H2>
34<P>A 16-KB region memory block from the top of main memory is added to the existing heap region.</P>
35<P>This function has special uses. (The added region is fixed at 16 KB of the bottom of main memory that is possible when a hybrid ROM is running in NITRO mode.) The function that adds the main memory block to the existing heap, for ordinary purposes, is the <A href="OS_AddToHeap.html"><CODE>OS_AddToHeap</CODE></A> function. Note that the <CODE>OS_AddExtraAreaToHeap</CODE> function is an inline function that internally calls the <CODE>OS_AddToHeap</CODE> function</P>
36<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>
37<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">This function does nothing even if called while a hybrid ROM is running on TWL hardware in TWL mode.</FONT></P>
38<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.</P>
39<P>This function <FONT color="#ff0000">adds the 16-KB region to the existing heap.</FONT>See the <A href="OS_CreateExtraHeap.html"><CODE>OS_CreateExtraHeap</CODE></A> function for more information on creating a heap using a 16-KB region Note that both cannot be run simultaneously.</P>
40<H2>See Also</H2>
41<P><A href="OS_AddToHeap.html"><CODE>OS_AddToHeap</CODE></A><BR> <A href="OS_CreateExtraHeap.html"><CODE>OS_CreateExtraHeap</CODE></A></P>
42<H2>Revision History</H2>
43<P>2009/04/03 Initial version.</P>
44<hr><p>CONFIDENTIAL</p></body>
45</HTML>