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. Portion Offset (hex) Size Type Name Use Reserved for system 000 8 bytes u8[] corp_id Should be \"NINTENDO\" 008 24 bytes u8[] reserved_A Unused, should be 0 Static module params 020 4 bytes void* main_rom_offset Offset of ARM9 startup code in ROM 024 4 bytes void* main_entry_address Entry address [unimplemented] 028 4 bytes void* main_ram_address ARM9 destination RAM address 02C 4 bytes u32 main_size Size to copy for ARM9 code 030 4 bytes void* sub_rom_offset Offset of ARM7 startup code in ROM 034 4 bytes void* sub_entry_address Entry address [unimplemented] 038 4 bytes void* sub_ram_address ARM7 destination RAM address 03C 4 bytes u32 sub_size Size to copy for ARM7 code Nametable params 040 4 bytes ROM_FNTDir* fnt_offset Offset of name table in ROM 044 4 bytes u32 fnt_size Size of table FAT params 048 4 bytes ROM_FAT* fat_offset Offset of allocation table 04C 4 bytes u32 fat_size Table size Overlay header params 050 4 bytes ROM_OVT* main_ovt_offset ARM9 overlay offset in ROM 054 4 bytes u32 main_ovt_size Size of ARM9 overlay 058 4 bytes ROM_OVT* sub_ovt_offset ARM7 overlay offset 05C 4 bytes u32 sub_ovt_size Size of ARM7 overlay Reserved 060 16 bytes u8[] reserved_B Should be 0 070 3984 bytes u8[] reserved_C Again with the 0\'s 100 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 (hex) Size Type Name Use 000 4 bytes u32 entry_start Offset of the constituent file sub-table 004 2 bytes u16 entry_file_id ID of first file in the file sub-table 006 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 (hex) Size Type Name Use 000 Bitfield: 1 bit u8 entry_type 0 for a file 000 Bitfield: 7 bits u8 entry_name_length Length of entry name 001 [length] bytes char[] entry_name File name (NOT zero terminated)
This table describes a ROM_FNTStrDir structure. Offset (hex) 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 (hex) Size Type Name Use 000 4 bytes u32 id Overlay ID 004 4 bytes void* ram_address Point at which to load 008 4 bytes u32 ram_size Amount to load 00C 4 bytes u32 bss_size Size of BSS data region 010 4 bytes void* sinit_init Static initialiser start address 014 4 bytes void* sinit_init_end Static initialiser end address 018 4 bytes u32 file_id Overlay file 01C 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 (hex) Size Type Name Use 000 4 bytes void* top Start address of file in ROM 004 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.