

The FS library will mount several standard archives depending on the type of program that has been booted. This document explains the basics about these archives.


Within the ROM data region of the DS Game Card, all programs store a single directory tree that was created with the makerom tool. The archive that accesses this directory tree is the ROM archive, and is always mounted using the name rom:. The data to include in the ROM can be specified at build time with the makerom tool. This data is arranged in a data structure known as the NitroROM format. For details about how to include data in the ROM, refer to the reference for the makerom tool.
The ROM archive can be used without any particular issues for normal card applications. With applications that are booted in other modes, however, there is no certainty that a DS Game Card is actually inserted in the console, so the system will behave as though this directory is empty. For information about the various boot types for programs, see the explanation in the OS_GetBootType page.
If you want to use the ROM archive in a program that has started using DS Download Play in the same way that you would with a card application, we recommend using the WFS library. This library is a utility for reconnecting to the parent that originated the download and accessing ROM data via local wireless communication.
If a program is booted as a NAND application, the program's own ROM data exists as a NAND file instead of being located on a DS Game Card. For this reason, during its initialization processing the NA library will automatically create an archive that treats the NAND file as if it were a DS Game Card.
When running in the TWL mode environment, hash check processing will verify ROM data validity, regardless of the boot type. This is a significant additional specification compared to before. Note that this uses significant CPU calculation time and reduces transfer speed. Using a card boot as an example, access speed in NTR mode is approximately 1.6MB/s compared to approximately 1.2MB/s in TWL mode.
Because this verification process requires information stored in an SRL or TAD file, it is not executed when only TLF files are loaded.

The TWL includes built-in NAND memory. In the documentation, the term NAND archive is used as a collective term for several types of archives that are used to access file systems located in this area. The system NAND memory is actually split into several partitions. The save data files stored by each individual NAND application form independent file systems, but they all use the FAT format as their internal structure. Refer to the TWL Programming Manual for more information on the properties of the system NAND memory.
Depending on the NAND application settings, up to 10 archives can be mounted as NAND archives. Each of these will have a different name, such as photo: or dataPub:. For details about each of these archives, see the NAND Application Development Manual.

TWL comes with an SD Memory Card slot, and certain program configurations allow this slot to be accessed. The SD Memory Card archive is mounted using the name sdmc:. SD Memory Cards also use the FAT format, so in general they are used in exactly the same way as NAND archives. That said, some care must be taken because there is wide variation in the data transfer speeds of individual SD Memory Cards, and because there is always a chance that the media could be removed or reinserted during access.
In addition, SD Memory Card recordable media are also used with personal computers and many consumer electronic devices. As a result, when using SD Memory Cards, you must always be aware of the potential danger posed by receiving external data whose content has been tampered with. The use of SD Memory Card archives is prohibited, therefore, with one exception. The SD Memory Card archive is convenient for development purposes, so restricted access is allowed for Debug/Release builds in TWL-SDK version 5.1PR and later.


This archive is a nameless archive that exists within the FS library and is not mounted by the system. Nameless files that have been opened by calls to the FS_CreateFileFromMemory function fall under this category of archive.
Since this archive can treat arbitrary memory spaces just as if they were files, this type of archive can be extremely useful if used properly (for example, by storing frequently used small files in memory).
The various standard archives described above use internal formats that differ from each other in their characteristics. This section describes the basic characteristics of each of these formats.
This is a data archive format unique to TWL-SDK that is used by tools such as nnsarc.exe in the TWL-System package as well as the makerom tool. It has the following characteristics:
FS_ConvertPathToFileID repeatedly to get the IDs of all files you'll be using in advance will allow you to open the files quickly using FS_OpenFileFast thereafter.
Most developers do not need to give consideration to the specifications of the NitroROM format, but those who require more detailed documentation should refer to $TwlSDK/docs/technicalNotes/NitroRomFormat.pdf.
This specifies the FAT file system that is widely used on SD Memory Cards, hard discs, and other such devices. FAT standards are defined in ISO/IEC 9293. There are various publications and specifications that describe the FAT format, so we have omitted a description here, but following are some characteristics to consider when you use it.
The implementation of the FAT driver used with TWL has the following characteristics.
ReadFile/WriteFile does not align with the cache line, a memory copy takes place via the temporary buffer inside the library. Asynchronous calls are ignored, and the process always blocks, causing the transfer speeds to decline.FS_RESULT_CANCELED and be canceled. Examples of such operations include the initial access to an SD Memory Card, or batch reads or writes of 2 MB or greater.FS_ReadDirectory are not sorted in any particular order; they are passed in the same order in which they are stored within the file system. Special entries (system nodes such as "." or "..", volume labels for SD Memory Cards, and so on) are also not filtered and can be obtained unchanged.FS_ReadDirectory (the creation and last-accessed dates/times cannot be obtained). If this information is required, it must be obtained separately by calling FS_GetPathInfo.aaaaaaaa101.bin, the first candidate for the shortened name is AAAAAA~1.BIN. Suppose, however, a series of 100 files with the names aaaaaaaa001.bin through aaaaaaaa100.bin already exist in the folder. The new shortened candidate name is recursively compared against all the existing shortened names, from AAAAAA~1.BIN through AAAA~100.BIN. The process would repeat 100 times before AAAA~101.BIN is assigned.A fatal timing exists that will cause inconsistency in the FAT internal state if an SD Card is removed while it is being accessed. The following describes the malfunction that can occur and a countermeasure.
| Situation when SD Card is removed | Symptom that could rarely occur | Possible workaround in the program |
| Changing file size (SetFileLength) | The intended addition to file size will be lost from free space. Or intended reduction in file size will be lost from free space. (The file itself will be OK.) |
There is no way to fix this from the program. You may be able to fix this using a check disk tool from an external environment such as a PC. |
| Creating an entry (Create) Moving an entry (Rename) |
The internally allocated long file name will be lost, and 13 characters or 32 bytes will be lost from free space. | |
| Deleting an entry (Delete) Moving and entry (Rename) |
All clusters used by the entry being deleted are lost from free space.1 | |
| A long filename will be lost, and the filename will become 8.3 format (short filename).2 | This will not be a problem if the program is not case-sensitive. | |
| When moving an entry (Rename) | Both entries will exist. Whichever you reference or change, it will point to the same content. If you delete one, any operation other that deleting the other one will fail as FS_RESULT_ERROR. |
You must delete both the old and new entry and create a new one. |
| Closing after appending a file (Close) | Data integrity problems arise because file size information is updated without allocating memory for the appended file. Attempted access to the appended memory fails on an FS_RESULT_ERROR. |
You must delete the file and create a new one. |
| * Note that 1 and 2 cannot occur at the same time. | ||
The FS library provides functions for manipulating most file systems, and while the various archives are required to be compliant with that interface, it is permissible not to implement operations that cannot be supported due to the nature of the file system. If functions are called for archives of this sort, the error FS_RESULT_UNSUPPORTED is always returned. The support status of each format in relation to main functions is shown in the table below.
| Usable | Not Usable |
The error codes defined by the FS library are incorporated into the internal processing of the archives. A number of the error codes are only returned by certain archives. The following table shows the error codes that can be returned from each archive.
Error Code (FSResult) | ROM Archive | NAND Archive | SD Memory Card Archive | Memory File Archive | Comments |
| FS_RESULT_SUCCESS | O | O | O | O | |
| FS_RESULT_FAILURE | O | O | O | O | |
| FS_RESULT_BUSY | O | O | O | O | |
| FS_RESULT_CANCELED | O | O | O | O | |
| FS_RESULT_UNSUPPORTED | O | O | O | O | |
| FS_RESULT_ERROR | O | O | O | O | |
| FS_RESULT_INVALID_PARAMETER | O | O | O | O | |
| FS_RESULT_NO_MORE_RESOURCE | X | O | O | X | |
| FS_RESULT_ALREADY_DONE | X | O | O | X | |
| FS_RESULT_PERMISSION_DENIED | O | O | O | X | |
| FS_RESULT_MEDIA_FATAL | X | O | O | X | Error unique to NAND/SD Memory Cards |
| FS_RESULT_NO_ENTRY | O | O | O | X | |
| FS_RESULT_MEDIA_NOTHING | X | X | O | X | Error unique to SD Memory Cards |
| FS_RESULT_MEDIA_UNKNOWN | X | X | O | X | Error unique to SD Memory Cards |
| FS_RESULT_BAD_FORMAT | X | O | O | X | Error unique to the FAT format |
2009/02/27 Added text about the file access behavior of the FAT driver.
2009/01/13 Mentioned that restricted access to the SD Memory Card archive is permitted, but only for the Debug and Release builds.
2008/12/08 Added a list of error codes returned by the archives.
2008/10/28 Added note about creating series of files with FAT driver.
2008/10/20 Added mention that ROM verification process is not executed when TLF is loaded.
2008/09/30 Added text about FAT state inconsistencies when SD Memory Card is inserted or removed.
2008/09/26 Added text about insertion and removal of SD Memory cards and the speed of ROM archive access.
2008/09/16 Added text about the FAT driver specification.
2008/09/12 Initial version.
CONFIDENTIAL