The Cafe Core OS (COS) uses the memory map shown in the Figure 1. Application code and data are placed in MEM2, or main memory. The production version of an application is allocated 1 GB of main memory.
On a CAT-DEV, the development version of an application is allocated 2 GB of main memory, as shown in Figure 2.
The system reserves all of the memory, except for the areas allocated to your application. The system-reserved memory is not available to your application.
Your application's code and data areas reside in MEM2, or main memory.
MEM1 is a dedicated 32 MB of fast memory that is reserved for graphics rendering or other high-use textures (render targets, depth buffers, auxiliary buffers). You should profile your application with various resources stored in MEM1 to determine the best performance.
An application can access MEM1 only when the application is running in the foreground.
You may not use MEM1 for resources that have lifetimes longer than your foreground state.
OSDynLoad_SetAllocator, OS data structures such as
and calls to File System and other I/O functions may not target the foreground bucket
The Frame Heap Manager.
The foreground bucket is an extra 40 MB area in the foreground area of MEM2, above and beyond the 1 GB that is reserved for your application's code and data. This memory is available to an application only when it is running in the foreground.
You should use this only for graphics scan buffers and other data that:
Similar to MEM1, you may not use the foreground bucket for resources that have lifetimes longer than your foreground state.
ProcUISetBucketStorage function can be used to save and restore the foreground bucket over a transition to the background and back, doing so effectively defeats any advantages of using the foreground bucket.
The GPU has the ability to remap CPU accesses to a given texture or render target such that a tiled surface appears with its pixels in linear order in memory. This is known as the graphics tiling aperture feature. When the relevant GX2 API is called, the address returned will be in the graphics tiling aperture memory range. No actual memory exists here; it just points back to another area of user graphics memory space (in MEM1 or MEM2).
An application uses cache to access memory as shown in Figure 3. Cached and uncached access were both available to Wii applications. Only cached memory access is available to Wii U applications.
The MEM Library is the memory management library provided in Cafe SDK. It supports three types of heaps: expanded heap, frame heap, and unit heap. Under Operating System in the Cafe API Function Reference Manual, there is a Mem category, in which the algorithm and APIs for each heap type are described.
The Wii SDK had two types of memory management functions:
OSAlloc and the
MEM Library. For Cafe,
OSAlloc, which was retained for Nintendo GameCube compatibility, is discontinued,
and the MEM Library is the only remaining type of memory management function. Also, in Wii, the memory
area that remains after loading an application was called arena. For Cafe, the arena is
integrated into the MEM Library and provided as a base heap.
One big heap that is created from the memory area available to the application is referred to as a 'base heap'. MEM1, MEM2, and the foreground area (FG) have their own base heaps, which are initialized when an application starts up.
The MEM1 base heap is the frame heap of the MEM Library; the MEM2 base heap is an expanded heap; the FG base heap is also a frame heap. However, it is recommended that MEM1 be used as the storage location for GPU render targets and that the FG area be used as the storage location for scan buffers.
Management of a base heap can be accomplished by using a default allocator (
or can be overridden with another heap management mechanism, if the application specifies it. The default
allocator allocates memory from the default heap. By default, the default heap
is the base heap of MEM2. The default heap implementation uses the
MEM_HEAP_OPT_THREAD_SAFE flag to assure that it is thread-safe.
new allocate memory from the heap for Green Hills standard
library. The standard library obtains memory from the default heap to create its own heap. If
new attempt to allocate memory larger than the free space in the
malloc heap, the library will obtain additional memory from the default heap to enlarge
mallocis created before an application begins and is not deleted until the application exits. The default heap survives for the rest of the applications lifetime. For information on customizing the default heap, see Customize Memory Management.
The default allocator is a convenient function available to applications without initialization. Complex applications may require more flexible memory management.
Typical memory management methods include:
By using separate heaps, memory may be managed for different purposes. For example, you may want to create a heap for each module, such as one for graphics and one for audio. The default allocator may be used to allocate blocks of memory to be managed by subordinate heaps.
Depending on the application, you may want to shrink the default heap and free the remaining memory to the application, which can be performed in Cafe SDK. The freed memory can then be handled in the same way as the arena for the Wii console. For information about using a preinitialization function to shrink the default heap before your application runs, see Customize Memory Management.
For additional information about how this is performed, see the following demo:
In this demo,
sMEMInitDefaultHeap shrinks the default heap to 32 MB. The rest of
the memory should be turned into an expanded heap in the main function, and invoked before the
main function of an application.
sMEMInitDefaultHeap is defined in
$CAFE_ROOT/system/src/demo/os/memory/create_heap_for_application/defheap.c. For more information, see
A Visual Guide to How the System Starts.
For more advanced applications, you may want to replace the default allocator with the one that is defined by the application, which is supported in the Cafe SDK. When you replace the default allocator, the replacement heap implementation must be thread-safe.
Similar to shrinking the default heap, the default heap can be replaced with any algorithm by
creating an application-specific
__preinit_user, which is described in
Customize Memory Management.
For more information on how to replace the default heap, see the following demo:
Some SDK libraries allocate memory from the default heap. The tables below summarizes their usage.
|OS Loader||Depends on the size of the requested RPL. See
|Audio (AX)||Depends on the specific effect requested; see the AX Effects Memory Usage table. You can supply an alternate memory allocator.|
|USB_MIC||100 KB per microphone or headset, up to a maximum of 2 devices, for a total of 200 KB.|
|GFD||Depends on the specific request. Source code is available for this optional library, and you can supply an alternate memory allocator.|
|Matrix (MAT)||Depends on the specific request. Source code is available for this optional library, and you can supply an alternate memory allocator.|
|ProcUI||24 KB on initialization + 112 bytes per registered callback. You can supply an alternate memory allocator; see
|Network DNS||6144 bytes per request up to a max of 190,464 bytes. You can supply an alternate memory allocator; see
|HTTP Client||Depends on the specific request. You can supply an alternate memory allocator; see Memory Management in the HTTP Client Library for details.|
|Standard C library from Green Hills Software||Depends on the specific request.|
|C++ Runtime Library from Green Hills Software||Depends on the specific request.|
|zlib||Depends on the specific operation requested; see its
Memory allocation requirements for AX effects vary depending on the effect. By default, the required memory is allocated from the default heap. See
AXFX2SetHooks if you wish to supply a different allocator. The table below lists AX effects and their memory requirements.
|Delay 2ch||512||[26 ~ 256]||[39 ~ 384]|
|Delay 4ch||1024||[52 ~ 512]||[78 ~ 768]|
|Delay 6ch||1536||[78 ~ 768]||[117 ~ 1152]|
All of these allocations are dependent on an explicit call of an SDK API function, except for thread-local variables defined using the
__thread storage specifier and C++ exceptions.
Most memory usage by API functions is repeatable; for example:
strdupto create a copy of the same size string always allocates the same amount of memory.
However, a few cases are not readily predicted; for example:
__threadand by C++ exception handlers, while always the same, are non-trivial to compute.
You should also review the documentation that comes with any additional SDK patches that you have received from your local Nintendo support organization. These packages describe any additional sources of memory allocation.
You should leave 1 MB free in the default heap beyond the application's maximum usage to deal with these unpredictable memory allocation effects in the SDK. You should monitor and measure your application's maximum usage as it runs and add in any additional margin (on top of the already mentioned 1 MB) to account for any application variability.
The following demo shows how to allocate all areas in the default heap and how an allocated area can be used for another heap:
The following demo shows how to allocate memory from the default heap. Memory can be allocated without initialization. The default heap is an expanded heap.
The following demo measures the memory allocation performance:
Memory is allocated for three types of heaps and in various sizes to indicate the difference.
2014/03/04 Added info on default heap.
2014/02/06 Added Note for memalloc.
2013/12/05 ProcUI now supports a user-provided allocator.
2013/05/08 Automated cleanup pass.
2013/03/20 Converted to HTML.