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_Alloc[From*]</TITLE> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</HEAD> 10<BODY> 11<H1 align="left">OS_Alloc[From*] <IMG src="../../image/NTR.gif" align="middle"><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>void* OS_AllocFromHeap( OSArenaId id, OSHeapHandle heap, u32 size ); 17 18void* OS_AllocFromMain( u32 size ); 19void* OS_AllocFromSubPriv( u32 size ); 20void* OS_AllocFromMainEx( u32 size ); 21void* OS_AllocFromITCM( u32 size ); 22void* OS_AllocFromDTCM( u32 size ); 23void* OS_AllocFromShared( u32 size ); 24void* OS_AllocFromWramMain( u32 size ); 25void* OS_AllocFromWramSub( u32 size ); 26void* OS_AllocFromSubPrivWram( u32 size ); 27 28void* OS_Alloc( u32 size );</code></PRE> 29</DL> 30<H2>Arguments</H2> 31<TABLE border="1" width="100%"> 32 <TBODY> 33 <TR> 34<TD width="13%"><EM><STRONG>id</STRONG></EM></TD> 35<TD width="87%">Arena ID of the arena associated with the heap from which a region will be reserved</TD> 36 </TR> 37 <TR> 38<TD><B><I>heap</I></B></TD> 39<TD>Handle of the heap from which a region will be reserved</TD> 40 </TR> 41 <TR> 42<TD><B><I>size</I></B></TD> 43<TD>Size of the region you want to reserve (bytes)</TD> 44 </TR> 45 </TBODY> 46</TABLE> 47<H2>Return Values</H2> 48<P>If a region was allocated, the region's start address is returned.<br />If it was not possible to allocate a region, <code>NULL</code> is returned.</P> 49<H2>Description</H2> 50<P>Allocates a memory block from a heap</P> 51<P>In <code>OS_AllocFromHeap</code>, you must specify the handle of the allocating heap and the arena ID of the arena that is associated with that heap. The arena is specified with the arena ID (<em><strong>id</strong></em>). To read more about this value, see <a href="../arena/OS_InitArena.html"><code>OS_InitArena</code></a>.</P> 52<P>If <code>OS_CURRENT_HEAP_HANDLE</code> is specified as the heap handle, it will be assumed that the arena's current heap is being specified.</P> 53<P>The secure memory domain is aligned at 32 bytes.</P> 54<P><code>OS_AllocFromMain</code> is the inline function for <code>OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... </code>.<br /></P> 55<P><CODE>OS_AllocFromSubPriv</CODE> is the inline function for <CODE>OS_AllocFromHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... )</CODE>.</P> 56<P><code>OS_AllocFromMainEx</code> is the inline function for <CODE>OS_AllocFromHeap( OS_ARENA_MAINEX, OS_CURRENT_HEAP_HANDLE, ... )</CODE>.</P> 57<P><code>OS_AllocFromICTM</code> is the inline function for <code>OS_AllocFromHeap( OS_ARENA_ITCM, OS_CURRENT_HEAP_HANDLE, ... )</code>.<br /></P> 58<P><code>OS_AllocFromDTCM</code> is the inline function for <code>OS_AllocFromHeap( OS_ARENA_DTCM, OS_CURRENT_HEAP_HANDLE, ... )</code>.<br /></P> 59<P><code>OS_AllocFromShared</code> is the inline function for <code>OS_AllocFromHeap( OS_ARENA_SHARED, OS_CURRENT_HEAP_HANDLE, ... )</code>.<br /></P> 60<P><CODE>OS_AllocFromWramMain</CODE> is the inline function for <CODE>OS_AllocFromHeap( OS_ARENA_WRAM_MAIN, OS_CURRENT_HEAP_HANDLE, ... )</CODE>.</P> 61<P><CODE>OS_AllocFromWramSub</CODE> is the inline function for <CODE>OS_AllocFromHeap( OS_ARENA_WRAM_SUB, OS_CURRENT_HEAP_HANDLE, ... )</CODE>. </P> 62<P><CODE>OS_AllocFromSubPrivWram</CODE> is the inline function for <CODE>OS_AllocFromHeap( OS_ARENA_WRAM_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... )</CODE>.</P> 63<P>For ARM9, <code>OS_Alloc</code> is the inline function for <code>OS_AllocFromHeap( OS_ARENA_MAIN, OS_CURRENT_HEAP_HANDLE, ... )</code>. For ARM7, <CODE>OS_Alloc</CODE> is the inline function for <CODE>OS_AllocFromHeap( OS_ARENA_MAIN_SUBPRIV, OS_CURRENT_HEAP_HANDLE, ... )</CODE>.</P> 64<P><B>Caution:</B> When trying to allocate a 0–byte region, DEBUG builds stop at <CODE>ASSERT</CODE>. In other builds, the operation is undefined.</P> 65<P>In the case of a DEBUG build, build stops on an assert if an attempt is made to allocate memory for a heap destroyed using the <A href="OS_DestroyHeap.html"><CODE>OS_DestroyHeap</CODE></A> function. Returns <CODE>NULL</CODE> in the case of RELEASE and FINALROM builds.</P> 66<H2>See Also</H2> 67<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_CreateHeap.html"><CODE>OS_CreateHeap</CODE></a><BR> <a href="OS_FreeToHeap.html"><CODE>OS_FreeToHeap</CODE></a><BR> <a href="OS_FreeAllToHeap.html"><CODE>OS_FreeAllToHeap</CODE></a></P> 68<H2>Revision History</H2> 69<P>2004/07/07 Added caution regarding 0-byte regions.<BR> 2004/03/08 Added difference in behavior when called in ARM7 and ARM9.<BR>2004/02/25 Changed the number of arenas from 6 to 9.<BR>2004/01/06 Initial version.</P> 70<hr><p>CONFIDENTIAL</p></body> 71</HTML>
