Nintendo DS: NitroROM File System Specifications

# NitroROM File System Specifications

### Note that this document has been reworded in an attempt to circumvent possible watermarking measures. No pertinent information has been lost.

## Introduction

This document describes a simple file system which can be used to speed up development time, and where the program and data files map into ROM. Application developers need not concern themselves with the format of the file system; an API is provided.

### Details within this document may change before final release.

## Data Format

A NitroROM file has the following constituents.

- Header: 16KB of management stuff.
- Startup static blocks: Modules for the Main and Sub systems that are loaded and executed on startup.
- File name table: Array associating file names with numbers.
- Overlay header: Links for main and sub systems between file numbers and overlay IDs.
- File allocation table: Array of file numbers and ROM positions.
- File Images: Take a guess what these do.

For each block in the file, the developer can specify whether and to what granularity the block should be aligned. If alignment is required, padding will be added.

The ROM header is fixed at the top of the NitroROM file; all other blocks are accessed by direct or indirect pointers relative to the top of the header. Due to this, it is possible for the other blocks to lie in any order in the file.

## ROM Header Format

The following table shows the format of the ROM_Header structure.

Offset | Size | Type | Name | Use
--- | --- | --- | --- | ---
000h | 8 bytes | u8[] | corp_id | Should be "NINTENDO" *Reserved for system*
008h | 24 bytes | u8[] | reserved_A | Unused, should be 0
020h | 4 bytes | void* | main_rom_offset | Offset of ARM9 startup code in ROM *Static module params*
024h | 4 bytes | void* | main_entry_address | Entry address [unimplemented]
028h | 4 bytes | void* | main_ram_address | ARM9 destination RAM address
02Ch | 4 bytes | u32 | main_size | Size to copy for ARM9 code
030h | 4 bytes | void* | sub_rom_offset | Offset of ARM7 startup code in ROM
034h | 4 bytes | void* | sub_entry_address | Entry address [unimplemented]
038h | 4 bytes | void* | sub_ram_address | ARM7 destination RAM address
03Ch | 4 bytes | u32 | sub_size | Size to copy for ARM7 code
040h | 4 bytes | ROM_FNTDir* | fnt_offset | Offset of name table in ROM *Nametable params*
044h | 4 bytes | u32 | fnt_size | Size of table
048h | 4 bytes | ROM_FAT* | fat_offset | Offset of allocation table *FAT params*
04Ch | 4 bytes | u32 | fat_size | Table size
050h | 4 bytes | ROM_OVT* | main_ovt_offset | ARM9 overlay offset in ROM *Overlay header params*
054h | 4 bytes | u32 | main_ovt_size | Size of ARM9 overlay
058h | 4 bytes | ROM_OVT* | sub_ovt_offset | ARM7 overlay offset
05Ch | 4 bytes | u32 | sub_ovt_size | Size of ARM7 overlay
060h | 16 bytes | u8[] | reserved_B | Should be 0 *Reserved*
070h | 3984 bytes | u8[] | reserved_C | Again with the 0's
100h | 12288 bytes | u8[] | reserved_D | And again

## Startup Module

This is a supplied binary, linked in with the application ELF. The binary is placed in ROM without modification. The top ROM address for both processors must be aligned at a 512 byte boundary.

## File Name Table

This table associates file names with IDs. The table is built up from two sub-tables: a table of directories, and a file table. Directories are distinguished from files by their ID: a file can only have an ID in the range of 0x0000-0xEFFF, and a directory has an ID of 0xF000-0xFFFF. Therefore, there can be a maximum of 61440 files and 4096 directories. Directory sub-table

The size of the directory table implies the number of entries within it; the subscript of a given entry corresponds to a directory ID of subscript+0xF000.

The following table specifies the format of the ROM_FNTDir structure.

Offset | Size | Type | Name | Use
--- | --- | --- | --- | ---
000h | 4 bytes | u32 | entry_start | Offset of the constituent file sub-table
004h | 2 bytes | u16 | entry_file_id | ID of first file in the file sub-table
006h | 2 bytes | u16 | parent_id | ID of parent directory

The directory with ID 0xF000 is the root directory. In this case, the parent_id field holds the number of directories contained within the filesystem, since it has no parent. File sub-table

An entry in a file sub-table can be produced with either of two structures; one describes a file entry, and one a directory reference. The developer must choose which structure to use dependent on the circumstances.

The following table describes a ROM_FNTStrFile entry.

Offset | Size | Type | Name | Use
--- | --- | --- | --- | ---
000h | Bitfield: 1 bit | u8 | entry_type | 0 for a file
000h | Bitfield: 7 bits | u8 | entry_name_length | Length of entry name
001h | [length] bytes | char[] | entry_name | File name (NOT zero terminated)

This table describes a ROM_FNTStrDir structure.

Offset | Size | Type | Name | Use
--- | --- | --- | --- | ---
000 | Bitfield: 1 bit | u8 | entry_type | 1 for a dir
000 | Bitfield: 7 bits | u8 | entry_name_length | Length of entry name
001 | [length] bytes | char[] | entry_name | Dir name (NOT zero terminated)
[length]+1 | 1 byte | u8 | dir_id_L | Directory sub-table ID, low byte
[length]+2 | 1 byte | u8 | dir_id_H | Directory sub-table ID, high byte

A file or directory name must follow these rules:

- Maximum length of 127 single-byte characters
- Case-sensitive filenames. (Speeds up the read process)
- Entries with the same file name within the same directory are not allowed. The check for this is done at the time of compilation of the file system; hence, case sensitivity is ignored when this comparison is made.
- File name characters may only take values within the range of ASCII 0x20-0x7E, except the characters \/?"<>*:;|

Any file entries that are in the same directory are arranged in successive order, and as such get successive IDs. After a directory entry, and after the last file in a directory, a file entry of length 0 and name "\0" is entered.

Example filesystem:

- /Nitro.rom
- /l33t.dat
- /img/sprite.png

## Overlay Table Format

This table is normally created automatically by the compiler and linked in as binary. Since the IDs of the overlay files are not known at compile time, these must be filled in later.

The table comprises an array of ROM_OVT structures, which are described in detail below.

Offset | Size | Type | Name | Use
--- | --- | --- | --- | ---
000h | 4 bytes | u32 | id | Overlay ID
004h | 4 bytes | void* | ram_address | Point at which to load
008h | 4 bytes | u32 | ram_size | Amount to load
00Ch | 4 bytes | u32 | bss_size | Size of BSS data region
010h | 4 bytes | void* | sinit_init | Static initialiser start address
014h | 4 bytes | void* | sinit_init_end | Static initialiser end address
018h | 4 bytes | u32 | file_id | Overlay file
01Ch | 4 bytes | u32 | reserved | For future expansion

## File Allocation Table

The FAT is made up of an array of ROM_FAT structures, which are given in detail below. The array subscript corresponds to the file ID given in the FNT. A set of zero values in a FAT entry designates an unused file ID.

Offset | Size | Type | Name | Use
--- | --- | --- | --- | ---
000h | 4 bytes | void* | top | Start address of file in ROM
004h | 4 bytes | void* | bottom | End address of file in ROM

## File Images

The files are simply placed into the NitroROM image at the places specified by the FAT.