# Standard Archives: Overview

## Description

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.

## ROM Archive

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.

## NAND Archive

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.

## SD Memory Card Archive

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.

## Memory File Archive

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).

## Internal Format

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.

### NitroROM Format

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:

- With this format unique IDs are assigned to all files and directories, so calling `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.
- Because this format was designed for ROM storage media, it is difficult to change the structure of a directory tree. Archives that use the NitroROM format do not support operations such as adding, deleting, or moving files or directories.

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`.

### FAT Format

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.

- Because internal management information must be retained for directories and filenames, the actual amount of drive space consumed may exceed the nominal size of the file. The amount of needed drive space depends on the internal state of the file system and the length of the path name. Creating a directory requires at least 1 cluster of available space. If an indeterminate number of directories and files will be created in total, be sure to include adequate margin in your estimate of the amount of needed free space.
- There are upper limits on the total number of files and directories that can be created directly under the root directory, and that limit depends on various factors including the FAT format type, the FAT capacity, and the length of the file names.
- Certain SD Memory Cards may require an extremely long time for the initial access. This time will depend on various factors, including the cluster size and capacity and the manufacturer-specific data transfer speed.
- There are two types of file names: short file names (SFNs) and long file names (LFNs). These types have different character encodings. Long file names are always stored using UTF-16LE (Unicode), but there is no particular standard for the encoding of short file names other than the tendency to use the local encoding for the environment in which the file was created. As a result, it is impossible to reliably recognize the character encoding given only a short file name.

The implementation of the FAT driver used with TWL has the following characteristics.

- It supports FAT12/FAT16/FAT32 and SDHC memory cards.
- All archives implemented using the FAT format are processed by a single driver in the ARM7 component, so even if commands are issued simultaneously from multiple threads to multiple archives, those commands are processed one by one.
- The driver exists in the ARM7 component, so the reading and writing of files is affected by the cache line 32-byte boundary.
  If the buffer or transfer sizes specified in `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.
- When creating files or directories, the driver will always create long file names, regardless of whether the entry name can be represented in 8.3 format.
- If the seek pointer is not 4-byte aligned when reading from or writing to opened files, the access performance will drop.
- If a system shutdown is started, all commands that might require a long processing time will return `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.
- It will internally emulate the read/write lifetime of the system NAND memory in order to achieve conditions that are closer to those of the retail product. Random latency is added to the read access times for Debug or Release builds.
- The directory entries obtained with `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.
- Due to the driver design, only the date/time modified can be obtained using `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`.
- When you create a new filename that is long and not in the 8.3 format, it may require a very large amount of processing time to assign a short filename.
  For example, if you create a file with the name `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.
  The naming process is faster if you use the 8.3 naming format for files with sequentially numbered prefixes and suffixes.

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.

### Operational Comparison of Each Format

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

Functions | NitroROM Format (ROM Archive) | FAT Format (NAND Archive / SD Memory Card Archive) | (Memory File Archive)
FS_OpenFileEx (FS_OpenFile) |  |  | *3
FS_OpenFileFast |  | *4 | *3
FS_ConvertPathToFileID |  | *4 | *3
FS_OpenFileDirect |  | *5 | *3
FS_GetFileImageTop |  | *5 |
FS_GetFileImageBottom |  | *5 |
FS_CloseFile |  |  |
FS_GetFileLength |  |  |
FS_SetFileLength |  |  |
FS_GetFilePosition |  |  |
FS_SeekFile , FS_SeekFileToBegin , FS_SeekFileToEnd |  |  |
FS_ReadFile |  |  |
FS_ReadFileAsync |  |  |
FS_WriteFile | *1 |  |
FS_WriteFileAsync | *1 |  |
FS_FlushFile | *1 |  |
FS_OpenDirectory (FS_FindDir) |  |  | *3
FS_ReadDirectory (FS_ReadDir) |  |  | *3
FS_CloseDirectory |  |  | *3
FS_TellDir |  | *4 | *3
FS_SeekDir |  | *4 | *3
FS_RewindDir |  | *4 | *3
FS_GetPathName |  | *4 | *3
FS_GetPathLength |  | *4 | *3
FS_CreateFile | *2 |  | *3
FS_DeleteFile | *2 |  | *3
FS_RenameFile | *2 |  | *3
FS_CreateDirectory | *2 |  | *3
FS_DeleteDirectory | *2 |  | *3
FS_RenameDirectory | *2 |  | *3

*1: Commands that overwrite the contents of files are not supported.
*2: Commands that dynamically change directory structures are not supported.
*3: Commands that access directory structures are not supported.
*4: Commands that use file IDs or directory IDs are not supported.
*5: Commands that directly access a device's address space are not supported.

### List of Error Codes

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

## See Also

FS Function List

## Revision History

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