This chapter describes memory regions that can be accessed by applications and Nintendo 3DS Game Cards written to by card-based software.
3.1. Memory
3.1.1. Memory Map
The following figure shows a memory map as seen by applications. This memory map is for release versions.
Memory access from applications is carried out using virtual addresses.
For security reasons, it is not possible to execute data arrays loaded into memory other than the region where the program is loaded (such as heap memory or device memory).
Memory above address 0x4000_0000
is reserved.
3.1.2. Device Memory
Device memory is a region in memory for which the operating system guarantees address integrity when it is accessed by the GPU or other peripheral device. Some of the buffers accessed by the GPU used for graphics and the DSP used for sound must be allocated from this device memory. Conversely, some buffers cannot be allocated from device memory. Generally, those buffers must be 4096-byte aligned and have sizes that are multiples of 4096 bytes.
You can use the nn::os::SetDeviceMemorySize()
function to specify the size of the memory region to allocate as device memory. Specify the size as a multiple of nn::os::DEVICE_MEMORY_UNITSIZE
(4096 bytes). On CTR, you can allocate up to 64 MB for the main program, heap memory and device memory (96 MB on development hardware). On SNAKE, you can allocate up to 124 MB (178 MB on development hardware). You can call this function again to change the size of the memory region to allocate, but if you do you must change the size by a multiple of 1 MB (1,048,576 bytes). When changing to size 0 at this time, there are no issues if the size before the change is a multiple of 1 MB. Similarly, when changing from size 0, there are no issues if the size before the change is a multiple of 1 MB. However, it has to be made a multiple of 4096 bytes.
There is no guarantee that the address of the memory region allocated will be the same for every call. After specifying the size of the region, first use the nn::os::GetDeviceMemoryAddress
function to get the starting address of the region and then access the device memory. Use the nn::os::GetDeviceMemorySize
function to get the size of the currently allocated memory.
Device |
Buffer Type |
Alignment |
Comments |
---|---|---|---|
GPU |
Texture image |
128 bytes |
|
Vertex buffers |
1 to 4 bytes |
Changes depending on vertex attributes. |
|
Display buffer |
16 bytes |
|
|
DSP |
Sound source data |
32 bytes |
The size of the whole region storing sound source data must be a multiple of 32 bytes. |
CAMERA |
Receive buffer |
64 bytes (recommended) |
If you use a buffer allocated in a space other than device memory, the SDK stops on a panic. |
Y2R |
Image data receive/send buffer |
64 bytes (recommended) |
If you use a buffer allocated in a space other than device memory, the SDK stops on a panic. |
Buffers accessed by the GPU may also be allocated from VRAM.
Buffer |
Comments |
---|---|
Buffer storing microphone sampling results |
Must be 4096-byte aligned, and its size must be a multiple of 4096 bytes. |
UDS library’s receive buffer |
Must be 4096-byte aligned, and its size must be a multiple of 4096 bytes. |
Socket library’s receive buffer |
Must be 4096-byte aligned, and its size must be a multiple of 4096 bytes. |
HTTP library’s working buffer |
Must be 4096-byte aligned, and its size must be a multiple of 4096 bytes. |
DLP library’s working buffer |
Must be 4096-byte aligned, and its size must be a multiple of 4096 bytes. |
ACT library communication buffer |
Must be 4096-byte aligned, and its size must be a multiple of 4096 bytes. |
3.1.3. VRAM
VRAM consists of the two regions VRAM-A and VRAM-B, each 3 MB, for a total of 6 MB.
Applications must manage memory regions used by the GX (graphics) library, such as by allocating color buffers. (Note that when reading VRAM on the CPU, the data is not guaranteed to be accurate.) To allocate memory in VRAM, use the nngxGetVramStartAddr
, nngxGetVramEndAddr
, and nngxGetVramSize()
functions to get the start and end addresses and size of VRAM to manage the location of the requested memory regions.
For more information about the GX library and how to manage memory used by libraries, see 5.5. Initializing the GX Library (in this manual) and the 3DS Programming Manual: Basic Graphics.
3.1.4. Heap Memory
This memory is freely usable by applications, such as for allocating file read and write buffers. Use the nn::os::SetHeapSize
function to specify the size of heap memory to allocate. The size must be a multiple of nn::os::HEAP_UNITSIZE
(4096 bytes) On CTR, the total size of main program meny, heap memory, and device memory must be no greater than 64 MB (96 MB for development units). On SNAKE, the heap can use up to 96 MB and the total size of main program memory, heap memory, and device memory must be no greater than 124 MB (178 MB for development hardware). Call this function again to change the size of the memory region to allocate.
When expanding and reducing the size of the heap memory region according to the usage status, and resizing the device memory region accordingly, take note of the following points when managing the heap memory region.
- When reducing the heap memory region after it was expanded, reduce it by the same amount it was incremented.
- The heap memory region can be divided more than once and expanded. In such cases, reduce its size in stages, so that it returns to the size prior to expansion.
If this condition is violated, it may not be guaranteed that the unassigned region can be secured as device memory.
As shown in Figure 3-2, when reducing the heap memory region and expanding the device memory region from a state where the heap memory region was expanded in stages (Step 1, Step 2, Step 3), to return the heap memory region to the size it was prior to expansion, first reduce it by the same size it was incremented by in Step 3 (Step 4), and then reduce it by the same size it was increased by in Step 2 (Step 5).
Wherever possible, we recommend maintaining the total size required by the heap memory region and not resizing it. Perform these steps only when a resize is absolutely required. However, resizing in small units can lead to a considerable drop in performance when accessing the memory.
There is no guarantee that the address of the memory region allocated will be the same for every call. After specifying the size, use the nn::os::GetHeapAddr()
function to get the starting address of the region. Use the nn::os::GetHeapSize()
function to get the size of the currently allocated heap.
3.2. Nintendo 3DS Game Cards
There are two types of Nintendo 3DS Game Cards: CARD1 and CARD2. The card most appropriate for use is determined by the game title’s specifications.
As a rule, use CARD1 for game titles with a backup memory capacity of 512 KB, and use CARD2 for those with a capacity of 1 MB or more.
3.2.1. CARD1
CARD1 cards come equipped with both read-only memory (ROM) and backup memory (rewritable non-volatile memory).
3.2.1.1. ROM
The CARD1 ROM transfer speed varies depending on the version of the SDK in use and the size of the data being transferred. The actual speed may also vary slightly due to differences in individual cards, so do not design applications that depend on transfer speeds.
There are six different ROM capacities, ranging from 128 MB to 4 GB.
ROM Capacity |
Transfer |
Usable Space Size by Market |
||
---|---|---|---|---|
Japan, North America, Korea |
Europe |
China, Taiwan |
||
128 MB |
(See Note) |
93.5 MB |
91.5 MB |
61.5 MB |
256 MB |
219.0 MB |
217.0 MB |
187.0 MB |
|
512 MB |
470.0 MB (492,830,720 bytes) |
468.0 MB |
438.0 MB |
|
1 GB |
921.5 MB |
919.5 MB |
889.5 MB |
|
2 GB |
1875.5 MB |
1873.5 MB |
1843.5 MB |
|
4 GB |
3783.0 MB |
3781.0 MB |
3751.0 MB |
Transfer speeds depend on the version of the SDK and the size of the data. For more information, see 3DS Performance Tips.
3.2.1.2. Backup Memory
The transfer speed for backup memory in CARD1 cards depends on the version of the SDK in use and the size of the data being transferred. The actual speed may also vary slightly due to differences in individual cards, so do not design applications that depend on transfer speeds. See the CTR Guidelines and follow its standards for the number of write operations.
There are two different backup memory capacities, either 128 KB or 512 KB. Use a CARD2 card if you need 1 MB or more of backup memory.
The content of backup memory at time of shipment is guaranteed to be padded with 0xFF
throughout the entire memory region. Pad all of backup memory with 0xFF
when emulating the memory state at time of shipment.
You can enable automatic redundancy of the backup memory region used for save data files. However, when automatic redundancy is enabled, the capacity available for saving files is roughly 40% of the total capacity.
Backup Memory Capacity |
Transfer Speed |
Usable Region Size When Automatic Redundancy Is Enabled |
---|---|---|
128 KB |
(See Note) |
50 KB or less |
512 KB |
239 KB or less |
Transfer speeds depend on the version of the SDK and the size of the data. For more information, see 3DS Performance Tips.
3.2.2. CARD2
CARD2 cards come equipped with writable memory that has features of both ROM and backup memory.
3.2.2.1. Writable Memory
The transfer speed for writable memory in CARD2 cards depends on the version of the SDK used and the size of the data involved. The actual speed may vary slightly due to differences in individual cards, so do not design applications that depend on transfer speeds. See the CTR Guidelines and follow its standards for the number of write operations.
With writable memory, you can change the boundaries of the ROM (read-only) and backup (rewritable) regions in 1-MB increments.
You can use the library to enable automatic redundancy for data in backup memory, just as with CARD1 backup memory. Calculate the usable capacity for saving files in a similar manner. The maximum file size that you can specify as backup space is half of the writable memory capacity. There are three sizes of writable memory capacity: 512 MB, 1 GB, and 2 GB.
Writable Memory Capacity |
Transfer |
Usable Space Size by Market |
||
---|---|---|---|---|
Japan, North America, Korea |
Europe |
China, Taiwan |
||
512 MB |
(See Note) |
412.5 MB |
410.5 MB |
412.5 MB |
1 GB |
889.5 MB |
887.5 MB |
889.5 MB |
|
2 GB |
1843.5 MB |
1841.5 MB |
1843.5 MB |
Transfer speeds depend on the version of the SDK and the size of the data. For more information, see 3DS Performance Tips.