This chapter describes required application support for access to storage media. There are several types of Nintendo 3DS applications, including card-based software, downloadable applications, and applications that run as Download Play clients. The contents of this chapter apply to all applications.
The table below shows whether applications can access the various storage media.
Game Card | SD Card | System NAND Memory | ||
---|---|---|---|---|
NTR/TWL | Nintendo 3DS | |||
Able to access? | Generally NO | Only the save data region | Direct access is prohibited | Direct access is impossible |
3.1.1 Access to NTR/TWL Game Cards
NTR and TWL data is more vulnerable than Nintendo 3DS data. Allowing Nintendo 3DS-exclusive applications to read and write vulnerable data would introduce a risk that the Nintendo 3DS data could also be analyzed by malicious users. In order to preserve the security of Nintendo 3DS data, the system has been designed so that Nintendo 3DS-exclusive applications cannot access NTR or TWL Game Cards. If you absolutely require access for some reason (such as to inherit the save data of past titles), contact Nintendo at support@noa.com.
It is possible for applications other than Nintendo 3DS card-based applications to read the contents of the ROM header.
No required guideline items.
3.1.2 Access to Nintendo 3DS Game Cards
On Nintendo 3DS, it is possible for downloadable applications and Download Play clients to access the save data region of a game card. When accessing this region, see 3.2.2 Accessing the Save Data of Other Applications for relevant precautions.
When the Game Card containing a currently running application is removed from the system, the system displays an error message and quits the application. The application itself does not need to do anything in response to the removal of the Game Card. For the same reason, you cannot swap an application’s Game Card while an application is running.
No required guideline items.
3.1.3 Access to SD Cards
If you specify DirectSdmc for FileSystemAccess in the RSF file's AccessControlInfo item, the application can directly access the SD card. Use this setting when using libraries like ImageDb that handle data in general-purpose formats, or when writing data in any format directly to the SD card in addition to using these libraries. Applications are forbidden from reading directly from the SD Card without using the libraries specified by Nintendo.
If you specify DirectSdmcWrite for FileSystemAccess, the application is able to write data in any format directly to the SD card. If you want to write data directly to the SD card without using libraries like ImageDb that handle data in general-purpose formats, you must specify this setting.
If you write data in any format to the SD card without using ImageDb, you must use the following directory structure to avoid any name collisions with files and directories from other applications.
\private\Nintendo 3DS\app\<Initial Code>\<any file or directory name>
This restriction does not apply when you write data using ImageDb because it is saved to a predetermined directory.
When sharing a directory among multiple applications, replace the <Initial Code> portion with the Initial Code of any one of the applications that will use the directory. It is acceptable to notify the user where data is saved either in the manual or within the application.
Access to SD Cards also takes place when the save data region of downloadable applications is accessed and when extra data is accessed, among other cases. To read about these cases, see chapter 3.3 Extra Data and chapter 3.4 Save Data and Extra Data: Common Items.
In addition, Nintendo 3DS specifications make it technically possible for the application to access an SD Card that was removed while the application was running, if the SD Card is reinserted and remounted. However, if an SD Card is removed while it is being written to, the entire SD Card may no longer be readable. For this reason, do not prompt the user to remove or insert an SD Card while the Nintendo 3DS is turned on.
It is acceptable to allow a user to reinsert an SD Card he or she has mistakenly removed if the application is able to once again read a card that has been removed. However, make sure not to make this action advantageous as part of error handling; for example, do not unintentionally allow the user to roll back to old versions of data. In these cases, users may start hot-swapping the SD card without that operation being intended or anticipated by the application. If you handle hot-swapping as an error, Nintendo recommends avoiding the inclusion of specifications that would make it beneficial for the user to reinsert the SD card.
3.1.3.1 Prohibition of Reading Directly from SD Cards
Guideline Item |
Content from SD Cards must not be read directly without using the libraries provided by Nintendo. |
---|---|
Software to Be Tested |
Applications for which DirectSdmc is specified for FileSystemAccess in the RSF file’s AccessControlInfo item. |
Test Method |
Check the source code. |
Pass/Fail Determination |
Passes if the SD Card content is not read directly. |
3.1.3.2 Handling Writing Data in Any Format to SD Cards
Guideline Item |
When writing data in any format directly to an SD Card, the application must only write to the specified folder. |
---|---|
Software to Be Tested |
|
Test Method |
|
Pass/Fail Determination |
When using the data in a single application: Passes if in step 2, the following folder on the SD Card has the data created by the application. \private\Nintendo 3DS\app\<Initial Code for this application> |
When using the data in multiple applications: Passes if in step 2, the following folder on the SD Card has the data created by the application. \private\Nintendo 3DS\app\<Initial Code for one of the applications using the data> |
3.1.3.3 Prohibition of Messages Prompting to Hot-Swap SD Cards While the Nintendo 3DS System Is Turned On
Guideline Item |
It is prohibited to display messages to prompt the user to remove or insert an SD Card while the Nintendo 3DS system is turned on. |
---|---|
Software to Be Tested |
All applications. |
Test Method |
Play through all modes of the application from beginning to end. |
Pass/Fail Determination |
Passes if the application does not display a message prompting the user to remove and re-insert the SD Card while the Nintendo 3DS system is turned on. |
3.1.4 Access to System NAND Memory
Applications cannot directly access the system NAND memory, but they can use certain libraries to access certain data. In particular, writes to the system NAND memory are sometimes performed when accessing shared extended save data (see the section on "Shared Data" in the Nintendo 3DS Overview).
It is prohibited to write to the system NAND memory with any high frequency, such as by calling a function that writes to this memory every second. If your application calls any of these functions periodically and automatically without user operations, then keep the total number of calls to all such functions combined to no more than 4 calls per minute.
As explained in section 2.21.4 Functions to Get the Remaining Number of Play Coins in the General Volume, the nn::pl::GetGameCoinCount function is used to get a value, but it also writes to system NAND memory; as such, it must not be called too frequently. However, this restriction does not apply in limited instances when the user is playing in an atypical way, such as when repeatedly pressing a button to frequently refresh the StreetPass outbox.
The following are some of the functions that write to the system NAND memory. However, depending on the function, one function call will not necessarily result in one write operation.
- The Create, Set, Write, Delete, Commit, and Close member functions of classes in the CEC library.
- The Initialize, Clear, and Entry functions of the ubl library.
- The CFL_SetReceivedPacket, CFL_FlushNetInformation, and CFL_Exit functions of the Face library.
- The NsData::Set functions of the Boss library.
- The GetGameCoinCount and UseGameCoin functions of the PL library.
3.1.4.1 Prohibition of Excessive Writes to System NAND Memory
Guideline Item |
An application must not write excessively to the system NAND memory, such as by updating shared extended save data every second. |
---|---|
Software to Be Tested |
Applications that write to the system NAND memory. |
Test Method |
Check the source code. |
Pass/Fail Determination |
Passes if the application does not write excessively, such as by updating save data every second. |
3.1.5 Write Frequency to Various Media
Just like system NAND memory, SD Cards and the backup memory regions of Game Cards have a limited number of erase-write cycles.
Avoid excessive writing and erasing of SD Cards or of backup memory (for example, performing a save every second or each time a character takes a step).
Even data that will ultimately need to be stored as save data should be stored in main memory until you are ready to write it to an SD Card or to the backup memory of a Nintendo 3DS Game Card. To minimize the number of writes required, consolidate as much data as you can into each write operation.
Be particularly careful not to rewrite excessively when performing automatic saves.
Automatic saves are saves that the application performs automatically and periodically.
An example of an automatic save is an electronic version of chess that saves the game each time the player moves a piece.
Nintendo defines excessive rewrites as writing 140 KB or more of data in a 1-minute period.
Nintendo defines the term rewrite frequency in terms of the average amount of save data written over the period of time the application is used in the intended way.
For example, if your application saves automatically once every 30 minutes, you must write no more than 4.1 MB of data each time.
This precaution does not apply only to save data and extended save data; it also applies to SD Card writes via the ImageDb or SoundIO libraries, and to direct SD Card writes.
Furthermore, storage media will undergo significant deterioration if small chunks of data are written using random access.
Avoid frequent small write operations.
Do not perform more than four write operations in a 1-minute period (on average), no matter how small the amount of data you are writing.
Your game may exceed the designated rewrite frequency if playing it in an atypical way (for example, if the user occasionally goes to a mini-game that takes less than a minute to complete and plays that mini-game over and over, or the user repeatedly performs a save at a save point), as long as the average rewrite frequency does not exceed the designated limit when the game is played normally.
3.1.5.1 Prohibition of Excessive Rewrites of Data
Guideline Item |
An application must not rewrite data excessively, such as by saving or erasing data every second or every time a character takes a step.
|
---|---|
Software to Be Tested |
Applications that save data automatically.
|
Exceptions |
Cases that exceed the limitations but are considered atypical, such as repeatedly playing a roughly 1-minute mini-game that saves after completing, or saving over and over at a save point.
|
Test Method |
Check the source code.
|
Pass/Fail Determination |
Passes if the total data written every 1 minute does not exceed 140 KB, and the total number of writes per minute on average does not exceed four operations.
|
3.1.6 Media Access Speeds
While access speeds will naturally differ between Nintendo 3DS Game Cards, system NAND memory, and SD Cards, access speeds to any single media type may also change over time due to media deterioration or system updates. Access speeds do not always get slower; they may also increase and be faster than expected. Access speeds may also vary from one SD Card to the next.
Consequently, do not design your application to depend on access speeds such that speeds faster or slower than expected would cause your application to lock up or result in some other fatal error, regardless of the application format.
Note that unlike section 3.2.3 Screen Display While Writing Data, this requirement is not meant to apply to unexpected access speeds or to all access speeds in all situations. Rather, this requirement is intended to prohibit implementations that hard-code assumptions about access speeds; for example, assuming that because loading should finish within 2 seconds at expected loading speeds, it is okay to forcibly halt loading after 2 seconds and start rendering from the loaded data.
See both these Guidelines and the CTR Programming Manual: System sections on "Latency Emulation" and "Media-Specific Cautions" for more information on how to check for normal behavior under various access speeds. Moreover, it is necessary to call the nn::fs::InitializeLatencyEmulation function inside the application in order to activate Latency Emulation (used to change the access speeds for purposes of debugging). No delay will occur if this API is called as-is in a mastered commercial version. Set your application so that it immediately calls the nn::fs::InitializeLatencyEmulation function upon launch so that Nintendo Lotcheck is able to verify your access speeds.
Game Card Verification
There are methods to check whether any processing in your application depends on Game Card access speeds. The respective methods are explained below.
■ If Using PARTNER-CTR Debugger:
- Start up the PARTNER-CTR Debugger software.
- From the main menu, select CTR → Card operations → FlashCard control.
- Under Latency Setting, set Transfer rate and Refresh time.
■ If Using PARTNER-CTR Writer:
- Start up the PARTNER-CTR Writer software.
- Select Flash memory process → Write.
- Set the transfer speed in the Latency Setting drop-down menu.
■ If Using IS-SNAKE DevKit:
- Start up the IS-CTR-DEBUGGER software.
- From the main menu, select Tools → Flash Card.
- Under the CTR Flash Card Settings, set Transfer Speed and Refresh time.
If at all possible, be sure to use the latest version of the PARTNER-CTR Debugger, PARTNER-CTR Writer, or IS-CTR-DEBUGGER software.
SD Card Verification
The guideline for this section requires the application to run without problems while latency emulation (mentioned above) is enabled.
Aside from this requirement, keep in mind that different SD Cards available in the market have different speed characteristics, and it is possible that using a different SD Card may greatly affect the "feel" and responsiveness of your application during normal operation. Nintendo recommends using several different types of SD Cards while testing your application.
Out of the standard SD Cards supported by Nintendo, ones that have relatively slow access speeds are listed below.
- Genuine Nintendo SD Card 8GB/16GB
Out of the standard SD Cards supported by Nintendo, ones that have relatively fast access speeds are listed below.
- Lexar 4GB SD Cards packaged with SPR
- Lexar Platinum II Series
- Japanese market: 8GB [LSD8GBBBJP200], 16GB [LSD16GBBJP200], and 32GB [LSD32GBBJP200]
- Korean market: 8GB [LSD8GBBSBAS200], 16GB [LSD16GBSBAS200], and 32GB [LSD32GBSBAS200]
- European market: 8GB [LSD8GBBBEU200C10], 16GB [LSD16GBBEU200], and 32GB [LSD32GBBEU200]
- Australian market: 8GB [LSD8GBBSBANZ200C10], 16GB [LSD16GBBANZ200], and 32GB [LSD32GBBANZ200]
- Americas market: 8GB [LSD8GBBSBNA200C10], 16GB [LSD16GBSBNA200], and 32GB [LSD32GBSBNA200]
Out of the micro SD Cards supported by Nintendo, ones that have relatively slow access speeds are listed below.
- Toshiba micro SD card 4GB packaged with SNAKE
- Genuine Nintendo SD Card 16GB/32GB
Out of the micro SD Cards supported by Nintendo, ones that have relatively fast access speeds are listed below.
- SanDisk Extreme
- Japanese market: 16GB [SDSDQX-016G-J35A, SDSDQXL-016G-J35A] and 32GB [SDSDQX-032G-J35A, SDSDQXL-032G-J35A]
- European market: 16GB [SDSDQXL-016G-Q46A] and 32GB [SDSDQXL-032G-Q46A]
- SanDisk Extreme PLUS
- Japanese market: 16GB [SDSDQX-016G-J35PA] and 32GB [SDSDQX-032G-J35PA]
- European market: 16GB [SDSDQX-016G-UQ46A] and 32GB [SDSDQX-032G-UQ46A]
- SanDisk Extreme PRO
- Japanese market: 16GB [SDSDQXP-016G-J35A] and 32GB [SDSDQXP-032G-J35A]
- European market: 16GB [SDSDQXP-016G-XQ46] and 32GB [SDSDQXP-032G-Q46A]
3.1.6.1 Prohibition of Processing That Depends on Access Speed (Card-Based Applications)
Guideline Item |
Application processing must not depend on access speeds such that speeds faster or slower than expected would cause abnormal operation. |
---|---|
Software to Be Tested |
All card-based applications |
Test Method |
If creating a ROM using PARTNER-CTR Debugger or Writer:
|
If creating a ROM using IS-SNAKE DevKit or MONOWRITER:
|
|
Pass/Fail Determination |
Passes if no fatal problems preventing application progress (such as lock-ups) occur in steps 6 or 8. |
3.1.6.2 Prohibition of Processing That Depends on Access Speed (Downloadable Applications)
Guideline Item |
Application processing must not depend on access speeds such that speeds faster or slower than expected would cause abnormal operation.
|
---|---|
Software to Be Tested |
All downloadable applications.
|
Test Method |
|
Pass/Fail Determination |
Passes if no fatal problems preventing application progress (such as lock-ups) occur in steps 4 or 6.
|