RomFS

RomFS (or Read-Only Filesystem) is part of the NCCH format, and is used as external file storage.

RomFS can be used:

• in conjunction with the ExeFS of a NCCH

• to contain the game manual accessible from the Home Menu

• to contain the DLP Child CIA)

• or to contain game cartridge update data

(There may be more implementations in the future)

The RomFS is wrapped inside a IVFC hash-tree container, and the actual data is structured like a node-based tree, starting at the root level directory node, moving down to other directory and file nodes. Each directory node has pointers to child directory nodes and siblings, together with a pointer to the first file node for that directory. Each file node has pointers to their next file node, together with information about the actual file data.

The RomFS IVFC hash-tree header is 0x5C bytes long and is structured as follows:

The Level 3 partition of a RomFS consists of a header specifying offsets to four tables, followed by filedata (aligned to 16-bytes). Though their size varies by RomFS contents, the tables are always sequential and in the same order, as follows:

RomFS Header data is always 0x28 bytes long, and follows this layout (offsets are from the start of the header):

When a RomFS is built, directories are added recursively starting with the root. When a directory is added, all of its files are added to the File Metadata Table, then all of its subdirectories (if any), are added to the table. If any of the directory’s subdirectories have their own subdirectories, the current directory’s subdirectories are all added before the subdirectories’ subdirectories are added.

A Metadata entry for a directory has the following structure (all values are initialized to 0xFFFFFFFF, and remain that way when unused):

A Metadata entry for a file has the following structure (all values are initialized to 0xFFFFFFFF, and remain that way when unused):

For both files and directories, a 🔗 separate chaining hash table is created for quick lookup.

A hash table consists of a number of buckets, all initialized to 0xFFFFFFFF. The size of the table is dependent on the number of entries in the relevant MetaData table (it’s probably intended to always be the smallest prime number greater than or equal to the number of entries, but the implementation was lazy), illustrated by the following code (C#):

        public static byte[] GetHashTableLength(uint numEntries)
        {
            uint count = numEntries;
            if (numEntries < 3)
                count = 3;
            else if (numEntries < 19)
                count |= 1;
            else
            {
                while (count % 2 == 0
                    || count % 3 == 0
                    || count % 5 == 0
                    || count % 7 == 0
                    || count % 11 == 0
                    || count % 13 == 0
                    || count % 17 == 0)
                {
                    count++;
                }
            }
            return count;
        }

The hash function is based off directory/file name (byte array taken from Metadata entry) and Parent Directory’s offset (C#):

        public static uint CalcPathHash(byte[] Name, uint ParentOffset)
        {
            uint hash = ParentOffset ^ 123456789;
            for (int i = 0; i < Name.Length; i += 2)
            {
                hash = (hash >> 5) | (hash << 27);
                hash ^= (ushort)((Name[i]) | (Name[i + 1] << 8));
            }
            return hash;
        }

Each directory/file is put into the ith bucket, where i is the hash taken modulus of bucket count. The directories/files in the same bucket form a linked list, with the value in hash table as the offset to the head element. When creating the hash table, a latter added directory/file is always added as the head element of the linked list.