3dbrew - User contributions [en]

Inner FAT

2020-01-30T19:50:21Z

Wwylele: /* Directory Hash Table & File Hash Table */

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram:

[[File:Inner-fat.png]]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

The special file <code>00000000/00000001</code> is configured as external IVFC level 4 disabled, and all other device files are configured as it enabled.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks (including pre header for title database)
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| ID of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
(excluding the leading 0th entry. See below)
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= File allocation table entry count)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.
* For title database (except for ticket), the range specified for data region seems overflow the file end by 0x80 bytes, which is exactly the size of the pre header. This makes it as if the data region offset should be relative to the pre header instead of the BDRI header. However, further investigation on the directory/file table allocated inside the data region shows that the data region offset is indeed relative to the BDRI header. It might be a bug in 3DS that the title database files miss 0x80-byte space at the end.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
uint8_t name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example:

[[File:Disa-fat.png]]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

RomFS

2020-01-24T14:58:39Z

Wwylele: Undo revision 21154 by Marius851000 (talk) This is not true. I opened one of RomFS of an official game I have. The root directory has the "Offset of first Child Directory" = 0x18, implying the root directory entry located at offset 0 is 0x18 bytes, which would contain the "Name Length" field. The said field also has value 0 as expected.

=== Overview ===
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 [[Download Play#Broadcasted application data|DLP Child CIA]])

*or to contain game cartridge update data

(There may be more implementations in the future)

=== Format ===

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:

{| class="wikitable" border="1"
|-
! START
! SIZE
! DESCRIPTION
|-
| 0x00
| 0x4
| Magic "IVFC"
|-
| 0x04
| 0x4
| Magic number 0x10000
|-
| 0x08
| 0x4
| Master hash size
|-
| 0x0C
| 0x8
| Level 1 logical offset
|-
| 0x14
| 0x8
| Level 1 hashdata size
|-
| 0x1C
| 0x4
| Level 1 block size, in log2
|-
| 0x20
| 0x4
| Reserved
|-
| 0x24
| 0x8
| Level 2 logical offset
|-
| 0x2C
| 0x8
| Level 2 hashdata size
|-
| 0x34
| 0x4
| Level 2 block size, in log2.
|-
| 0x38
| 0x4
| Reserved
|-
| 0x3C
| 0x8
| Level 3 logical offset
|-
| 0x44
| 0x8
| Level 3 hashdata size
|-
| 0x4C
| 0x4
| Level 3 block size, in log2.
|-
| 0x50
| 0x4
| Reserved
|-
| 0x54
| 0x4
| Reserved
|-
| 0x58
| 0x4
| Optional info size.
|}

=== Level 3 Format ===

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:

{| class="wikitable" border="1"
|-
! START
! SIZE
! DESCRIPTION
|-
| 0x0
| 0x28
| Header
|-
| 0x28
| Varies
| Directory HashKey Table
|-
| Varies
| Varies
| Directory Metadata Table
|-
| Varies
| Varies
| File HashKey Table
|-
| Varies
| Varies
| File Metadata Table
|-
| Varies
| Varies
| File Data
|}

=== Level 3 Header Format ===

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

{| class="wikitable" border="1"
|-
! START
! SIZE
! DESCRIPTION
|-
| 0x0
| 0x4
| Header Length
|-
| 0x4
| 0x4
| Directory Hash Table Offset
|-
| 0x8
| 0x4
| Directory Hash Table Length
|-
| 0xC
| 0x4
| Directory Metadata Table Offset
|-
| 0x10
| 0x4
| Directory Metadata Table Length
|-
| 0x14
| 0x4
| File Hash Table Offset
|-
| 0x18
| 0x4
| File Hash Table Length
|-
| 0x1C
| 0x4
| File Metadata Table Offset
|-
| 0x20
| 0x4
| File Metadata Table Length
|-
| 0x24
| 0x4
| File Data Offset
|}

=== Directory Metadata Structure ===

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

{| class="wikitable" border="1"
|-
! START
! SIZE
! DESCRIPTION
|-
| 0x0
| 0x4
| Offset of Parent Directory (self if Root)
|-
| 0x4
| 0x4
| Offset of next Sibling Directory
|-
| 0x8
| 0x4
| Offset of first Child Directory (Subdirectory)
|-
| 0xC
| 0x4
| Offset of first File (in File Metadata Table)
|-
| 0x10
| 0x4
| Offset of next Directory in the same Hash Table bucket
|-
| 0x14
| 0x4
| Name Length
|-
| 0x18
| Name Length (rounded up to multiple of 4)
| Directory Name (Unicode)
|}

=== File Metadata Structure ===

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

{| class="wikitable" border="1"
|-
! START
! SIZE
! DESCRIPTION
|-
| 0x0
| 0x4
| Offset of Containing Directory (within Directory Metadata Table)
|-
| 0x4
| 0x4
| Offset of next Sibling File
|-
| 0x8
| 0x8
| Offset of File's Data
|-
| 0x10
| 0x8
| Length of File's Data
|-
| 0x18
| 0x4
| Offset of next File in the same Hash Table bucket
|-
| 0x1C
| 0x4
| Name Length
|-
| 0x20
| Name Length (rounded up to multiple of 4)
| File Name (Unicode)
|}

=== Hash Table Structure ===

For both files and directories, a [https://en.wikipedia.org/wiki/Hash_table#Collision_resolution 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#):

<pre>
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;
}
</pre>

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

<pre>
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;
}
</pre>

Each directory/file is put into the ''i''th 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.

DISA and DIFF

2020-01-02T05:21:18Z

Wwylele: /* Summary diagram */

This page describes DISA and DIFF format as the underlying container of [[Savegames]], [[Extdata]] and [[Title Database]]. For further format specification of the inner data, please refer to their own page.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

== Overview ==

DISA and DIFF are two container formats. They are very similar and are used for various purposes in 3DS. Here is a summary table of their usage, the CMAC type and the AES key slot used (the meaning of these is explained in the next section):

{| class="wikitable" border="1"
! Usage
! Media
! Container format
! [[#AES CMAC|CMAC type]]
! CMAC [[AES Registers|Keyslot]]
|-
| [[Savegames]]
| Gamecard
| DISA
| [[#CTR-NOR0|CTR-NOR0]]
| 0x19 / 0x33
|-
| [[Savegames]]
| [[SD Filesystem|SD]]
| DISA
| [[#CTR-SIGN|CTR-SIGN]]
| 0x30
|-
| [[System SaveData]]
| [[Flash Filesystem|NAND]]
| DISA
| [[#CTR-SYS0|CTR-SYS0]]
| 0x30
|-
| [[Extdata|Private Extdata]]
| [[SD Filesystem|SD]]
| DIFF
| [[#CTR-EXT0|CTR-EXT0]]
| 0x30
|-
| [[Extdata|Shared Extdata]]
| [[Flash Filesystem|NAND]]
| DIFF
| [[#CTR-EXT0|CTR-EXT0]]
| 0x30
|-
| [[Title Database]]
| [[SD Filesystem|SD]]
| DIFF
| [[#CTR-9DB0|CTR-9DB0]]
| 0x30
|-
| [[Title Database]]
| [[Flash Filesystem|NAND]]
| DIFF
| [[#CTR-9DB0|CTR-9DB0]]
| 0x0B
|}

== Encryption ==

DISA and DIFF formats don't have their own encryption specification. They follow the encryption method defined by their media:

* Gamecard savegames have special wear leveling + encryption layers. See [[Savegames]] for detail.
* Files on SD follow [[SD Filesystem|the general SD filesystem encryption rule]].
* Files on NAND are in cleartext, after decrypting [[Flash Filesystem|the NAND partition encryption]].

== Format ==

A DISA / DIFF file consists of the following components:

* 0x100-byte AES CMAC
* 0x100-byte Header
* Secondary partition table
** Contains one or two partition descriptors, depending on the number of partitions.
* Primary partition table
** Same layout as the secondary one
* Partition A
* Partition B (optional)
** can only exist for DISA.

== AES CMAC ==

The AES CMAC is located at the beginning of the DISA / DIFF image, and it is 0x10 long. The rest 0xF0 bytes before the header are unused.

The key used for the AES CMAC is generated by the [[AES Registers|hardware key engine]]. See the keyslot it uses in the table above.

The data being authenticated by the AES CMAC is a 0x20-byte SHA-256 hash of a data block. The data block has different content formats among CMAC types. All types of data block contain a copy or a hash of the header, which is the start of the the rest of the verification chain, so the AES CMAC effectively authenticates the whole save image. Each type of data block is explained below.

=== CTR-NOR0 ===

This CMAC type is used for gamecard savegames. It is 0x28-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-NOR0"
|-
| 0x8
| 0x20
| SHA-256 of the following 0x108-byte block
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SAV0"
|-
| 0x08
| 0x100
| Copy of the DISA header
|}
|}

=== CTR-SIGN ===

This CMAC type is used for SD savegames. It is 0x30-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SIGN"
|-
| 0x08
| 8
| Title ID
|-
| 0x10
| 0x20
| SHA-256 of the following 0x108-byte block
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SAV0"
|-
| 0x08
| 0x100
| Copy of the DISA header
|}
|}

=== CTR-SYS0 ===

This CMAC type is used for NAND system save. It is 0x110-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SYS0"
|-
| 0x08
| 8
| Save ID. The higher word is always zero
|-
| 0x10
| 0x100
| Copy of the DISA header
|}

=== CTR-EXT0 ===

This CMAC type is used for extdata. It is 0x11C-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-EXT0"
|-
| 0x08
| 8
| Extdata ID
|-
| 0x10
| 4
| 0 for Quota.dat, 1 otherwise
|-
| 0x14
| 4
| ID in the device file name. 0 for Quota.dat
|-
| 0x18
| 4
| ID in the device directory name that the file is in. 0 for Quota.dat
|-
| 0x1C
| 0x100
| Copy of the DIFF header
|}

=== CTR-9DB0 ===

This CMAC type is used for title database. It is 0x10C-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-9DB0"
|-
| 0x08
| 4
| Database ID. Each .db file has its own ID
|-
| 0x0C
| 0x100
| Copy of the DIFF header
|}

== Header ==

The header located at offset 0x100 defines the rest components of the file (partitions and their tables). All offsets in the header are relative to the beginning of the DISA/DIFF file, except for partition descriptor offsets, which are relative to the beginning of the (active) partition table. DISA and DIFF have different header format.

=== DISA header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DISA"
|-
| 0x04
| 4
| Magic 0x40000
|-
| 0x08
| 4
| Partition count, 1 or 2
|-
| 0x0C
| 4
| Padding
|-
| 0x10
| 8
| Secondary partition table offset
|-
| 0x18
| 8
| Primary partition table offset
|-
| 0x20
| 8
| Partition table size
|-
| 0x28
| 8
| Partition A descriptor offset in the partition table
|-
| 0x30
| 8
| Partition A descriptor size
|-
| 0x38
| 8
| Partition B descriptor offset in the partition table
|-
| 0x40
| 8
| Partition B descriptor size
|-
| 0x48
| 8
| Partition A offset
|-
| 0x50
| 8
| Partition A size
|-
| 0x58
| 8
| Partition B offset
|-
| 0x60
| 8
| Partition B size
|-
| 0x68
| 1
| Active partition table, 0 = primary, 1 = secondary
|-
| 0x69
| 3
| Padding
|-
| 0x6C
| 0x20
| SHA-256 over the active partition table
|-
| 0x8C
| 0x74
| Unused
|}

Note:

* When the partition count is 1, there is no partition B and all of its related fields are zero.

=== DIFF header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DIFF"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 8
| Secondary partition table/descriptor offset
|-
| 0x10
| 8
| Primary partition table/descriptor offset
|-
| 0x18
| 8
| Partition table/descriptor size
|-
| 0x20
| 8
| Partition (A) offset
|-
| 0x28
| 8
| Partition (A) size
|-
| 0x30
| 4
| Active partition descriptor, 0 = primary, 1 = secondary
|-
| 0x34
| 0x20
| SHA-256 over the active partition table/descriptor
|-
| 0x54
| 8
| Unique identifier
|-
| 0x5C
| 0xA4
| Unused, might contain leftover data
|}

Note:

* Since DIFF can only contain one partition, a partition table can only have one partition descriptor, so they become the same concept here.
* See [[Extdata]] for its usage of the unique identifier field. For title database files, this field is zero.

== Partition table & partition descriptor ==

There are two partition tables, but only one of them is active. When operating on a DISA / DIFF file, 3DS FS alternately activate one of the two tables, presumably for data backup or atomic file writing. A newly created DISA / DIFF file may have entirely uninitialized data in the inactive partition table.

One partition table contains one or two partition descriptors , each of which describes the layout of one partition. A partition descriptor contains the following components:

* DIFI header
* IVFC descriptor
* DPFS descriptor
* Partition master hash

=== DIFI header ===

The DIFI header locates at the beginning of a partition descriptor. This header defines the rest components of the partition descriptor (IVFC descriptor, DPFS descriptor and partition master hash). All offsets are relative to the beginning of the partition descriptor, except for <code>External IVFC level 4 offset</code>, which is relative to the beginning of the partition.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DIFI"
|-
| 0x04
| 4
| Magic 0x10000
|-
| 0x08
| 8
| IVFC descriptor offset
|-
| 0x10
| 8
| IVFC descriptor size
|-
| 0x18
| 8
| DPFS descriptor offset
|-
| 0x20
| 8
| DPFS descriptor size
|-
| 0x28
| 8
| Partition hash offset
|-
| 0x30
| 8
| Partition hash size
|-
| 0x38
| 1
| If none zero, enable external IVFC level 4.
|-
| 0x39
| 1
| DPFS tree level 1 selector
|-
| 0x3A
| 2
| Padding
|-
| 0x3C
| 8
| External IVFC level 4 offset (zero if external IVFC level 4 disabled)
|}

Note:

* The meaning of fields after 0x38 are explained in the section [[#Partition]]

=== IVFC descriptor ===

This header defines each level of IVFC tree (explained in the section [[#Partition]]). All offsets are relative to the beginning of DPFS level 3.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "IVFC"
|-
| 0x04
| 4
| Magic 0x20000
|-
| 0x08
| 8
| Master hash size = partition master hash size in DIFI header
|-
| 0x10
| 8
| IVFC level 1 offset
|-
| 0x18
| 8
| IVFC level 1 size
|-
| 0x20
| 4
| IVFC level 1 block size in log2
|-
| 0x24
| 4
| Padding
|-
| 0x28
| 8
| IVFC level 2 offset
|-
| 0x30
| 8
| IVFC level 2 size
|-
| 0x38
| 4
| IVFC level 2 block size in log2
|-
| 0x3C
| 4
| Padding
|-
| 0x40
| 8
| IVFC level 3 offset
|-
| 0x48
| 8
| IVFC level 3 size
|-
| 0x50
| 4
| IVFC level 3 block size in log2
|-
| 0x54
| 4
| Padding
|-
| 0x58
| 8
| IVFC level 4 offset (unused if external IVFC level 4 enabled)
|-
| 0x60
| 8
| IVFC level 4 size
|-
| 0x68
| 4
| IVFC level 4 block size in log2
|-
| 0x6C
| 4
| Padding
|-
| 0x70
| 8
| IVFC descriptor size? The value is usually 0x78
|}

=== DPFS descriptor ===

This header defines each level of DPFS tree (explained in the section [[#Partition]]). All offsets are relative to the beginning of the partition.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DPFS"
|-
| 0x04
| 4
| Magic 0x10000
|-
| 0x08
| 8
| DPFS level 1 offset
|-
| 0x10
| 8
| DPFS level 1 size
|-
| 0x18
| 4
| DPFS level 1 block size in log2 (unused?)
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 8
| DPFS level 2 offset
|-
| 0x28
| 8
| DPFS level 2 size
|-
| 0x30
| 4
| DPFS level 2 block size in log2
|-
| 0x34
| 4
| Padding
|-
| 0x38
| 8
| DPFS level 3 offset
|-
| 0x40
| 8
| DPFS level 3 size
|-
| 0x48
| 4
| DPFS level 3 block size in log2
|-
| 0x4C
| 4
| Padding
|}

=== Partition master hash ===

This is a SHA-256 hash list over IVFC level 1. See [[#IVFC tree]] for explanation.

== Partition ==

A partition can have two types of layout. This is determined by the field DIFF + 0x38 (<code>Enable external IVFC level 4</code>).

The layout type 0 (external IVFC level 4 disabled) contains

* DPFS level 1
* DPFS level 2
* DPFS level 3, and inside
** IVFC level 1
** IVFC level 2
** IVFC level 3
** IVFC level 4 (the actual content data)

The layout type 1 (external IVFC level 4 enabled) contains

* DPFS level 1
* DPFS level 2
* DPFS level 3, and inside
** IVFC level 1
** IVFC level 2
** IVFC level 3
* IVFC level 4 (the actual content data, note that this is out side DPFS level 3)

=== DPFS tree ===

Everything inside the DPFS tree comes in pairs, and at one time only one of a pair is active. The tree is probably designed for atomic writing: for a file writing operation, it writes to the inactive part, then commits the data by switching a bit to activate it.

Each level of DPFS tree consists of a pair of chunks. The size of one chunk is defined as it in the DPFS descriptor, so the total size of a level is actually twice as large as the size recorded in the descriptor. For level 1 and 2, each chunk is a bit array, in which each bit corresponds to a block in the next level (the block size of the next level is also defined in the DPFS descriptor). This bit indicates which one of the pair in the next level is active for this block: 0 means the first one and 1 means the second one. The active chunk of level 1 is selected by <code>DPFS tree level 1 selector</code> in the DIFI header. The bit array is encoded in u32 array, with MSB as the first bit of each 32 bits.

To access data in level 3, one needs to check the bits in level 1 and level 2 to know which chunk of level 3 is active for the accessed location. For example, for a following configuration:

* Level 1: size = 4 bytes = 32 bits
* Level 2: size = 0x380 bytes = 0x1C00 bits, block size = 0x80 bytes
* Level 3: size = 0x1B7F000, block size = 0x1000, block size = 0x1000 bytes

if one want to read byte at 0x1234567 of level 3, the following calculation is performed:

* get level 2 bit index <code>0x1234567 / 0x1000 = 0x1234</code>, and its byte location <code>0x1234 / 8 = 0x246</code>
* get level 1 bit index <code>0x246 / 0x80 = 4</code>
* get <code>level1_selector</code> from DIFI header
* read <code>level2_selector = Level1[level1_selector].bits[4]</code>;
* read <code>level3_selector = Level2[level2_selector].bits[0x1234]</code>;
* read <code>data = Level3[level3_selector].bytes[0x1234567]</code> as the final data
* in the code above <code>Levelx[k]</code> means the <code>k</code>-th chunk in level <code>x</code>, where <code>k = 0, 1</code>. <code>.bits[n]</code> is expanded to <code>(.u32_array[n / 32] >> (31 - n % 32)) & 1</code> as the bit array is encoded in u32 array.

Effectively, the active data is scattered among the two level 3 chunk. One can assemble the whole active level 3 image following the same rule.

=== IVFC tree ===

The IVFC tree is used for data verification. It is very similar to the IVFC tree in [[RomFS]], except that it has an additional level here. For level 1, 2 and 3, each level is a list of SHA-256 hash, of which each corresponds to a block of the next level which is zero-padded to align the block size (the block size of the next level is defined in the IVFC descriptor).

The partition master hash in the partition descriptor can be seen as IVFC level 0, which hashes level 1 following the same rule. The master hash is usually 0x20 long, consisting only one hash. This is because most DISA / DIFF files are not large enough to have multiple hashes on the top level, which isn't the case for some title database files.

However, not all data is hashed - only ranges that have been written with valid data are properly hashed.

Level 4 is the actual content of the partition, which is what the container format essentially contains.

== Extracting content from a DISA / DIFF container ==

* Find the active partition table and the partition(s).
* Unwrap DPFS tree of partition(s) by reconstructing active data.
* Unwrap IVFC tree. Either take out level 4 directly, or, better, verify all the hashes and poison the data that is not properly hashed.
* The IVFC level 4 is the inner content of the file. The format of it varies among different usage. Refer their own page for further extraction.

== Chain of trust ==

* AES CMAC verifies the header.
* The header verifies the active partition table via the table hash.
* In the partition table, each descriptor verifies level 1 of its IVFC tree via the master hash.
* Each IVFC level verifies the next level, until the level 4, which is the inner content.

== Summary diagram ==

[[File:Disa-diff.png]]

File:Disa-diff.png

2020-01-02T05:20:28Z

Wwylele:

Inner FAT

2020-01-02T05:16:41Z

Wwylele: Embed diagrams

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram:

[[File:Inner-fat.png]]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

The special file <code>00000000/00000001</code> is configured as external IVFC level 4 disabled, and all other device files are configured as it enabled.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks (including pre header for title database)
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| ID of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
(excluding the leading 0th entry. See below)
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= File allocation table entry count)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.
* For title database (except for ticket), the range specified for data region seems overflow the file end by 0x80 bytes, which is exactly the size of the pre header. This makes it as if the data region offset should be relative to the pre header instead of the BDRI header. However, further investigation on the directory/file table allocated inside the data region shows that the data region offset is indeed relative to the BDRI header. It might be a bug in 3DS that the title database files miss 0x80-byte space at the end.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example:

[[File:Disa-fat.png]]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

File:Disa-fat.png

2020-01-02T04:59:47Z

Wwylele:

File:Inner-fat.png

2020-01-02T00:41:14Z

Wwylele:

Savegames

2019-12-23T02:51:05Z

Wwylele: /* Gamecard savegame Encryption */

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]]. Inside the DISA container, it forms a [[Inner FAT|FAT filesystem]]. '''Please refer to these pages for how to fully extract save files'''. This page only describes additional encryption wear leveling on top of the DISA container. These layers only apply to gamecard save games. SD savegames and NAND savegames are DISA containers in plaintext after decrypting the common SD/NAND encryption layer.

== Gamecard savegame Encryption ==

Gamecard encryption is AES-CTR applied on top of DISA container, but below the wear leveling layer (if exists). The same key Y used for encryption is also used for DISA CMAC signing. Several versions of encryption scheme have been introduced over the time.

{| class="wikitable" border="1"
|-
! FW Introduced
! Old3DS
! [[AES#Keyslot|AES Keyslots]] (Encryotion / CMAC)
! KeyY generation method
! Repeating CTR
|-
| The initial version
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v1
| style="background: #ccffbb" | Yes
|-
| [[2.0.0-2]]
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v2
| style="background: #ccffbb" | Yes
|-
| [[2.2.0-4]]
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v2
| style="background: #ffccbb" | No
|-
| [[6.0.0-11]]
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v3
| style="background: #ffccbb" | No
|-
| [[9.6.0-24|9.6.0-X]]
| style="background: #ffccbb" | No
| 0x1A / 0x19
| v2?
| style="background: #ffccbb" | No
|}

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== KeyY Generation methid ===

The [[NCSD]] partition flags determine the method used to generate this keyY.

==== v1 ====

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== v2 ====

Key Y is the first 0x10 bytes of SHA-256 calculated over the following data

{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x40
| read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID)
|}

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== v3 ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

First, a SHA-256 hash is calculated over the following data

{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x40
| Same ID as [[Process_Services_PXI|GetRomId]]
|-
| 0x48
| 0x8
| CXI Program ID
|-
| 0x50
| 0x20
| ExeFS:/.code hash from the decrypted [[ExeFS]] header
|}

Then an [[AES]]-CMAC is calculated over this hash. The output CMAC is used for keyY. The key slot for this CMAC is 0x2F.

The 0x2F keyY used for calculating this AES-CMAC (not to be confused with the final keyY for decrypting/signing savegames) is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

There are two versions of wear leveling have been observed. V1 is used for 128KB and 512 KB CARD1 flash chips. V2 is used for 1MB CARD1 flash chips (uncommon. Pokemon Sun/Moon is an exampe).

First, there are two 32-bit integers whose purposes are currently unknown. They generally increase the value as the savegame is written more times, so probably counter for how many times the journal became full and got flushed into the block map, and/or how many times <code>alloc_cnt</code> has wrapped around.

Then comes the actual blockmap. The block map contains entries of 10 bytes (V1) or 2 bytes (V2) with total number of <code>(flash_size / 0x1000 - 1)</code>.
The blockmap entry is simple:
<pre>
struct blockmap_entry_v1 {
uint8_t phys_sec; // when bit7 is set, block is initialized and has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));

struct blockmap_entry_v2 {
// Note that the phys_sec and alloc_cnt field are swapped in v2,
// but the initialized bit is still on the first byte
uint8_t alloc_cnt; // when bit7 is set, block is initialized
uint8_t phys_sec;
// v2 has no chksums
} __attribute__((__packed__));
</pre>

There's one entry per 0x1000-byte sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

A 2-byte CRC16 follows the block map. For V1 it immediately follows the last block map entry. For V2 it is located at 0x3FE, and bytes before the CRC is padded with zero. The CRC16 checks all the bytes before it, including the two unknown integers, the block map, and the padding bytes for V2. The CRC standard used looks like CRC-16-IBM (modbus). Here is the code in Rust for it

<pre>
fn crc16(data: &[u8]) -> u16 {
let poly = 0xA001;
let mut crc = 0xFFFFu16;
for byte in data {
crc ^= <u16>::from(*byte);
for _ in 0..8 {
let b = crc & 1 != 0;
crc >>= 1;
if b {
crc ^= poly;
}
}
}
crc
}
</pre>

Then comes the journal. The journal contains entries that describes how sectors should be remapped. The rest bytes before 0x1000 after all journal entries are padded with 0xFF
The journal entry structure is as follows:
<pre>
struct journal_entry_half {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8]; // Unused & uninitialized for V2
} __attribute__((__packed__));

struct journal_entry{
struct journal_entry_half entry;
struct journal_entry_half dupe; // same data as `entry`. No idea what this is used fore
uint32_t uninitialized; // 0xFFFFFFFF in newer system
}__attribute__((__packed__));
</pre>

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (same CRC16 algorithm as above) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/wwylele/save3ds save3ds] supports reading and modifying savegames, extdata and title database in FUSE filesystem or batch extracting/importing.
* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard. (This is an old tool that doesn't handle the savegame format correctly. --[[User:Wwylele|Wwylele]] ([[User talk:Wwylele|talk]]) 16:13, 2 December 2019 (CET))
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.

[[セーブデータ|Japanese]]

Savegames

2019-12-22T18:30:24Z

Wwylele: /* Gamecard savegame Encryption */ Add summary table for encryption

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]]. Inside the DISA container, it forms a [[Inner FAT|FAT filesystem]]. '''Please refer to these pages for how to fully extract save files'''. This page only describes additional encryption wear leveling on top of the DISA container. These layers only apply to gamecard save games. SD savegames and NAND savegames are DISA containers in plaintext after decrypting the common SD/NAND encryption layer.

== Gamecard savegame Encryption ==

Gamecard encryption is AES-CTR applied on top of DISA container, but below the wear leveling layer (if exists). The same key Y used for encryption is also used for DISA CMAC signing. Several versions of encryption scheme have been introduced over the time.

{| class="wikitable" border="1"
|-
! FW Introduced
! Old3DS
! [[AES#Keyslot|AES Keyslots]] (Encryotion / CMAC)
! Key Y generation method
! Repeating CTR
|-
| The initial version
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v1
| style="background: #ccffbb" | Yes
|-
| [[2.0.0-2]]
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v2
| style="background: #ccffbb" | Yes
|-
| [[2.2.0-4]]
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v2
| style="background: #ffccbb" | No
|-
| [[6.0.0-11]]
| style="background: #ccffbb" | Yes
| 0x37 / 0x33
| v3
| style="background: #ffccbb" | No
|-
| [[9.6.0-24|9.6.0-X]]
| style="background: #ffccbb" | No
| 0x1A / 0x19
| v2?
| style="background: #ffccbb" | No
|}

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== Savegame keyY ===

All gamecard and SD savegames are encrypted with AES-CTR. The base CTR for gamecard savegames is all-zero. The gamecard savegame [[AES|keyslots]]' keyY(these savegame keyslots use the hardware key-generator) is unique for each region and for each game. The [[NCSD]] partition flags determine the method used to generate this keyY. When the save [[NCSD]] flags checked by the running NATIVE_FIRM are all-zero, the system will use the repeating CTR, otherwise a proper CTR which never repeats within the image is used.

The [[AES]]-CMAC (which uses a hardware key-generator keyslot, as mentioned above) at the the beginning of the savegame must match the calculated CMAC using the DISA/DIFF data, otherwise the savegame is considered corrupted(see below).

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY(original keyY method used with saves where the CTR repeats within the image) is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== [[2.0.0-2]] Hashed keyY and [[2.2.0-4]] Savegame Encryption ====

When certain [[NCSD]] partition flags are set, a SHA-256 hash is calculated over the data from the CXI(same data used with the original plain keyY), and the 0x40-bytes read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID). The first 0x10-bytes from this hash is used for the keyY. When flag[7] is set, the CTR will never repeat within the save image, unlike the original CTR-method. All games which had the retail NCSD image finalized after the [[2.2.0-4]] update(and contain [[2.2.0-4]]+ in the [[System Update CFA|System update partition]]), use this encryption method.

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== [[6.0.0-11]] Savegame keyY ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

A SHA-256 hash is calculated over the same data used with the above hashed keyY method, after hashing the above data the following data is hashed: the CXI programID, and the ExeFS:/.code hash from the decrypted [[ExeFS]] header. An [[AES]]-CMAC (the keyslot used for this uses the hardware key-scrambler) is then calculated over this hash, the output CMAC is used for the savegame keyY.

The keyY used for calculating this AES-CMAC is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

There are two versions of wear leveling have been observed. V1 is used for 128KB and 512 KB CARD1 flash chips. V2 is used for 1MB CARD1 flash chips (uncommon. Pokemon Sun/Moon is an exampe).

First, there are two 32-bit integers whose purposes are currently unknown. They generally increase the value as the savegame is written more times, so probably counter for how many times the journal became full and got flushed into the block map, and/or how many times <code>alloc_cnt</code> has wrapped around.

Then comes the actual blockmap. The block map contains entries of 10 bytes (V1) or 2 bytes (V2) with total number of <code>(flash_size / 0x1000 - 1)</code>.
The blockmap entry is simple:
<pre>
struct blockmap_entry_v1 {
uint8_t phys_sec; // when bit7 is set, block is initialized and has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));

struct blockmap_entry_v2 {
// Note that the phys_sec and alloc_cnt field are swapped in v2,
// but the initialized bit is still on the first byte
uint8_t alloc_cnt; // when bit7 is set, block is initialized
uint8_t phys_sec;
// v2 has no chksums
} __attribute__((__packed__));
</pre>

There's one entry per 0x1000-byte sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

A 2-byte CRC16 follows the block map. For V1 it immediately follows the last block map entry. For V2 it is located at 0x3FE, and bytes before the CRC is padded with zero. The CRC16 checks all the bytes before it, including the two unknown integers, the block map, and the padding bytes for V2. The CRC standard used looks like CRC-16-IBM (modbus). Here is the code in Rust for it

<pre>
fn crc16(data: &[u8]) -> u16 {
let poly = 0xA001;
let mut crc = 0xFFFFu16;
for byte in data {
crc ^= <u16>::from(*byte);
for _ in 0..8 {
let b = crc & 1 != 0;
crc >>= 1;
if b {
crc ^= poly;
}
}
}
crc
}
</pre>

Then comes the journal. The journal contains entries that describes how sectors should be remapped. The rest bytes before 0x1000 after all journal entries are padded with 0xFF
The journal entry structure is as follows:
<pre>
struct journal_entry_half {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8]; // Unused & uninitialized for V2
} __attribute__((__packed__));

struct journal_entry{
struct journal_entry_half entry;
struct journal_entry_half dupe; // same data as `entry`. No idea what this is used fore
uint32_t uninitialized; // 0xFFFFFFFF in newer system
}__attribute__((__packed__));
</pre>

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (same CRC16 algorithm as above) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/wwylele/save3ds save3ds] supports reading and modifying savegames, extdata and title database in FUSE filesystem or batch extracting/importing.
* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard. (This is an old tool that doesn't handle the savegame format correctly. --[[User:Wwylele|Wwylele]] ([[User talk:Wwylele|talk]]) 16:13, 2 December 2019 (CET))
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.

[[セーブデータ|Japanese]]

DISA and DIFF

2019-12-22T18:12:17Z

Wwylele: /* AES CMAC */ Explicitly shows the nested hash block format

Savegames

2019-12-02T14:13:50Z

Wwylele: /* Tools */ Bump my tools to the top. Sorry for self-promotion, but it is better than the old one in anyway now.

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]]. Inside the DISA container, it forms a [[Inner FAT|FAT filesystem]]. '''Please refer to these pages for how to fully extract save files'''. This page only describes additional encryption wear leveling on top of the DISA container. These layers only apply to gamecard save games. SD savegames and NAND savegames are DISA containers in plaintext after decrypting the common SD/NAND encryption layer.

== Gamecard savegame Encryption ==

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== Savegame keyY ===

All gamecard and SD savegames are encrypted with AES-CTR. The base CTR for gamecard savegames is all-zero. The gamecard savegame [[AES|keyslots]]' keyY(these savegame keyslots use the hardware key-generator) is unique for each region and for each game. The [[NCSD]] partition flags determine the method used to generate this keyY. When the save [[NCSD]] flags checked by the running NATIVE_FIRM are all-zero, the system will use the repeating CTR, otherwise a proper CTR which never repeats within the image is used.

The [[AES]]-CMAC (which uses a hardware key-generator keyslot, as mentioned above) at the the beginning of the savegame must match the calculated CMAC using the DISA/DIFF data, otherwise the savegame is considered corrupted(see below).

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY(original keyY method used with saves where the CTR repeats within the image) is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== [[2.0.0-2]] Hashed keyY and [[2.2.0-4]] Savegame Encryption ====

When certain [[NCSD]] partition flags are set, a SHA-256 hash is calculated over the data from the CXI(same data used with the original plain keyY), and the 0x40-bytes read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID). The first 0x10-bytes from this hash is used for the keyY. When flag[7] is set, the CTR will never repeat within the save image, unlike the original CTR-method. All games which had the retail NCSD image finalized after the [[2.2.0-4]] update(and contain [[2.2.0-4]]+ in the [[System Update CFA|System update partition]]), use this encryption method.

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== [[6.0.0-11]] Savegame keyY ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

A SHA-256 hash is calculated over the same data used with the above hashed keyY method, after hashing the above data the following data is hashed: the CXI programID, and the ExeFS:/.code hash from the decrypted [[ExeFS]] header. An [[AES]]-CMAC (the keyslot used for this uses the hardware key-scrambler) is then calculated over this hash, the output CMAC is used for the savegame keyY.

The keyY used for calculating this AES-CMAC is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

There are two versions of wear leveling have been observed. V1 is used for 128KB and 512 KB CARD1 flash chips. V2 is used for 1MB CARD1 flash chips (uncommon. Pokemon Sun/Moon is an exampe).

First, there are two 32-bit integers whose purposes are currently unknown. They generally increase the value as the savegame is written more times, so probably counter for how many times the journal became full and got flushed into the block map, and/or how many times <code>alloc_cnt</code> has wrapped around.

Then comes the actual blockmap. The block map contains entries of 10 bytes (V1) or 2 bytes (V2) with total number of <code>(flash_size / 0x1000 - 1)</code>.
The blockmap entry is simple:
<pre>
struct blockmap_entry_v1 {
uint8_t phys_sec; // when bit7 is set, block is initialized and has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));

struct blockmap_entry_v2 {
// Note that the phys_sec and alloc_cnt field are swapped in v2,
// but the initialized bit is still on the first byte
uint8_t alloc_cnt; // when bit7 is set, block is initialized
uint8_t phys_sec;
// v2 has no chksums
} __attribute__((__packed__));
</pre>

There's one entry per 0x1000-byte sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

A 2-byte CRC16 follows the block map. For V1 it immediately follows the last block map entry. For V2 it is located at 0x3FE, and bytes before the CRC is padded with zero. The CRC16 checks all the bytes before it, including the two unknown integers, the block map, and the padding bytes for V2. The CRC standard used looks like CRC-16-IBM (modbus). Here is the code in Rust for it

<pre>
fn crc16(data: &[u8]) -> u16 {
let poly = 0xA001;
let mut crc = 0xFFFFu16;
for byte in data {
crc ^= <u16>::from(*byte);
for _ in 0..8 {
let b = crc & 1 != 0;
crc >>= 1;
if b {
crc ^= poly;
}
}
}
crc
}
</pre>

Then comes the journal. The journal contains entries that describes how sectors should be remapped. The rest bytes before 0x1000 after all journal entries are padded with 0xFF
The journal entry structure is as follows:
<pre>
struct journal_entry_half {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8]; // Unused & uninitialized for V2
} __attribute__((__packed__));

struct journal_entry{
struct journal_entry_half entry;
struct journal_entry_half dupe; // same data as `entry`. No idea what this is used fore
uint32_t uninitialized; // 0xFFFFFFFF in newer system
}__attribute__((__packed__));
</pre>

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (same CRC16 algorithm as above) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/wwylele/save3ds save3ds] supports reading and modifying savegames, extdata and title database in FUSE filesystem or batch extracting/importing.
* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard. (This is an old tool that doesn't handle the savegame format correctly. --[[User:Wwylele|Wwylele]] ([[User talk:Wwylele|talk]]) 16:13, 2 December 2019 (CET))
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.

[[セーブデータ|Japanese]]

Savegames

2019-12-02T14:06:26Z

Wwylele: /* Gamecard wear leveling */ Update info for wear leveling V2

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]]. Inside the DISA container, it forms a [[Inner FAT|FAT filesystem]]. '''Please refer to these pages for how to fully extract save files'''. This page only describes additional encryption wear leveling on top of the DISA container. These layers only apply to gamecard save games. SD savegames and NAND savegames are DISA containers in plaintext after decrypting the common SD/NAND encryption layer.

== Gamecard savegame Encryption ==

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== Savegame keyY ===

All gamecard and SD savegames are encrypted with AES-CTR. The base CTR for gamecard savegames is all-zero. The gamecard savegame [[AES|keyslots]]' keyY(these savegame keyslots use the hardware key-generator) is unique for each region and for each game. The [[NCSD]] partition flags determine the method used to generate this keyY. When the save [[NCSD]] flags checked by the running NATIVE_FIRM are all-zero, the system will use the repeating CTR, otherwise a proper CTR which never repeats within the image is used.

The [[AES]]-CMAC (which uses a hardware key-generator keyslot, as mentioned above) at the the beginning of the savegame must match the calculated CMAC using the DISA/DIFF data, otherwise the savegame is considered corrupted(see below).

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY(original keyY method used with saves where the CTR repeats within the image) is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== [[2.0.0-2]] Hashed keyY and [[2.2.0-4]] Savegame Encryption ====

When certain [[NCSD]] partition flags are set, a SHA-256 hash is calculated over the data from the CXI(same data used with the original plain keyY), and the 0x40-bytes read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID). The first 0x10-bytes from this hash is used for the keyY. When flag[7] is set, the CTR will never repeat within the save image, unlike the original CTR-method. All games which had the retail NCSD image finalized after the [[2.2.0-4]] update(and contain [[2.2.0-4]]+ in the [[System Update CFA|System update partition]]), use this encryption method.

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== [[6.0.0-11]] Savegame keyY ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

A SHA-256 hash is calculated over the same data used with the above hashed keyY method, after hashing the above data the following data is hashed: the CXI programID, and the ExeFS:/.code hash from the decrypted [[ExeFS]] header. An [[AES]]-CMAC (the keyslot used for this uses the hardware key-scrambler) is then calculated over this hash, the output CMAC is used for the savegame keyY.

The keyY used for calculating this AES-CMAC is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

There are two versions of wear leveling have been observed. V1 is used for 128KB and 512 KB CARD1 flash chips. V2 is used for 1MB CARD1 flash chips (uncommon. Pokemon Sun/Moon is an exampe).

First, there are two 32-bit integers whose purposes are currently unknown. They generally increase the value as the savegame is written more times, so probably counter for how many times the journal became full and got flushed into the block map, and/or how many times <code>alloc_cnt</code> has wrapped around.

Then comes the actual blockmap. The block map contains entries of 10 bytes (V1) or 2 bytes (V2) with total number of <code>(flash_size / 0x1000 - 1)</code>.
The blockmap entry is simple:
<pre>
struct blockmap_entry_v1 {
uint8_t phys_sec; // when bit7 is set, block is initialized and has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));

struct blockmap_entry_v2 {
// Note that the phys_sec and alloc_cnt field are swapped in v2,
// but the initialized bit is still on the first byte
uint8_t alloc_cnt; // when bit7 is set, block is initialized
uint8_t phys_sec;
// v2 has no chksums
} __attribute__((__packed__));
</pre>

There's one entry per 0x1000-byte sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

A 2-byte CRC16 follows the block map. For V1 it immediately follows the last block map entry. For V2 it is located at 0x3FE, and bytes before the CRC is padded with zero. The CRC16 checks all the bytes before it, including the two unknown integers, the block map, and the padding bytes for V2. The CRC standard used looks like CRC-16-IBM (modbus). Here is the code in Rust for it

<pre>
fn crc16(data: &[u8]) -> u16 {
let poly = 0xA001;
let mut crc = 0xFFFFu16;
for byte in data {
crc ^= <u16>::from(*byte);
for _ in 0..8 {
let b = crc & 1 != 0;
crc >>= 1;
if b {
crc ^= poly;
}
}
}
crc
}
</pre>

Then comes the journal. The journal contains entries that describes how sectors should be remapped. The rest bytes before 0x1000 after all journal entries are padded with 0xFF
The journal entry structure is as follows:
<pre>
struct journal_entry_half {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8]; // Unused & uninitialized for V2
} __attribute__((__packed__));

struct journal_entry{
struct journal_entry_half entry;
struct journal_entry_half dupe; // same data as `entry`. No idea what this is used fore
uint32_t uninitialized; // 0xFFFFFFFF in newer system
}__attribute__((__packed__));
</pre>

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (same CRC16 algorithm as above) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard.
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.
* [https://github.com/wwylele/save3ds save3ds] similar to 3dsfuse, but supports savegame inner FS, proper DPFS handling, and automatic CMAC update. Mainly supports SD/NAND save/extdata. Cart save WIP

[[セーブデータ|Japanese]]

DISA and DIFF

2019-10-25T19:18:27Z

Wwylele: Correct CMAC for cart save

This page describes DISA and DIFF format as the underlying container of [[Savegames]], [[Extdata]] and [[Title Database]]. For further format specification of the inner data, please refer to their own page.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

== Overview ==

DISA and DIFF are two container formats. They are very similar and are used for various purposes in 3DS. Here is a summary table of their usage, the CMAC type and the AES key slot used (the meaning of these is explained in the next section):

{| class="wikitable" border="1"
! Usage
! Media
! Container format
! [[#AES CMAC|CMAC type]]
! CMAC [[AES Registers|Keyslot]]
|-
| [[Savegames]]
| Gamecard
| DISA
| [[#CTR-NOR0|CTR-NOR0]]
| 0x19 / 0x33
|-
| [[Savegames]]
| [[SD Filesystem|SD]]
| DISA
| [[#CTR-SIGN|CTR-SIGN]]
| 0x30
|-
| [[System SaveData]]
| [[Flash Filesystem|NAND]]
| DISA
| [[#CTR-SYS0|CTR-SYS0]]
| 0x30
|-
| [[Extdata|Private Extdata]]
| [[SD Filesystem|SD]]
| DIFF
| [[#CTR-EXT0|CTR-EXT0]]
| 0x30
|-
| [[Extdata|Shared Extdata]]
| [[Flash Filesystem|NAND]]
| DIFF
| [[#CTR-EXT0|CTR-EXT0]]
| 0x30
|-
| [[Title Database]]
| [[SD Filesystem|SD]]
| DIFF
| [[#CTR-9DB0|CTR-9DB0]]
| 0x30
|-
| [[Title Database]]
| [[Flash Filesystem|NAND]]
| DIFF
| [[#CTR-9DB0|CTR-9DB0]]
| 0x0B
|}

== Encryption ==

DISA and DIFF formats don't have their own encryption specification. They follow the encryption method defined by their media:

* Gamecard savegames have special wear leveling + encryption layers. See [[Savegames]] for detail.
* Files on SD follow [[SD Filesystem|the general SD filesystem encryption rule]].
* Files on NAND are in cleartext, after decrypting [[Flash Filesystem|the NAND partition encryption]].

== Format ==

A DISA / DIFF file consists of the following components:

* 0x100-byte AES CMAC
* 0x100-byte Header
* Secondary partition table
** Contains one or two partition descriptors, depending on the number of partitions.
* Primary partition table
** Same layout as the secondary one
* Partition A
* Partition B (optional)
** can only exist for DISA.

== AES CMAC ==

The AES CMAC is located at the beginning of the DISA / DIFF image, and it is 0x10 long. The rest 0xF0 bytes before the header are unused.

The key used for the AES CMAC is generated by the [[AES Registers|hardware key engine]]. See the keyslot it uses in the table above.

The data being authenticated by the AES CMAC is a 0x20-byte SHA-256 hash of a data block. The data block has different content formats among CMAC types. All types of data block contain a copy or a hash of the header, which is the start of the the rest of the verification chain, so the AES CMAC effectively authenticates the whole save image. Each type of data block is explained below.

=== CTR-NOR0 ===

This CMAC type is used for gamecard savegames. It is 0x28-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-NOR0"
|-
| 0x8
| 0x20
| SHA-256 of the following 0x108-byte block
|-
|

|

|

|-
| 0x00
| 8
| Magic "CTR-SAV0"
|-
| 0x08
| 0x100
| Copy of the DISA header
|}

=== CTR-SIGN ===

This CMAC type is used for SD savegames. It is 0x30-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SIGN"
|-
| 0x08
| 8
| Title ID
|-
| 0x10
| 0x20
| SHA-256 of the following 0x108-byte block
|-
|

|

|

|-
| 0x00
| 8
| Magic "CTR-SAV0"
|-
| 0x08
| 0x100
| Copy of the DISA header
|}

=== CTR-SYS0 ===

This CMAC type is used for NAND system save. It is 0x110-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SYS0"
|-
| 0x08
| 8
| Save ID. The higher word is always zero
|-
| 0x10
| 0x100
| Copy of the DISA header
|}

=== CTR-EXT0 ===

This CMAC type is used for extdata. It is 0x11C-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-EXT0"
|-
| 0x08
| 8
| Extdata ID
|-
| 0x10
| 4
| 0 for Quota.dat, 1 otherwise
|-
| 0x14
| 4
| ID in the device file name. 0 for Quota.dat
|-
| 0x18
| 4
| ID in the device directory name that the file is in. 0 for Quota.dat
|-
| 0x1C
| 0x100
| Copy of the DIFF header
|}

=== CTR-9DB0 ===

This CMAC type is used for title database. It is 0x10C-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-9DB0"
|-
| 0x08
| 4
| Database ID. Each .db file has its own ID
|-
| 0x0C
| 0x100
| Copy of the DIFF header
|}

== Header ==

The header located at offset 0x100 defines the rest components of the file (partitions and their tables). All offsets in the header are relative to the beginning of the DISA/DIFF file, except for partition descriptor offsets, which are relative to the beginning of the (active) partition table. DISA and DIFF have different header format.

=== DISA header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DISA"
|-
| 0x04
| 4
| Magic 0x40000
|-
| 0x08
| 4
| Partition count, 1 or 2
|-
| 0x0C
| 4
| Padding
|-
| 0x10
| 8
| Secondary partition table offset
|-
| 0x18
| 8
| Primary partition table offset
|-
| 0x20
| 8
| Partition table size
|-
| 0x28
| 8
| Partition A descriptor offset in the partition table
|-
| 0x30
| 8
| Partition A descriptor size
|-
| 0x38
| 8
| Partition B descriptor offset in the partition table
|-
| 0x40
| 8
| Partition B descriptor size
|-
| 0x48
| 8
| Partition A offset
|-
| 0x50
| 8
| Partition A size
|-
| 0x58
| 8
| Partition B offset
|-
| 0x60
| 8
| Partition B size
|-
| 0x68
| 1
| Active partition table, 0 = primary, 1 = secondary
|-
| 0x69
| 3
| Padding
|-
| 0x6C
| 0x20
| SHA-256 over the active partition table
|-
| 0x8C
| 0x74
| Unused
|}

Note:

* When the partition count is 1, there is no partition B and all of its related fields are zero.

=== DIFF header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DIFF"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 8
| Secondary partition table/descriptor offset
|-
| 0x10
| 8
| Primary partition table/descriptor offset
|-
| 0x18
| 8
| Partition table/descriptor size
|-
| 0x20
| 8
| Partition (A) offset
|-
| 0x28
| 8
| Partition (A) size
|-
| 0x30
| 4
| Active partition descriptor, 0 = primary, 1 = secondary
|-
| 0x34
| 0x20
| SHA-256 over the active partition table/descriptor
|-
| 0x54
| 8
| Unique identifier
|-
| 0x5C
| 0xA4
| Unused, might contain leftover data
|}

Note:

* Since DIFF can only contain one partition, a partition table can only have one partition descriptor, so they become the same concept here.
* See [[Extdata]] for its usage of the unique identifier field. For title database files, this field is zero.

== Partition table & partition descriptor ==

There are two partition tables, but only one of them is active. When operating on a DISA / DIFF file, 3DS FS alternately activate one of the two tables, presumably for data backup or atomic file writing. A newly created DISA / DIFF file may have entirely uninitialized data in the inactive partition table.

One partition table contains one or two partition descriptors , each of which describes the layout of one partition. A partition descriptor contains the following components:

* DIFI header
* IVFC descriptor
* DPFS descriptor
* Partition master hash

=== DIFI header ===

The DIFI header locates at the beginning of a partition descriptor. This header defines the rest components of the partition descriptor (IVFC descriptor, DPFS descriptor and partition master hash). All offsets are relative to the beginning of the partition descriptor, except for <code>External IVFC level 4 offset</code>, which is relative to the beginning of the partition.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DIFI"
|-
| 0x04
| 4
| Magic 0x10000
|-
| 0x08
| 8
| IVFC descriptor offset
|-
| 0x10
| 8
| IVFC descriptor size
|-
| 0x18
| 8
| DPFS descriptor offset
|-
| 0x20
| 8
| DPFS descriptor size
|-
| 0x28
| 8
| Partition hash offset
|-
| 0x30
| 8
| Partition hash size
|-
| 0x38
| 1
| If none zero, enable external IVFC level 4.
|-
| 0x39
| 1
| DPFS tree level 1 selector
|-
| 0x3A
| 2
| Padding
|-
| 0x3C
| 8
| External IVFC level 4 offset (zero if external IVFC level 4 disabled)
|}

Note:

* The meaning of fields after 0x38 are explained in the section [[#Partition]]

=== IVFC descriptor ===

This header defines each level of IVFC tree (explained in the section [[#Partition]]). All offsets are relative to the beginning of DPFS level 3.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "IVFC"
|-
| 0x04
| 4
| Magic 0x20000
|-
| 0x08
| 8
| Master hash size = partition master hash size in DIFI header
|-
| 0x10
| 8
| IVFC level 1 offset
|-
| 0x18
| 8
| IVFC level 1 size
|-
| 0x20
| 4
| IVFC level 1 block size in log2
|-
| 0x24
| 4
| Padding
|-
| 0x28
| 8
| IVFC level 2 offset
|-
| 0x30
| 8
| IVFC level 2 size
|-
| 0x38
| 4
| IVFC level 2 block size in log2
|-
| 0x3C
| 4
| Padding
|-
| 0x40
| 8
| IVFC level 3 offset
|-
| 0x48
| 8
| IVFC level 3 size
|-
| 0x50
| 4
| IVFC level 3 block size in log2
|-
| 0x54
| 4
| Padding
|-
| 0x58
| 8
| IVFC level 4 offset (unused if external IVFC level 4 enabled)
|-
| 0x60
| 8
| IVFC level 4 size
|-
| 0x68
| 4
| IVFC level 4 block size in log2
|-
| 0x6C
| 4
| Padding
|-
| 0x70
| 8
| IVFC descriptor size? The value is usually 0x78
|}

=== DPFS descriptor ===

This header defines each level of DPFS tree (explained in the section [[#Partition]]). All offsets are relative to the beginning of the partition.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DPFS"
|-
| 0x04
| 4
| Magic 0x10000
|-
| 0x08
| 8
| DPFS level 1 offset
|-
| 0x10
| 8
| DPFS level 1 size
|-
| 0x18
| 4
| DPFS level 1 block size in log2 (unused?)
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 8
| DPFS level 2 offset
|-
| 0x28
| 8
| DPFS level 2 size
|-
| 0x30
| 4
| DPFS level 2 block size in log2
|-
| 0x34
| 4
| Padding
|-
| 0x38
| 8
| DPFS level 3 offset
|-
| 0x40
| 8
| DPFS level 3 size
|-
| 0x48
| 4
| DPFS level 3 block size in log2
|-
| 0x4C
| 4
| Padding
|}

=== Partition master hash ===

This is a SHA-256 hash list over IVFC level 1. See [[#IVFC tree]] for explanation.

== Partition ==

A partition can have two types of layout. This is determined by the field DIFF + 0x38 (<code>Enable external IVFC level 4</code>).

The layout type 0 (external IVFC level 4 disabled) contains

* DPFS level 1
* DPFS level 2
* DPFS level 3, and inside
** IVFC level 1
** IVFC level 2
** IVFC level 3
** IVFC level 4 (the actual content data)

The layout type 1 (external IVFC level 4 enabled) contains

* DPFS level 1
* DPFS level 2
* DPFS level 3, and inside
** IVFC level 1
** IVFC level 2
** IVFC level 3
* IVFC level 4 (the actual content data, note that this is out side DPFS level 3)

=== DPFS tree ===

Everything inside the DPFS tree comes in pairs, and at one time only one of a pair is active. The tree is probably designed for atomic writing: for a file writing operation, it writes to the inactive part, then commits the data by switching a bit to activate it.

Each level of DPFS tree consists of a pair of chunks. The size of one chunk is defined as it in the DPFS descriptor, so the total size of a level is actually twice as large as the size recorded in the descriptor. For level 1 and 2, each chunk is a bit array, in which each bit corresponds to a block in the next level (the block size of the next level is also defined in the DPFS descriptor). This bit indicates which one of the pair in the next level is active for this block: 0 means the first one and 1 means the second one. The active chunk of level 1 is selected by <code>DPFS tree level 1 selector</code> in the DIFI header. The bit array is encoded in u32 array, with MSB as the first bit of each 32 bits.

To access data in level 3, one needs to check the bits in level 1 and level 2 to know which chunk of level 3 is active for the accessed location. For example, for a following configuration:

* Level 1: size = 4 bytes = 32 bits
* Level 2: size = 0x380 bytes = 0x1C00 bits, block size = 0x80 bytes
* Level 3: size = 0x1B7F000, block size = 0x1000, block size = 0x1000 bytes

if one want to read byte at 0x1234567 of level 3, the following calculation is performed:

* get level 2 bit index <code>0x1234567 / 0x1000 = 0x1234</code>, and its byte location <code>0x1234 / 8 = 0x246</code>
* get level 1 bit index <code>0x246 / 0x80 = 4</code>
* get <code>level1_selector</code> from DIFI header
* read <code>level2_selector = Level1[level1_selector].bits[4]</code>;
* read <code>level3_selector = Level2[level2_selector].bits[0x1234]</code>;
* read <code>data = Level3[level3_selector].bytes[0x1234567]</code> as the final data
* in the code above <code>Levelx[k]</code> means the <code>k</code>-th chunk in level <code>x</code>, where <code>k = 0, 1</code>. <code>.bits[n]</code> is expanded to <code>(.u32_array[n / 32] >> (31 - n % 32)) & 1</code> as the bit array is encoded in u32 array.

Effectively, the active data is scattered among the two level 3 chunk. One can assemble the whole active level 3 image following the same rule.

=== IVFC tree ===

The IVFC tree is used for data verification. It is very similar to the IVFC tree in [[RomFS]], except that it has an additional level here. For level 1, 2 and 3, each level is a list of SHA-256 hash, of which each corresponds to a block of the next level which is zero-padded to align the block size (the block size of the next level is defined in the IVFC descriptor).

The partition master hash in the partition descriptor can be seen as IVFC level 0, which hashes level 1 following the same rule. The master hash is usually 0x20 long, consisting only one hash. This is because most DISA / DIFF files are not large enough to have multiple hashes on the top level, which isn't the case for some title database files.

However, not all data is hashed - only ranges that have been written with valid data are properly hashed.

Level 4 is the actual content of the partition, which is what the container format essentially contains.

== Extracting content from a DISA / DIFF container ==

* Find the active partition table and the partition(s).
* Unwrap DPFS tree of partition(s) by reconstructing active data.
* Unwrap IVFC tree. Either take out level 4 directly, or, better, verify all the hashes and poison the data that is not properly hashed.
* The IVFC level 4 is the inner content of the file. The format of it varies among different usage. Refer their own page for further extraction.

== Chain of trust ==

* AES CMAC verifies the header.
* The header verifies the active partition table via the table hash.
* In the partition table, each descriptor verifies level 1 of its IVFC tree via the master hash.
* Each IVFC level verifies the next level, until the level 4, which is the inner content.

== Summary diagram ==

external link: https://i.imgur.com/BjwShJZ.png
* Please move this into 3dbrew when file uploading is fixed.

Savegames

2019-10-18T19:05:17Z

Wwylele: /* Tools */ update my save tool

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]]. Inside the DISA container, it forms a [[Inner FAT|FAT filesystem]]. '''Please refer to these pages for how to fully extract save files'''. This page only describes additional encryption wear leveling on top of the DISA container. These layers only apply to gamecard save games. SD savegames and NAND savegames are DISA containers in plaintext after decrypting the common SD/NAND encryption layer.

== Gamecard savegame Encryption ==

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== Savegame keyY ===

All gamecard and SD savegames are encrypted with AES-CTR. The base CTR for gamecard savegames is all-zero. The gamecard savegame [[AES|keyslots]]' keyY(these savegame keyslots use the hardware key-generator) is unique for each region and for each game. The [[NCSD]] partition flags determine the method used to generate this keyY. When the save [[NCSD]] flags checked by the running NATIVE_FIRM are all-zero, the system will use the repeating CTR, otherwise a proper CTR which never repeats within the image is used.

The [[AES]]-CMAC (which uses a hardware key-generator keyslot, as mentioned above) at the the beginning of the savegame must match the calculated CMAC using the DISA/DIFF data, otherwise the savegame is considered corrupted(see below).

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY(original keyY method used with saves where the CTR repeats within the image) is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== [[2.0.0-2]] Hashed keyY and [[2.2.0-4]] Savegame Encryption ====

When certain [[NCSD]] partition flags are set, a SHA-256 hash is calculated over the data from the CXI(same data used with the original plain keyY), and the 0x40-bytes read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID). The first 0x10-bytes from this hash is used for the keyY. When flag[7] is set, the CTR will never repeat within the save image, unlike the original CTR-method. All games which had the retail NCSD image finalized after the [[2.2.0-4]] update(and contain [[2.2.0-4]]+ in the [[System Update CFA|System update partition]]), use this encryption method.

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== [[6.0.0-11]] Savegame keyY ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

A SHA-256 hash is calculated over the same data used with the above hashed keyY method, after hashing the above data the following data is hashed: the CXI programID, and the ExeFS:/.code hash from the decrypted [[ExeFS]] header. An [[AES]]-CMAC (the keyslot used for this uses the hardware key-scrambler) is then calculated over this hash, the output CMAC is used for the savegame keyY.

The keyY used for calculating this AES-CMAC is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

First, there are 8 bytes whose purposes are currently unknown. Then comes the actual blockmap.
The blockmap structure is simple:
<pre>
struct header_entry {
uint8_t phys_sec; // when bit7 is set, block has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));
</pre>

There's one entry per sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

The 2 bytes that follow the blockmap are the CRC16 (with starting value 0xFFFF (like modbus)) of the first 8 bytes and the blockmap.

Then comes the journal.
The journal structure is as follows:
<pre>
struct sector_entry {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8];
} __attribute__((__packed__));

struct long_sector_entry{
struct sector_entry sector;
struct sector_entry dupe;
uint32_t magic;
}__attribute__((__packed__));
</pre>

With magic being a constant 0x080d6ce0.

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (with starting value 0xFFFF) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard.
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.
* [https://github.com/wwylele/save3ds save3ds] similar to 3dsfuse, but supports savegame inner FS, proper DPFS handling, and automatic CMAC update. Mainly supports SD/NAND save/extdata. Cart save WIP

[[セーブデータ|Japanese]]

FS:Obsoleted 2 0 FormatThisUserSaveData

2019-05-30T21:19:45Z

Wwylele:

=Request=
{| class="wikitable" border="1"
|-
! Index Word
! Description
|-
| 0
| Header code [0x080F0180]
|-
| 1
| Size of a block. Only 0x200 and 0x1000 are accepted it seems.
|-
| 2
| Number of Directories
|-
| 3
| Number of Files
|-
| 4
| Directory Bucket Count
|-
| 5
| File Bucket Count
|-
| 6
| u8, 0 = don't duplicate data, 1 = duplicate data
|}

=Response=
{| class="wikitable" border="1"
|-
! Index Word
! Description
|-
| 0
| Header code
|-
| 1
| Result code
|}

=Description=
This has been obsoleted. Prefer [[FS:FormatSaveData]].

FS:FormatSaveData

2019-05-30T21:19:21Z

Wwylele: /* Request */

=Request=
{| class="wikitable" border="1"
|-
! Index Word
! Description
|-
| 0
| Header code [0x084C0242]
|-
| 1
| [[Filesystem_services#ArchiveId|Archive ID]]. This must be either 0x4 (SaveData) or 0x567890B2, otherwise error 0xE0E046BE is returned.
|-
| 2
| [[Filesystem_services#PathType|Path Type]]
|-
| 3
| Path Size
|-
| 4
| Size of a block. Only 0x200 and 0x1000 are accepted it seems. The value of this word is hard-coded to 0x200 in official titles it appears.
|-
| 5
| Number of Directories
|-
| 6
| Max number of Files
|-
| 7
| Directory Bucket Count
|-
| 8
| File Bucket Count
|-
| 9
| u8, 0 = don't duplicate data, 1 = duplicate data
|-
| 10
| (PathSize << 14) <nowiki>|</nowiki> 2
|-
| 11
| Path Data Pointer
|}

=Response=
{| class="wikitable" border="1"
|-
! Index Word
! Description
|-
| 0
| Header code
|-
| 1
| Result code
|}

=Description=
This clears the SaveData archive for the specified game, if the LowPath.Type is Empty then this will clear the SaveData for the current game. The target SaveData to format is determined by a Binary path, a game needs an exheader permission set in order to format the SaveData of another program.

See [[RomFS#Hash_Table_Structure|here]] for an example of how bucket counts should be calculated.

Extdata

2019-05-28T13:34:51Z

Wwylele: /* Quota File */

This page describes the format and encryption of extdata, "extra data" stored on SD card and NAND, at:

* <code>nand/data/<ID>/extdata/<ExtdataID-High></code>
* <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/<ExtdataID-High></code>

ExtdataID-High is always 00000000 for SD, and always 00048000 for NAND. Regular apps can only mount SD extdata using the same extdataID which is stored in the CXI exheader. Therefore, regular apps which have the exheader extdataID set to zero can't use extdata. This restriction doesn't apply for shared extdata with extdataID high bitmask 0x48000 stored on NAND. System apps with a certain access right can mount arbitrary extdata. All NAND extdata is shared extdata, while all SD extdata is normal extdata.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

= Format =

To avoid confusion, the terms '''device directory / file''' and '''virtual directory / file''' are used with the following meanings:

* '''Device directory / file''' are the real directory / file stored on SD / NAND that can be seen under path <code>nand/data/<ID>/extdata/</code> or <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/</code>.
* '''Virtual directory / file''' are directory / file stored inside extdata virtual file system, which can be seen by applications in the mounted extdata archives.

An extdata consists of several device directories and files, which forms a file system consisting of multiple virtual directories and files.

An extdata with ID <code>ExtdataId</code> has the following device files:

* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/Quota.dat</code> (optional)
* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/<SubDirID>/<SubFileID></code>

Note:

* All device files are [[DISA and DIFF|DIFF containers]]. '''All format description below is about the inner content of the containers'''. Please unwrap these files first according to the DIFF format description before reading them using the extdata format description below.
* <code>Quota.dat</code> is only observed existing for NAND shared extdata.
* <code><SubDirID></code> and <code><SubFileID></code> are 8-digit hex strings.
* Device file with <code>SubDirID = SubFileID = 00000000</code> doesn't exist. Other ID combinations can exists.
* Device file with <code>SubDirID = 00000000</code> and <code>SubFileID = 00000001</code> is the VSXE metadata file and must exist.
* Other files, besides <code>Quota.dat</code> and <code>00000000/00000001</code>, are normal sub files, are these device files one-to-one correspond to virtual files. They contain raw virtual file data in the DIFF inner content.
* <code>SubDirID = 00000000</code> is usually the only one device directory that can be seen. See [[#Device Directory Capacity]] for more information.

== Quota File ==

The inner data of <code>Quota.dat</code> is 0x48 bytes with the following format. The file seems to limit the extdata total size.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "QUOT"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 4
| 0x1000, block size
|-
| 0x0C
| 4
| Always 126. Probably device directory capacity. See the [[#Device Directory Capacity]] more information.
|-
| 0x10
| 4
| Always 0?
|-
| 0x14
| 4
| Max number of blocks
|-
| 0x18
| 4
| Always 0?
|-
| 0x1C
| 4
| Free blocks remained
|-
| 0x20
| 4
| Always 0?
|-
| 0x24
| 4
| Always 0?
|-
| 0x28
| 4
| Free blocks remained + (blocks occupied by the recently mounted file, specified by the ID below (0 if recently deleted))
|-
| 0x2C
| 4
| Always 0?
|-
| 0x30
| 4
| ID of most recently mounted file. Same as the one in [[Inner_FAT#Filesystem Header]]
|-
| 0x34
| 4
| Always 0?
|-
| 0x38
| 4
| Always 0?
|-
| 0x3C
| 4
| Always 0?
|-
| 0x40
| 4
| Size in bytes of most recently mounted file (device file size). 0 if recently deleted
|-
| 0x44
| 4
| Always 0?
|}

== Device Directory Capacity ==

A device directory in an extdata (a <code><SubDirID></code> directory) seems to have a maximum number of device files it can contain. For SD extdata, this maximum number seems to be hard-coded as 126. For NAND extdata, the number is probably indicated by a field in Quota.dat, which is, again, always 126 as observed. 3DS FS tries to put all device files in the device directory <code>00000000</code> if possible, and only when more than 126 files needed to add, a second device directory <code>00000001</code> and so on are created. However, few extdata have such amount of files to store, so the behavior lacks of use cases to confirm.

The number 126 is probably from some kind of other capacity of 128 with <code>"."</code> and <code>".."</code> entries reserved. It is theorized that this is to keep a FAT directory table, with 0x20 bytes for each entry, in one 0x1000 cluster. The motivation is unclear.

== VSXE Filesystem ==

This is one variant of the [[Inner FAT|FAT filesystem]]. Please refer to its page for the description of the filesystem. In general, device file <code>00000000/00000001</code> contains the metadata of the filesystem, while other device files (except for the Quota file) contains normal sub-files

Each non-dummy file entry corresponds to a device file. The path to the device file is generated by the following computation:

<pre>// See previous section about this capacity
const uint32_t device_dir_capacity = 126;

// entry index is the index in the file entry table, with the first dummy entry as
// index = 0, which is never used for a real file.
// file_index = 1 is reserved for the VSXE Filesystem Metadata itself, so real files
// started from file_index = 2.
uint32_t file_index = entry_index + 1;

uint32_t SubDirID = file_index / device_dir_capacity;
uint32_t SubFileID = file_index % pdevice_dir_capacity;

char extdata_path[...]; // ".../extdata/<ExtdataID-High>/<ExtdataId-Low>"
char device_path[...]; // output path
sprintf(device_path, "%s/%08x/%08x", extdata_path, SubDirID, SubFileID);
</pre>
When mounting extdata, the unique identifier is used to match the ID stored in subfile's [[DISA and DIFF#DIFF header|DIFF header]]. If the ID doesn't match, mounting will fail.

== Virtual File System Structure ==

When extdata is created, these are ''always'' created regardless of whether the title actually uses them.

* <code>/icon</code> This virtual file contains the extdata icon displayed in data management. This icon can only be written to by titles when creating extdata, titles would have to recreate extdata to change the icon. This file can't be read directly, instead it is read via FS:ReadExtSaveDataIcon.
* <code>/user/</code> This virtual directory contains the title's actual extdata files.
* <code>/boss/</code> This virtual directory can contain SpotPass content. SpotPass content can only be downloaded to this <code>/boss</code> virtual directory.

User extdata and SpotPass extdata use separate mount points at <code>/user</code> and <code>/boss</code>. Therefore one mount can't access the other virtual directory, and also can't access <code>/icon</code>.(The title's SpotPass extdata can be mounted by the title itself, if it uses SpotPass)

Other optional but notable directories include:

* <code>/user/ExBanner</code> This virtual directory can optionally store extended banners. When this is available, this banner is displayed instead of the CXI ExeFS banner. <code>COMMON.bin</code> stores the common exbanner, while <code><regionlang_code>.bin</code> stores an optional separate region/language specific banner.(regionlang_code can be "JPN_JP", "USA_EN", etc)

== SD Extdata ==
Usually the ExtdataID low is in the format '00<Unique ID>'

{| class="wikitable" border="1"
|-
! JPN ExtdataID
! USA ExtdataID
! EUR ExtdataID
! Description
! Extdata images
|-
| 00000082
| 0000008f
| 00000098
| [[Home Menu]] extdata, this contains home-menu savedata and cached icons for applications.
|
|-
| 00000200
| 00000210
| 00000220
| [[System_Settings|System Settings]] extdata added with [[2.0.0-2]].
|
|-
| 00000207
| 00000217
| 00000227
| [[Mii Maker]], contains an ExBanner
| [https://dl.dropbox.com/u/20520664/extdata00000217.zip cleartext]
|-
| 00000208
| 00000218
| 00000228
| Streetpass Mii Plaza
| 11 mb big!
|-
| 00000209
| 00000219
| 00000229
| [[eShop]], contains store music in AAC format.
|
|-
| 0000020b
| 0000021b
| 0000022b
| Nintendo Zone
|
|-
| 0000020d
| 0000021d
| 0000022d
| Face Raiders, likely contains an ExBanner
|
|-
| 000002cc
| 000002cd
| 000002ce
| [[Home Menu]] theme
|
|-
| ?
| 000004aa
| 000004ab
| Nintendo Video Extra Data
This is where the video files are stored, and [[Nintendo_Video|includes]] the thumbnail, the description, and possibly some checksum info in each video file stored in the extdata images. There are always 9 files within the subdirectory "00000000" of this folder, even without any videos downloaded. The files are "00000001" - "00000009", and "00000003" - "00000008" have the same filesize of 50.7 MB. It is possible to restore the older videos by overwriting all the files within this directory. Provided of course you have made a backup of the files before hand, by copying all the files within this directory to your computer. As far I'm aware its not possible to mix and match the files in order to get certain videos in one grouping, ie. having all 3 Zelda orchestral recordings in one group of 4 Nintendo videos.
|
|-
|00000306
|00000308
|00000307
|Mario Kart 7
|
|-
| 0000030b
| 0000030d
| 0000030c
| Nintendogs + Cats
|
|-
| 00000326
| 00000326
| 00000326
| Pokédex 3D
|
|-
| 00000305
| 0000032d
| 0000033c
| Super Street Fighter IV 3D
|
|-
| 00000328
| 00000358
| 0000033b
| Ridge Racer 3D
|
|-
| ?
| 0000034d
| 00000402
| Samurai Warriors Chronicles
|
|-
| ?
| 0000034f
| 0000038a
| Dead or Alive Dimensions
|
|-
| 00000481
| N/A
| N/A
| Monster Hunter Tri G (Download-Quests)
|
|-
| ?
| 00000517
| 00000518
| Swapnote
|
|-
| 0000055d
| 0000055d
| 0000055d
| Pokémon X Pokémon Y
|
|-
| ?
| 00000725
| 00000724
| Ambassador Certificate
|
|-
| ?
| ?
| 000007af
| New Super Mario Bros. 2
|
|-
| ?
| 00000863
| 00000864
| Animal Crossing: New Leaf
|
|-
| ?
| 00000a85
| 00000a86
| Professor Layton and the Miracle Mask Professor Layton and the Azran Legacy
German Version ExtdataID is 00000a87
|
|-
| ?
| ?
| 00000b4f
| Fullblox / Crashmo
|
|-
| ?
| ?
| 00000ba9
| Pokémon Mystery Dungeon: Gates to Infinity
|
|-
| ?
| ?
| 00000c24
| Denpa men
|
|-
| 00000c73
| 00000c73
| 00000c73
| Save Data Transfer Tool
|
|-
| ?
| ?
| 00000d9a
| Donkey Kong Country™ Returns 3D: Trailer
|
|-
| ?
| ?
| 00000ea6
| Etrian Odyssey IV
|
|-
| ?
| 00000edf
| 00000ee0
| Super Smash Bros. for Nintendo 3DS
|
|-
| ?
| 00000f14
| 00000f1e
| Phoenix Wright: Ace Attorney - Dual Destinies
|
|-
| ?
| 00001007
| 00001005
| Professor Layton vs Phoenix Wright: Ace Attorney
|
|-
| ?
| ?
| 00001062
| Nintendo Pocket Football Club
|
|-
| ?
| ?
| 0000111c
| Yoshi's New Island
|
|-
| ?
| ?
| 00001131
| Fantasy Life
|
|-
| 000011c5
| 000011c5
| 000011c5
| Pokémon Omega Ruby Pokémon Alpha Sapphire
|
|-
| ?
| ?
| 000012ca
| Mario vs. Donkey Kong: Tipping Stars
|
|-
| ?
| ?
| 00001499
| Korg DSN-12
|
|-
| ?
| ?
| 000014f2
| Animal Crossing: Happy Home Designer
|
|-
| 000014d1
| 000014d1
| 000014d1
| [[Home Menu]] badge
|
|-
| ?
| ?
| 00001632
| Fullblox / Stretchmo
|
|-
| ?
| ?
| 00001646
| Pokémon Rumble World
|
|-
| 00001648
| 00001648
| 00001648
| Pokémon Sun Pokémon Moon
|
|-
| 0000165c
| 0000165c
| 0000165c
| [[Home Menu]] saved theme layouts
|
|-
| ?
| ?
| 00001678
| Yo-kai Watch
|
|-
| ?
| ?
| 000018fa
| Phoenix Wright: Ace Attorney - Spirit of Justice
|
|-
| ?
| ?
| 0000198f
| Animal Crossing: New Leaf - Welcome amiibo
|
|-
| ?
| ?
| 00001a05
| Super Mario Maker
|
|-
| ?
| ?
| 00001a2e
| Swapdoodle
|
|}

== NAND Shared Extdata ==
{| class="wikitable" border="1"
|-
! ExtdataID
! Description
|-
| 0xe0000000
| Home Menu attempts to open this archive during boot, if [[FS:OpenArchive]] doesn't return an error Home Menu seems to then launch the [[System Transfer]] application. Home Menu doesn't actually use this archive at all except for checking whether it exists.
|-
| 0xf0000001
| NAND JPEG/MPO files and phtcache.bin from the camera application are stored here. This also contains UploadData.dat.
|-
| 0xf0000002
| NAND M4A files from the sound application are stored here
|-
| 0xf0000009
| Used for [[BOSS_Services|SpotPass]] content storage for [[News_Services|notifications]].
|-
| 0xf000000b
| Contains idb.dat, idbt.dat, gamecoin.dat, ubll.lst, CFL_DB.dat, and CFL_OldDB.dat. These files contain cleartext [[Mii_Maker|Miis]] and some data relating (including cached ICN data) to Play/Usage Records.
|-
| 0xf000000c
| Contains bashotorya.dat and bashotorya2.dat.
|-
| 0xf000000d
| Home Menu SpotPass content data [[BOSS_Services|storage]].
|-
| 0xf000000e
| Contains [[VersionList|versionlist.dat]], used by Home Menu for the software update notification added with [[7.0.0-13]].
|}

==== Shared Extdata 0xf000000b gamecoin.dat ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Magic number: 0x4F00
|-
| 0x4
| 0x2
| Total Play Coins
|-
| 0x6
| 0x2
| Total Play Coins obtained on the date stored below. When the below date does not match the current date, this field is reset to zero, then the date(and other fields) are updated. Once this value is >=10, no more Play Coins can be obtained until the current date changes.
|-
| 0x8
| 0x4
| Total step [[PTM:GetTotalStepCount|count]] at the time a new Play Coin was obtained.
|-
| 0xC
| 0x4
| Step count for the day the last Play Coin was obtained, for that day's step count(same as the step count displayed by home-menu when this file was updated).
|-
| 0x10
| 0x2
| Year
|-
| 0x12
| 0x1
| Month
|-
| 0x13
| 0x1
| Day
|}

The above date stores the last time new Play Coin(s) were obtained. The contents of this file is updated by home-menu. [[PTM:GetTotalStepCount]] is not checked constantly, after home-menu boot this is only checked when waking from sleep-mode. Each time home-menu updates the contents of this file, home-menu will set the Play Coin total to 300 if it's higher than the 300 Play Coin limit.

[[Home Menu]] loads this file / opens this archive during [[Home Menu|startup]]. When accessing this file fails, like when the file/archive is corrupted(or at least on older system-versions), the result is a brick due to Home Menu using [[SVC|svcBreak]]. [[User:Yellows8|Yellows8]] bricked a 3DS this way due to corruption via invalid [[FSFile:Write]] flush flags. When opening this extdata archive(0xf000000b) fails, Home Menu executes svcBreak.

==== Shared Extdata 0xf000000b ubll.lst ====
List of blocked users.

Empty space is filled with 0xC-long sequences of 00 00 ... 07

=== Tools ===

* [https://github.com/wwylele/3ds-save-tool 3ds-save-tool] - Extract/verifies extdata

Extdata

2019-05-28T13:31:09Z

Wwylele: /* Quota File */

This page describes the format and encryption of extdata, "extra data" stored on SD card and NAND, at:

* <code>nand/data/<ID>/extdata/<ExtdataID-High></code>
* <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/<ExtdataID-High></code>

ExtdataID-High is always 00000000 for SD, and always 00048000 for NAND. Regular apps can only mount SD extdata using the same extdataID which is stored in the CXI exheader. Therefore, regular apps which have the exheader extdataID set to zero can't use extdata. This restriction doesn't apply for shared extdata with extdataID high bitmask 0x48000 stored on NAND. System apps with a certain access right can mount arbitrary extdata. All NAND extdata is shared extdata, while all SD extdata is normal extdata.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

= Format =

To avoid confusion, the terms '''device directory / file''' and '''virtual directory / file''' are used with the following meanings:

* '''Device directory / file''' are the real directory / file stored on SD / NAND that can be seen under path <code>nand/data/<ID>/extdata/</code> or <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/</code>.
* '''Virtual directory / file''' are directory / file stored inside extdata virtual file system, which can be seen by applications in the mounted extdata archives.

An extdata consists of several device directories and files, which forms a file system consisting of multiple virtual directories and files.

An extdata with ID <code>ExtdataId</code> has the following device files:

* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/Quota.dat</code> (optional)
* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/<SubDirID>/<SubFileID></code>

Note:

* All device files are [[DISA and DIFF|DIFF containers]]. '''All format description below is about the inner content of the containers'''. Please unwrap these files first according to the DIFF format description before reading them using the extdata format description below.
* <code>Quota.dat</code> is only observed existing for NAND shared extdata.
* <code><SubDirID></code> and <code><SubFileID></code> are 8-digit hex strings.
* Device file with <code>SubDirID = SubFileID = 00000000</code> doesn't exist. Other ID combinations can exists.
* Device file with <code>SubDirID = 00000000</code> and <code>SubFileID = 00000001</code> is the VSXE metadata file and must exist.
* Other files, besides <code>Quota.dat</code> and <code>00000000/00000001</code>, are normal sub files, are these device files one-to-one correspond to virtual files. They contain raw virtual file data in the DIFF inner content.
* <code>SubDirID = 00000000</code> is usually the only one device directory that can be seen. See [[#Device Directory Capacity]] for more information.

== Quota File ==

The inner data of <code>Quota.dat</code> is 0x48 bytes with the following format. The file seems to limit the extdata total size.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "QUOT"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 4
| 0x1000, block size
|-
| 0x0C
| 4
| Always 126. Probably device directory capacity. See the [[#Device Directory Capacity]] more information.
|-
| 0x10
| 4
| Always 0?
|-
| 0x14
| 4
| Max number of blocks
|-
| 0x18
| 4
| Always 0?
|-
| 0x1C
| 4
| Free blocks remained
|-
| 0x20
| 4
| Always 0?
|-
| 0x24
| 4
| Always 0?
|-
| 0x28
| 4
| Free blocks remained + (blocks occupied by the recently mounted file, specified by the ID below (0 if recently deleted))
|-
| 0x2C
| 4
| Always 0?
|-
| 0x30
| 4
| ID of most recently mounted file. Same as the one in [[Inner_FAT#Filesystem Header]]
|-
| 0x34
| 4
| Always 0?
|-
| 0x38
| 4
| Always 0?
|-
| 0x3C
| 4
| Always 0?
|-
| 0x40
| 4
| ?
|-
| 0x44
| 4
| Always 0?
|}

== Device Directory Capacity ==

A device directory in an extdata (a <code><SubDirID></code> directory) seems to have a maximum number of device files it can contain. For SD extdata, this maximum number seems to be hard-coded as 126. For NAND extdata, the number is probably indicated by a field in Quota.dat, which is, again, always 126 as observed. 3DS FS tries to put all device files in the device directory <code>00000000</code> if possible, and only when more than 126 files needed to add, a second device directory <code>00000001</code> and so on are created. However, few extdata have such amount of files to store, so the behavior lacks of use cases to confirm.

The number 126 is probably from some kind of other capacity of 128 with <code>"."</code> and <code>".."</code> entries reserved. It is theorized that this is to keep a FAT directory table, with 0x20 bytes for each entry, in one 0x1000 cluster. The motivation is unclear.

== VSXE Filesystem ==

This is one variant of the [[Inner FAT|FAT filesystem]]. Please refer to its page for the description of the filesystem. In general, device file <code>00000000/00000001</code> contains the metadata of the filesystem, while other device files (except for the Quota file) contains normal sub-files

Each non-dummy file entry corresponds to a device file. The path to the device file is generated by the following computation:

<pre>// See previous section about this capacity
const uint32_t device_dir_capacity = 126;

// entry index is the index in the file entry table, with the first dummy entry as
// index = 0, which is never used for a real file.
// file_index = 1 is reserved for the VSXE Filesystem Metadata itself, so real files
// started from file_index = 2.
uint32_t file_index = entry_index + 1;

uint32_t SubDirID = file_index / device_dir_capacity;
uint32_t SubFileID = file_index % pdevice_dir_capacity;

char extdata_path[...]; // ".../extdata/<ExtdataID-High>/<ExtdataId-Low>"
char device_path[...]; // output path
sprintf(device_path, "%s/%08x/%08x", extdata_path, SubDirID, SubFileID);
</pre>
When mounting extdata, the unique identifier is used to match the ID stored in subfile's [[DISA and DIFF#DIFF header|DIFF header]]. If the ID doesn't match, mounting will fail.

== Virtual File System Structure ==

When extdata is created, these are ''always'' created regardless of whether the title actually uses them.

* <code>/icon</code> This virtual file contains the extdata icon displayed in data management. This icon can only be written to by titles when creating extdata, titles would have to recreate extdata to change the icon. This file can't be read directly, instead it is read via FS:ReadExtSaveDataIcon.
* <code>/user/</code> This virtual directory contains the title's actual extdata files.
* <code>/boss/</code> This virtual directory can contain SpotPass content. SpotPass content can only be downloaded to this <code>/boss</code> virtual directory.

User extdata and SpotPass extdata use separate mount points at <code>/user</code> and <code>/boss</code>. Therefore one mount can't access the other virtual directory, and also can't access <code>/icon</code>.(The title's SpotPass extdata can be mounted by the title itself, if it uses SpotPass)

Other optional but notable directories include:

* <code>/user/ExBanner</code> This virtual directory can optionally store extended banners. When this is available, this banner is displayed instead of the CXI ExeFS banner. <code>COMMON.bin</code> stores the common exbanner, while <code><regionlang_code>.bin</code> stores an optional separate region/language specific banner.(regionlang_code can be "JPN_JP", "USA_EN", etc)

== SD Extdata ==
Usually the ExtdataID low is in the format '00<Unique ID>'

{| class="wikitable" border="1"
|-
! JPN ExtdataID
! USA ExtdataID
! EUR ExtdataID
! Description
! Extdata images
|-
| 00000082
| 0000008f
| 00000098
| [[Home Menu]] extdata, this contains home-menu savedata and cached icons for applications.
|
|-
| 00000200
| 00000210
| 00000220
| [[System_Settings|System Settings]] extdata added with [[2.0.0-2]].
|
|-
| 00000207
| 00000217
| 00000227
| [[Mii Maker]], contains an ExBanner
| [https://dl.dropbox.com/u/20520664/extdata00000217.zip cleartext]
|-
| 00000208
| 00000218
| 00000228
| Streetpass Mii Plaza
| 11 mb big!
|-
| 00000209
| 00000219
| 00000229
| [[eShop]], contains store music in AAC format.
|
|-
| 0000020b
| 0000021b
| 0000022b
| Nintendo Zone
|
|-
| 0000020d
| 0000021d
| 0000022d
| Face Raiders, likely contains an ExBanner
|
|-
| 000002cc
| 000002cd
| 000002ce
| [[Home Menu]] theme
|
|-
| ?
| 000004aa
| 000004ab
| Nintendo Video Extra Data
This is where the video files are stored, and [[Nintendo_Video|includes]] the thumbnail, the description, and possibly some checksum info in each video file stored in the extdata images. There are always 9 files within the subdirectory "00000000" of this folder, even without any videos downloaded. The files are "00000001" - "00000009", and "00000003" - "00000008" have the same filesize of 50.7 MB. It is possible to restore the older videos by overwriting all the files within this directory. Provided of course you have made a backup of the files before hand, by copying all the files within this directory to your computer. As far I'm aware its not possible to mix and match the files in order to get certain videos in one grouping, ie. having all 3 Zelda orchestral recordings in one group of 4 Nintendo videos.
|
|-
|00000306
|00000308
|00000307
|Mario Kart 7
|
|-
| 0000030b
| 0000030d
| 0000030c
| Nintendogs + Cats
|
|-
| 00000326
| 00000326
| 00000326
| Pokédex 3D
|
|-
| 00000305
| 0000032d
| 0000033c
| Super Street Fighter IV 3D
|
|-
| 00000328
| 00000358
| 0000033b
| Ridge Racer 3D
|
|-
| ?
| 0000034d
| 00000402
| Samurai Warriors Chronicles
|
|-
| ?
| 0000034f
| 0000038a
| Dead or Alive Dimensions
|
|-
| 00000481
| N/A
| N/A
| Monster Hunter Tri G (Download-Quests)
|
|-
| ?
| 00000517
| 00000518
| Swapnote
|
|-
| 0000055d
| 0000055d
| 0000055d
| Pokémon X Pokémon Y
|
|-
| ?
| 00000725
| 00000724
| Ambassador Certificate
|
|-
| ?
| ?
| 000007af
| New Super Mario Bros. 2
|
|-
| ?
| 00000863
| 00000864
| Animal Crossing: New Leaf
|
|-
| ?
| 00000a85
| 00000a86
| Professor Layton and the Miracle Mask Professor Layton and the Azran Legacy
German Version ExtdataID is 00000a87
|
|-
| ?
| ?
| 00000b4f
| Fullblox / Crashmo
|
|-
| ?
| ?
| 00000ba9
| Pokémon Mystery Dungeon: Gates to Infinity
|
|-
| ?
| ?
| 00000c24
| Denpa men
|
|-
| 00000c73
| 00000c73
| 00000c73
| Save Data Transfer Tool
|
|-
| ?
| ?
| 00000d9a
| Donkey Kong Country™ Returns 3D: Trailer
|
|-
| ?
| ?
| 00000ea6
| Etrian Odyssey IV
|
|-
| ?
| 00000edf
| 00000ee0
| Super Smash Bros. for Nintendo 3DS
|
|-
| ?
| 00000f14
| 00000f1e
| Phoenix Wright: Ace Attorney - Dual Destinies
|
|-
| ?
| 00001007
| 00001005
| Professor Layton vs Phoenix Wright: Ace Attorney
|
|-
| ?
| ?
| 00001062
| Nintendo Pocket Football Club
|
|-
| ?
| ?
| 0000111c
| Yoshi's New Island
|
|-
| ?
| ?
| 00001131
| Fantasy Life
|
|-
| 000011c5
| 000011c5
| 000011c5
| Pokémon Omega Ruby Pokémon Alpha Sapphire
|
|-
| ?
| ?
| 000012ca
| Mario vs. Donkey Kong: Tipping Stars
|
|-
| ?
| ?
| 00001499
| Korg DSN-12
|
|-
| ?
| ?
| 000014f2
| Animal Crossing: Happy Home Designer
|
|-
| 000014d1
| 000014d1
| 000014d1
| [[Home Menu]] badge
|
|-
| ?
| ?
| 00001632
| Fullblox / Stretchmo
|
|-
| ?
| ?
| 00001646
| Pokémon Rumble World
|
|-
| 00001648
| 00001648
| 00001648
| Pokémon Sun Pokémon Moon
|
|-
| 0000165c
| 0000165c
| 0000165c
| [[Home Menu]] saved theme layouts
|
|-
| ?
| ?
| 00001678
| Yo-kai Watch
|
|-
| ?
| ?
| 000018fa
| Phoenix Wright: Ace Attorney - Spirit of Justice
|
|-
| ?
| ?
| 0000198f
| Animal Crossing: New Leaf - Welcome amiibo
|
|-
| ?
| ?
| 00001a05
| Super Mario Maker
|
|-
| ?
| ?
| 00001a2e
| Swapdoodle
|
|}

== NAND Shared Extdata ==
{| class="wikitable" border="1"
|-
! ExtdataID
! Description
|-
| 0xe0000000
| Home Menu attempts to open this archive during boot, if [[FS:OpenArchive]] doesn't return an error Home Menu seems to then launch the [[System Transfer]] application. Home Menu doesn't actually use this archive at all except for checking whether it exists.
|-
| 0xf0000001
| NAND JPEG/MPO files and phtcache.bin from the camera application are stored here. This also contains UploadData.dat.
|-
| 0xf0000002
| NAND M4A files from the sound application are stored here
|-
| 0xf0000009
| Used for [[BOSS_Services|SpotPass]] content storage for [[News_Services|notifications]].
|-
| 0xf000000b
| Contains idb.dat, idbt.dat, gamecoin.dat, ubll.lst, CFL_DB.dat, and CFL_OldDB.dat. These files contain cleartext [[Mii_Maker|Miis]] and some data relating (including cached ICN data) to Play/Usage Records.
|-
| 0xf000000c
| Contains bashotorya.dat and bashotorya2.dat.
|-
| 0xf000000d
| Home Menu SpotPass content data [[BOSS_Services|storage]].
|-
| 0xf000000e
| Contains [[VersionList|versionlist.dat]], used by Home Menu for the software update notification added with [[7.0.0-13]].
|}

==== Shared Extdata 0xf000000b gamecoin.dat ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Magic number: 0x4F00
|-
| 0x4
| 0x2
| Total Play Coins
|-
| 0x6
| 0x2
| Total Play Coins obtained on the date stored below. When the below date does not match the current date, this field is reset to zero, then the date(and other fields) are updated. Once this value is >=10, no more Play Coins can be obtained until the current date changes.
|-
| 0x8
| 0x4
| Total step [[PTM:GetTotalStepCount|count]] at the time a new Play Coin was obtained.
|-
| 0xC
| 0x4
| Step count for the day the last Play Coin was obtained, for that day's step count(same as the step count displayed by home-menu when this file was updated).
|-
| 0x10
| 0x2
| Year
|-
| 0x12
| 0x1
| Month
|-
| 0x13
| 0x1
| Day
|}

The above date stores the last time new Play Coin(s) were obtained. The contents of this file is updated by home-menu. [[PTM:GetTotalStepCount]] is not checked constantly, after home-menu boot this is only checked when waking from sleep-mode. Each time home-menu updates the contents of this file, home-menu will set the Play Coin total to 300 if it's higher than the 300 Play Coin limit.

[[Home Menu]] loads this file / opens this archive during [[Home Menu|startup]]. When accessing this file fails, like when the file/archive is corrupted(or at least on older system-versions), the result is a brick due to Home Menu using [[SVC|svcBreak]]. [[User:Yellows8|Yellows8]] bricked a 3DS this way due to corruption via invalid [[FSFile:Write]] flush flags. When opening this extdata archive(0xf000000b) fails, Home Menu executes svcBreak.

==== Shared Extdata 0xf000000b ubll.lst ====
List of blocked users.

Empty space is filled with 0xC-long sequences of 00 00 ... 07

=== Tools ===

* [https://github.com/wwylele/3ds-save-tool 3ds-save-tool] - Extract/verifies extdata

Extdata

2019-05-28T12:46:52Z

Wwylele: /* Quota File */

This page describes the format and encryption of extdata, "extra data" stored on SD card and NAND, at:

* <code>nand/data/<ID>/extdata/<ExtdataID-High></code>
* <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/<ExtdataID-High></code>

ExtdataID-High is always 00000000 for SD, and always 00048000 for NAND. Regular apps can only mount SD extdata using the same extdataID which is stored in the CXI exheader. Therefore, regular apps which have the exheader extdataID set to zero can't use extdata. This restriction doesn't apply for shared extdata with extdataID high bitmask 0x48000 stored on NAND. System apps with a certain access right can mount arbitrary extdata. All NAND extdata is shared extdata, while all SD extdata is normal extdata.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

= Format =

To avoid confusion, the terms '''device directory / file''' and '''virtual directory / file''' are used with the following meanings:

* '''Device directory / file''' are the real directory / file stored on SD / NAND that can be seen under path <code>nand/data/<ID>/extdata/</code> or <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/</code>.
* '''Virtual directory / file''' are directory / file stored inside extdata virtual file system, which can be seen by applications in the mounted extdata archives.

An extdata consists of several device directories and files, which forms a file system consisting of multiple virtual directories and files.

An extdata with ID <code>ExtdataId</code> has the following device files:

* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/Quota.dat</code> (optional)
* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/<SubDirID>/<SubFileID></code>

Note:

* All device files are [[DISA and DIFF|DIFF containers]]. '''All format description below is about the inner content of the containers'''. Please unwrap these files first according to the DIFF format description before reading them using the extdata format description below.
* <code>Quota.dat</code> is only observed existing for NAND shared extdata.
* <code><SubDirID></code> and <code><SubFileID></code> are 8-digit hex strings.
* Device file with <code>SubDirID = SubFileID = 00000000</code> doesn't exist. Other ID combinations can exists.
* Device file with <code>SubDirID = 00000000</code> and <code>SubFileID = 00000001</code> is the VSXE metadata file and must exist.
* Other files, besides <code>Quota.dat</code> and <code>00000000/00000001</code>, are normal sub files, are these device files one-to-one correspond to virtual files. They contain raw virtual file data in the DIFF inner content.
* <code>SubDirID = 00000000</code> is usually the only one device directory that can be seen. See [[#Device Directory Capacity]] for more information.

== Quota File ==

The inner data of <code>Quota.dat</code> is 0x48 bytes with the following format. The file seems to limit the extdata total size.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "QUOT"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 4
| 0x1000, block size
|-
| 0x0C
| 4
| Always 126. Probably device directory capacity. See the [[#Device Directory Capacity]] more information.
|-
| 0x10
| 4
| Always 0?
|-
| 0x14
| 4
| Max number of blocks
|-
| 0x18
| 4
| Always 0?
|-
| 0x1C
| 4
| Free blocks remained
|-
| 0x20
| 4
| Always 0?
|-
| 0x24
| 4
| Always 0?
|-
| 0x28
| 4
| Equal or greater than the free blocks number?
|-
| 0x2C
| 4
| Always 0?
|-
| 0x30
| 4
| ID of most recently mounted Extdata image. Same as the one in [[Inner_FAT#Filesystem Header]]
|-
| 0x34
| 4
| Always 0?
|-
| 0x38
| 4
| Always 0?
|-
| 0x3C
| 4
| Always 0?
|-
| 0x40
| 4
| ?
|-
| 0x44
| 4
| Always 0?
|}

== Device Directory Capacity ==

A device directory in an extdata (a <code><SubDirID></code> directory) seems to have a maximum number of device files it can contain. For SD extdata, this maximum number seems to be hard-coded as 126. For NAND extdata, the number is probably indicated by a field in Quota.dat, which is, again, always 126 as observed. 3DS FS tries to put all device files in the device directory <code>00000000</code> if possible, and only when more than 126 files needed to add, a second device directory <code>00000001</code> and so on are created. However, few extdata have such amount of files to store, so the behavior lacks of use cases to confirm.

The number 126 is probably from some kind of other capacity of 128 with <code>"."</code> and <code>".."</code> entries reserved. It is theorized that this is to keep a FAT directory table, with 0x20 bytes for each entry, in one 0x1000 cluster. The motivation is unclear.

== VSXE Filesystem ==

This is one variant of the [[Inner FAT|FAT filesystem]]. Please refer to its page for the description of the filesystem. In general, device file <code>00000000/00000001</code> contains the metadata of the filesystem, while other device files (except for the Quota file) contains normal sub-files

Each non-dummy file entry corresponds to a device file. The path to the device file is generated by the following computation:

<pre>// See previous section about this capacity
const uint32_t device_dir_capacity = 126;

// entry index is the index in the file entry table, with the first dummy entry as
// index = 0, which is never used for a real file.
// file_index = 1 is reserved for the VSXE Filesystem Metadata itself, so real files
// started from file_index = 2.
uint32_t file_index = entry_index + 1;

uint32_t SubDirID = file_index / device_dir_capacity;
uint32_t SubFileID = file_index % pdevice_dir_capacity;

char extdata_path[...]; // ".../extdata/<ExtdataID-High>/<ExtdataId-Low>"
char device_path[...]; // output path
sprintf(device_path, "%s/%08x/%08x", extdata_path, SubDirID, SubFileID);
</pre>
When mounting extdata, the unique identifier is used to match the ID stored in subfile's [[DISA and DIFF#DIFF header|DIFF header]]. If the ID doesn't match, mounting will fail.

== Virtual File System Structure ==

When extdata is created, these are ''always'' created regardless of whether the title actually uses them.

* <code>/icon</code> This virtual file contains the extdata icon displayed in data management. This icon can only be written to by titles when creating extdata, titles would have to recreate extdata to change the icon. This file can't be read directly, instead it is read via FS:ReadExtSaveDataIcon.
* <code>/user/</code> This virtual directory contains the title's actual extdata files.
* <code>/boss/</code> This virtual directory can contain SpotPass content. SpotPass content can only be downloaded to this <code>/boss</code> virtual directory.

User extdata and SpotPass extdata use separate mount points at <code>/user</code> and <code>/boss</code>. Therefore one mount can't access the other virtual directory, and also can't access <code>/icon</code>.(The title's SpotPass extdata can be mounted by the title itself, if it uses SpotPass)

Other optional but notable directories include:

* <code>/user/ExBanner</code> This virtual directory can optionally store extended banners. When this is available, this banner is displayed instead of the CXI ExeFS banner. <code>COMMON.bin</code> stores the common exbanner, while <code><regionlang_code>.bin</code> stores an optional separate region/language specific banner.(regionlang_code can be "JPN_JP", "USA_EN", etc)

== SD Extdata ==
Usually the ExtdataID low is in the format '00<Unique ID>'

{| class="wikitable" border="1"
|-
! JPN ExtdataID
! USA ExtdataID
! EUR ExtdataID
! Description
! Extdata images
|-
| 00000082
| 0000008f
| 00000098
| [[Home Menu]] extdata, this contains home-menu savedata and cached icons for applications.
|
|-
| 00000200
| 00000210
| 00000220
| [[System_Settings|System Settings]] extdata added with [[2.0.0-2]].
|
|-
| 00000207
| 00000217
| 00000227
| [[Mii Maker]], contains an ExBanner
| [https://dl.dropbox.com/u/20520664/extdata00000217.zip cleartext]
|-
| 00000208
| 00000218
| 00000228
| Streetpass Mii Plaza
| 11 mb big!
|-
| 00000209
| 00000219
| 00000229
| [[eShop]], contains store music in AAC format.
|
|-
| 0000020b
| 0000021b
| 0000022b
| Nintendo Zone
|
|-
| 0000020d
| 0000021d
| 0000022d
| Face Raiders, likely contains an ExBanner
|
|-
| 000002cc
| 000002cd
| 000002ce
| [[Home Menu]] theme
|
|-
| ?
| 000004aa
| 000004ab
| Nintendo Video Extra Data
This is where the video files are stored, and [[Nintendo_Video|includes]] the thumbnail, the description, and possibly some checksum info in each video file stored in the extdata images. There are always 9 files within the subdirectory "00000000" of this folder, even without any videos downloaded. The files are "00000001" - "00000009", and "00000003" - "00000008" have the same filesize of 50.7 MB. It is possible to restore the older videos by overwriting all the files within this directory. Provided of course you have made a backup of the files before hand, by copying all the files within this directory to your computer. As far I'm aware its not possible to mix and match the files in order to get certain videos in one grouping, ie. having all 3 Zelda orchestral recordings in one group of 4 Nintendo videos.
|
|-
|00000306
|00000308
|00000307
|Mario Kart 7
|
|-
| 0000030b
| 0000030d
| 0000030c
| Nintendogs + Cats
|
|-
| 00000326
| 00000326
| 00000326
| Pokédex 3D
|
|-
| 00000305
| 0000032d
| 0000033c
| Super Street Fighter IV 3D
|
|-
| 00000328
| 00000358
| 0000033b
| Ridge Racer 3D
|
|-
| ?
| 0000034d
| 00000402
| Samurai Warriors Chronicles
|
|-
| ?
| 0000034f
| 0000038a
| Dead or Alive Dimensions
|
|-
| 00000481
| N/A
| N/A
| Monster Hunter Tri G (Download-Quests)
|
|-
| ?
| 00000517
| 00000518
| Swapnote
|
|-
| 0000055d
| 0000055d
| 0000055d
| Pokémon X Pokémon Y
|
|-
| ?
| 00000725
| 00000724
| Ambassador Certificate
|
|-
| ?
| ?
| 000007af
| New Super Mario Bros. 2
|
|-
| ?
| 00000863
| 00000864
| Animal Crossing: New Leaf
|
|-
| ?
| 00000a85
| 00000a86
| Professor Layton and the Miracle Mask Professor Layton and the Azran Legacy
German Version ExtdataID is 00000a87
|
|-
| ?
| ?
| 00000b4f
| Fullblox / Crashmo
|
|-
| ?
| ?
| 00000ba9
| Pokémon Mystery Dungeon: Gates to Infinity
|
|-
| ?
| ?
| 00000c24
| Denpa men
|
|-
| 00000c73
| 00000c73
| 00000c73
| Save Data Transfer Tool
|
|-
| ?
| ?
| 00000d9a
| Donkey Kong Country™ Returns 3D: Trailer
|
|-
| ?
| ?
| 00000ea6
| Etrian Odyssey IV
|
|-
| ?
| 00000edf
| 00000ee0
| Super Smash Bros. for Nintendo 3DS
|
|-
| ?
| 00000f14
| 00000f1e
| Phoenix Wright: Ace Attorney - Dual Destinies
|
|-
| ?
| 00001007
| 00001005
| Professor Layton vs Phoenix Wright: Ace Attorney
|
|-
| ?
| ?
| 00001062
| Nintendo Pocket Football Club
|
|-
| ?
| ?
| 0000111c
| Yoshi's New Island
|
|-
| ?
| ?
| 00001131
| Fantasy Life
|
|-
| 000011c5
| 000011c5
| 000011c5
| Pokémon Omega Ruby Pokémon Alpha Sapphire
|
|-
| ?
| ?
| 000012ca
| Mario vs. Donkey Kong: Tipping Stars
|
|-
| ?
| ?
| 00001499
| Korg DSN-12
|
|-
| ?
| ?
| 000014f2
| Animal Crossing: Happy Home Designer
|
|-
| 000014d1
| 000014d1
| 000014d1
| [[Home Menu]] badge
|
|-
| ?
| ?
| 00001632
| Fullblox / Stretchmo
|
|-
| ?
| ?
| 00001646
| Pokémon Rumble World
|
|-
| 00001648
| 00001648
| 00001648
| Pokémon Sun Pokémon Moon
|
|-
| 0000165c
| 0000165c
| 0000165c
| [[Home Menu]] saved theme layouts
|
|-
| ?
| ?
| 00001678
| Yo-kai Watch
|
|-
| ?
| ?
| 000018fa
| Phoenix Wright: Ace Attorney - Spirit of Justice
|
|-
| ?
| ?
| 0000198f
| Animal Crossing: New Leaf - Welcome amiibo
|
|-
| ?
| ?
| 00001a05
| Super Mario Maker
|
|-
| ?
| ?
| 00001a2e
| Swapdoodle
|
|}

== NAND Shared Extdata ==
{| class="wikitable" border="1"
|-
! ExtdataID
! Description
|-
| 0xe0000000
| Home Menu attempts to open this archive during boot, if [[FS:OpenArchive]] doesn't return an error Home Menu seems to then launch the [[System Transfer]] application. Home Menu doesn't actually use this archive at all except for checking whether it exists.
|-
| 0xf0000001
| NAND JPEG/MPO files and phtcache.bin from the camera application are stored here. This also contains UploadData.dat.
|-
| 0xf0000002
| NAND M4A files from the sound application are stored here
|-
| 0xf0000009
| Used for [[BOSS_Services|SpotPass]] content storage for [[News_Services|notifications]].
|-
| 0xf000000b
| Contains idb.dat, idbt.dat, gamecoin.dat, ubll.lst, CFL_DB.dat, and CFL_OldDB.dat. These files contain cleartext [[Mii_Maker|Miis]] and some data relating (including cached ICN data) to Play/Usage Records.
|-
| 0xf000000c
| Contains bashotorya.dat and bashotorya2.dat.
|-
| 0xf000000d
| Home Menu SpotPass content data [[BOSS_Services|storage]].
|-
| 0xf000000e
| Contains [[VersionList|versionlist.dat]], used by Home Menu for the software update notification added with [[7.0.0-13]].
|}

==== Shared Extdata 0xf000000b gamecoin.dat ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Magic number: 0x4F00
|-
| 0x4
| 0x2
| Total Play Coins
|-
| 0x6
| 0x2
| Total Play Coins obtained on the date stored below. When the below date does not match the current date, this field is reset to zero, then the date(and other fields) are updated. Once this value is >=10, no more Play Coins can be obtained until the current date changes.
|-
| 0x8
| 0x4
| Total step [[PTM:GetTotalStepCount|count]] at the time a new Play Coin was obtained.
|-
| 0xC
| 0x4
| Step count for the day the last Play Coin was obtained, for that day's step count(same as the step count displayed by home-menu when this file was updated).
|-
| 0x10
| 0x2
| Year
|-
| 0x12
| 0x1
| Month
|-
| 0x13
| 0x1
| Day
|}

The above date stores the last time new Play Coin(s) were obtained. The contents of this file is updated by home-menu. [[PTM:GetTotalStepCount]] is not checked constantly, after home-menu boot this is only checked when waking from sleep-mode. Each time home-menu updates the contents of this file, home-menu will set the Play Coin total to 300 if it's higher than the 300 Play Coin limit.

[[Home Menu]] loads this file / opens this archive during [[Home Menu|startup]]. When accessing this file fails, like when the file/archive is corrupted(or at least on older system-versions), the result is a brick due to Home Menu using [[SVC|svcBreak]]. [[User:Yellows8|Yellows8]] bricked a 3DS this way due to corruption via invalid [[FSFile:Write]] flush flags. When opening this extdata archive(0xf000000b) fails, Home Menu executes svcBreak.

==== Shared Extdata 0xf000000b ubll.lst ====
List of blocked users.

Empty space is filled with 0xC-long sequences of 00 00 ... 07

=== Tools ===

* [https://github.com/wwylele/3ds-save-tool 3ds-save-tool] - Extract/verifies extdata

DISA and DIFF

2019-05-26T13:35:47Z

Wwylele: /* Partition table & partition descriptor */ The padding doesn't actually belongs to the descriptor, according to the descriptor size in the header

This page describes DISA and DIFF format as the underlying container of [[Savegames]], [[Extdata]] and [[Title Database]]. For further format specification of the inner data, please refer to their own page.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

== Overview ==

DISA and DIFF are two container formats. They are very similar and are used for various purposes in 3DS. Here is a summary table of their usage, the CMAC type and the AES key slot used (the meaning of these is explained in the next section):

{| class="wikitable" border="1"
! Usage
! Media
! Container format
! [[#AES CMAC|CMAC type]]
! CMAC [[AES Registers|Keyslot]]
|-
| [[Savegames]]
| Gamecard
| DISA
| [[#CTR-SAV0|CTR-SAV0]]
| 0x19
|-
| [[Savegames]]
| [[SD Filesystem|SD]]
| DISA
| [[#CTR-SIGN|CTR-SIGN]]
| 0x30
|-
| [[System SaveData]]
| [[Flash Filesystem|NAND]]
| DISA
| [[#CTR-SYS0|CTR-SYS0]]
| 0x30
|-
| [[Extdata|Private Extdata]]
| [[SD Filesystem|SD]]
| DIFF
| [[#CTR-EXT0|CTR-EXT0]]
| 0x30
|-
| [[Extdata|Shared Extdata]]
| [[Flash Filesystem|NAND]]
| DIFF
| [[#CTR-EXT0|CTR-EXT0]]
| 0x30
|-
| [[Title Database]]
| [[SD Filesystem|SD]]
| DIFF
| [[#CTR-9DB0|CTR-9DB0]]
| 0x30
|-
| [[Title Database]]
| [[Flash Filesystem|NAND]]
| DIFF
| [[#CTR-9DB0|CTR-9DB0]]
| 0x0B
|}

== Encryption ==

DISA and DIFF formats don't have their own encryption specification. They follow the encryption method defined by their media:

* Gamecard savegames have special wear leveling + encryption layers. See [[Savegames]] for detail.
* Files on SD follow [[SD Filesystem|the general SD filesystem encryption rule]].
* Files on NAND are in cleartext, after decrypting [[Flash Filesystem|the NAND partition encryption]].

== Format ==

A DISA / DIFF file consists of the following components:

* 0x100-byte AES CMAC
* 0x100-byte Header
* Secondary partition table
** Contains one or two partition descriptors, depending on the number of partitions.
* Primary partition table
** Same layout as the secondary one
* Partition A
* Partition B (optional)
** can only exist for DISA.

== AES CMAC ==

The AES CMAC is located at the beginning of the DISA / DIFF image, and it is 0x10 long. The rest 0xF0 bytes before the header are unused.

The key used for the AES CMAC is generated by the [[AES Registers|hardware key engine]]. See the keyslot it uses in the table above.

The data being authenticated by the AES CMAC is a 0x20-byte SHA-256 hash of a data block. The data block has different content formats among CMAC types. All types of data block contain a copy or a hash of the header, which is the start of the the rest of the verification chain, so the AES CMAC effectively authenticates the whole save image. Each type of data block is explained below.

=== CTR-SAV0 ===

This CMAC type is used for gamecard savegames. It is 0x28-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SAV0"
|-
| 0x8
| 0x20
| SHA-256 of the following 0x108-byte block
|-
|

|

|

|-
| 0x00
| 8
| Magic "CTR-NOR0"
|-
| 0x08
| 0x100
| Copy of the DISA header
|}

=== CTR-SIGN ===

This CMAC type is used for SD savegames. It is 0x30-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SIGN"
|-
| 0x08
| 8
| Title ID
|-
| 0x10
| 0x20
| SHA-256 of the following 0x108-byte block
|-
|

|

|

|-
| 0x00
| 8
| Magic "CTR-SAV0"
|-
| 0x08
| 0x100
| Copy of the DISA header
|}

=== CTR-SYS0 ===

This CMAC type is used for NAND system save. It is 0x110-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-SYS0"
|-
| 0x08
| 8
| Save ID. The higher word is always zero
|-
| 0x10
| 0x100
| Copy of the DISA header
|}

=== CTR-EXT0 ===

This CMAC type is used for extdata. It is 0x11C-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-EXT0"
|-
| 0x08
| 8
| Extdata ID
|-
| 0x10
| 4
| 0 for Quota.dat, 1 otherwise
|-
| 0x14
| 4
| ID in the device file name. 0 for Quota.dat
|-
| 0x18
| 4
| ID in the device directory name that the file is in. 0 for Quota.dat
|-
| 0x1C
| 0x100
| Copy of the DIFF header
|}

=== CTR-9DB0 ===

This CMAC type is used for title database. It is 0x10C-byte long.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 8
| Magic "CTR-9DB0"
|-
| 0x08
| 4
| Database ID. Each .db file has its own ID
|-
| 0x0C
| 0x100
| Copy of the DIFF header
|}

== Header ==

The header located at offset 0x100 defines the rest components of the file (partitions and their tables). All offsets in the header are relative to the beginning of the DISA/DIFF file, except for partition descriptor offsets, which are relative to the beginning of the (active) partition table. DISA and DIFF have different header format.

=== DISA header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DISA"
|-
| 0x04
| 4
| Magic 0x40000
|-
| 0x08
| 4
| Partition count, 1 or 2
|-
| 0x0C
| 4
| Padding
|-
| 0x10
| 8
| Secondary partition table offset
|-
| 0x18
| 8
| Primary partition table offset
|-
| 0x20
| 8
| Partition table size
|-
| 0x28
| 8
| Partition A descriptor offset in the partition table
|-
| 0x30
| 8
| Partition A descriptor size
|-
| 0x38
| 8
| Partition B descriptor offset in the partition table
|-
| 0x40
| 8
| Partition B descriptor size
|-
| 0x48
| 8
| Partition A offset
|-
| 0x50
| 8
| Partition A size
|-
| 0x58
| 8
| Partition B offset
|-
| 0x60
| 8
| Partition B size
|-
| 0x68
| 1
| Active partition table, 0 = primary, 1 = secondary
|-
| 0x69
| 3
| Padding
|-
| 0x6C
| 0x20
| SHA-256 over the active partition table
|-
| 0x8C
| 0x74
| Unused
|}

Note:

* When the partition count is 1, there is no partition B and all of its related fields are zero.

=== DIFF header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DIFF"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 8
| Secondary partition table/descriptor offset
|-
| 0x10
| 8
| Primary partition table/descriptor offset
|-
| 0x18
| 8
| Partition table/descriptor size
|-
| 0x20
| 8
| Partition (A) offset
|-
| 0x28
| 8
| Partition (A) size
|-
| 0x30
| 4
| Active partition descriptor, 0 = primary, 1 = secondary
|-
| 0x34
| 0x20
| SHA-256 over the active partition table/descriptor
|-
| 0x54
| 8
| Unique identifier
|-
| 0x5C
| 0xA4
| Unused, might contain leftover data
|}

Note:

* Since DIFF can only contain one partition, a partition table can only have one partition descriptor, so they become the same concept here.
* See [[Extdata]] for its usage of the unique identifier field. For title database files, this field is zero.

== Partition table & partition descriptor ==

There are two partition tables, but only one of them is active. When operating on a DISA / DIFF file, 3DS FS alternately activate one of the two tables, presumably for data backup or atomic file writing. A newly created DISA / DIFF file may have entirely uninitialized data in the inactive partition table.

One partition table contains one or two partition descriptors , each of which describes the layout of one partition. A partition descriptor contains the following components:

* DIFI header
* IVFC descriptor
* DPFS descriptor
* Partition master hash

=== DIFI header ===

The DIFI header locates at the beginning of a partition descriptor. This header defines the rest components of the partition descriptor (IVFC descriptor, DPFS descriptor and partition master hash). All offsets are relative to the beginning of the partition descriptor, except for <code>External IVFC level 4 offset</code>, which is relative to the beginning of the partition.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DIFI"
|-
| 0x04
| 4
| Magic 0x10000
|-
| 0x08
| 8
| IVFC descriptor offset
|-
| 0x10
| 8
| IVFC descriptor size
|-
| 0x18
| 8
| DPFS descriptor offset
|-
| 0x20
| 8
| DPFS descriptor size
|-
| 0x28
| 8
| Partition hash offset
|-
| 0x30
| 8
| Partition hash size
|-
| 0x38
| 1
| If none zero, enable external IVFC level 4.
|-
| 0x39
| 1
| DPFS tree level 1 selector
|-
| 0x3A
| 2
| Padding
|-
| 0x3C
| 8
| External IVFC level 4 offset (zero if external IVFC level 4 disabled)
|}

Note:

* The meaning of fields after 0x38 are explained in the section [[#Partition]]

=== IVFC descriptor ===

This header defines each level of IVFC tree (explained in the section [[#Partition]]). All offsets are relative to the beginning of DPFS level 3.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "IVFC"
|-
| 0x04
| 4
| Magic 0x20000
|-
| 0x08
| 8
| Master hash size = partition master hash size in DIFI header
|-
| 0x10
| 8
| IVFC level 1 offset
|-
| 0x18
| 8
| IVFC level 1 size
|-
| 0x20
| 4
| IVFC level 1 block size in log2
|-
| 0x24
| 4
| Padding
|-
| 0x28
| 8
| IVFC level 2 offset
|-
| 0x30
| 8
| IVFC level 2 size
|-
| 0x38
| 4
| IVFC level 2 block size in log2
|-
| 0x3C
| 4
| Padding
|-
| 0x40
| 8
| IVFC level 3 offset
|-
| 0x48
| 8
| IVFC level 3 size
|-
| 0x50
| 4
| IVFC level 3 block size in log2
|-
| 0x54
| 4
| Padding
|-
| 0x58
| 8
| IVFC level 4 offset (unused if external IVFC level 4 enabled)
|-
| 0x60
| 8
| IVFC level 4 size
|-
| 0x68
| 4
| IVFC level 4 block size in log2
|-
| 0x6C
| 4
| Padding
|-
| 0x70
| 8
| IVFC descriptor size? The value is usually 0x78
|}

=== DPFS descriptor ===

This header defines each level of DPFS tree (explained in the section [[#Partition]]). All offsets are relative to the beginning of the partition.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "DPFS"
|-
| 0x04
| 4
| Magic 0x10000
|-
| 0x08
| 8
| DPFS level 1 offset
|-
| 0x10
| 8
| DPFS level 1 size
|-
| 0x18
| 4
| DPFS level 1 block size in log2 (unused?)
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 8
| DPFS level 2 offset
|-
| 0x28
| 8
| DPFS level 2 size
|-
| 0x30
| 4
| DPFS level 2 block size in log2
|-
| 0x34
| 4
| Padding
|-
| 0x38
| 8
| DPFS level 3 offset
|-
| 0x40
| 8
| DPFS level 3 size
|-
| 0x48
| 4
| DPFS level 3 block size in log2
|-
| 0x4C
| 4
| Padding
|}

=== Partition master hash ===

This is a SHA-256 hash list over IVFC level 1. See [[#IVFC tree]] for explanation.

== Partition ==

A partition can have two types of layout. This is determined by the field DIFF + 0x38 (<code>Enable external IVFC level 4</code>).

The layout type 0 (external IVFC level 4 disabled) contains

* DPFS level 1
* DPFS level 2
* DPFS level 3, and inside
** IVFC level 1
** IVFC level 2
** IVFC level 3
** IVFC level 4 (the actual content data)

The layout type 1 (external IVFC level 4 enabled) contains

* DPFS level 1
* DPFS level 2
* DPFS level 3, and inside
** IVFC level 1
** IVFC level 2
** IVFC level 3
* IVFC level 4 (the actual content data, note that this is out side DPFS level 3)

=== DPFS tree ===

Everything inside the DPFS tree comes in pairs, and at one time only one of a pair is active. The tree is probably designed for atomic writing: for a file writing operation, it writes to the inactive part, then commits the data by switching a bit to activate it.

Each level of DPFS tree consists of a pair of chunks. The size of one chunk is defined as it in the DPFS descriptor, so the total size of a level is actually twice as large as the size recorded in the descriptor. For level 1 and 2, each chunk is a bit array, in which each bit corresponds to a block in the next level (the block size of the next level is also defined in the DPFS descriptor). This bit indicates which one of the pair in the next level is active for this block: 0 means the first one and 1 means the second one. The active chunk of level 1 is selected by <code>DPFS tree level 1 selector</code> in the DIFI header. The bit array is encoded in u32 array, with MSB as the first bit of each 32 bits.

To access data in level 3, one needs to check the bits in level 1 and level 2 to know which chunk of level 3 is active for the accessed location. For example, for a following configuration:

* Level 1: size = 4 bytes = 32 bits
* Level 2: size = 0x380 bytes = 0x1C00 bits, block size = 0x80 bytes
* Level 3: size = 0x1B7F000, block size = 0x1000, block size = 0x1000 bytes

if one want to read byte at 0x1234567 of level 3, the following calculation is performed:

* get level 2 bit index <code>0x1234567 / 0x1000 = 0x1234</code>, and its byte location <code>0x1234 / 8 = 0x246</code>
* get level 1 bit index <code>0x246 / 0x80 = 4</code>
* get <code>level1_selector</code> from DIFI header
* read <code>level2_selector = Level1[level1_selector].bits[4]</code>;
* read <code>level3_selector = Level2[level2_selector].bits[0x1234]</code>;
* read <code>data = Level3[level3_selector].bytes[0x1234567]</code> as the final data
* in the code above <code>Levelx[k]</code> means the <code>k</code>-th chunk in level <code>x</code>, where <code>k = 0, 1</code>. <code>.bits[n]</code> is expanded to <code>(.u32_array[n / 32] >> (31 - n % 32)) & 1</code> as the bit array is encoded in u32 array.

Effectively, the active data is scattered among the two level 3 chunk. One can assemble the whole active level 3 image following the same rule.

=== IVFC tree ===

The IVFC tree is used for data verification. It is very similar to the IVFC tree in [[RomFS]], except that it has an additional level here. For level 1, 2 and 3, each level is a list of SHA-256 hash, of which each corresponds to a block of the next level which is zero-padded to align the block size (the block size of the next level is defined in the IVFC descriptor).

The partition master hash in the partition descriptor can be seen as IVFC level 0, which hashes level 1 following the same rule. The master hash is usually 0x20 long, consisting only one hash. This is because most DISA / DIFF files are not large enough to have multiple hashes on the top level, which isn't the case for some title database files.

However, not all data is hashed - only ranges that have been written with valid data are properly hashed.

Level 4 is the actual content of the partition, which is what the container format essentially contains.

== Extracting content from a DISA / DIFF container ==

* Find the active partition table and the partition(s).
* Unwrap DPFS tree of partition(s) by reconstructing active data.
* Unwrap IVFC tree. Either take out level 4 directly, or, better, verify all the hashes and poison the data that is not properly hashed.
* The IVFC level 4 is the inner content of the file. The format of it varies among different usage. Refer their own page for further extraction.

== Chain of trust ==

* AES CMAC verifies the header.
* The header verifies the active partition table via the table hash.
* In the partition table, each descriptor verifies level 1 of its IVFC tree via the master hash.
* Each IVFC level verifies the next level, until the level 4, which is the inner content.

== Summary diagram ==

external link: https://i.imgur.com/BjwShJZ.png
* Please move this into 3dbrew when file uploading is fixed.

Inner FAT

2019-05-23T01:16:31Z

Wwylele: /* Filesystem Header */ Nintendo please

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks (including pre header for title database)
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| ID of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
(excluding the leading 0th entry. See below)
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= File allocation table entry count)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.
* For title database (except for ticket), the range specified for data region seems overflow the file end by 0x80 bytes, which is exactly the size of the pre header. This makes it as if the data region offset should be relative to the pre header instead of the BDRI header. However, further investigation on the directory/file table allocated inside the data region shows that the data region offset is indeed relative to the BDRI header. It might be a bug in 3DS that the title database files miss 0x80-byte space at the end.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Inner FAT

2019-05-15T08:54:51Z

Wwylele: /* Filesystem Header */

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks (including pre header for title database)
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| ID of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
(excluding the leading 0th entry. See below)
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= File allocation table entry count)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Inner FAT

2019-05-05T12:15:04Z

Wwylele: /* Filesystem Header */

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks (including pre header for title database)
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
(excluding the leading 0th entry. See below)
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= File allocation table entry count)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Title Database

2019-05-03T20:03:21Z

Wwylele: Migrate to Inner FAT

These files contain data relating to install/usage/management of installed 3DS titles. The database files are located at:

* nand/dbs
* sdmc/Nintendo 3DS/<ID0>/<ID1>/dbs

ID0 is the first 0x10-bytes from a SHA256 [[nand/private/movable.sed|hash]]. The installation of [[SD Filesystem|SD Card]] titles was introduced in the [[2.0.0-2]] update and the SD dbs files are encrypted by [[SD Filesystem|the general SD filesystem encryption rule]]. These files are [[DISA and DIFF|DIFF containers]]. These DIFF files do not use external IVFC level 4, so all database data is duplicated in the container. In this page only the inner content of the container is described.

These files are only created on SD (via [[Application_Manager_Services|AM]]) if they don't exist when the [[eShop]] application is starting up, during network init etc (prior to showing the "system update required" dialog).

These files are stored under this directory:
{| class="wikitable" border="1"
|-
! Stored on SD card
! Stored in CTR-NAND
! Filename
! [[DISA and DIFF#CTR-9DB0|CTR-9DB0]] ID
! Description
|-
| No
| Yes
| ticket.db
| 0x0
| This contains the installed tickets (NAND and SD).
|-
| No
| Yes
| certs.db
| 0x1
| This contains the certificate chain used to verify TMDs and other certificates.
|-
| Yes
| Yes
| title.db
| 0x2
| Title database, this contains entries for all installed titles (TWL & CTR) on the 3DS (Each database is responsible for titles installed on its medium).
|-
| Yes
| Yes
| import.db
| 0x3
| This is an Import Database, it contains entries for titles (or versions of titles) not yet installed, ready for transferring to the title.db. (Automatic Update uses this, so completing the update takes seconds.)
|-
| No
| Yes
| tmp_t.db
| 0x4
| This is the temporary Title database containing one entry for the currently installed [[Download Play]] Child.
|-
| No
| Yes
| tmp_i.db
| 0x5
| Similar to import.db, except it's used in conjunction with tmp_t.db, for installing [[Download Play]] Children.
|}

The inner content of the container consists of a pre-header with size of 0x80 identifying the Database Type, followed by a BDRI container. The offsets in the BDRI header are usually relative to the offset to the start of the BDRI header (0x80 in the file)

== Pre Header ==

{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x00
| 8
| Database Type "Magic" (see below)
|-
| 0x08
| 0x78
| Reserved
|}

For ticket.db different pre header is used:

{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x00
| 4
| Database Type "Magic" (see below)
|-
| 0x04
| 0x04
| Unknown (always 0x00000001 ?)
|-
| 0x08
| 0x04
| Unknown
|-
| 0x0C
| 0x04
| Unknown (0x30 smaller than previous one)
|}

=== Database Magic ===

{| class="wikitable"
|-
! Database Type
! Magic
|-
| CTR-NAND ticket.db
| TICK
|-
| CTR-NAND import.db
| NANDIDB
|-
| CTR-NAND title.db
| NANDTDB
|-
| CTR-NAND tmp_i.db
| TEMPIDB
|-
| CTR-NAND tmp_t.db
| TEMPIDB
|-
| SD Card import.db
| TEMPTDB
|-
| SD Card title.db
| TEMPTDB
|}

== BDRI ==

This is a variant of [[Inner FAT|FAT filesystem]]. It consists one "root" directory and multiple "files". Each "file" is one title info entry described below.

== Title Info Entry ==

An entry contains information taken from both the application NCCH file(s) and TMD.

{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x0
| 8
| Title Size
|-
| 0x8
| 4
| Title Type(usually 0x40)
|-
| 0xC
| 4
| Title Version
|-
| 0x10
| 4
| Flags_0
|-
| 0x14
| 4
| TMD Content ID
|-
| 0x18
| 4
| CMD Content ID
|-
| 0x1c
| 4
| Flags_1
|-
| 0x20
| 4
| ExtdataID low (zero if title doesn't use Extdata)
|-
| 0x24
| 4
| Reserved
|-
| 0x28
| 8
| Flags_2
|-
| 0x30
| 0x10
| Product Code
|-
| 0x40
| 0x10
| Reserved
|-
| 0x50
| 0x4
| Unknown
|-
| 0x54
| 0x2c
| Reserved
|}

For ticket.db title info contains a small header and actual ticket data:
{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x0
| 4
| Unknown (always 0x00000001?)
|-
| 0x4
| 4
| Ticket data size X (=0x530)
|-
| 0x8
| X
| [[Ticket|Ticket]] data
|}

==== Flags_0 ====

{| class="wikitable"
|-
! Index
! Description
|-
| 0
| Electronic Manual
|-
| 1
| ?
|-
| 2
| ?
|-
| 3
| ?
|}

==== Flags_1 ====

{| class="wikitable"
|-
! Index
! Description
|-
| 0
| SD Save Data
|-
| 1
| ?
|-
| 2
| ?
|-
| 3
| ?
|}

==== Flags_2 ====

{| class="wikitable"
|-
! Index
! Description
|-
| 0
| DSiWare Related (Visibility on Home Menu/Export Flag?)
|-
| 1
| ?
|-
| 2
| ?
|-
| 3
| ?
|-
| 4
| Found with DSiWare Titles and titles with an 'Application' Title ID
|-
| 5
| DSiWare Related (Visibility on Home Menu/Export Flag?)
|-
| 6
| ?
|-
| 7
| ?
|}

'''NOTES:'''

It is important to note the database doesn't contain a hash of the [[Title Data Structure|.cmd]]. So if a user has more than one valid set of [[Title Data Structure|application data]] for a given .cmd Content ID they can be manually interchanged without issue. Though renaming a .cmd file to match the Content ID which the title.db is expecting will result in an error, as the CTR for the per-console encryption layer changes depending on the file path, and the MAC of the .cmd is probably generated with the .cmd Content ID in mind.

These NAND/SD /dbs images seem to be loaded by the ARM9 while NATIVE_FIRM is booting.

Removing ticket.db from a New-3DS with signature checks disabled will not result in an unbootable system, however all icons except Slot-1 will disappear from Home. Applets can however still be used. Recovery can be accomplished via [[Hardware|hardmod]] or [[arm9loaderhax]] plus a known good backup of the file (or the whole partition or disk); Gamecard exploits were not tested, and Browserhax did not work.

Inner FAT

2019-05-03T19:58:09Z

Wwylele: /* Filesystem Header */

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks (including pre header for title database)
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= number of file allocation table entries excluding the leading 0th entry. See below)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Extdata

2019-05-03T19:52:51Z

Wwylele: /* VSXE File System Metadata */ Migrate to Inner FAT

This page describes the format and encryption of extdata, "extra data" stored on SD card and NAND, at:

* <code>nand/data/<ID>/extdata/<ExtdataID-High></code>
* <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/<ExtdataID-High></code>

ExtdataID-High is always 00000000 for SD, and always 00048000 for NAND. Regular apps can only mount SD extdata using the same extdataID which is stored in the CXI exheader. Therefore, regular apps which have the exheader extdataID set to zero can't use extdata. This restriction doesn't apply for shared extdata with extdataID high bitmask 0x48000 stored on NAND. System apps with a certain access right can mount arbitrary extdata. All NAND extdata is shared extdata, while all SD extdata is normal extdata.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

= Format =

To avoid confusion, the terms '''device directory / file''' and '''virtual directory / file''' are used with the following meanings:

* '''Device directory / file''' are the real directory / file stored on SD / NAND that can be seen under path <code>nand/data/<ID>/extdata/</code> or <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/</code>.
* '''Virtual directory / file''' are directory / file stored inside extdata virtual file system, which can be seen by applications in the mounted extdata archives.

An extdata consists of several device directories and files, which forms a file system consisting of multiple virtual directories and files.

An extdata with ID <code>ExtdataId</code> has the following device files:

* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/Quota.dat</code> (optional)
* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/<SubDirID>/<SubFileID></code>

Note:

* All device files are [[DISA and DIFF|DIFF containers]]. '''All format description below is about the inner content of the containers'''. Please unwrap these files first according to the DIFF format description before reading them using the extdata format description below.
* <code>Quota.dat</code> is only observed existing for NAND shared extdata.
* <code><SubDirID></code> and <code><SubFileID></code> are 8-digit hex strings.
* Device file with <code>SubDirID = SubFileID = 00000000</code> doesn't exist. Other ID combinations can exists.
* Device file with <code>SubDirID = 00000000</code> and <code>SubFileID = 00000001</code> is the VSXE metadata file and must exist.
* Other files, besides <code>Quota.dat</code> and <code>00000000/00000001</code>, are normal sub files, are these device files one-to-one correspond to virtual files. They contain raw virtual file data in the DIFF inner content.
* <code>SubDirID = 00000000</code> is usually the only one device directory that can be seen. See [[#Device Directory Capacity]] for more information.

== Quota File ==

The inner data of <code>Quota.dat</code> is 0x48 bytes with the following format. The exact function of this file is unclear.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "QUOT"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 4
| 0x1000, block size?
|-
| 0x0C
| 4
| Always 126. Probably device directory capacity. See the [[#Device Directory Capacity]] more information.
|-
| ...
|

| The meaning of other fields is unknown
|}

== Device Directory Capacity ==

A device directory in an extdata (a <code><SubDirID></code> directory) seems to have a maximum number of device files it can contain. For SD extdata, this maximum number seems to be hard-coded as 126. For NAND extdata, the number is probably indicated by a field in Quota.dat, which is, again, always 126 as observed. 3DS FS tries to put all device files in the device directory <code>00000000</code> if possible, and only when more than 126 files needed to add, a second device directory <code>00000001</code> and so on are created. However, few extdata have such amount of files to store, so the behavior lacks of use cases to confirm.

The number 126 is probably from some kind of other capacity of 128 with <code>"."</code> and <code>".."</code> entries reserved. It is theorized that this is to keep a FAT directory table, with 0x20 bytes for each entry, in one 0x1000 cluster. The motivation is unclear.

== VSXE Filesystem ==

This is one variant of the [[Inner FAT|FAT filesystem]]. Please refer to its page for the description of the filesystem. In general, device file <code>00000000/00000001</code> contains the metadata of the filesystem, while other device files (except for the Quota file) contains normal sub-files

Each non-dummy file entry corresponds to a device file. The path to the device file is generated by the following computation:

<pre>// See previous section about this capacity
const uint32_t device_dir_capacity = 126;

// entry index is the index in the file entry table, with the first dummy entry as
// index = 0, which is never used for a real file.
// file_index = 1 is reserved for the VSXE Filesystem Metadata itself, so real files
// started from file_index = 2.
uint32_t file_index = entry_index + 1;

uint32_t SubDirID = file_index / device_dir_capacity;
uint32_t SubFileID = file_index % pdevice_dir_capacity;

char extdata_path[...]; // ".../extdata/<ExtdataID-High>/<ExtdataId-Low>"
char device_path[...]; // output path
sprintf(device_path, "%s/%08x/%08x", extdata_path, SubDirID, SubFileID);
</pre>
When mounting extdata, the unique identifier is used to match the ID stored in subfile's [[DISA and DIFF#DIFF header|DIFF header]]. If the ID doesn't match, mounting will fail.

== Virtual File System Structure ==

When extdata is created, these are ''always'' created regardless of whether the title actually uses them.

* <code>/icon</code> This virtual file contains the extdata icon displayed in data management. This icon can only be written to by titles when creating extdata, titles would have to recreate extdata to change the icon. This file can't be read directly, instead it is read via FS:ReadExtSaveDataIcon.
* <code>/user/</code> This virtual directory contains the title's actual extdata files.
* <code>/boss/</code> This virtual directory can contain SpotPass content. SpotPass content can only be downloaded to this <code>/boss</code> virtual directory.

User extdata and SpotPass extdata use separate mount points at <code>/user</code> and <code>/boss</code>. Therefore one mount can't access the other virtual directory, and also can't access <code>/icon</code>.(The title's SpotPass extdata can be mounted by the title itself, if it uses SpotPass)

Other optional but notable directories include:

* <code>/user/ExBanner</code> This virtual directory can optionally store extended banners. When this is available, this banner is displayed instead of the CXI ExeFS banner. <code>COMMON.bin</code> stores the common exbanner, while <code><regionlang_code>.bin</code> stores an optional separate region/language specific banner.(regionlang_code can be "JPN_JP", "USA_EN", etc)

== SD Extdata ==
Usually the ExtdataID low is in the format '00<Unique ID>'

{| class="wikitable" border="1"
|-
! JPN ExtdataID
! USA ExtdataID
! EUR ExtdataID
! Description
! Extdata images
|-
| 00000082
| 0000008f
| 00000098
| [[Home Menu]] extdata, this contains home-menu savedata and cached icons for applications.
|
|-
| 00000200
| 00000210
| 00000220
| [[System_Settings|System Settings]] extdata added with [[2.0.0-2]].
|
|-
| 00000207
| 00000217
| 00000227
| [[Mii Maker]], contains an ExBanner
| [https://dl.dropbox.com/u/20520664/extdata00000217.zip cleartext]
|-
| 00000208
| 00000218
| 00000228
| Streetpass Mii Plaza
| 11 mb big!
|-
| 00000209
| 00000219
| 00000229
| [[eShop]], contains store music in AAC format.
|
|-
| 0000020b
| 0000021b
| 0000022b
| Nintendo Zone
|
|-
| 0000020d
| 0000021d
| 0000022d
| Face Raiders, likely contains an ExBanner
|
|-
| 000002cc
| 000002cd
| 000002ce
| [[Home Menu]] theme
|
|-
| ?
| 000004aa
| 000004ab
| Nintendo Video Extra Data
This is where the video files are stored, and [[Nintendo_Video|includes]] the thumbnail, the description, and possibly some checksum info in each video file stored in the extdata images. There are always 9 files within the subdirectory "00000000" of this folder, even without any videos downloaded. The files are "00000001" - "00000009", and "00000003" - "00000008" have the same filesize of 50.7 MB. It is possible to restore the older videos by overwriting all the files within this directory. Provided of course you have made a backup of the files before hand, by copying all the files within this directory to your computer. As far I'm aware its not possible to mix and match the files in order to get certain videos in one grouping, ie. having all 3 Zelda orchestral recordings in one group of 4 Nintendo videos.
|
|-
|00000306
|00000308
|00000307
|Mario Kart 7
|
|-
| 0000030b
| 0000030d
| 0000030c
| Nintendogs + Cats
|
|-
| 00000326
| 00000326
| 00000326
| Pokédex 3D
|
|-
| 00000305
| 0000032d
| 0000033c
| Super Street Fighter IV 3D
|
|-
| 00000328
| 00000358
| 0000033b
| Ridge Racer 3D
|
|-
| ?
| 0000034d
| 00000402
| Samurai Warriors Chronicles
|
|-
| ?
| 0000034f
| 0000038a
| Dead or Alive Dimensions
|
|-
| 00000481
| N/A
| N/A
| Monster Hunter Tri G (Download-Quests)
|
|-
| ?
| 00000517
| 00000518
| Swapnote
|
|-
| 0000055d
| 0000055d
| 0000055d
| Pokémon X Pokémon Y
|
|-
| ?
| 00000725
| 00000724
| Ambassador Certificate
|
|-
| ?
| ?
| 000007af
| New Super Mario Bros. 2
|
|-
| ?
| 00000863
| 00000864
| Animal Crossing: New Leaf
|
|-
| ?
| 00000a85
| 00000a86
| Professor Layton and the Miracle Mask Professor Layton and the Azran Legacy
German Version ExtdataID is 00000a87
|
|-
| ?
| ?
| 00000b4f
| Fullblox / Crashmo
|
|-
| ?
| ?
| 00000ba9
| Pokémon Mystery Dungeon: Gates to Infinity
|
|-
| ?
| ?
| 00000c24
| Denpa men
|
|-
| 00000c73
| 00000c73
| 00000c73
| Save Data Transfer Tool
|
|-
| ?
| ?
| 00000d9a
| Donkey Kong Country™ Returns 3D: Trailer
|
|-
| ?
| ?
| 00000ea6
| Etrian Odyssey IV
|
|-
| ?
| 00000edf
| 00000ee0
| Super Smash Bros. for Nintendo 3DS
|
|-
| ?
| 00000f14
| 00000f1e
| Phoenix Wright: Ace Attorney - Dual Destinies
|
|-
| ?
| 00001007
| 00001005
| Professor Layton vs Phoenix Wright: Ace Attorney
|
|-
| ?
| ?
| 00001062
| Nintendo Pocket Football Club
|
|-
| ?
| ?
| 0000111c
| Yoshi's New Island
|
|-
| ?
| ?
| 00001131
| Fantasy Life
|
|-
| 000011c5
| 000011c5
| 000011c5
| Pokémon Omega Ruby Pokémon Alpha Sapphire
|
|-
| ?
| ?
| 000012ca
| Mario vs. Donkey Kong: Tipping Stars
|
|-
| ?
| ?
| 00001499
| Korg DSN-12
|
|-
| ?
| ?
| 000014f2
| Animal Crossing: Happy Home Designer
|
|-
| 000014d1
| 000014d1
| 000014d1
| [[Home Menu]] badge
|
|-
| ?
| ?
| 00001632
| Fullblox / Stretchmo
|
|-
| ?
| ?
| 00001646
| Pokémon Rumble World
|
|-
| 00001648
| 00001648
| 00001648
| Pokémon Sun Pokémon Moon
|
|-
| 0000165c
| 0000165c
| 0000165c
| [[Home Menu]] saved theme layouts
|
|-
| ?
| ?
| 00001678
| Yo-kai Watch
|
|-
| ?
| ?
| 000018fa
| Phoenix Wright: Ace Attorney - Spirit of Justice
|
|-
| ?
| ?
| 0000198f
| Animal Crossing: New Leaf - Welcome amiibo
|
|-
| ?
| ?
| 00001a05
| Super Mario Maker
|
|-
| ?
| ?
| 00001a2e
| Swapdoodle
|
|}

== NAND Shared Extdata ==
{| class="wikitable" border="1"
|-
! ExtdataID
! Description
|-
| 0xe0000000
| Home Menu attempts to open this archive during boot, if [[FS:OpenArchive]] doesn't return an error Home Menu seems to then launch the [[System Transfer]] application. Home Menu doesn't actually use this archive at all except for checking whether it exists.
|-
| 0xf0000001
| NAND JPEG/MPO files and phtcache.bin from the camera application are stored here. This also contains UploadData.dat.
|-
| 0xf0000002
| NAND M4A files from the sound application are stored here
|-
| 0xf0000009
| Used for [[BOSS_Services|SpotPass]] content storage for [[News_Services|notifications]].
|-
| 0xf000000b
| Contains idb.dat, idbt.dat, gamecoin.dat, ubll.lst, CFL_DB.dat, and CFL_OldDB.dat. These files contain cleartext [[Mii_Maker|Miis]] and some data relating (including cached ICN data) to Play/Usage Records.
|-
| 0xf000000c
| Contains bashotorya.dat and bashotorya2.dat.
|-
| 0xf000000d
| Home Menu SpotPass content data [[BOSS_Services|storage]].
|-
| 0xf000000e
| Contains [[VersionList|versionlist.dat]], used by Home Menu for the software update notification added with [[7.0.0-13]].
|}

==== Shared Extdata 0xf000000b gamecoin.dat ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Magic number: 0x4F00
|-
| 0x4
| 0x2
| Total Play Coins
|-
| 0x6
| 0x2
| Total Play Coins obtained on the date stored below. When the below date does not match the current date, this field is reset to zero, then the date(and other fields) are updated. Once this value is >=10, no more Play Coins can be obtained until the current date changes.
|-
| 0x8
| 0x4
| Total step [[PTM:GetTotalStepCount|count]] at the time a new Play Coin was obtained.
|-
| 0xC
| 0x4
| Step count for the day the last Play Coin was obtained, for that day's step count(same as the step count displayed by home-menu when this file was updated).
|-
| 0x10
| 0x2
| Year
|-
| 0x12
| 0x1
| Month
|-
| 0x13
| 0x1
| Day
|}

The above date stores the last time new Play Coin(s) were obtained. The contents of this file is updated by home-menu. [[PTM:GetTotalStepCount]] is not checked constantly, after home-menu boot this is only checked when waking from sleep-mode. Each time home-menu updates the contents of this file, home-menu will set the Play Coin total to 300 if it's higher than the 300 Play Coin limit.

[[Home Menu]] loads this file / opens this archive during [[Home Menu|startup]]. When accessing this file fails, like when the file/archive is corrupted(or at least on older system-versions), the result is a brick due to Home Menu using [[SVC|svcBreak]]. [[User:Yellows8|Yellows8]] bricked a 3DS this way due to corruption via invalid [[FSFile:Write]] flush flags. When opening this extdata archive(0xf000000b) fails, Home Menu executes svcBreak.

==== Shared Extdata 0xf000000b ubll.lst ====
List of blocked users.

Empty space is filled with 0xC-long sequences of 00 00 ... 07

=== Tools ===

* [https://github.com/wwylele/3ds-save-tool 3ds-save-tool] - Extract/verifies extdata

Savegames

2019-05-03T19:48:21Z

Wwylele: Migrate file system doc

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]]. Inside the DISA container, it forms a [[Inner FAT|FAT filesystem]]. '''Please refer to these pages for how to fully extract save files'''. This page only describes additional encryption wear leveling on top of the DISA container. These layers only apply to gamecard save games. SD savegames and NAND savegames are DISA containers in plaintext after decrypting the common SD/NAND encryption layer.

== Gamecard savegame Encryption ==

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== Savegame keyY ===

All gamecard and SD savegames are encrypted with AES-CTR. The base CTR for gamecard savegames is all-zero. The gamecard savegame [[AES|keyslots]]' keyY(these savegame keyslots use the hardware key-generator) is unique for each region and for each game. The [[NCSD]] partition flags determine the method used to generate this keyY. When the save [[NCSD]] flags checked by the running NATIVE_FIRM are all-zero, the system will use the repeating CTR, otherwise a proper CTR which never repeats within the image is used.

The [[AES]]-CMAC (which uses a hardware key-generator keyslot, as mentioned above) at the the beginning of the savegame must match the calculated CMAC using the DISA/DIFF data, otherwise the savegame is considered corrupted(see below).

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY(original keyY method used with saves where the CTR repeats within the image) is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== [[2.0.0-2]] Hashed keyY and [[2.2.0-4]] Savegame Encryption ====

When certain [[NCSD]] partition flags are set, a SHA-256 hash is calculated over the data from the CXI(same data used with the original plain keyY), and the 0x40-bytes read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID). The first 0x10-bytes from this hash is used for the keyY. When flag[7] is set, the CTR will never repeat within the save image, unlike the original CTR-method. All games which had the retail NCSD image finalized after the [[2.2.0-4]] update(and contain [[2.2.0-4]]+ in the [[System Update CFA|System update partition]]), use this encryption method.

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== [[6.0.0-11]] Savegame keyY ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

A SHA-256 hash is calculated over the same data used with the above hashed keyY method, after hashing the above data the following data is hashed: the CXI programID, and the ExeFS:/.code hash from the decrypted [[ExeFS]] header. An [[AES]]-CMAC (the keyslot used for this uses the hardware key-scrambler) is then calculated over this hash, the output CMAC is used for the savegame keyY.

The keyY used for calculating this AES-CMAC is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

First, there are 8 bytes whose purposes are currently unknown. Then comes the actual blockmap.
The blockmap structure is simple:
<pre>
struct header_entry {
uint8_t phys_sec; // when bit7 is set, block has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));
</pre>

There's one entry per sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

The 2 bytes that follow the blockmap are the CRC16 (with starting value 0xFFFF (like modbus)) of the first 8 bytes and the blockmap.

Then comes the journal.
The journal structure is as follows:
<pre>
struct sector_entry {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8];
} __attribute__((__packed__));

struct long_sector_entry{
struct sector_entry sector;
struct sector_entry dupe;
uint32_t magic;
}__attribute__((__packed__));
</pre>

With magic being a constant 0x080d6ce0.

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (with starting value 0xFFFF) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard.
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.
* [https://github.com/wwylele/3dsfuse-ex 3dsfuse-ex] similar to 3dsfuse, but supports savegame inner FS, proper DPFS handling, and automatic CMAC update. Still WIP.

[[セーブデータ|Japanese]]

Inner FAT

2019-05-03T19:39:59Z

Wwylele:

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all relative to the beginning of the header, while all "starting block index" are relative to the beginning of data region. This is especially important for title database, as the offsets doesn't count the pre header.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= number of file allocation table entries excluding the leading 0th entry. See below)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

* For savegames, the file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* For extdata, the maximum file/directory count are specified by the parameters of [[FS:CreateExtSaveData]]. The bucket count is likely calculated by the system.
* Directory & file entry tables are allocated in the data region as if they are two normal files (except for savegame <code>duplicate data = false</code> layout). However, only continuous allocation has been observed, so directly reading block_count * block_size bytes from data_region + starting_block_index * block_size should be safe.

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier. See [[Extdata]]
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Inner FAT

2019-05-03T19:27:52Z

Wwylele: Merge hash table here

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all related to the beginning of the header. This is especially important for title database, as the offsets doesn't count the pre header there.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= number of file allocation table entries excluding the leading 0th entry. See below)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== Directory Hash Table & File Hash Table ==

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the ASCII name (or title ID for title database) as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16 or 8], // For savegame/extdata, this takes all 16 bytes including trailing zeros; For title database, this is the 8-byte title ID
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4 or 2; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Inner FAT

2019-05-03T19:21:22Z

Wwylele: Merge file entry table here

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all related to the beginning of the header. This is especially important for title database, as the offsets doesn't count the pre header there.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= number of file allocation table entries excluding the leading 0th entry. See below)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type, and a dummy entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Entry Table ==

The file entry table is an array of the entry type shown below. It contains information for each file. There are three variants of the file entry type, and a dummy entry type.

=== Savegame Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Extdata Variant ===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| Always 0x80000000
|-
| 0x20
| 8
| Unique identifier
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Title database Variant ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 8
| Title ID
|-
| 0x0C
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x10
| 4
| Padding
|-
| 0x14
| 4
| First block index in data region.
|-
| 0x18
| 8
| File size
|-
| 0x20
| 8
| Padding?
|-
| 0x28
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

=== Dummy Entry ===
Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36/32
| Padding / All zero
|-
| 0x2C/0x28
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Inner FAT

2019-05-03T19:11:44Z

Wwylele: Merge directory entry table here

This page describes a common FAT-like file system used in [[Savegames]], [[Extdata]] and [[Title Database]]. This file system format has several variants depending on which kind of data it stores. All the three kinds of data that use this file system structure also happen to use the [[DISA and DIFF]] container as well, but there is no direct relationship between the file system and the DISA/DIFF container. All data formats described here is in the inner data of the DISA/DIFF container (i.e. IVFC level 4). Please refer to the DISA/DIFF page for how to unwrap it first before trying to extract the file system.

== Overview ==

The file system consists of the following components:
* header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

The file allocation table (FAT) forms several linked lists inside, each of which represents a "file" allocated in the data region. Please refer to the File Allocation Table section below for more detail. In some variants, the directory entry table and the file entry table are also allocated as two special "files" in the data region, managed by the FAT, while in others they are stand-alone tables located outside the data region.

== Layout Variants ==
Four variants of the file system layout has been identified. A summary diagram can be found here: [https://github.com/wwylele/3ds-save-tool/raw/master/inner-fat.png]

=== Savegame, <code>duplicate data = true</code> ===

Such savegame is a single DISA container that only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA]] format for details). All components are stored in this partition as

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Savegame, <code>duplicate data = false</code> ===
Such savegame is a single DISA container that has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** filesystem header at the beginning.
** directory hash table
** file hash table
** (stand-alone) file allocation table
** (stand-alone) directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== Extdata ===
An extdata consists of several DIFF containers (device files), among which the special device file <code>00000000/00000001</code> contains the inner FAT system, while other devices contains normal subfiles of the extdata. Please refer to [[Extdata]] for detail. The special file <code>00000000/00000001</code> contists of the following components

* filesystem header at the beginning
* directory hash table
* file hash table
* file allocation table (degenerate, because the data region only has two "files": the directory entry table and the file entry table)
* data region
** directory entry table allocated inside data region
** file entry table as well
** normal subfiles are NOT in the data region. They are in their DIFF containers instead.

=== Title database ===
All [[Title Database]] files are DIFF containers. Except for <code>certs.db</code>, all of them uses this filesystem in the DIFF inner data, which consists of

* database-specific pre-header at the beginning (See [[Title Database]])
* filesystem header
* directory Hash Table (degenerate and always has only one bucket, as there is only one directory for "root")
* file Hash Table
* file allocation table
* data region
** directory entry table allocated inside data region (degenerate, as there is only one directory for "root")
** file entry table as well
** title entries (title info or ticket) are allocated as normal files in the data region as well.

== Filesystem Header ==
Offsets listed in the table below are all related to the beginning of the header. This is especially important for title database, as the offsets doesn't count the pre header there.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic ("SAVE" for savegame; "BDRI" for title database; "VSXE" for extdata)
|-
| 0x04
| 4
| Version (0x40000 for savegame; 0x30000 for title database and extdata)
|-
| 0x08
| 8
| Filesystem Information offset (Y, =0x20 for savegame and title database, =0x138 for extdata)
|-
| 0x10
| 8
| Filesystem image size in blocks
|-
| 0x18
| 4
| Filesystem Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 0x118 in total
| Below is additional data for extdata. Not present in savegame or title database
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
| Y
| 0x68 in total
| Below is Filesystem Information
|-
| Y + 0x00
| 4
| Unknown
|-
| Y + 0x04
| 4
| Data region block size
|-
| Y + 0x08
| 8
| Directory hash table offset
|-
| Y + 0x10
| 4
| Directory hash table bucket count (=1 for title database)
|-
| Y + 0x14
| 4
| Padding
|-
| Y + 0x18
| 8
| File hash table offset
|-
| Y + 0x20
| 4
| File hash table bucket count
|-
| Y + 0x24
| 4
| Padding
|-
| Y + 0x28
| 8
| File allocation table offset
|-
| Y + 0x30
| 4
| File allocation table entry count
|-
| Y + 0x34
| 4
| Padding
|-
| Y + 0x38
| 8
| Data region offset
(0 for savegame <code>duplicate data = false</code> layout, as the data region is in partition B for that layout)
|-
| Y + 0x40
| 4
| Data region block count
(= number of file allocation table entries excluding the leading 0th entry. See below)
|-
| Y + 0x44
| 4
| Padding
|-
| Y + 0x48
| 8
| for savegame <code>duplicate data = false</code> layout: directory entry table offset;
otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| Y + 0x50
| 4
| Maximum directory count, excluding the mandatory "root" directory
(=1 for title database, but that 1 free directory slot is never used)
|-
| Y + 0x54
| 4
| Padding
|-
| Y + 0x58
| 8
| for savegame <code>duplicate data = false</code> layout: file entry table offset;
otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| Y + 0x60
| 4
| Maximum file count
|-
| Y + 0x64
| 4
| Padding
|}

== Directory Entry Table ==

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system. There are two variants of the directory entry type.

=== Savegame/Extdata Variant===
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

=== Title Database Variant===
Because title database only has one directory for "root", its directory entry table degenerates into many zeros whose structure is not recognizable. The size of one entry here is guessed.
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index = 0 for root
|-
| 0x04
| 4
| Next sibling directory index = 0 because this is the last one
|-
| 0x08
| 4
| First subdirectory index = 0 because there is no subdirectory
|-
| 0x0C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x10
| 12
| Padding / zero?
|-
| 0x1C
| 4
| Index of the next directory in the same hash table bucket = 0 because there is no other directory
|}

=== Dummy Entry===
There are also some dummy entries in the array
{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28/20
| Padding / All zero
|-
| 0x24/0x1C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

== File Allocation Table ==

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the filesystem header. Each entry corresponds to a block in the data region (the block size is defined in filesystem header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

For extdata, because only two "files" (directory and file entry tables) are allocated in the data region, and their size never changes once the extdata is created, they are guaranteed continuous in the data region, and the FAT degenerates to two big nodes. Therefore, instead of going through FAT, the offset and size of directory / file entry table can be found directly by offset = entry_table_starting block * data_region_block_size + data_region_offset and size = entry_table_block_count * data_region_block_size.

Inner FAT

2019-05-03T18:58:32Z

Wwylele: Merge header info for savegame/extdata/database here

Inner FAT

2019-05-03T18:30:30Z

Wwylele: Copy FAT info from savegame

Inner FAT

2019-05-03T18:24:04Z

Wwylele: Layout Variants

Inner FAT

2019-05-03T18:00:59Z

Wwylele: Start a new page to unify the filesystem doc of save/extdata/database

NCCH

2019-05-01T16:01:07Z

Wwylele: /* Encryption */ Just document the encryption stuff here instead of external link

[[Category:File formats]]
The following text tries to document the structure of the NCCH (Nintendo Content Container Header) container format. This format is used to store the content of any installed [[Titles|title]].

== Overview ==
There are two known NCCH container specializations used on the 3DS, "executable" and "non-executable", officially known as CXI and CFA, respectively.

=== CXI ===

The CXI (CTR Executable Image) specialization of the NCCH container contains executable code, which runs on a single ARM11 core.

The CXI format is structured in the following order:
* first a NCCH header,
* followed by an [[NCCH/Extended Header|extended header]],
* followed by an access descriptor,
* followed by an '''optional''' plain binary region,
* followed by an '''optional''' executable filesystem ([[ExeFS]]) - (contains ARM11 code, Home menu [[SMDH|icn]]/bnr and [[Logo|logo]]),
* and finally followed by an '''optional''' read-only filesystem ([[RomFS]]) - (Used for external file storage).

The extended header contains additional information regarding access control.
The plain binary region is an area specifically stored in plaintext, mostly containing SDK library strings for identification.

=== CFA ===

The CFA (CTR File Archive) specialization of the NCCH container is not executable, but is used in conjunction with CXI files, e.g. the DLP Child Container and the Electronic Manual. (There is a system update NCCH which follows this format, but is used by the 3DS rather than the Application NCCH, and only works when embedded in the [[CCI]] format because the nVer is kept in the header of retail [[CCI]] files instead of the application NCCH). There are CFA files which exist alone in a title, but these are just [[Title list|System Data Archive]] titles and are found only in the [[Flash Filesystem#CTR partition|NAND]].

CFA files are structured in the following order:
* first a NCCH header,
* followed by an '''optional''' executable filesystem ([[ExeFS]]) (same as in CXI, except no ARM11 code)
* followed by an '''optional''' read-only filesystem ([[RomFS]])

== Container File Format ==

=== Encryption ===
The [[NCCH/Extended Header|extended header]], the [[ExeFS]], and the [[RomFS]] are encrypted using [https://github.com/3dshax/ctr/blob/master/ctrtool/ncch.c 128-bit AES CTR] unless the NoCrypto flag is set in ncchflag[7]. There are different sets of encryption parameters in use, as over the time new system updates introduced more sophisticated means of encryption.

All encrypted regions are grouped into two categories, each of which uses one kind of encryption scheme:

* The "menu info" group, including the [[NCCH/Extended Header|extended header]], the [[ExeFS]] header, and the files "icon" and "banner" in [[ExeFS]], which are needed to display the game on the menu regardless whether system version supports the game, or whether the pre-downloaded eshop game is officially released.

* The "content" group, including the rest files (".code" and ".firm") in [[ExeFS]], and the entire [[RomFS]], which is needed for actually running the game, and which can be only decrypted on the supported system (and when the seed is officially released for eshop games).

The decryption key is generated using the [[AES|AES Engine]]. The keyX and keyY for each group are set as follows:

* The "menu info" group uses the primary key, always generated by keyX in the slot 0x2C (set by bootrom) and keyY from the first 0x10 bytes of the NCCH signature.

* The "content" group uses the secondary key. The slot selection for keyX depends on ncchflag[3], as listed in the table below.
{| class="wikitable" border="1"
|-
! ncchflag[3]
! FW Introduced
! Old3DS
! [[AES#Keyslot|AES Keyslots]]
! Notes
|-
| 0x00
| The initial version
| style="background: #ccffbb" | Yes
| 0x2C
| This keyslot is initialized by bootrom. This is the same key as the primary key.
|-
| 0x01
| [[7.0.0-13|7.0.0-X]]
| style="background: #ccffbb" | Yes
| 0x25
| This keyslot is [[Savegames|initialized]] by the 6.0 gamecard savegame keyY init function during boot, using a different portion of the [[Savegames|final]] hash (this keyslot is separate from the one used for the 6.0 save crypto).
|-
| 0x0A
| [[9.3.0-21|9.3.0-X]]
| style="background: #ffccbb" | No
| 0x18
| This keyslot is initialized by [[FIRM#New_3DS_FIRM|arm9loader]] on New3DS starting with [[8.1.0-0_New3DS]], but only [[9.3.0-21|9.3.0-X]] and later know how to use it with ncchflag[3].
|-
| 0x0B
| [[9.6.0-24|9.6.0-X]]
| style="background: #ffccbb" | No
| 0x1B
| [[9.6.0-24|9.6.0-X]]'s [[FIRM#New_3DS_FIRM|arm9loader]] changed the contents of keyslots 0x19-0x1F; 9.6.0-X was the first time they were officially used, so this is not a breaking change (there is no content that would use the old versions of those keys).
|}

Besides all rules above, if ncchflag[7] bitmask 0x1 is set, and a fixed AES key instead is used for both groups. There are two fixed keys, one for titles which have the system category bit set (SystemFixedKey), and one for the rest ("zeros" key). These are debug keys, as they aren't nomally supported on retail systems.

The initial CTR for decryption each region is generated from the partition ID, as described below:

* if the version field (NCCH header + 0x112) is 0 or 2, the 16-byte CTR is [partition_id[7], partition_id[6], ..., partition_id[0], M, 0, ..., 0], where
** The 8-byte partition ID starts from the beginning in the reverse order. If the partition ID is viewed as a little-endian u64, and the CTR is viewed as big-endian u128, then this is to put the partition ID to the most significant bits of the CTR
** CTR[8] is set to a magic number M. For [[NCCH/Extended Header|extended header]], M = 1. For [[ExeFS]], M = 2. For [[RomFS]], M = 3.
** The rest 7 bytes (the least significant bits of big-endian CTR) are set to zero

* if the version field is 1, the 16-byte CTR is [partition_id[0], partition_id[1], ...,partition_id[7], 0, 0, 0, 0, T[0], T[1], T[2], T[3]], where
** The 8-byte partition ID starts from the beginning in the same order.
** Then four zeros follow.
** Then a number T in big-endian follows. This number is the offset of each encrypted region to the NCCH beginning. So for [[NCCH/Extended Header|extended header]], T = 0x200. For [[ExeFS]]/[[RomFS]]. T = 0x200 * ExeFS/RomFS offset in media units

Note that due to the key generation schemes described above, ExeFS can contain regions using different keys. Regardless of this, both regions shared the same initial CTR at the beginning of ExeFS. If one region doesn't start at the beginning of ExeFS, its actual CTR at its own beginning = ExeFS CTR + (region offset / AESBlockSize=16)

=== Format ===

Currently, only [[ExeFS]]:/.code can be compressed (with a LZ77 variant). A flag in the [[NCCH/Extended Header#System Info|exheader]] determines if this is the case.

On retail for SD applications, exheader_systeminfoflags.flag bit1 must be set.

Retail CFAs use the default NCCH product code "CTR-P-CTAP", while retail title/gamecard CXIs use NCCH product code "CTR-X-XXXX". This product code is the NCCH [[Serials|serial code]]. The region-locking info checked by home menu is stored in the [[SMDH#BNR Region|icon]].

All of the hashes stored in this NCCH header are over the cleartext data. The ExeFS/RomFS superblock starts at offset 0x0 in the ExeFS/RomFS, and the size is specified by the hash region fields. Nintendo's NCCH validation code seems to have the size of this region fixed to 0x200 bytes (for ExeFS at least).

As of [[5.0.0-11]] the application [[ExeFS]]:/logo can be loaded from the plaintext region between the access descriptor and the plain region, all applications built since [[5.0.0-11]] store the logo here. The size of this logo is always 0x2000-bytes.

The plain region mainly contains tags for each SDK library used when building the CXI. The version used for the "FIRMWARE" tag is the kernel/FIRM [[Configuration_Memory|version]], this version can also be stored in the exheader "kernel release version" ARM11 kernel descriptor field. As of [[2.2.0-X]] the NATIVE_FIRM kernels check the CXI exheader "kernel release version" field, if it is stored in the CXI exheader. If the kernel/FIRM version specified by this field is higher than the version of the running NATIVE_FIRM, the kernel will return error-code 0xD9001413.

=== NCCH Header ===
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x000
| 0x100
| RSA-2048 signature of the NCCH header, using SHA-256.
|-
| 0x100
| 4
| Magic ID, always 'NCCH'
|-
| 0x104
| 4
| Content size, in media units (1 media unit = 0x200 bytes)
|-
| 0x108
| 8
| Partition ID
|-
| 0x110
| 2
| Maker code
|-
| 0x112
| 2
| Version
|-
| 0x114
| 4
| When ncchflag[7] = 0x20 starting with FIRM [[9.6.0-24|9.6.0-X]], this is compared with the first output u32 from a SHA256 hash. The data used for that hash is 0x18-bytes: <0x10-long title-unique content lock seed> <programID from NCCH+0x118>. This hash is only used for verification of the content lock seed, and is not the actual keyY.
|-
| 0x118
| 8
| Program ID
|-
| 0x120
| 0x10
| Reserved
|-
| 0x130
| 0x20
| Logo Region SHA-256 hash. (For applications built with SDK 5+) (Supported from firmware: [[5.0.0-11]])
|-
| 0x150
| 0x10
| Product code
|-
| 0x160
| 0x20
| Extended header SHA-256 hash (SHA256 of 2x Alignment Size, beginning at 0x0 of ExHeader)
|-
| 0x180
| 4
| Extended header size, in bytes
|-
| 0x184
| 4
| Reserved
|-
| 0x188
| 8
| Flags (See Below)
|-
| 0x190
| 4
| Plain region offset, in media units
|-
| 0x194
| 4
| Plain region size, in media units
|-
| 0x198
| 4
| Logo Region offset, in media units (For applications built with SDK 5+) (Supported from firmware: [[5.0.0-11]])
|-
| 0x19c
| 4
| Logo Region size, in media units (For applications built with SDK 5+) (Supported from firmware: [[5.0.0-11]])
|-
| 0x1A0
| 4
| ExeFS offset, in media units
|-
| 0x1A4
| 4
| ExeFS size, in media units
|-
| 0x1A8
| 4
| ExeFS hash region size, in media units
|-
| 0x1AC
| 4
| Reserved
|-
| 0x1B0
| 4
| RomFS offset, in media units
|-
| 0x1B4
| 4
| RomFS size, in media units
|-
| 0x1B8
| 4
| RomFS hash region size, in media units
|-
| 0x1BC
| 4
| Reserved
|-
| 0x1C0
| 0x20
| ExeFS superblock SHA-256 hash - (SHA-256 hash, starting at 0x0 of the ExeFS over the number of media units specified in the ExeFS hash region size)
|-
| 0x1E0
| 0x20
| RomFS superblock SHA-256 hash - (SHA-256 hash, starting at 0x0 of the RomFS over the number of media units specified in the RomFS hash region size)
|}

Given offsets are based on the start of the file.

=== NCCH Flags ===
{| class="wikitable" border="1"
|-
! INDEX
! DESCRIPTION
|-
| 3
| Crypto Method: When this is non-zero, a NCCH crypto method using two keyslots is used(see above).
|-
| 4
| Content Platform: 1 = CTR, 2 = snake (New 3DS).
|-
| 5
| Content Type Bit-masks: Data = 0x1, Executable = 0x2, SystemUpdate = 0x4, Manual = 0x8, Child = (0x4<nowiki>|</nowiki>0x8), Trial = 0x10. When 'Data' is set, but not 'Executable', NCCH is a CFA. Otherwise when 'Executable' is set, NCCH is a CXI.
|-
| 6
| Content Unit Size i.e. u32 ContentUnitSize = 0x200*2^flags[6];
|-
| 7
| Bit-masks: FixedCryptoKey = 0x1, NoMountRomFs = 0x2, NoCrypto = 0x4, using a new keyY generator = 0x20(starting with FIRM [[9.6.0-24|9.6.0-X]]).
|}
CXIs NCCH header signature is verified using the RSA public key stored in the accessdesc,(which follows the exheader) while CFAs NCCH header is verified with a fixed RSA public key.

==== NCCH header example for Lego Starwars III ====
Signature: 720FF8F83F2A1E998322A026D1434165
ED19642ABC1CB2722135AA202BEAD60A
80BCD21C768C597B8268FEF2C64EA710
4C9BA5E12CFFBD1D0C619F4EF7B42CA7
DD8482CB4EB26720AD66CDA57ABCBCFB
D63268A6E2896A59B3B744E39E45B88A
ABB4C0980ACC6210818DCE6DAC838A10
95D0F66B352474D4B3DA4B333F49912D
29AF7EA58BC8C890B18C70B7D540A9FB
EBE24A5312055617D3353B28C3EB1D17
61021BEFF6AD22C384835B40BD44DFAD
981F6350F9458B17BCB5F768C92ABC93
2BCE9888855A8998F4CDE40C9543514A
C57B84EB75A680E7C742632614620D1D
A253284DF3DC01091EB3800C36FD62EE
BA15340F1FD498FAB67C0302E9CDA397
Magic: NCCH
Content size: 0x1cfef400
Partition id: 0004000000038c00
Maker code: 3436 ("46")
Version: 0002
Program id: 0004000000038c00
Temp flag: 00
Product code: CTR-P-ALGP
Extended header hash: 0C27E3C1DE7B2AE2D3114F32A4EEBF46
9AFD0CF352C11D4984C2A9F1D2144C63
Extended header size: 00000400
Flags: 0000030100000000
Plain region offset: 0x00004a00
Plain region size: 0x00000200
ExeFS offset: 0x00004c00
ExeFS size: 0x00143800
ExeFS hash region size: 0x00000200
RomFS offset: 0x00148400
RomFS size: 0x1ceab000
RomFS hash region size: 0x00000200
ExeFS Superblock Hash: 130C042615F647C4C63225EA9E67F8A2
7B15246B88FBC7A927257B84977B787B
RomFS Superblock Hash: A65BEE1060BB6A6821BBCEC600035B7E
64FB6EACA7F0960CFB1F5A37087728F7
Note: Offsets and sizes in media units have been converted to byte sizes.

==== Plain region example for Lego Starwars III ====
0004a00: 5b 53 44 4b 2b 4e 49 4e 54 45 4e 44 4f 3a 43 54 [SDK+NINTENDO:CT [SDK+NINTENDO:CTR_SDK-0_14_23_200_none]
0004a10: 52 5f 53 44 4b 2d 30 5f 31 34 5f 32 33 5f 32 30 R_SDK-0_14_23_20
0004a20: 30 5f 6e 6f 6e 65 5d 00 5b 53 44 4b 2b 4e 49 4e 0_none].[SDK+NIN [SDK+NINTENDO:Firmware-02_27]
0004a30: 54 45 4e 44 4f 3a 46 69 72 6d 77 61 72 65 2d 30 TENDO:Firmware-0
0004a40: 32 5f 32 37 5d 00 5b 53 44 4b 2b 4d 6f 62 69 63 2_27].[SDK+Mobic [SDK+Mobiclip:Deblocker_1_0_2]
0004a50: 6c 69 70 3a 44 65 62 6c 6f 63 6b 65 72 5f 31 5f lip:Deblocker_1_
0004a60: 30 5f 32 5d 00 5b 53 44 4b 2b 4d 6f 62 69 63 6c 0_2].[SDK+Mobicl [SDK+Mobiclip:ImaAdpcmDec_1_0_0]
0004a70: 69 70 3a 49 6d 61 41 64 70 63 6d 44 65 63 5f 31 ip:ImaAdpcmDec_1
0004a80: 5f 30 5f 30 5d 00 5b 53 44 4b 2b 4d 6f 62 69 63 _0_0].[SDK+Mobic [SDK+Mobiclip:MobiclipDec_1_0_1]
0004a90: 6c 69 70 3a 4d 6f 62 69 63 6c 69 70 44 65 63 5f lip:MobiclipDec_
0004aa0: 31 5f 30 5f 31 5d 00 5b 53 44 4b 2b 4d 6f 62 69 1_0_1].[SDK+Mobi [SDK+Mobiclip:MoflexDemuxer_1_0_2]
0004ab0: 63 6c 69 70 3a 4d 6f 66 6c 65 78 44 65 6d 75 78 clip:MoflexDemux
0004ac0: 65 72 5f 31 5f 30 5f 32 5d 00 00 00 00 00 00 00 er_1_0_2].......
0004ad0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
0004ae0: 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................

==== Example dependency list from the extended header ====
00850 41 50 54 3A 55 00 00 00 24 68 69 6F 46 49 4F 00 APT:U...$hioFIO.
00860 24 68 6F 73 74 69 6F 30 24 68 6F 73 74 69 6F 31 $hostio0$hostio1
00870 61 63 3A 75 00 00 00 00 62 6F 73 73 3A 55 00 00 ac:u....boss:U..
00880 63 61 6D 3A 75 00 00 00 63 65 63 64 3A 75 00 00 cam:u...cecd:u..
00890 63 66 67 3A 75 00 00 00 64 6C 70 3A 46 4B 43 4C cfg:u...dlp:FKCL
008A0 64 6C 70 3A 53 52 56 52 64 73 70 3A 3A 44 53 50 dlp:SRVRdsp::DSP
008B0 66 72 64 3A 75 00 00 00 66 73 3A 55 53 45 52 00 frd:u...fs:USER.
008C0 67 73 70 3A 3A 47 70 75 68 69 64 3A 55 53 45 52 gsp::Gpuhid:USER
008D0 68 74 74 70 3A 43 00 00 6D 69 63 3A 75 00 00 00 http:C..mic:u...
008E0 6E 64 6D 3A 75 00 00 00 6E 65 77 73 3A 75 00 00 ndm:u...<nowiki>news:u..</nowiki>
008F0 6E 77 6D 3A 3A 55 44 53 70 74 6D 3A 75 00 00 00 nwm::UDSptm:u...
00900 70 78 69 3A 64 65 76 00 73 6F 63 3A 55 00 00 00 pxi:dev.soc:U...
00910 73 73 6C 3A 43 00 00 00 79 32 72 3A 75 00 00 00 ssl:C...y2r:u...
00920 69 72 3A 55 53 45 52 00 6C 64 72 3A 72 6F 00 00 ir:USER.ldr:ro..
00930 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00940 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00950 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
00960 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
... ...
009D0 FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF FF
009E0 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 ................
009F0 00 03 00 00 00 00 00 00 00 00 00 00 00 00 00 02 . .............

== Tools ==

[https://github.com/profi200/Project_CTR/tree/master/ctrtool ctrtool] - (CMD)(Windows/Linux) Parsing and decrypting (debug only) NCCH files

ARM11 Interrupts

2019-04-29T00:13:57Z

Wwylele: /* Hardware Interrupts */

== Interrupts ==

Interrupt priority is 0-0xF. A priority of 0xF means that the interrupt is disabled.

= Private Interrupts =

Each CPU core has 32 software interrupts that are private and belong to that core. These interrupts are numbers 0-0x1F for each core. The hardware interrupts are not core-specific and start at interrupt ID 0x20.

{| class="wikitable" border="1"
! IRQ
! Listener
! Description
|-
| 0
|
| MPCore software-interrupt. Not configured.
|-
| 0x1
|
| MPCore software-interrupt. Used by BOOT11 to kickstart Core1.
|-
| 0x2-0x3
|
| MPCore software-interrupt. Seem to be unused.
|-
| 0x4
| Kernel
| MPCore software-interrupt. Used to manage the performance counter.
|-
| 0x5
| Kernel
| MPCore software-interrupt. Does apparently nothing.
|-
| 0x6
| Kernel
| MPCore software-interrupt. Extensively used by [[SVC|KernelSetState]] (and contains most of the actual code of the latter).
|-
| 0x7
| Kernel
| MPCore software-interrupt. See [[KCacheMaintenanceInterruptEvent]]
|-
| 0x8
| Kernel
| MPCore software-interrupt. Used for scheduling.
|-
| 0x9
| Kernel
| MPCore software-interrupt. Used when handling exceptions that require termination of a thread or a process, and in some cases by svcSetDebugThreadContext, to store VFP registers in the thread's register storage.
|-
| 0xA
| Kernel
| TLB operations interrupt, see [[KTLBOperationsInterruptEvent]]
|-
| 0xB-0xE
|
| MPCore software-interrupt. Not configured.
|-
| 0xF
| dmnt/debugger
| MPCore software-interrupt. Used to abstract FIQ (debug). This interrupt is never sent to core2 nor core3 on N3DS.
|-
| 0x1D
| Kernel
| MPCore timer.
|-
| 0x1E
| Kernel
| MPCore watchdog - set when the watchdog counter reaches 0 in timer mode, causes interrupt 30 to set as pending. Only set on core 1 as core 1's timer is used for everything.
|}

= Hardware Interrupts =

There are 0x60 hardware interrupts starting at 0x20 and continuing up to 0x7F. These are not private and are accessible from any core.

{| class="wikitable" border="1"
! IRQ
! Listener
! Description
|-
| 0x28
| gsp, TwlBg
| PSC0
|-
| 0x29
| gsp, TwlBg
| PSC1
|-
| 0x2A
| gsp, TwlBg
| PDC0 (VBlank0)
|-
| 0x2B
| gsp, TwlBg
| PDC1 (VBlank1)
|-
| 0x2C
| gsp, TwlBg
| PPF
|-
| 0x2D
| gsp, TwlBg
| P3D
|-
| 0x30
| Kernel
| ?
|-
| 0x39
| Kernel
| DMA
|-
| 0x3A
| Kernel
| DMA
|-
| 0x3B
| Kernel
| DMA
|-
| 0x40
| nwm
| WIFI SDIO Controller @ 0x10122000
|-
| 0x41
| nwm
| ?
|-
| 0x42
| nwm_dev?
| WIFI SDIO Controller @ 0x10100000
|-
| 0x45
| mvd (New3DS)
| ?
|-
| 0x46
| mvd (New3DS)
| ?
|-
| 0x48
| camera
| ?
|-
| 0x49
| camera
| ?
|-
| 0x4A
| dsp
| General interrupt from DSP, including semaphore and command/reply registers status change
|-
| 0x4B
| camera
| Y2R Conversion Finished
|-
| 0x4C
| TwlBg
| ?
|-
| 0x4D
| TwlBg
| ?
|-
| 0x4E
| mvd (New3DS)
| Y2R2 End Event
|-
| 0x4F
| mvd (New3DS)
| Related to mvd services
|-
| 0x50
| pxi, TwlBg
| Sync
|-
| 0x51
| pxi, TwlBg
| ?
|-
| 0x52
| pxi, TwlBg
| Send Fifo Empty
|-
| 0x53
| pxi, TwlBg
| Receive Fifo Not Empty
|-
| 0x54
| i2c, TwlBg
| I2C Bus0 work done
|-
| 0x55
| i2c, TwlBg
| I2C Bus1 work done
|-
| 0x56
| spi, TwlBg
| ?
|-
| 0x57
| spi, TwlBg
| SPI bus 0 transfer finished?
|-
| 0x58
| Kernel
| PDN
|-
| 0x59
| TwlBg
| ?
|-
| 0x5A
| mic
| ?
|-
| 0x5C
| i2c, TwlBg
| I2C Bus2 work done
|-
| 0x60
| gpio, TwlBg
| Shell opened
|-
| 0x62
| gpio, TwlBg
| Shell closed
|-
| 0x63
| gpio, TwlBg
| Touchscreen
|-
| 0x64
| gpio, TwlBg
| Headphone jack plugged in/out
|-
| 0x66
| gpio, TwlBg
| ?
|-
| 0x68
| gpio, TwlBg
| IR
|-
| 0x69
| gpio, TwlBg
| ?
|-
| 0x6A
| gpio, TwlBg
| ?
|-
| 0x6B
| gpio, TwlBg
| ?
|-
| 0x6C
| gpio, TwlBg
| ?
|-
| 0x6D
| gpio, TwlBg
| ?
|-
| 0x6E
| gpio, TwlBg
| ?
|-
| 0x6F
| gpio, TwlBg
| ?
|-
| 0x70
| gpio, TwlBg
| ?
|-
| 0x71
| gpio, TwlBg
| MCU (HOME/POWER pressed/released or WiFi switch pressed)
|-
| 0x72
| gpio, TwlBg
| ?
|-
| 0x73
| TwlBg
| ?
|-
| 0x74
| ?
| Gamecard related
|-
| 0x75
| ?
| Gamecard inserted
|-
| 0x78 to 0x7B
| Kernel
| Core 0-3 Performance monitor counter (any) overflow
|-
| 0x7A to 0x82 (PDN_MPCORE_CFG bit2 set) or
0x7C to 0x84 (bit2 clear)
| Kernel
| ?
|}
(interrupts from 0x80 and up can't be mapped in available builds of the kernel)

There are 2 tables in the ARM11 kernel: the first has 32 * 2(or 32 * 4) 8-byte entries. This table is for the private interrupts that belong to each core. The data for each interrupt can be found by doing table_base + (core_num * 0x100) + (intr_num * 8). The second table is for public hardware interrupts and the data for each interrupt can be retrieved by doing table_base + (intr_num * 8).

= InterruptData =
{| class="wikitable" border="1"
|-
! Offset
! Type
! Description
|-
| 0x0
| [[KBaseInterruptEvent]] *
| Pointer to the KBaseInterruptEvent object for this interrupt
|-
| 0x4
| u8
| Interrupt will be disabled by the IRQ handler as soon as it is acknowledged.
Ignored for FIQ: the FIQ handler always sets bit2 of [[PDN_Registers#PDN_FIQ_CNT|PDN_FIQ_CNT]]
|-
| 0x5
| u8
| Interrupt is disabled
|-
| 0x6
| u8
| Interrupt priority
|-
| 0x7
| u8
| Unused, alignment
|}

= Interrupt Table (New3DS) =
(0xFFF318F4 in 10.3)

{| class="wikitable" border="1"
! Offset
! Type
! Description
|-
| 0x0
| InterruptData[224]
| Data for all hardware and software interrupts
|-
| 0x700
| [[KObjectMutex]]
| Mutex
|}

CSND Registers

2019-04-20T23:32:58Z

Wwylele:

=0x1EC03000=
?

=0x1EC03400=
The channel registers are based at 0x1EC03400(process virtual address). There's 0x20-bytes total for each channel slot, thus the base-address for a channel's slot is determined with: 0x1EC03400 + (channel_index*0x20). The below offsets are relative to these channel register slots.

{| class="wikitable" border="1"
! Relative offset
! Size
! Description
|-
| 0x0
| 2
| REG_CSNDCHANX_CNT. For Type0 [[CSND_Shared_Memory|Cmd]] 0xE, CSND module basically writes this value here: u16 (cmdword[2] & 0xFFFF).
|-
| 0x2
| 2
| For Type0 [[CSND_Shared_Memory|Cmd]] 0xE, CSND module writes this value here: 0 - (cmdword[2]>>16).
|-
| 0x4
| 2
| For Type0 [[CSND_Shared_Memory|Cmd]] 0xE, CSND module writes value 0 here.
|-
| 0x6
| 2
| For Type0 [[CSND_Shared_Memory|Cmd]] 0xE, CSND module writes value 0 here.
|-
| 0x8
| 2
| For Type0 [[CSND_Shared_Memory|Cmd]] 0xE, CSND module writes this value here: (u16)cmdword[4].
|-
| 0xA
| 2
| For Type0 [[CSND_Shared_Memory|Cmd]] 0xE, CSND module writes this value here: cmdword[4]>>16.
|-
| 0xC
| 4
| This is the audio data physical address, for the main channel.
|-
| 0x10
| 4
| This is the audio data total byte-size. The CSND module masks the size loaded from the Type0 command-data with value 0x7FFFFFF, which is then used when writing these registers.
|-
| 0x14
| 4
| This is the audio data physical address, for the second channel. When this is not 0x0 stereo audio is used, otherwise mono audio is used.
|-
| 0x18
| 4
| When CSND module handles type0 Cmd 0xE with encoding!=IMA-ADPCM, CSND module sets this to zero. This register can be initialized via CSND module type0 Cmd 0xB.
|-
| 0x1C
| 4
| CSND module writes value zero here immediately after it writes to chanslotreg+0x18.
|}

=0x1EC03800=

There are two capture unit slot located at 0x1EC03800. Each slot has 0x10 bytes.

IO Registers

2019-04-20T02:26:18Z

Wwylele: /* Overview */

= Overview =

{| class="wikitable" border="1"
! Old3DS
! A9/A11
! Category
! Physaddr
! Used by
! Comments
|-
| style="background: green" | Yes
| A9
| [[CONFIG9 Registers]]
| 0x10000000
| Boot9, Process9
|
|-
| style="background: green" | Yes
| A9
| [[IRQ Registers]]
| 0x10001000
| Boot9, Process9, Kernel9
| ARM9 Interrupt Masking
|-
| style="background: green" | Yes
| A9
| [[NDMA Registers]]
| 0x10002000
| Boot9, Process9
| DMA Engine
|-
| style="background: green" | Yes
| A9
| [[TIMER Registers]]
| 0x10003000
| Boot9, Process9
|
|-
| style="background: green" | Yes
| A9
| [[CTRCARD Registers]]
| 0x10004000 / 0x10005000
| Process9
|
|-
| style="background: green" | Yes
| A9
| [[EMMC Registers]]
| 0x10006000 / 0x10007000
| Boot9, Process9, NewKernel9Loader
| 0x10007000 is normally not enabled on retail, all-zeros when read.
|-
| style="background: green" | Yes
| A9
| [[PXI Registers]]
| 0x10008000
| Boot9, Process9
|
|-
| style="background: green" | Yes
| A9
| [[AES Registers]]
| 0x10009000
| Boot9, Process9, NewKernel9Loader
|
|-
| style="background: green" | Yes
| A9
| [[SHA Registers]]
| 0x1000A000
| Boot9, Process9, NewKernel9Loader
|
|-
| style="background: green" | Yes
| A9
| [[RSA Registers]]
| 0x1000B000
| Boot9, Process9
|
|-
| style="background: green" | Yes
| A9
| [[Corelink DMA Engines|XDMA Registers]]
| 0x1000C000
| Boot9, Kernel9
| [http://infocenter.arm.com/help/topic/com.arm.doc.subset.primecell.system/index.html CoreLink™ DMA-330 r0p0] (two channels).
|-
| style="background: green" | Yes
| A9
| [[SPICARD Registers]]
| 0x1000D800
| Process9
|
|-style="border-top: double"
| style="background: green" | Yes
| A9
| [[CONFIG Registers]]
| 0x10010000
| Process9
|
|-
| style="background: green" | Yes
| A9
| PRNG Registers
| 0x10011000
| Boot9, Process9
| Used as entropy-source for seeding random number generators.
|-
| style="background: green" | Yes
| A9
| [[OTP Registers]]
| 0x10012000
| Boot9, Kernel9, NewKernel9Loader
| Top secret.
|-
| style="background: green" | Yes
| A9
| [[ARM7|ARM7 Registers]]
| 0x10018000
| TwlProcess9
| Used to setup the ARM7 core for AGB/TWL
|-style="border-top: double"
| style="background: green" | Yes
| A11/A9
| Debug WIFI SDIO Registers?
| 0x10100000
|
| An SDIO controller is mapped here, NWM references this controller but doesn't have access to it.
|-
| style="background: green" | Yes
| A11/A9
| [[HASH Registers]]
| 0x10101000
| [[Filesystem services]]
| These registers function the same as the [[SHA Registers]], with the exception of the FIFO being located at 0x10301000.
|-
| style="background: green" | Yes
| A11/A9
| [[Y2R Registers]]
| 0x10102000
| [[Camera Services]]
| y2r
|-
| style="background: green" | Yes
| A11/A9
| [[CSND Registers]]
| 0x10103000
| TwlBg, [[Codec Services]], [[CSND Services]], [[DSP Services]]
| Sound hardware.
|-style="border-top: double"
| style="background: green" | Yes
| A11/A9
| LGYFB0
| 0x10110000
| TwlBg
| IO registers used to access legacy output framebuffer, as well as configure the upscaling filter.
|-
| style="background: green" | Yes
| A11/A9
| LGYFB1
| 0x10111000
| TwlBg
| IO registers used to access legacy output framebuffer, as well as configure the upscaling filter.
|-style="border-top: double"
| style="background: green" | Yes
| A11/A9
| [[Camera Registers]]
| 0x10120000
| [[Camera Services]]
|
|-
| style="background: green" | Yes
| A11/A9
| [[Camera Registers]]
| 0x10121000
| [[Camera Services]]
| Mirror of 0x10120000?
|-
| style="background: green" | Yes
| A11/A9
| [[WIFI Registers]]
| 0x10122000
| [[NWM Services]]
| WIFI SDIO bus registers
|-
| style="background: green" | Yes
| A11/A9
| ?
| 0x10123000
| [[NWM Services]]
| WIFI?
|-style="border-top: double"
| style="background: red" | No
| A11/A9
| [[MVD Registers]]
| 0x10130000
| [[MVD Services]]
|
|-
| style="background: red" | No
| A11/A9
| [[MVD Registers]]
| 0x10131000
| [[MVD Services]]
|
|-
| style="background: red" | No
| A11/A9
| [[MVD Registers]]
| 0x10132000
| [[MVD Services]]
|
|-style="border-top: double"
| style="background: green" | Yes
| A11/A9
| [[CONFIG11 Registers]]
| 0x10140000
| Process9, Boot11, Kernel11, TwlBg, [[DSP Services]], [[NWM Services]], [[SPI Services]]
| Power management.
|-
| style="background: green" | Yes
| A11/A9
| [[CONFIG11 Registers]]
| 0x10141000
| Process9, Boot11, Kernel11, TwlBg, [[Codec Services]], [[NWM Services]], [[SPI Services]], [[PDN Services]]
| Power management
|-
| style="background: green" | Yes
| A11/A9
| [[SPI Registers]]
| 0x10142000
| TwlBg, [[SPI Services]]
|
|-
| style="background: green" | Yes
| A11/A9
| [[SPI Registers]]
| 0x10143000
| TwlBg, dmnt Module
| Debugger related?
|-
| style="background: green" | Yes
| A11/A9
| [[I2C Registers]]
| 0x10144000
| Boot11, Kernel11, TwlBg, [[I2C Services]]
| 3DS I2C interface (MCU + Cameras + LCD)
|-
| style="background: green" | Yes
| A11/A9
| [[CODEC Registers]]
| 0x10145000
| TwlBg, [[Codec Services]]
|
|-
| style="background: green" | Yes
| A11/A9
| [[HID Registers]]
| 0x10146000
| Boot9, Boot11, Kernel11, TwlBg, [[HID Services]], dlp Services
| See [[PAD]].
|-
| style="background: green" | Yes
| A11/A9
| [[GPIO Registers]]
| 0x10147000
| Boot11, TwlBg, [[GPIO Services]], [[DSP Services]](v0)
|
|-
| style="background: green" | Yes
| A11/A9
| [[I2C Registers]]
| 0x10148000
| TwlBg, [[I2C Services]]
| 3DS I2C interface (Gyro + IR)
|-style="border-top: double"
| style="background: green" | Yes
| A11/A9
| [[SPI Registers]]
| 0x10160000
| Boot9, TwlBg, [[SPI Services]]
|
|-
| style="background: green" | Yes
| A11/A9
| [[I2C Registers]]
| 0x10161000
| Boot11, TwlBg, [[I2C Services]]
| TWL I2C interface (MCU + Cameras)
|-
| style="background: green" | Yes
| A11/A9
| [[MIC Registers]]
| 0x10162000
| [[MIC Services]]
|
|-
| style="background: green" | Yes
| A11/A9
| [[PXI Registers]]
| 0x10163000
| Boot11, Kernel11, TwlBg, [[PXI Services]]
|
|-
| style="background: green" | Yes
| A11/A9
| [[NTRCARD Registers]]
| 0x10164000
| Boot9, Process9
|
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10165000
| [[MP Services]]
|
|-style="border-top: double"
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10170000
| [[MP Services]]
| NTR WIFI Registers, see [http://problemkaputt.de/gbatek.htm#dswirelesscommunications GBATek].
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10171000
| [[MP Services]]
| NTR WIFI Registers (mirror)
|-
| style="background: green" | Yes
| A11/A9
|?
| 0x10172000
|?
| NTR WIFI Unused?
|-
| style="background: green" | Yes
| A11/A9
|?
| 0x10173000
|?
| NTR WIFI Unused?
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10174000
| [[MP Services]]
| NTR WIFI RAM
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10175000
|?
| NTR WIFI RAM
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10176000
|?
| NTR WIFI Registers (mirror)
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10177000
|?
| NTR WIFI Registers (mirror)
|-
| style="background: green" | Yes
| A11/A9
| [[MP Registers]]
| 0x10178000 - 0x10180000
| [[MP Services]]
| NTR WIFI WS1 Region
|-style="border-top: double"
| style="background: green" | Yes
| A11
| [[Corelink DMA Engines|CDMA]]
| 0x10200000
| Boot11, Kernel11
| [http://infocenter.arm.com/help/topic/com.arm.doc.subset.primecell.system/index.html CoreLink™ DMA-330 r0p0] (eight channels). Only used by bootrom on New3DS.
|-
| style="background: green" | Yes
| A11
| ?
| 0x10201000
| TwlBg
|
|-
| style="background: green" | Yes
| A11
| [[LCD Registers]]
| 0x10202000
| TwlBg, Kernel11, [[GSP Services]]
|
|-
| style="background: green" | Yes
| A11
| [[DSP Registers]]
| 0x10203000
| [[DSP Services]]
| see the "DSi XpertTeak" section in [http://problemkaputt.de/gba.htm no$gba] help.
|-
| style="background: green" | Yes
| A11
|
| 0x10204000
|
|
|-style="border-top: double"
| style="background: red" | No
| A11
| [[Corelink DMA Engines|CDMA]]
| 0x10206000
| NewKernel11
| [http://infocenter.arm.com/help/topic/com.arm.doc.ddi0424d/index.html CoreLink™ DMA-330 r1p2] (eight channels). This is the DMA engine actually being used by the New3DS ARM11 kernel.
|-
| style="background: red" | No
| A11
| [[MVD Registers]]
| 0x10207000
| [[MVD Services]]
| New 3DS only?
|-style="border-top: double"
| style="background: green" | Yes
| A11
| AXI
| 0x1020F000
| TwlBg, [[GSP Services]]
| [http://infocenter.arm.com/help/topic/com.arm.doc.ddi0422a/CHDGHIID.html CoreLink™ NIC-301 r1p0].
|-style="border-top: double"
| style="background: green" | Yes
| A11
| DMA region
| 0x10300000-0x10400000
|
| CDMA wants these addresses. Most pages in this region correspond to the same respective pages in the 0x10100000-0x10200000 region. The HASH FIFO register is located at 0x10301000 only.
|-style="border-top: double"
| style="background: green" | Yes
| A11
| [[GPU/External_Registers|GPU Registers]]
| 0x10400000
| Boot11, Kernel11, [[GSP Services]]
||
|}

IO registers starting at physical address 0x10200000 are not accessible from the ARM9 (which includes all LCD/GPU registers). It seems IO registers below physical address 0x10100000 are not accessible from the ARM11 bus.

ARM11 kernel virtual address mappings for these registers varies for different builds. For ARM11 user mode applications you have:
physaddr = virtaddr - 0x1EC00000 + 0x10100000

CSND Registers

2019-04-20T02:24:38Z

Wwylele: /* 0x1EC03000 */ No, these are not DSP registers, which are located at 1ED03000 (100000 bytes off). RE of CSND command 0x200 also shows that this region has different layout than DSP registers. DSP reigsters are all 2-bytes, while command 0x200 writes 1/4

Extdata

2019-04-03T19:14:25Z

Wwylele: /* VSXE Header */

This page describes the format and encryption of extdata, "extra data" stored on SD card and NAND, at:

* <code>nand/data/<ID>/extdata/<ExtdataID-High></code>
* <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/<ExtdataID-High></code>

ExtdataID-High is always 00000000 for SD, and always 00048000 for NAND. Regular apps can only mount SD extdata using the same extdataID which is stored in the CXI exheader. Therefore, regular apps which have the exheader extdataID set to zero can't use extdata. This restriction doesn't apply for shared extdata with extdataID high bitmask 0x48000 stored on NAND. System apps with a certain access right can mount arbitrary extdata. All NAND extdata is shared extdata, while all SD extdata is normal extdata.

All data in this page is little-endian. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

= Format =

To avoid confusion, the terms '''device directory / file''' and '''virtual directory / file''' are used with the following meanings:

* '''Device directory / file''' are the real directory / file stored on SD / NAND that can be seen under path <code>nand/data/<ID>/extdata/</code> or <code>sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/</code>.
* '''Virtual directory / file''' are directory / file stored inside extdata virtual file system, which can be seen by applications in the mounted extdata archives.

An extdata consists of several device directories and files, which forms a file system consisting of multiple virtual directories and files.

An extdata with ID <code>ExtdataId</code> has the following device files:

* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/Quota.dat</code> (optional)
* <code>.../extdata/<ExtdataID-High>/<ExtdataId-Low>/<SubDirID>/<SubFileID></code>

Note:

* All device files are [[DISA and DIFF|DIFF containers]]. '''All format description below is about the inner content of the containers'''. Please unwrap these files first according to the DIFF format description before reading them using the extdata format description below.
* <code>Quota.dat</code> is only observed existing for NAND shared extdata.
* <code><SubDirID></code> and <code><SubFileID></code> are 8-digit hex strings.
* Device file with <code>SubDirID = SubFileID = 00000000</code> doesn't exist. Other ID combinations can exists.
* Device file with <code>SubDirID = 00000000</code> and <code>SubFileID = 00000001</code> is the VSXE metadata file and must exist.
* Other files, besides <code>Quota.dat</code> and <code>00000000/00000001</code>, are normal sub files, are these device files one-to-one correspond to virtual files. They contain raw virtual file data in the DIFF inner content.
* <code>SubDirID = 00000000</code> is usually the only one device directory that can be seen. See [[#Device Directory Capacity]] for more information.

== Quota File ==

The inner data of <code>Quota.dat</code> is 0x48 bytes with the following format. The exact function of this file is unclear.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "QUOT"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 4
| 0x1000, block size?
|-
| 0x0C
| 4
| Always 126. Probably device directory capacity. See the [[#Device Directory Capacity]] more information.
|-
| ...
|

| The meaning of other fields is unknown
|}

== Device Directory Capacity ==

A device directory in an extdata (a <code><SubDirID></code> directory) seems to have a maximum number of device files it can contain. For SD extdata, this maximum number seems to be hard-coded as 126. For NAND extdata, the number is probably indicated by a field in Quota.dat, which is, again, always 126 as observed. 3DS FS tries to put all device files in the device directory <code>00000000</code> if possible, and only when more than 126 files needed to add, a second device directory <code>00000001</code> and so on are created. However, few extdata have such amount of files to store, so the behavior lacks of use cases to confirm.

The number 126 is probably from some kind of other capacity of 128 with <code>"."</code> and <code>".."</code> entries reserved. It is theorized that this is to keep a FAT directory table, with 0x20 bytes for each entry, in one 0x1000 cluster. The motivation is unclear.

== VSXE File System Metadata ==

The inner data of <code>00000000/00000001</code> consists of the following components

* VSXE header
* Directory Hash Table
* File Hash Table
* File Allocation Table
* Data region
** Directory Entry Table
** File Entry Table

=== VSXE Header ===

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "VSXE"
|-
| 0x04
| 4
| Magic 0x30000
|-
| 0x08
| 8
| File system Information offset (0x138)
|-
| 0x10
| 8
| Image size in blocks
|-
| 0x18
| 4
| Image block size
|-
| 0x1C
| 4
| Padding
|-
| 0x20
| 8
| Unknown
|-
| 0x28
| 4
| 'Action' made on most recently mounted Extdata image
|-
| 0x2C
| 4
| Unknown
|-
| 0x30
| 4
| D of most recently mounted Extdata image
|-
| 0x34
| 4
| Unknown
|-
| 0x38
| 0x100
| Mount path, from most recently mounted Extdata image
|-
|

|

| Below is File system Information, which is assumed following the same layout as [[Savegames#SAVE_Header]]
|-
| 0x138
| 4
| Unknown
|-
| 0x13C
| 4
| Data region block size
|-
| 0x140
| 8
| Directory hash table offset
|-
| 0x148
| 4
| Directory hash table bucket count
|-
| 0x14C
| 4
| Padding
|-
| 0x150
| 8
| File hash table offset
|-
| 0x158
| 4
| File hash table bucket count
|-
| 0x15C
| 4
| Padding
|-
| 0x160
| 8
| File allocation table offset
|-
| 0x168
| 4
| File allocation table entry count
|-
| 0x16C
| 4
| Padding
|-
| 0x170
| 8
| Data region offset
|-
| 0x178
| 4
| Data region block count (= File allocation table entry count)
|-
| 0x17C
| 4
| Padding
|-
| 0x180
| 4
| Directory entry table starting block
|-
| 0x184
| 4
| Directory entry table block count
|-
| 0x188
| 4
| Maximum directory count
|-
| 0x18C
| 4
| Padding
|-
| 0x190
| 4
| File entry table starting block
|-
| 0x194
| 4
| File entry table block count
|-
| 0x198
| 4
| Maximum file count
|-
| 0x19C
| 4
| Padding
|}

* All "offsets" are relative to the beginning of VSXE image. All "starting block index" are relative to the beginning of data region.

=== File Allocation Table & Data Region ===

These function in the same way as [[Savegames#File Allocation Table|the file allocation in savegames]]. However, the only two "files" allocated in the data region are the directory entry table and file entry table, so the data region is usually pretty small, and the file allocation table is unchanged once created and has no free blocks. Thus, the offset and size of directory / file entry table can be found directly by <code>offset = entry_table_starting block * data_region_block_size + data_region_offset</code> and <code>size = entry_table_block_count * data_region_block_size</code>

=== Directory Hash Table & File Hash Table ===

These function in the same way as [[Savegames#Directory Hash Table & File Hash Table|those in savegames]]

=== Directory Entry Table ===

This functions in the same way as [[Savegames#Directory Entry Table|the one in savegames]]. It lists all virtual directories in this extdata.

=== File Entry Table ===

This functions in a similar way as [[Savegames#File Entry Table|the one in savegames]]. It lists all virtual files in this extdata. However, the format of a (non-dummy) file entry is a little bit modified:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| <s>First block index in data region</s> '''Always 0x80000000 because unused'''
|-
| 0x20
| 8
| <s>File size</s> '''Unique identifier'''
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

Each non-dummy file entry corresponds to a device file. The path to the device file is generated by the following computation:

<pre>// See previous section about this capacity
const uint32_t device_dir_capacity = 126;

// entry index is the index in the file entry table, with the first dummy entry as
// index = 0, which is never used for a real file.
// file_index = 1 is reserved for the VSXE Filesystem Metadata itself, so real files
// started from file_index = 2.
uint32_t file_index = entry_index + 1;

uint32_t SubDirID = file_index / device_dir_capacity;
uint32_t SubFileID = file_index % pdevice_dir_capacity;

char extdata_path[...]; // ".../extdata/<ExtdataID-High>/<ExtdataId-Low>"
char device_path[...]; // output path
sprintf(device_path, "%s/%08x/%08x", extdata_path, SubDirID, SubFileID);
</pre>
When mounting extdata, the unique identifier is used to match the ID stored in subfile's [[DISA and DIFF#DIFF header|DIFF header]]. If the ID doesn't match, mounting will fail.

== Virtual File System Structure ==

When extdata is created, these are ''always'' created regardless of whether the title actually uses them.

* <code>/icon</code> This virtual file contains the extdata icon displayed in data management. This icon can only be written to by titles when creating extdata, titles would have to recreate extdata to change the icon. This file can't be read directly, instead it is read via FS:ReadExtSaveDataIcon.
* <code>/user/</code> This virtual directory contains the title's actual extdata files.
* <code>/boss/</code> This virtual directory can contain SpotPass content. SpotPass content can only be downloaded to this <code>/boss</code> virtual directory.

User extdata and SpotPass extdata use separate mount points at <code>/user</code> and <code>/boss</code>. Therefore one mount can't access the other virtual directory, and also can't access <code>/icon</code>.(The title's SpotPass extdata can be mounted by the title itself, if it uses SpotPass)

Other optional but notable directories include:

* <code>/user/ExBanner</code> This virtual directory can optionally store extended banners. When this is available, this banner is displayed instead of the CXI ExeFS banner. <code>COMMON.bin</code> stores the common exbanner, while <code><regionlang_code>.bin</code> stores an optional separate region/language specific banner.(regionlang_code can be "JPN_JP", "USA_EN", etc)

== SD Extdata ==
Usually the ExtdataID low is in the format '00<Unique ID>'

{| class="wikitable" border="1"
|-
! JPN ExtdataID
! USA ExtdataID
! EUR ExtdataID
! Description
! Extdata images
|-
| 00000082
| 0000008f
| 00000098
| [[Home Menu]] extdata, this contains home-menu savedata and cached icons for applications.
|
|-
| 00000200
| 00000210
| 00000220
| [[System_Settings|System Settings]] extdata added with [[2.0.0-2]].
|
|-
| 00000207
| 00000217
| 00000227
| [[Mii Maker]], contains an ExBanner
| [https://dl.dropbox.com/u/20520664/extdata00000217.zip cleartext]
|-
| 00000208
| 00000218
| 00000228
| Streetpass Mii Plaza
| 11 mb big!
|-
| 00000209
| 00000219
| 00000229
| [[eShop]], contains store music in AAC format.
|
|-
| 0000020b
| 0000021b
| 0000022b
| Nintendo Zone
|
|-
| 0000020d
| 0000021d
| 0000022d
| Face Raiders, likely contains an ExBanner
|
|-
| 000002cc
| 000002cd
| 000002ce
| [[Home Menu]] theme
|
|-
| ?
| 000004aa
| 000004ab
| Nintendo Video Extra Data
This is where the video files are stored, and [[Nintendo_Video|includes]] the thumbnail, the description, and possibly some checksum info in each video file stored in the extdata images. There are always 9 files within the subdirectory "00000000" of this folder, even without any videos downloaded. The files are "00000001" - "00000009", and "00000003" - "00000008" have the same filesize of 50.7 MB. It is possible to restore the older videos by overwriting all the files within this directory. Provided of course you have made a backup of the files before hand, by copying all the files within this directory to your computer. As far I'm aware its not possible to mix and match the files in order to get certain videos in one grouping, ie. having all 3 Zelda orchestral recordings in one group of 4 Nintendo videos.
|
|-
|00000306
|00000308
|00000307
|Mario Kart 7
|
|-
| 0000030b
| 0000030d
| 0000030c
| Nintendogs + Cats
|
|-
| 00000326
| 00000326
| 00000326
| Pokédex 3D
|
|-
| 00000305
| 0000032d
| 0000033c
| Super Street Fighter IV 3D
|
|-
| 00000328
| 00000358
| 0000033b
| Ridge Racer 3D
|
|-
| ?
| 0000034d
| 00000402
| Samurai Warriors Chronicles
|
|-
| ?
| 0000034f
| 0000038a
| Dead or Alive Dimensions
|
|-
| 00000481
| N/A
| N/A
| Monster Hunter Tri G (Download-Quests)
|
|-
| ?
| 00000517
| 00000518
| Swapnote
|
|-
| 0000055d
| 0000055d
| 0000055d
| Pokémon X Pokémon Y
|
|-
| ?
| 00000725
| 00000724
| Ambassador Certificate
|
|-
| ?
| ?
| 000007af
| New Super Mario Bros. 2
|
|-
| ?
| 00000863
| 00000864
| Animal Crossing: New Leaf
|
|-
| ?
| 00000a85
| 00000a86
| Professor Layton and the Miracle Mask Professor Layton and the Azran Legacy
German Version ExtdataID is 00000a87
|
|-
| ?
| ?
| 00000b4f
| Fullblox / Crashmo
|
|-
| ?
| ?
| 00000ba9
| Pokémon Mystery Dungeon: Gates to Infinity
|
|-
| ?
| ?
| 00000c24
| Denpa men
|
|-
| 00000c73
| 00000c73
| 00000c73
| Save Data Transfer Tool
|
|-
| ?
| ?
| 00000d9a
| Donkey Kong Country™ Returns 3D: Trailer
|
|-
| ?
| ?
| 00000ea6
| Etrian Odyssey IV
|
|-
| ?
| 00000edf
| 00000ee0
| Super Smash Bros. for Nintendo 3DS
|
|-
| ?
| 00000f14
| 00000f1e
| Phoenix Wright: Ace Attorney - Dual Destinies
|
|-
| ?
| 00001007
| 00001005
| Professor Layton vs Phoenix Wright: Ace Attorney
|
|-
| ?
| ?
| 00001062
| Nintendo Pocket Football Club
|
|-
| ?
| ?
| 0000111c
| Yoshi's New Island
|
|-
| ?
| ?
| 00001131
| Fantasy Life
|
|-
| 000011c5
| 000011c5
| 000011c5
| Pokémon Omega Ruby Pokémon Alpha Sapphire
|
|-
| ?
| ?
| 000012ca
| Mario vs. Donkey Kong: Tipping Stars
|
|-
| ?
| ?
| 00001499
| Korg DSN-12
|
|-
| ?
| ?
| 000014f2
| Animal Crossing: Happy Home Designer
|
|-
| 000014d1
| 000014d1
| 000014d1
| [[Home Menu]] badge
|
|-
| ?
| ?
| 00001632
| Fullblox / Stretchmo
|
|-
| ?
| ?
| 00001646
| Pokémon Rumble World
|
|-
| 00001648
| 00001648
| 00001648
| Pokémon Sun Pokémon Moon
|
|-
| 0000165c
| 0000165c
| 0000165c
| [[Home Menu]] saved theme layouts
|
|-
| ?
| ?
| 00001678
| Yo-kai Watch
|
|-
| ?
| ?
| 000018fa
| Phoenix Wright: Ace Attorney - Spirit of Justice
|
|-
| ?
| ?
| 0000198f
| Animal Crossing: New Leaf - Welcome amiibo
|
|-
| ?
| ?
| 00001a05
| Super Mario Maker
|
|-
| ?
| ?
| 00001a2e
| Swapdoodle
|
|}

== NAND Shared Extdata ==
{| class="wikitable" border="1"
|-
! ExtdataID
! Description
|-
| 0xe0000000
| Home Menu attempts to open this archive during boot, if [[FS:OpenArchive]] doesn't return an error Home Menu seems to then launch the [[System Transfer]] application. Home Menu doesn't actually use this archive at all except for checking whether it exists.
|-
| 0xf0000001
| NAND JPEG/MPO files and phtcache.bin from the camera application are stored here. This also contains UploadData.dat.
|-
| 0xf0000002
| NAND M4A files from the sound application are stored here
|-
| 0xf0000009
| Used for [[BOSS_Services|SpotPass]] content storage for [[News_Services|notifications]].
|-
| 0xf000000b
| Contains idb.dat, idbt.dat, gamecoin.dat, ubll.lst, CFL_DB.dat, and CFL_OldDB.dat. These files contain cleartext [[Mii_Maker|Miis]] and some data relating (including cached ICN data) to Play/Usage Records.
|-
| 0xf000000c
| Contains bashotorya.dat and bashotorya2.dat.
|-
| 0xf000000d
| Home Menu SpotPass content data [[BOSS_Services|storage]].
|-
| 0xf000000e
| Contains [[VersionList|versionlist.dat]], used by Home Menu for the software update notification added with [[7.0.0-13]].
|}

==== Shared Extdata 0xf000000b gamecoin.dat ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Magic number: 0x4F00
|-
| 0x4
| 0x2
| Total Play Coins
|-
| 0x6
| 0x2
| Total Play Coins obtained on the date stored below. When the below date does not match the current date, this field is reset to zero, then the date(and other fields) are updated. Once this value is >=10, no more Play Coins can be obtained until the current date changes.
|-
| 0x8
| 0x4
| Total step [[PTM:GetTotalStepCount|count]] at the time a new Play Coin was obtained.
|-
| 0xC
| 0x4
| Step count for the day the last Play Coin was obtained, for that day's step count(same as the step count displayed by home-menu when this file was updated).
|-
| 0x10
| 0x2
| Year
|-
| 0x12
| 0x1
| Month
|-
| 0x13
| 0x1
| Day
|}

The above date stores the last time new Play Coin(s) were obtained. The contents of this file is updated by home-menu. [[PTM:GetTotalStepCount]] is not checked constantly, after home-menu boot this is only checked when waking from sleep-mode. Each time home-menu updates the contents of this file, home-menu will set the Play Coin total to 300 if it's higher than the 300 Play Coin limit.

[[Home Menu]] loads this file / opens this archive during [[Home Menu|startup]]. When accessing this file fails, like when the file/archive is corrupted(or at least on older system-versions), the result is a brick due to Home Menu using [[SVC|svcBreak]]. [[User:Yellows8|Yellows8]] bricked a 3DS this way due to corruption via invalid [[FSFile:Write]] flush flags. When opening this extdata archive(0xf000000b) fails, Home Menu executes svcBreak.

==== Shared Extdata 0xf000000b ubll.lst ====
List of blocked users.

Empty space is filled with 0xC-long sequences of 00 00 ... 07

=== Tools ===

* [https://github.com/wwylele/3ds-save-tool 3ds-save-tool] - Extract/verifies extdata

NWM Services

2019-03-13T00:20:54Z

Wwylele: /* NWM local-WLAN service "nwm::UDS" */ Correct command ID. Verified against UDS disassembly

[[Category:Services]]

These NWM services are used for local-WLAN communications, NWM module handles regular wifi APs as well. These services are used for creating/connecting to networks, and for sending/receiving data over the network etc. NWM module uses the wifi SDIO hardware via the IO registers for this.

=NWM local-WLAN service "nwm::UDS"=
{| class="wikitable" border="1"
|-
! Command Header
! Available since system version
! Description
|-
| 0x000102C2
|
| Initialize Deprecated. Appears to be handled about the same way as [[NWMUDS:InitializeWithVersion]], except this uses version=0x100 internally instead of loading it from the command request.
|-
| 0x00020000
|
| Scrap Not used by sub-wars. This sets a state value to 0x2 then signals an event. This is probably some sort of shutdown command since this state write will result in all UDS commands returning an error if used afterwards.
|-
| 0x00030000
|
| [[NWMUDS:Shutdown|Shutdown]]
|-
| 0x00040402
|
| CreateNetwork Deprecated. Only used by very old titles.
|-
| 0x00050040
|
| [[NWMUDS:EjectClient|EjectClient]]
|-
| 0x00060000
|
| [[NWMUDS:EjectSpectator|EjectSpectator]]
|-
| 0x00070080
|
| [[NWMUDS:UpdateNetworkAttribute|UpdateNetworkAttribute]]
|-
| 0x00080000
|
| [[NWMUDS:DestroyNetwork|DestroyNetwork]]
|-
| 0x00090442
|
| ConnectNetwork Deprecated. Only used by very old titles.
|-
| 0x000A0000
|
| [[NWMUDS:DisconnectNetwork|DisconnectNetwork]]
|-
| 0x000B0000
|
| [[NWMUDS:GetConnectionStatus|GetConnectionStatus]]
|-
| 0x000C0000
|
| This writes two output u8 values to cmdreply[2] +0/+1. Not used by sub-wars.
|-
| 0x000D0040
|
| [[NWMUDS:GetNodeInformation|GetNodeInformation]]
|-
| 0x000E0006
|
| ''Identical'' to [[NWMUDS:DecryptBeaconData|DecryptBeaconData]]. Deprecated, only used by old titles.
|-
| 0x000F0404
|
| [[NWMUDS:RecvBeaconBroadcastData|RecvBeaconBroadcastData]]
|-
| 0x00100042
|
| [[NWMUDS:SetApplicationData|SetApplicationData]]
|-
| 0x00110040
|
| [[NWMUDS:GetApplicationData|GetApplicationData]]
|-
| 0x00120100
|
| [[NWMUDS:Bind|Bind]]
|-
| 0x00130040
|
| [[NWMUDS:Unbind|Unbind]]
|-
| 0x001400C0
|
| [[NWMUDS:PullPacket|PullPacket]]
|-
| 0x00150080
|
| SetMaxSendDelay(u64 unk) Not used by sub-wars.
|-
| 0x00160040
|
| (u8 inputval) Unknown. Not used by sub-wars.
|-
| 0x00170182
|
| [[NWMUDS:SendTo|SendTo]]
|-
| 0x00180040
|
| (u16 inputval) Unknown. Not used by sub-wars.
|-
| 0x00190040
|
| (u32 inputval) Unknown. Not used by sub-wars.
|-
| 0x001A0000
|
| [[NWMUDS:GetChannel|GetChannel]]
|-
| 0x001B0302
|
| [[NWMUDS:InitializeWithVersion|InitializeWithVersion]]
|-
| 0x001C0040
|
| (u8 inputval) Unknown. Not used by sub-wars.
|-
| 0x001D0044
| Unknown, >[[2.0.0-2]]
| [[NWMUDS:BeginHostingNetwork|BeginHostingNetwork]] This is a replacement for the original network-creation command.
|-
| 0x001E0084
| Unknown, >[[2.0.0-2]]
| [[NWMUDS:ConnectToNetwork|ConnectToNetwork]] This is a replacement for the original network-connection command.
|-
| 0x001F0006
| Unknown, >[[2.0.0-2]]
| [[NWMUDS:DecryptBeaconData|DecryptBeaconData]]
|-
| 0x00200040
| Unknown, >[[2.0.0-2]]
| Flush (u8 data_frame_index) Unknown. Not used by sub-wars.
|-
| 0x00210080
| Unknown, >[[2.0.0-2]]
| [[NWMUDS:SetProbeResponseParam|SetProbeResponseParam]]
|-
| 0x00220402
| Unknown, >[[2.0.0-2]]
| [[NWMUDS:ScanOnConnection|ScanOnConnection]]
|-
| 0x00230000
| Unknown, >[[2.0.0-2]]
| This writes an output u16 value to cmdreply[2]. Unknown. Not used by sub-wars.
|}

PullPacket is used for receiving data over the network and SendTo is for sending data over the network.

=NWM infrastructure service "nwm::INF"=
{| class="wikitable" border="1"
|-
! Command Header
! Description
|-
| 0x00010000
| ?
|-
| 0x00020000
| ?
|-
| 0x00030000
| ?
|-
| 0x00040000
| ?
|-
| 0x00050000
| ?
|-
| 0x000603C4
| [[NWMINF:RecvBeaconBroadcastData|RecvBeaconBroadcastData]]
|-
| 0x00070742
| [[NWMINF:ConnectToEncryptedAP|ConnectToEncryptedAP]]
|-
| 0x00080302
| [[NWMINF:ConnectToAP|ConnectToAP]]
|-
| 0x00090000
| ?
|-
| 0x000A0000
| ?
|-
| 0x000B0000
| ?, return event handle in cmdbuf[3]
|-
| 0x000C0040
| ?
|-
| 0x000D0000
| ?
|-
| 0x000E0002
| ?
|-
| 0x000F0082
| ?
|-
| 0x00100040
| ?
|}

=NWM socket service "nwm::SOC"=
{| class="wikitable" border="1"
|-
! Command Header
! Description
|-
| 0x00010042
| (u32 size, <static_buffer translate-hdr with static_buf_id=0>, addr) ?
|-
| 0x00020080
| (u32 unk, u32 size) Unknown. Uses size=0x5F8 internally unless the input is <=0x5F8. Uses an ipc static_buffer(static_buf_id=0) for output with the specified size(also used when writing the translate-hdr). Writes an output u32 to cmdreply[2].
|-
| 0x00030042
| (u32 unk, u32 size, <static_buffer translate-hdr with static_buf_id=0>, addr) ?
|-
| 0x00040042
| (u32 size, u32 unk, <static_buffer translate-hdr with static_buf_id=1>, addr) ?
|-
| 0x00050040
| (u32 unk) ?
|-
| 0x00060080
| (u32 unk0, u16 unk1) ?
|-
| 0x00070040
| (u16 unk) This writes an output u32 to cmdreply[2].
|-
| 0x00080040
| [[NWMSOC:GetMACAddress|GetMACAddress]]
|-
| 0x00090000
| This just copies data from state to the cmdreply, this always returns 0. u32 cmdreply[2] = sharedmem_size, cmdreply[4] = [[NWM_Shared_Memory|sharedmem_handle]], cmdreply[5] = eventhandle.
|-
| 0x000A0040
| (u32 unk) ?
|-
| 0x000B0040
| (u32 unk) This writes an output u32 to cmdreply[2].
|-
| 0x000C0040
| (u32 unk) ?
|-
| 0x000D0002
| ([[IPC|kernel_processid_translatehdr]], u32 processid) ?
|}

The only sysmodule which uses this is [[Socket_Services|socket]]-sysmodule. The first command used by socket-module is cmd9.

=NWM service "nwm::SAP"=

=NWM local-WLAN [[StreetPass]] service "nwm::CEC"=
{| class="wikitable" border="1"
|-
! Command Header
! Description
|-
| 0x00060002
| Unknown, called by CECD module, cmdbuf[2] takes an event handle.
|-
| 0x000D0082
| [[NWMCEC:SendProbeRequest|SendProbeRequest]]
|}

=NWM service "nwm::EXT"=
{| class="wikitable" border="1"
|-
! Command Header
! Available since system version
! Description
|-
| 0x00010000
| <=[[2.0.0-2]]
| ?
|-
| 0x00020000
| <=[[2.0.0-2]]
| ?
|-
| 0x00030000
| <=[[2.0.0-2]]
| ?
|-
| 0x00040040
| <=[[2.0.0-2]]
| ?
|-
| 0x00050002
| <=[[2.0.0-2]]
| ?
|-
| 0x00060000
| <=[[2.0.0-2]]
| ?
|-
| 0x00070000
| <=[[2.0.0-2]]
| This copies 0x1C-bytes from NWM-module state to the data starting at cmdreply[2].
|-
| 0x00080040
| <=[[2.0.0-2]]
| [[NWMEXT:ControlWirelessEnabled|ControlWirelessEnabled]]
|-
| 0x00090000
| <=[[2.0.0-2]]
| ?
|}

=NWM service "nwm::TST"=

=BeaconDataReply Structure=
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Max output size, from the command request.
|-
| 0x4
| 0x4
| Total amount of output data written relative to struct+0. 0xC when there's no entries.
|-
| 0x8
| 0x4
| Total entries, 0 for none.
|-
| 0xC
| <Rest of the structure>
| Beacon entries.
|}

Beacon entry:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| Size of this entire entry. The next entry starts at curentry_startoffset+curentry_size.
|-
| 0x4
| 0x1
| ?
|-
| 0x5
| 0x1
| AP wifi channel.
|-
| 0x6
| 0x1
| ?
|-
| 0x7
| 0x1
| ?
|-
| 0x8
| 0x6
| AP MAC address.
|-
| 0xE
| 0x6
| ?
|-
| 0x14
| 0x4
| Size of this entire entry, games use this value to traverse the beacons list.
|-
| 0x18
| 0x4
| Value 0x1C(size of this header and/or offset to the actual beacon data).
|-
| 0x1C
| Entry_size - 0x1C
| The actual beacon data is located here, starting at the 802.11 management frame header.
|}

This section describes the structure returned by [[NWMINF:RecvBeaconBroadcastData]] and [[NWMUDS:RecvBeaconBroadcastData]].

=ScanInputStruct=
{| class="wikitable" border="1"
|-
! Index Word
! Description
|-
| 0
| Two unknown u16s.
|-
| 1
| Two unknown u16s.
|-
| 2-3
| Host MAC address. The 6-bytes located here are normally all 0xFF, for all hosts. Otherwise when not set to broadcast-MAC, the command will only return info for the specified host MAC address.
|-
| 4-12
| Uninitialized for UDS.
|}

This section describes the 0x34-byte input structure used by [[NWMINF:RecvBeaconBroadcastData]] and [[NWMUDS:RecvBeaconBroadcastData]].

=Local-WLAN=
UDS is used for 3DS<>3DS local-WLAN communications, and for 3DS<>Wii U communications. The latter is mainly only used for multi-player in games.

All UDS local-WLAN communications have the CCMP key for data encryption generated via NWM module. The CCMP key passed to nwm::CEC commands(stored in a 0x44-byte input structure) for [[StreetPass]] is generated by the CECD module. The input data used with [[Process_Services|EncryptDecryptAes]] with [[PSPXI:EncryptDecryptAes|keytype1]] is a MD5 hash over the input passphrase. This input passphrase is fixed for [[Download Play]], it's unique per local-WLAN application. The CTR is a MD5 hash over the below 0x10-byte structure. The output from encrypting that data with AES-CTR is the final CCMP key. This passphrase is a raw input buffer: while the passphrase specified by user-processes is normally a string with the NUL-terminator included, it can be anything(like the [[DLP_Services|WirelessRebootPassphrase]] for example).

The maximum number of nodes(including the host) which can be on an UDS network is 16.

==NodeID==
There are two types of client connections: regular Client, and Spectator. The latter ''never'' sends ''any'' 802.11 frame at all to the host, hence ''nothing'' actually connected to the network(including the host) can know about any spectators. Once a spectator is "connected" to a network, it can only receive broadcasted data, no sending.

DLP-client connects to the network as a spectator during DLP scanning to get various [[Download_Play|metadata]] including icon data.

===NetworkNodeID===
This is the network u16 ID for each device on the UDS network. NodeID 0xFFFF is a broadcast alias. 0x1 is for the host, the 0x2 for the first client, 0x3 for the second client, and so on.

The spectator doesn't have a NetworkNodeID, since it can't [[NWMUDS:SendTo|send]] any data.

NetworkNodeIDs for clients do not change when any clients disconnect, likewise for the encrypted node-listing stored in the wifi beacons. When a client disconnects, the corresponding NetworkNodeID bit in the [[NWMUDS:GetConnectionStatus|node_bitmask]] is cleared. When a client is connecting, the client is assigned the NetworkNodeID with the lowest corresponding clear-bit in the [[NWMUDS:GetConnectionStatus|node_bitmask]], then that bit is set.

===BindNodeID===
This u32 is an ID only used on the local device. How many devices are on the network or which device this system is does not affect this ID.

The spectator uses BindNodeID 0x1. DLP uses BindNodeID 0x3 when connecting as an actual client. Hence, it seems BindNodeID bit0 is spectator-related. All normal nodes(host/client) start with BindNodeID 0x2. When connecting to a network again(and probably with network creation) without reinitializing NWMUDS, official user processes increase the used BindNodeID by 0x2.

BindNodeID value 0x0 is invalid. The maximum number of BindNodeIDs which can be open at the same time is 16.

==Application data transfer==
The protocol used for sending/receiving data over the network with UDS by official applications is [[PRUDP]](in some cases at least). Mario Kart 7 uses PRUDP here. Triforce Heroes uses plaintext for whatever protocol it uses for UDS.

The UDS version of [[PRUDP]] is different from the normal UDP version it appears(no afa1/a1af data for example).

==Communication protocol==
The process of connecting to a host and exchanging data follows the sequence:

Client->Server: Authentication frame SEQ1

Server->Client: Authentication frame SEQ2

[There does not appear to be an association request frame sent by the client to the server, it is however possible that it was sent and just not captured by the test equipment]

Server->Client: Association Response frame with association id

[From here on, the client is connected to the server]

Client->Server: Encrypted data packet containing an 8-byte 802.2 LLC header with ethertype = EAPoL (0x888E) and an u16 header of 0x201 ([[NWM_Services#EAPoL-Start frame|EAPoL-Start]])

Server->Broadcast: Encrypted data packet containing the updated node information after the client connected (Using ethertype = SecureData).

Server->Client: Encrypted data packet containing an 8-byte 802.2 LLC header with ethertype = EAPoL (0x888E) and an u16 header of 0x0202([[NWM_Services#EAPoL-Logoff frame|EAPoL-Logoff]])

[From here on, data packets sent using SendTo are encapsulated with an LLC header with ethertype = 0x876D ([[NWM_Services#SecureData NWM header|SecureData]])]

[The client also sends periodic SecureData data frames on its own, these are probably ping frames]

==Data frames==
Data is transferred over the network using [[NWMUDS:PullPacket]]/[[NWMUDS:SendTo]]. That data is transferred using 802.11 data frames using CCMP encryption. The encrypted data contained in the frame starts with the 0x8-byte [https://en.wikipedia.org/wiki/Subnetwork_Access_Protocol#Use LLC header], then the 0xE-byte NWM header, followed by the actual application data from the previously mentioned commands. When [[NWMUDS:SendTo]] was used with dst_NodeID = broadcast, the data frame is sent to the 802.11 broadcast MAC address. Otherwise with a specific NodeID, the data frame is sent to the actual MAC address for that device.

Official application data is normally stored here as big-endian.

Application data packets are sent to the host using 802.11 unicast, which then acts as a router and forwards the packet to the right destination node id based on the SecureData header using either broadcast or unicast, it is not yet known how it chooses which to use.

==Special data channels==
{| class="wikitable" border="1"
|-
! Channel
! Description
|-
| 0x101
| Used when broadcasting the updated node information after a new client connects.
|-
| 0x103
| Used when sending what appears to be "ping" or "null" frames.
|-
| 0x104
| Used to signal the ejection of all spectators in the network.
|}

==SecureData NWM header==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x2
| Size of the entire frame minus the 8 bytes from the LLC header.
|-
| 0x2
| 0x2
| unknown
|-
| 0x4
| 0x2
| Size of the entire frame minus 12 bytes.
|-
| 0x6
| 0x2
| Data channel. Applications can only use the low 8 bits, channels greater than 255 are reserved for management functions.
|-
| 0x8
| 0x2
| Sequence number, incremented after each sent packet.
|-
| 0xA
| 0x2
| Destination network node id
|-
| 0xC
| 0x2
| Source network node id
|}

This data is stored as big-endian.

==EAPoL-Start frame==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x2
| Always 0x201 in big-endian.
|-
| 0x2
| 0x2
| Association id of the sending client in big-endian.
|-
| 0x4
| 0x2
| Unknown. Always 0x1 in big-endian. The parser for this packet errors out if this is > 3.
|-
| 0x6
| 0x2
| Unknown
|-
| 0x8
| 0x28
| NodeInfo structure with all fields in big-endian
|}

This data is stored as big-endian.

==EAPoL-Logoff frame==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x2
| Always 0x202 in big-endian.
|-
| 0x2
| 0x2
| Unknown. Always 0?
|-
| 0x4
| 0x2
| Assigned network node id.
|-
| 0x6
| 0x6
| Mac address of the newly connected client.
|-
| 0xC
| 0x4
| Unknown
|-
| 0x10
| 0x2
| Unknown. Always 0.
|-
| 0x12
| 0x1
| Number of connected nodes, including the new client.
|-
| 0x13
| 0x1
| Max number of nodes.
|-
| 0x14
| 0x2
| Always 0.
|-
| 0x16
| 0x2
| Unknown.
|-
| 0x18
| 0x280
| List of 16 NodeInfo structures with all fields in big-endian
|}

This data is stored as big-endian.

==Structure used for generating the CTR for CCMP key generation==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x4
| wlancommID
|-
| 0x4
| 0x4
| networkID
|-
| 0x8
| 0x6
| Host MAC address.
|-
| 0xE
| 0x2
| id8
|}

This data is stored as little-endian.

==CTR used for beacon tags crypto==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x6
| Host MAC address
|-
| 0x6
| 0x4
| wlancommID
|-
| 0xA
| 0x1
| id8
|-
| 0xB
| 0x1
| Padding, value zero.
|-
| 0xC
| 0x4
| networkID
|}

This data is stored as little-endian. All data here is all-zero except for the MAC address, when the u8 at offset 0x8 in the network-struct is 0.

==Network structure==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x6
| This is the MAC address of the host. This is used for when [[NWMUDS:ConnectToNetwork|connecting]] to the network.
|-
| 0x6
| 0x1
| This is actually written as an u16 without byte-swapping. This is the network wifi channel. When connecting this is normally non-zero. When hosting, this can be 0 to automatically select a channel, otherwise the specified channel is used. When non-zero official user-processes require this value to be one of the following when hosting: 1, 6, or 11.
|-
| 0x7
| 0x1
| Padding
|-
| 0x8
| 0x1
| Initialized flag. Must be non-zero otherwise NWM-module will use value 0x0 for most/all(?) fields in this structure when reading these fields.
|-
| 0xC
| 0x3
| This is the OUI value for use with the beacon tags. Normally this is 001F32.
|-
| 0xF
| 0x1
| OUI type (21/0x15)
|-
| 0x10
| 0x4
| wlancommID. Local-WLAN communication ID, normally this is: (user_process [[Title_list|uniqueID]] << 8) | val. Where val is 0x10 on retail([[Configuration_Memory#ENVINFO|ENVINFO]] bit0 set), 0x90 for devunit. Official software includes an input bool flag parameter for setting bit0 in this wlancommID, normally that flag isn't set. For [[Download Play]], this is always 0x2810 on retail(0x2890 on devunit).

This wlancommID can have the side affect of region-locking when the title uses the uniqueID for the current title(hard-coded in .text normally), instead of using a fixed input uniqueID for each region of the title.
|-
| 0x14
| 0x1
| id8. ID, for [[Download Play]] this is 0x55. 0x55/'U' seems to be used for networks where Wii U can host it(Download Play, Smash Bros, ...) - this value isn't known to be actually checked anywhere however.
|-
| 0x15
| 0x1
| Number of times the network structure hash was updated.
|-
| 0x16
| 0x2
| This network attributes u16 bitmask can be written via [[NWMUDS:UpdateNetworkAttribute]].
Bitmasks:
* 0x1: When set, spectators are not allowed to connect(see [[NWMUDS:EjectSpectator|here]]). Checked by official user-processes before using [[NWMUDS:ConnectToNetwork]], when connecting as a Spectator. Must be clear otherwise that code returns error 0xE10113EA. If the initialized_flag at offset 0x8 is zero, this code handles it the same way as if this bit was set. The latest NWM-module handles checking this bit itself however.
* 0x2: When set, new regular-clients are not allowed to connect.
* 0x4: Unknown, has no affect on new clients/spectators connecting. Official software has an option for setting this bit via an input flag from the same code using bitmask 0x2. Official software always clears bitmask 0x6 when unblocking new connections.
|-
| 0x18
| 0x4
| u32 networkID, randomly-generated when creating the network. The network SSID used when a client connects to the network is sprintf(out, "%08X", networkID).
|-
| 0x1C
| 0x1
| Total number of currently connected nodes, including the host.
|-
| 0x1D
| 0x1
| Maximum number of nodes, including the host. This also is the total number of entries stored under the array in the encrypted beacon data.
|-
| 0x1E
| 0xD
| ?
|-
| 0x2B
| 0x14
| SHA1 hash of the network structure, starting at the OUI field (offset 0xC) and spanning SizeOfAppData + 0x34. The unused space of the app data buffer is not hashed.
|-
| 0x3F
| 0x1
| Size of appdata.
|-
| 0x40
| 0xC8
| Appdata(Application data), if any. Size of the appdata is specified via the u8 at offset 0x3F. This data is not used when the size-field is zero.
|}

This 0x108-byte structure is used for [[NWMUDS:BeginHostingNetwork]], [[NWMUDS:ConnectToNetwork]], etc. This data is stored as big-endian.

==NodeInfo structure==
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| u64 ID, this is the UDS version of the FriendCodeSeed. This is loaded from BlkID 0x00090000 in the [[Config_Savegame|system-config]] via [[CfgS:GetConfigInfoBlk2]].
|-
| 0x8
| 0x14
| The first 0x18-bytes from BlkID 0x000A0000 in the [[Config_Savegame|system-config]] loaded via [[CfgS:GetConfigInfoBlk2]] is written here by user-processes. However, the data at +0x14(absolute offset 0x1C) is written by NWM-module later.
|-
| 0x1C
| 0x2
| u16, unknown. Set to 0x0 with the output from [[NWMUDS:DecryptBeaconData]].
|-
| 0x1E
| 0x1
| u8 flag, unknown. Originates from the u16 bitmask in the beacon node-list header. This flag is normally 0 since that bitmask is normally 0?
|-
| 0x1F
| 0x1
| Padding?
|-
| 0x20
| 0x2
| u16 NetworkNodeID
|-
| 0x22
| 0x6
| Normally zero?
|}

The first 0x20-bytes are written by the user-process before using this structure with [[NWMUDS:InitializeWithVersion]]. The data starting at offset 0x8 is only initialized by NWM-module.

== UDS Beacons ==
The UDS host broadcasts a beacon containing at least two Nintendo-vendor tags(tag number 0xDD, see above for the OUI), normally the data stored in these tags are static. The second tag contains the big-endian u32 networkID, used by the clients when connecting to the host and for the above CCMP key generation. The Nintendo-vendor tag(s) following the first two are unique to the process using UDS, these tags are used for broadcasting metadata regarding the host.

A tool for these beacons is available here: [https://github.com/yellows8/ctr-wlanbeacontool]

=== UDS Beacon Tags ===
The following is the structure of each tag, starting at the OUI. The order of the tags is the same as listed below. All data stored under these tags are stored as big-endian.

==== OUI Type 20 ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x3
| OUI, see above.
|-
| 0x3
| 0x1
| OUI type (20/0x14)
|-
| 0x4
| 0x3
| Sample data: 0a 00 00
|}

Normally the size of this tag(from the tag size field) is 0x07.

==== OUI Type 21 ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x1F
| This is the network structure starting at offset 0xC, with the first 0x1F-bytes from there.
|-
| 0x1F
| 0x14
| SHA1 hash. When doing the hashing, this hash is cleared to zero. The hash data starts at offset 0x0(OUI), and the size is 0x34 + <value of the u8 at offset 0x33>.
|-
| 0x33
| 0x1
| Size of appdata. Normally zero. When non-zero this appdata is located at offset 0x34.
|}

Normally the size of this tag(from the tag size field) is 0x34, not including appdata.

==== OUI Type 24 ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x3
| OUI, see above.
|-
| 0x3
| 0x1
| OUI type (24/0x18)
|-
| 0x4
| See below
| Encrypted data
|}

This is the tag0 used with [[NWMUDS:DecryptBeaconData]]. The size of data stored under this tag has a maximum size of 0xFA-bytes, however normally the size is smaller than that. Additional encrypted data, if any, is stored under the below tag1.

==== OUI Type 25 ====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x3
| OUI, see above.
|-
| 0x3
| 0x1
| OUI type (25/0x19)
|-
| 0x4
| See above
| Encrypted data
|}

When this exists in the beacon, this is the tag1 used with [[NWMUDS:DecryptBeaconData]]. The data stored here is the 0xFA-bytes following the previous encrypted data in tag0, for more space for storing the encrypted data.

==== Encrypted beacon data ====
The following structure is for the plaintext version of the encrypted data, stored as big-endian.

This data is encrypted with AES-CTR, by NWM module in software. The AES key is stored in NWM module itself. See above for the CTR. The size of this encrypted data is 0x12 + (0x1E*val), where val is the u8 from networkstruct offset 0x1D.

===== Structure =====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x10
| MD5 over the rest of the data following this(plaintext).
|-
| 0x10
| 0x2
| u16 bitmask. Unknown, normally 0? Bit0 is for entry0, bit1 for entry1, and so on.
|-
| 0x12
| 0x1E * <total array entries>
| This is an array of entries for each of the devices on this network, the first entry is for the host and the rest is for the client(s).
|}

===== Array entry =====
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x1C
| This is the first 0x1C-bytes of the NodeInfo structure, stored as big-endian.
|-
| 0x1C
| 0x2
| u16 NetworkNodeID, stored as big-endian.
|}

Each entry is for a node.

= Mapped IO =
''All'' of the [[IO_Registers|IO]] mapped under the NWM-module process is listed below:

{| class="wikitable" border="1"
|-
! Userland address
! Physical address
! Size
! Description
|-
| 0x1EC22000
| 0x10122000
| 0x1000
| [[WIFI_Registers]]
|-
| 0x1EC40000
| 0x10140000
| 0x1000
| [[PDN_Registers]]
|-
| 0x1EE22000
| 0x10322000
| 0x1000
|
|}

=Errors=
{| class="wikitable" border="1"
|-
! Error code
! Description
|-
| 0xC8A06C0D
| The operation being performed is already done (e.g., if you run NWMEXT_ControlWirelessEnabled to turn wifi on when it's on already, you can't turn it on again).
|-
| 0xC8A113EA
| Returned when the command isn't allowed to be used on this device.
|-
| 0xC90113FA
| Node doesn't exist / invalid NetworkNodeID?
|-
| 0xC92113FB
| Returned when trying to connect to a host when the host has the specified connection-type blocked via the network attributes. There might be other causes too.
|-
| 0xE10113E9
| Returned when the input size is invalid. Returned by [[NWMUDS:PullPacket]] when the input size is smaller than the frame_size.
|-
| 0xE10113EA
| Invalid bind / data_channel is invalid(0x0).
|}

Mii

2019-03-05T22:46:22Z

Wwylele: /* Mii Database */ Record it in little-endian

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

The default endianness in this page is little-endian, unless explicitly specified.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00000100
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x2
| Linked list tail index. 0xFFFF if the list is empty
|-
| 0x23FE
| 0x2
| Linked list head index. 0xFFFF if the list is empty
|-
| 0x2400
| 0xA410 (3000 * 0xE)
| Linked list of objects? See chapter
|-
| 0xC810
| 0xE
| Padding?
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Mii count in this section. Maximum 100
|-
| 0xC828
| 0x64 (100 * 0x1)
| Order index of Mii in this section?
|-
| 0xC88C
| 0x1C20 (100 * 0x48)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii. The "author" field is missing
|-
| 0xE4AC
| 0x12
| 01 00 [..] 00
|-
| 0xE4BE
| 0x2
| Checksum over the data above starting from 0xC820
|-
| 0xE4C0
| 0x3D860 (3000 * 0x54)
| Another array of Miis. Seems related to the CFHE section. The Mii format in this section is modified. The "author" field is missing, A 4-byte timestamp (seconds since 2000) together with 8-byte zeros(?) is appended at the end.
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long linked list node. The format is 4-byte Mii ID (See Mii format) + 6-byte MAC + 2-byte previous node index (prev) + 2-byte next node index (next).

An invalid node has value: ID = 0, MAC = 0, prev = 0x7FFF, next = 0x7FFF.

The highest bit of these fields has some special meaning and isn't part of the index value.

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x1
| Always 3?
|-
| 0x1
| 0x1
| bit 0: allow copying bit 1: private name? bit 2-3: region lock (0=no lock, 1=JPN, 2=USA, 3=EUR) bit4-5:character set(0=JPN+USA+EUR, 1=CHN, 2=KOR, 3=TWN)
|-
| 0x2
| 0x1
| Mii position shown on the selection screen bit 0-3: page index bit 4-7: slot index
|-
| 0x3
| 0x1
| bit 0-3: ? bit 4-6: version? (1=Wii, 2=DSi, 3=3DS)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Mii ID (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 28: Always set? Bit 29: set for temporary Mii Bit 30: Set for DSi mii? Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| bit 0-5: eye style bit 6-8: eye color bit 9-12: eye scale bit 13-15: eye yscale bit 16-20: eye rotation bit 21-24: eye x spacing bit 25-29: eye y position
|-
| 0x38
| 0x4
| bit 0-4: eyebrow style bit 5-7: eyebrow color bit 8-11: eyebrow scale bit 12-14: eyebrow yscale bit 16-19: eyebrow rotation bit 21-24: eyebrow x spacing bit 25-29: eyebrow y position
|-
| 0x3C
| 0x2
| bit 0-4: nose style bit 5-8: nose scale bit 9-13: nose y position
|-
| 0x3E
| 0x2
| bit 0-5: mouse style biy 6-8: mouse color bit 9-12: mouse scale bit 13-15: mouse yscale
|-
| 0x40
| 0x2
| bit 0-4: mouse y position bit 5-7: mustach style
|-
| 0x42
| 0x2
| bit 0-2: beard style bit 3-5: beard color bit 6-9: mustache scale bit 10-14:mustache y position
|-
| 0x44
| 0x2
| bit 0-3: glasses style bit 4-6: glasses color bit 7-10: glasses scale bit 11-15: glasses y position
|-
| 0x46
| 0x2
| bit 0: enable mole bit 1-4: mole scale bit 5-9: mole x position bit 10-14: mole y position
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii categories (pants colors)==

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Mii

2019-03-05T16:08:09Z

Wwylele: /* Mii Header */

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

The default endianness in this page is little-endian, unless explicitly specified.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00010000
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x2
| Linked list tail index. 0xFFFF if the list is empty
|-
| 0x23FE
| 0x2
| Linked list head index. 0xFFFF if the list is empty
|-
| 0x2400
| 0xA410 (3000 * 0xE)
| Linked list of objects? See chapter
|-
| 0xC810
| 0xE
| Padding?
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Mii count in this section. Maximum 100
|-
| 0xC828
| 0x64 (100 * 0x1)
| Order index of Mii in this section?
|-
| 0xC88C
| 0x1C20 (100 * 0x48)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii. The "author" field is missing
|-
| 0xE4AC
| 0x12
| 01 00 [..] 00
|-
| 0xE4BE
| 0x2
| Checksum over the data above starting from 0xC820
|-
| 0xE4C0
| 0x3D860 (3000 * 0x54)
| Another array of Miis. Seems related to the CFHE section. The Mii format in this section is modified. The "author" field is missing, A 4-byte timestamp (seconds since 2000) together with 8-byte zeros(?) is appended at the end.
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long linked list node. The format is 4-byte Mii ID (See Mii format) + 6-byte MAC + 2-byte previous node index (prev) + 2-byte next node index (next).

An invalid node has value: ID = 0, MAC = 0, prev = 0x7FFF, next = 0x7FFF.

The highest bit of these fields has some special meaning and isn't part of the index value.

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x1
| Always 3?
|-
| 0x1
| 0x1
| bit 0: allow copying bit 1: private name? bit 2-3: region lock (0=no lock, 1=JPN, 2=USA, 3=EUR) bit4-5:character set(0=JPN+USA+EUR, 1=CHN, 2=KOR, 3=TWN)
|-
| 0x2
| 0x1
| Mii position shown on the selection screen bit 0-3: page index bit 4-7: slot index
|-
| 0x3
| 0x1
| bit 0-3: ? bit 4-6: version? (1=Wii, 2=DSi, 3=3DS)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Mii ID (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 28: Always set? Bit 29: set for temporary Mii Bit 30: Set for DSi mii? Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| bit 0-5: eye style bit 6-8: eye color bit 9-12: eye scale bit 13-15: eye yscale bit 16-20: eye rotation bit 21-24: eye x spacing bit 25-29: eye y position
|-
| 0x38
| 0x4
| bit 0-4: eyebrow style bit 5-7: eyebrow color bit 8-11: eyebrow scale bit 12-14: eyebrow yscale bit 16-19: eyebrow rotation bit 21-24: eyebrow x spacing bit 25-29: eyebrow y position
|-
| 0x3C
| 0x2
| bit 0-4: nose style bit 5-8: nose scale bit 9-13: nose y position
|-
| 0x3E
| 0x2
| bit 0-5: mouse style biy 6-8: mouse color bit 9-12: mouse scale bit 13-15: mouse yscale
|-
| 0x40
| 0x2
| bit 0-4: mouse y position bit 5-7: mustach style
|-
| 0x42
| 0x2
| bit 0-2: beard style bit 3-5: beard color bit 6-9: mustache scale bit 10-14:mustache y position
|-
| 0x44
| 0x2
| bit 0-3: glasses style bit 4-6: glasses color bit 7-10: glasses scale bit 11-15: glasses y position
|-
| 0x46
| 0x2
| bit 0: enable mole bit 1-4: mole scale bit 5-9: mole x position bit 10-14: mole y position
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii categories (pants colors)==

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Mii

2019-03-05T16:07:04Z

Wwylele: /* Mii format */

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

The default endianness in this page is little-endian, unless explicitly specified.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00010000
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x2
| Linked list tail index. 0xFFFF if the list is empty
|-
| 0x23FE
| 0x2
| Linked list head index. 0xFFFF if the list is empty
|-
| 0x2400
| 0xA410 (3000 * 0xE)
| Linked list of objects? See chapter
|-
| 0xC810
| 0xE
| Padding?
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Mii count in this section. Maximum 100
|-
| 0xC828
| 0x64 (100 * 0x1)
| Order index of Mii in this section?
|-
| 0xC88C
| 0x1C20 (100 * 0x48)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii. The "author" field is missing
|-
| 0xE4AC
| 0x12
| 01 00 [..] 00
|-
| 0xE4BE
| 0x2
| Checksum over the data above starting from 0xC820
|-
| 0xE4C0
| 0x3D860 (3000 * 0x54)
| Another array of Miis. Seems related to the CFHE section. The Mii format in this section is modified. The "author" field is missing, A 4-byte timestamp (seconds since 2000) together with 8-byte zeros(?) is appended at the end.
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long linked list node. The format is 4-byte Mii ID (See Mii format) + 6-byte MAC + 2-byte previous node index (prev) + 2-byte next node index (next).

An invalid node has value: ID = 0, MAC = 0, prev = 0x7FFF, next = 0x7FFF.

The highest bit of these fields has some special meaning and isn't part of the index value.

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x1
| Always 3?
|-
| 0x1
| 0x1
| bit 0: allow copying bit 1: private name? bit 2-3: region lock (0=no lock, 1=JPN, 2=USA, 3=EUR) bit4-5:character set(0=JPN+USA+EUR, 1=CHN, 2=KOR, 3=TWN)
|-
| 0x2
| 0x1
| Mii position shown on the selection screen bit 0-3: page index bit 4-7: slot index
|-
| 0x3
| 0x1
| bit 0-3: ? bit 4-6: version? (1=Wii, 2=DSi, 3=3DS)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Mii ID (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 28: Always set? Bit 29: set for temporary Mii Bit 30: Set for DSi mii? Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| bit 0-5: eye style bit 6-8: eye color bit 9-12: eye scale bit 13-15: eye yscale bit 16-20: eye rotation bit 21-24: eye x spacing bit 25-29: eye y position
|-
| 0x38
| 0x4
| bit 0-4: eyebrow style bit 5-7: eyebrow color bit 8-11: eyebrow scale bit 12-14: eyebrow yscale bit 16-19: eyebrow rotation bit 21-24: eyebrow x spacing bit 25-29: eyebrow y position
|-
| 0x3C
| 0x2
| bit 0-4: nose style bit 5-8: nose scale bit 9-13: nose y position
|-
| 0x3E
| 0x2
| bit 0-5: mouse style biy 6-8: mouse color bit 9-12: mouse scale bit 13-15: mouse yscale
|-
| 0x40
| 0x2
| bit 0-4: mouse y position bit 5-7: mustach style
|-
| 0x42
| 0x2
| bit 0-2: beard style bit 3-5: beard color bit 6-9: mustache scale bit 10-14:mustache y position
|-
| 0x44
| 0x2
| bit 0-3: glasses style bit 4-6: glasses color bit 7-10: glasses scale bit 11-15: glasses y position
|-
| 0x46
| 0x2
| bit 0: enable mole bit 1-4: mole scale bit 5-9: mole x position bit 10-14: mole y position
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii Header==
* Byte 0: generally equals 3 (category?)
* Byte 1: 0/1 = copying off/on
* Byte 2, most significant hex digit: position on page (0-9)
* Byte 2, least significant hex digit: page (0-9)
* Byte 3: generally 0x30 (always for user-created ones?)

===Mii categories (pants colors)===

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Mii

2019-03-05T16:06:46Z

Wwylele:

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

The default endianness in this page is little-endian, unless explicitly specified.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00010000
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x2
| Linked list tail index. 0xFFFF if the list is empty
|-
| 0x23FE
| 0x2
| Linked list head index. 0xFFFF if the list is empty
|-
| 0x2400
| 0xA410 (3000 * 0xE)
| Linked list of objects? See chapter
|-
| 0xC810
| 0xE
| Padding?
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Mii count in this section. Maximum 100
|-
| 0xC828
| 0x64 (100 * 0x1)
| Order index of Mii in this section?
|-
| 0xC88C
| 0x1C20 (100 * 0x48)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii. The "author" field is missing
|-
| 0xE4AC
| 0x12
| 01 00 [..] 00
|-
| 0xE4BE
| 0x2
| Checksum over the data above starting from 0xC820
|-
| 0xE4C0
| 0x3D860 (3000 * 0x54)
| Another array of Miis. Seems related to the CFHE section. The Mii format in this section is modified. The "author" field is missing, A 4-byte timestamp (seconds since 2000) together with 8-byte zeros(?) is appended at the end.
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long linked list node. The format is 4-byte Mii ID (See Mii format) + 6-byte MAC + 2-byte previous node index (prev) + 2-byte next node index (next).

An invalid node has value: ID = 0, MAC = 0, prev = 0x7FFF, next = 0x7FFF.

The highest bit of these fields has some special meaning and isn't part of the index value.

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

Note: 0x18-3B have been copied as-is from [[Mii_Maker#Mii_QR_Code_format|the QR code specification]], so they're unverified.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x1
| Always 3?
|-
| 0x1
| 0x1
| bit 0: allow copying bit 1: private name? bit 2-3: region lock (0=no lock, 1=JPN, 2=USA, 3=EUR) bit4-5:character set(0=JPN+USA+EUR, 1=CHN, 2=KOR, 3=TWN)
|-
| 0x2
| 0x1
| Mii position shown on the selection screen bit 0-3: page index bit 4-7: slot index
|-
| 0x3
| 0x1
| bit 0-3: ? bit 4-6: version? (1=Wii, 2=DSi, 3=3DS)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Mii ID (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 28: Always set? Bit 29: set for temporary Mii Bit 30: Set for DSi mii? Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| bit 0-5: eye style bit 6-8: eye color bit 9-12: eye scale bit 13-15: eye yscale bit 16-20: eye rotation bit 21-24: eye x spacing bit 25-29: eye y position
|-
| 0x38
| 0x4
| bit 0-4: eyebrow style bit 5-7: eyebrow color bit 8-11: eyebrow scale bit 12-14: eyebrow yscale bit 16-19: eyebrow rotation bit 21-24: eyebrow x spacing bit 25-29: eyebrow y position
|-
| 0x3C
| 0x2
| bit 0-4: nose style bit 5-8: nose scale bit 9-13: nose y position
|-
| 0x3E
| 0x2
| bit 0-5: mouse style biy 6-8: mouse color bit 9-12: mouse scale bit 13-15: mouse yscale
|-
| 0x40
| 0x2
| bit 0-4: mouse y position bit 5-7: mustach style
|-
| 0x42
| 0x2
| bit 0-2: beard style bit 3-5: beard color bit 6-9: mustache scale bit 10-14:mustache y position
|-
| 0x44
| 0x2
| bit 0-3: glasses style bit 4-6: glasses color bit 7-10: glasses scale bit 11-15: glasses y position
|-
| 0x46
| 0x2
| bit 0: enable mole bit 1-4: mole scale bit 5-9: mole x position bit 10-14: mole y position
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii Header==
* Byte 0: generally equals 3 (category?)
* Byte 1: 0/1 = copying off/on
* Byte 2, most significant hex digit: position on page (0-9)
* Byte 2, least significant hex digit: page (0-9)
* Byte 3: generally 0x30 (always for user-created ones?)

===Mii categories (pants colors)===

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Mii

2019-03-05T15:49:29Z

Wwylele:

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

The default endianness in this page is little-endian, unless explicitly specified.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00010000
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x2
| Linked list tail index. 0xFFFF if the list is empty
|-
| 0x23FE
| 0x2
| Linked list head index. 0xFFFF if the list is empty
|-
| 0x2400
| 0xA410 (3000 * 0xE)
| Linked list of objects? See chapter
|-
| 0xC810
| 0xE
| Padding?
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Mii count in this section. Maximum 100
|-
| 0xC828
| 0x64 (100 * 0x1)
| Order index of Mii in this section?
|-
| 0xC88C
| 0x1C20 (100 * 0x48)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii. The "author" field is missing
|-
| 0xE4AC
| 0x12
| 01 00 [..] 00
|-
| 0xE4BE
| 0x2
| Checksum over the data above starting from 0xC820
|-
| 0xE4C0
| 0x3D860 (3000 * 0x54)
| Another array of Miis. Seems related to the CFHE section. The Mii format in this section is modified. The "author" field is missing, A 4-byte timestamp (seconds since 2000) together with 8-byte zeros(?) is appended at the end.
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long linked list node. The format is 4-byte Mii ID (See Mii format) + 6-byte MAC + 2-byte previous node index (prev) + 2-byte next node index (next).

An invalid node has value: ID = 0, MAC = 0, prev = 0x7FFF, next = 0x7FFF.

The highest bit of these fields has some special meaning and isn't part of the index value.

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

Note: 0x18-3B have been copied as-is from [[Mii_Maker#Mii_QR_Code_format|the QR code specification]], so they're unverified.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Mii Header (see chapter)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Mii ID (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| unknown
|-
| 0x38
| 0x1
| bit 0-4: eyebrow style bit 5-7: eyebrow color
|-
| 0x39
| 0x1
| bit 0-3: eyebrow scale bit 4-6: eyebrow yscale
|-
| 0x3A
| 0x2
| note that the bytes are swapped over (little-endian layout) bit 0-3: eyebrow rotation bit 5-8: eyebrow x spacing bit 9-13: eyebrow y position
|-
| 0x3C
| 0x4
| unknown
|-
| 0x40
| 0x1
| Allow Copying (?) (0D on 0E off 8D on)
|-
| 0x41
| 0x7
| unknown
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii Header==
* Byte 0: generally equals 3 (category?)
* Byte 1: 0/1 = copying off/on
* Byte 2, most significant hex digit: position on page (0-9)
* Byte 2, least significant hex digit: page (0-9)
* Byte 3: generally 0x30 (always for user-created ones?)

===Mii categories (pants colors)===

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Mii

2019-02-19T15:48:52Z

Wwylele: /* Mii Database */ Confirmed another checksum according to MarioCart DLP child code

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00010000
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x4
| Header 0xFFFFFFFF
|-
| 0x2400
| 0xA41E
| Array of objects? See chapter
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Header? 0x39000000
|-
| 0xC861
| 0x2B
| Weird padding? 0x00
|-
| 0xC88C
| 0x1C20 (?)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii.
|-
| 0xE4AC
| 0x12
| 01 00 [..] 00
|-
| 0xE4BE
| 0x2
| Checksum over the data above starting from 0xC820
|-
| 0xE4C0
| 0x3D860
| Empty (00)
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long item.

On my database, they're all 0000 0000 0000 0000 0000 FF7F FF7F.

Wild speculation: blacklist of already scanned celebrity (gold) Mii QRs?

Alternative interpretation: FFFF FFFF 0000 0000 0000 0000 0000 is the 1st item; FF7F FF7F 0000 [...] the 2nd, etc;

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

Note: 0x18-3B have been copied as-is from [[Mii_Maker#Mii_QR_Code_format|the QR code specification]], so they're unverified.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Mii ID (see chapter)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Specialness and date of creation (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| unknown
|-
| 0x38
| 0x1
| bit 0-4: eyebrow style bit 5-7: eyebrow color
|-
| 0x39
| 0x1
| bit 0-3: eyebrow scale bit 4-6: eyebrow yscale
|-
| 0x3A
| 0x2
| note that the bytes are swapped over (little-endian layout) bit 0-3: eyebrow rotation bit 5-8: eyebrow x spacing bit 9-13: eyebrow y position
|-
| 0x3C
| 0x4
| unknown
|-
| 0x40
| 0x1
| Allow Copying (?) (0D on 0E off 8D on)
|-
| 0x41
| 0x7
| unknown
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii ID==
* Byte 0: generally equals 3 (category?)
* Byte 1: 0/1 = copying off/on
* Byte 2, most significant hex digit: position on page (0-9)
* Byte 2, least significant hex digit: page (0-9)
* Byte 3: generally 0x30 (always for user-created ones?)

===Mii categories (pants colors)===

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Mii

2019-02-19T15:40:10Z

Wwylele: /* Mii Database */ Fix obvious offset/size typo

Originally [http://wiibrew.org/wiki/Mii_Data created for the Nintendo Wii] (and backported to a selection of DS/i games), the '''Mii''' format was expanded with a larger selection of facial features and a new "copying" permission for the 3DS family, and later implemented as-is on Wii U.

See [[Mii Maker]] for the application chiefly designed to create, edit, delete, and trade Miis or convert them from and to a QR code.

==Mii Database==
Format of the Mii main database '''CFL_DB.dat''', found in [[Extdata#NAND_Shared_Extdata|shared extdata]] archive f0000000b.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Header "CFOG" (Mii Maker section)
|-
| 0x4
| 0x4
| Header 0x00010000
|-
| 0x8
| 0x23F0 (100 * 0x5C)
| Array of owned (saved in Mii Maker) Miis. Order in file is unrelated to canonical order in-app.
|-
| 0x23F8
| 0x4
| Header "CFHE"
|-
| 0x23FC
| 0x4
| Header 0xFFFFFFFF
|-
| 0x2400
| 0xA41E
| Array of objects? See chapter
|-
| 0xC81E
| 0x2
| Checksum of all of the above (the first 0xC81E byte). See section [[#Checksum|below]].
|-
| 0xC820
| 0x4
| Header "CFRA" (Invitations section)
|-
| 0xC824
| 0x4
| Header? 0x39000000
|-
| 0xC861
| 0x2B
| Weird padding? 0x00
|-
| 0xC88C
| 0x1C20 (?)
| Array of Miis contributed from games, used for Mii Plaza "invitations" feature. The format isn't that of a full Mii.
|-
| 0xE4AC
| 0x14
| 01 00 [..] 00 D2 74
|-
| 0xE4C0
| 0x3D860
| Empty (00)
|}
When encrypted in QR codes, 4 additional bytes are added. Two null bytes and a CRC-16. It's the exact same CRC-16 as for the Wii blocks on the 0x5e first bytes. It seems that the CRC is ignored, the Mii Maker expecting the result of APT:Unwrap to detect integrity loss.

==CFHE object==

A 0xE-byte long item.

On my database, they're all 0000 0000 0000 0000 0000 FF7F FF7F.

Wild speculation: blacklist of already scanned celebrity (gold) Mii QRs?

Alternative interpretation: FFFF FFFF 0000 0000 0000 0000 0000 is the 1st item; FF7F FF7F 0000 [...] the 2nd, etc;

==Checksum==

The algorithm used to verify the integrity of the database is based on [http://srecord.sourceforge.net/crc16-ccitt.html CRC16-CCITT], though it's an incorrect implementation. It is the same algorithm used to verify [http://wiibrew.org/wiki/Mii_Data#Block_format Mii Data on the Wii].

To obtain the correct value for the checksum, apply the algorithm to the first 0xC81E bytes of the database. This can be done using [https://gbatemp.net/threads/tutorial-give-your-mii-gold-pants-and-use-it-for-streetpass.379146/page-24#post-6569186 FixCRC]; alternativly a pseudocode implementation of the checksum algorithm is given below:

<source lang="python">
def crc16_CCITTWii(u8[]: data) -> u16:
"""Calculate a checksum of data using the CRC16-CCITT implementation of the Wii

This implementation uses 0x0000 as the starting value, which is different
from what CRC16-CCITT specifies.
"""

# note: a correct implementation of CRC16-CCITT
# would initialize this to 0xffff
u32 crc := 0x0

for byte in data:
# Iterate over every of the 8 bits in byte.
# Begin with the most significant bit. (7, 6, ... , 1, 0)
for bit in 7..0:
# & - binary `and'; <</>> - bitshift left/right; ^ - binary `xor'
crc := (
(crc << 1) | ((byte >> bit) & 0x1)
^ (0x1021 if crc & 0x8000 else 0)
)

for _ in 0..15:
crc := (crc << 1) ^ (0x1021 if crc & 0x8000 else 0)

# only return the lowest 16 bit of crc
return (u16) (crc & 0xffff)

checksum := crc16_CCITTWii(miidb[0:0xc81e]) # checksum over the first 0xc81e bytes
</source>

==Mii format==

Note: 0x18-3B have been copied as-is from [[Mii_Maker#Mii_QR_Code_format|the QR code specification]], so they're unverified.

{| class="wikitable"
|-
! Offset
! Length
!
|-
| 0x0
| 0x4
| Mii ID (see chapter)
|-
| 0x4
| 0x8
| System ID (identifies owner, for purpose of enforcing editing restrictions and blue pants). Is not tied to the MAC address anymore.
|-
| 0xC
| 0x4
| Specialness and date of creation (big-endian 32bit unsigned integer): Bit 0..27: (bit[0..27] * 2) = date of creation (seconds since 01/01/2010 00:00:00) Bit 31: not set iff Mii is special
|-
| 0x10
| 0x6
| Creator's full MAC
|-
| 0x16
| 0x2
| Padding (0000)
|-
| 0x18
| 0x2
| Bit-mapped: Birthday (4bit-day,5bit-month), Sex, Shirt color, Favorite (0x40 bit at 0x19)
|-
| 0x1A
| 0x14
| UTF-16 Mii Name (10 chars max, 0000 terminated)
|-
| 0x2E
| 0x2
| width & height
|-
| 0x30
| 0x1
| bit 0: disable sharing bit 1-4: face shape bit 5-7: skin color
|-
| 0x31
| 0x1
| bit 0-3: wrinkles bit 4-7: makeup
|-
| 0x32
| 0x1
| hair style
|-
| 0x33
| 0x1
| bit 0-2: hair color bit 3: flip hair
|-
| 0x34
| 0x4
| unknown
|-
| 0x38
| 0x1
| bit 0-4: eyebrow style bit 5-7: eyebrow color
|-
| 0x39
| 0x1
| bit 0-3: eyebrow scale bit 4-6: eyebrow yscale
|-
| 0x3A
| 0x2
| note that the bytes are swapped over (little-endian layout) bit 0-3: eyebrow rotation bit 5-8: eyebrow x spacing bit 9-13: eyebrow y position
|-
| 0x3C
| 0x4
| unknown
|-
| 0x40
| 0x1
| Allow Copying (?) (0D on 0E off 8D on)
|-
| 0x41
| 0x7
| unknown
|-
| 0x48
| 0x14
| UTF-16 Author Name (10 chars max, 0000 terminated)
|}

==Mii ID==
* Byte 0: generally equals 3 (category?)
* Byte 1: 0/1 = copying off/on
* Byte 2, most significant hex digit: position on page (0-9)
* Byte 2, least significant hex digit: page (0-9)
* Byte 3: generally 0x30 (always for user-created ones?)

===Mii categories (pants colors)===

====Special (gold) Miis====
Specialness will override any other color and make the Mii non-editable.

Copying is rumored to have to be disabled.

Zeroed system-id and timestamp?

====Imported (blue) Miis====
Any (non-gold) Mii with a different System ID will appear as a foreign one.

There is also a range of Mii IDs that are always foreign and uneditable, regardless of the System ID:

====Regular (black/red) Miis====
Always editable, since they can only appear as such on the console that created them.

====Personal (red) Mii====
A red Mii that happens to be the first in the file!

==Mii values==
Each of the following values were found with NTR Debugger:
If you want to access the value, grab the given "NTR address" and add 0x08815000.

{| class="wikitable"
|-
! Data
! NTR address
! Variation (hex)
! Notes
|-
| Face style
| 0x894
| 00-0B
| Not ordered as in editor, read below
|-
| Face color
| 0x898
| 00-05
| From top to bottom
|-
| Wrinkles
| 0x89C
| 00-0B
| Same order as displayed in editor
|-
| Makeup
| 0x8A0
| 00-0B
| Same order as displayed in editor
|-
| Hair style
| 0x8A4
| 00-84
| Not ordered as in editor, read below
|-
| Hair color
| 0x8A8
| 00-07
| From top to bottom
|-
| Hair flipped
| 0x8AC
| 1 if true
| From top to bottom
|-
| Eye style
| 0x8B0
| 00-3C
| Not ordered as in editor, read below
|-
| Eyes color
| 0x8B4
| 00-05
| From top to bottom
|-
| Eyes size
| 0x8B8
| 07-00
| Left button increases value.
|-
| Eyes thickness
| 0x8BC
| 06-00
| Left button increases value.
|-
| Eyes rotation
| 0x8C0
| 00-07
|
|-
| Eyes spacing
| 0x8C4
| 00-0C
|
|-
| Eyes height
| 0x8C8
| 00-12
|
|-
| Eyebrows style
| 0x8CC
| 00-18
| Not ordered as in editor, read below
|-
| Eyebrows color
| 0x8D0
| 00-07
| From top to bottom
|-
| Eyebrows size
| 0x8D4
| 08-00
| Left button increases value.
|-
| Eyebrows thickness
| 0x8D8
| 06-00
| Left button increases value.
|-
| Eyebrows rotation
| 0x8DC
| 00-0B
|
|-
| Eyebrows spacing
| 0x8E0
| 00-0C
|
|-
| Eyebrows height
| 0x8E4
| 03-12
| Yup, minimum is 0x03
|-
| Nose style
| 0x8E8
| 00-11
| Not ordered as in editor, read below
|-
| Nose size
| 0x8EC
| 08-00
| Left button increases value.
|-
| Nose height
| 0x8F0
| 00-12
|
|-
| Mouth style
| 0x8F4
| 00-23
| Not ordered as in editor, read below
|-
| Mouth color
| 0x8F8
| 00-04
| From top to bottom.
|-
| Mouth size
| 0x8FC
| 08-00
| Left button increases value.
|-
| Mouth thickness
| 0x900
| 06-00
| Left button increases value.
|-
| Mouth height
| 0x904
| 00-12
|
|-
| Mustache style
| 0x908
| 00-05
| Order like in editor.
|-
| Beard style
| 0x90C
| 00-05
| Order like in editor.
|-
| Mustache/Beard color
| 0x910
| 00-07
| From top to button.
|-
| Mustache size
| 0x914
| 08-00
| Left button increases value.
|-
| Mustache height
| 0x918
| 00-10
|
|-
| Glasses style
| 0x91C
| 00-08
| Order like in editor.
|-
| Glasses color
| 0x920
| 00-05
| From top to bottom
|-
| Glasses size
| 0x924
| 07-00
| Left button increases value.
|-
| Glasses height
| 0x928
| 00-14
|
|-
| Mole enable
| 0x92C
| 1 if enabled, 0 else.
|
|-
| Mole size
| 0x930
| 08-00
| Left button increases value.
|-
| Mole horiz pos
| 0x934
| 00-10
|
|-
| Mole vert pos
| 0x938
| 00-1E
|
|-
| Mii height
| 0x93C
| 00-7F
|
|-
| Mii weight
| 0x940
| 00-7F
|
|-
| Mii name
| 0x944-0x959
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Creator's name
| 0x95A-96F
| UTF-16
| Terminated with 0x0000. Not updated immediatly?
|-
| Mii gender
| 0x970
| 0: Male, 1: Female
|
|-
| Birthdate month
| 0x974
| 01-0C
|
|-
| Birthdate day
| 0x978
| 01-1F
|
|-
| Mii shirt color
| 0x97C
| 00-0B
| Ordered like in editor.
|-
| Favorite
| 0x980
| 0: false, 1: true
|
|-
| Allow copy
| 0x981
| 0: false, 1: true
|
|-
| Unused byte?
| 0x982
|
|
|-
| Allow sharing
| 0x983
| 0: true, 1: false
|
|-
| ???
| 0x984-0x98F
| All zero?
|
|-
| ???
| 0x990-0x997
| 4?
|
|}
0x08815998: Same 4 bytes as encrypted Mii: first 4 bits for Mii type, 4 next for number of seconds since 01/01/2010 00:00:00 UTC+3 (should be verified by other country and region 3DS) divided by 2.
0x0881599C: 6 bytes of MAC address of the 3DS that created the Mii.
0x088159A2: 6 unknow uses bytes
0x088159A8: Same 8 bytes as decrypted Mii at 0x04 through 0x0B. Seems NAND specific, kept the same on Miis created on same NAND but different 3DS via System Transfer. Might be a coincidence but the two first bytes are in ID0 folder name in the Nintendo 3DS folder.

===Mapped Editor <-> Hex values===

Most of the values are ordered (left button decreases, right increases, color choices are top to bottom...) but for most "main" part of the UI, where you choose the style of the part being edited, hex values has no correlation with displayed order.
Here is a JSON that can go from a Part, a Page and Position to the right hex value. This is 0 indexed (eg: datas["face"][0][11]).

<nowiki>{
face: [
0x00,0x01,0x08,
0x02,0x03,0x09,
0x04,0x05,0x0a,
0x06,0x07,0x0b
],
hairs: [
[0x21,0x2f,0x28,
0x25,0x20,0x6b,
0x30,0x33,0x37,
0x46,0x2c,0x42],
[0x34,0x32,0x26,
0x31,0x2b,0x1f,
0x38,0x44,0x3e,
0x73,0x4c,0x77],
[0x40,0x51,0x74,
0x79,0x16,0x3a,
0x3c,0x57,0x7d,
0x75,0x49,0x4b],
[0x2a,0x59,0x39,
0x36,0x50,0x22,
0x17,0x56,0x58,
0x76,0x27,0x24],
[0x2d,0x43,0x3b,
0x41,0x29,0x1e,
0x0c,0x10,0x0a,
0x52,0x80,0x81],
[0x0e,0x5f,0x69,
0x64,0x06,0x14,
0x5d,0x66,0x1b,
0x04,0x11,0x6e]
[0x7b,0x08,0x6a,
0x48,0x03,0x15,
0x00,0x62,0x3f,
0x5a,0x0b,0x78],
[0x05,0x4a,0x6c,
0x5e,0x7c,0x19,
0x63,0x45,0x23,
0x0d,0x7a,0x71],
[0x35,0x18,0x55,
0x53,0x47,0x83,
0x60,0x65,0x1d,
0x07,0x0f,0x70],
[0x4f,0x01,0x6d,
0x7f,0x5b,0x1a,
0x3d,0x67,0x02,
0x4d,0x12,0x5c],
[0x54,0x09,0x13,
0x82,0x61,0x68,
0x2e,0x4e,0x1c,
0x72,0x7e,0x6f]
],
eyebrows: [
[0x06,0x00,0x0c,
0x01,0x09,0x13,
0x07,0x15,0x08,
0x11,0x05,0x04],
[0x0b,0x0a,0x02,
0x03,0x0e,0x14,
0x0f,0x0d,0x16,
0x12,0x10,0x17]
],
nose: [
[0x01,0x0a,0x02,
0x03,0x06,0x00,
0x05,0x04,0x08,
0x09,0x07,0x0B],
[0x0d,0x0e,0x0c,
0x11,0x10,0x0f]
],
mouth: [
[0x17,0x01,0x13,
0x15,0x16,0x05,
0x00,0x08,0x0a,
0x10,0x06,0x0d],
[0x07,0x09,0x02,
0x11,0x03,0x04,
0x0f,0x0b,0x14,
0x12,0x0e,0x0c],
[0x1b,0x1e,0x18,
0x19,0x1d,0x1c,
0x1a,0x23,0x1f,
0x22,0x21,0x20]
]
}</nowiki>

Savegames

2018-10-29T20:05:51Z

Wwylele: /* File Allocation Table */ add example

This page describes the format and encryption of savegames contained in gamecards, SD and NAND. You can find savegames from various 3DS games on the [[Games]] page.

This page does not describe [[DISA and DIFF|DISA container format]], which all savegames use as wrappers.

All data in this page is little-endian unless otherwise specified. All "unused / padding" fields can contain uninitialized data unless otherwise specified.

== Overview ==
Savegames are stored in [[DISA and DIFF|DISA container format]] (follow this link for the container format description). It forms a file system inside the inner content of the container. In this page only the inner file system format of the content is described.

Unlike SD and NAND savegames, gamecard savegames has additional encryption + wear leveling layer. They are described in the following sections.

== Gamecard savegame Encryption ==

=== Repeating CTR Fail ===
On the 3DS savegames are stored much like on the DS, that is on a FLASH chip in the gamecart. On the DS these savegames were stored in plain-text but on the 3DS a layer of encryption was added. This is AES-CTR, as the contents of several savegames exhibit the odd behavior that xor-ing certain parts of the savegame together will result in the plain-text appearing.

The reason this works is because the stream cipher used has a period of 512 bytes. That is to say, it will repeat the same keystream after 512 bytes. The way you encrypt with a stream cipher is you XOR your data with the keystream as it is produced. Unfortunately, if your streamcipher repeats and you are encrypting a known plain-text (in our case, zeros) you are basically giving away your valuable keystream.

So how do you use this to decrypt a savegame on a 3DS? First off, you chunk up the savegame into 512 byte chunks. Then, you bin these chunks by their contents, discarding any that contain only FF. Now look for the most common chunk. This is your keystream. Now XOR the keystream with your original savegame and you should have a fully decrypted savegame. XOR with the keystream again to produce an encrypted savegame.

=== Savegame keyY ===

All gamecard and SD savegames are encrypted with AES-CTR. The base CTR for gamecard savegames is all-zero. The gamecard savegame [[AES|keyslots]]' keyY(these savegame keyslots use the hardware key-generator) is unique for each region and for each game. The [[NCSD]] partition flags determine the method used to generate this keyY. When the save [[NCSD]] flags checked by the running NATIVE_FIRM are all-zero, the system will use the repeating CTR, otherwise a proper CTR which never repeats within the image is used.

The [[AES]]-CMAC (which uses a hardware key-generator keyslot, as mentioned above) at the the beginning of the savegame must match the calculated CMAC using the DISA/DIFF data, otherwise the savegame is considered corrupted(see below).

When all of the flags checked by the running NATIVE_FIRM are clear, the keyY(original keyY method used with saves where the CTR repeats within the image) is the following:
{| class="wikitable" border="1"
|-
! Offset
! Size
! Description
|-
| 0x0
| 0x8
| First 8-bytes from the plaintext [[NCCH#CXI|CXI]] accessdesc signature.
|-
| 0x8
| 0x4
| u32 CardID0 from [[Gamecards|gamecard]] plaintext-mode command 0x90, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|-
| 0xC
| 0x4
| u32 CardID1 from [[Gamecards|gamecard]] plaintext-mode command 0xA0, Process9 reads this with the [[NTRCARD]] hw. The actual cmdID used by Process9 is different since Process9 reads it with the gamecard in encrypted-mode.
|}

==== [[2.0.0-2]] Hashed keyY and [[2.2.0-4]] Savegame Encryption ====

When certain [[NCSD]] partition flags are set, a SHA-256 hash is calculated over the data from the CXI(same data used with the original plain keyY), and the 0x40-bytes read from a gamecard command(this 0x40-byte data is also read by [[Process_Services_PXI|GetRomId]], which is the gamecard-uniqueID). The first 0x10-bytes from this hash is used for the keyY. When flag[7] is set, the CTR will never repeat within the save image, unlike the original CTR-method. All games which had the retail NCSD image finalized after the [[2.2.0-4]] update(and contain [[2.2.0-4]]+ in the [[System Update CFA|System update partition]]), use this encryption method.

This keyY generation method was implemented with [[2.0.0-2]] via NCSD partition flag[3], however the proper CTR wasn't implemented for flag[7] until [[2.2.0-4]]. The hashed keyY flag[3] implemented with [[2.0.0-2]] was likely never used with retail gamecards.

==== [[6.0.0-11]] Savegame keyY ====

[[6.0.0-11]] implemented support for generating the savegame keyY with a new method, this method is much more complex than previous keyY methods. This is enabled via new [[NCSD]] partition flags, all retail games which have the NCSD image finalized after the [[6.0.0-11]] release(and [[6.0.0-11]]+ in the system update partition) will have these flags set for using this new method.

A SHA-256 hash is calculated over the same data used with the above hashed keyY method, after hashing the above data the following data is hashed: the CXI programID, and the ExeFS:/.code hash from the decrypted [[ExeFS]] header. An [[AES]]-CMAC (the keyslot used for this uses the hardware key-scrambler) is then calculated over this hash, the output CMAC is used for the savegame keyY.

The keyY used for calculating this AES-CMAC is initialized while NATIVE_FIRM is loading, this keyY is generated via the [[RSA]] engine. The RSA slot used here is slot0(key-data for slot0 is initialized by bootrom), this RSA slot0 key-data is overwritten during system boot. This RSA slot0 key-data gets overwritten with the RSA key-data used for verifying RSA signatures, every time Process9 verifies any RSA signatures except for [[NCCH|NCCH]] accessdesc signatures. Starting with [[7.0.0-13]] this key-init function used at boot is also used to initialize a separate keyslot used for the new [[NCCH]] encryption method.

This [[FIRM|Process9]] key-init function first checks if a certain 0x10-byte block in the 0x01FF8000 region is all-zero. When all-zero it immediately returns, otherwise it clears that block then continues to do the key generation. This is likely for supporting launching a v6.0+ NATIVE_FIRM under this FIRM.

== Gamecard wear leveling ==

The 3DS employs a wear leveling scheme on the savegame FLASH chips(only used for CARD1 gamecards). This is done through the usage of blockmaps and a journal. The blockmap is located at offset 0 of the flash chip, and is immediately followed by the journal. The initial state is dictated by the blockmap, and the journal is then applied to that.

First, there are 8 bytes whose purposes are currently unknown. Then comes the actual blockmap.
The blockmap structure is simple:
<pre>
struct header_entry {
uint8_t phys_sec; // when bit7 is set, block has checksums, otherwise checksums are all zero
uint8_t alloc_cnt;
uint8_t chksums[8];
} __attribute__((__packed__));
</pre>

There's one entry per sector, counting from physical sector 1 (sector 0 contains the blockmap/journal).

The 2 bytes that follow the blockmap are the CRC16 (with starting value 0xFFFF (like modbus)) of the first 8 bytes and the blockmap.

Then comes the journal.
The journal structure is as follows:
<pre>
struct sector_entry {
uint8_t virt_sec; // Mapped to sector
uint8_t prev_virt_sec; // Physical sector previously mapped to
uint8_t phys_sec; // Mapped from sector
uint8_t prev_phys_sec; // Virtual sector previously mapped to
uint8_t phys_realloc_cnt; // Amount of times physical sector has been remapped
uint8_t virt_realloc_cnt; // Amount of times virtual sector has been remapped
uint8_t chksums[8];
} __attribute__((__packed__));

struct long_sector_entry{
struct sector_entry sector;
struct sector_entry dupe;
uint32_t magic;
}__attribute__((__packed__));
</pre>

With magic being a constant 0x080d6ce0.

The checksums in the blockmap/journal entries work as follows:
* each byte is the checksum of an encrypted 0x200 bytes large block
* to calculate the checksum, a CRC16 of the block (with starting value 0xFFFF) is calculated, and the two bytes of the CRC16 are XORed together to produce the 8bit checksum

== Components and partitions ==

A savegame, after unwrapping the DISA container, consists of the following components:

* SAVE header
* directory hash table
* file hash table
* file allocation table
* directory entry table
* file entry table
* data region

A DISA container can have one or two partitions, and correspondingly a savegame has two possible layouts. The layout is determined by the parameter <code>duplicate data</code> passed in [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].

=== Layout for <code>duplicate data = true</code> ===

The DISA container only has one partition which is always configured as external IVFC level 4 disabled (see [[DISA and DIFF|DISA format for details]]). All components are stored in this partition as

* SAVE header at the beginning
* directory hash table
* file hash table
* file allocation table
* data region
** directory entry table is allocated inside data region
** file entry table as well
** all file data is also allocated here

In this layout, all data is duplicated by DISA's DPFS tree, which is what the parameter <code>duplicate data</code> implies.

=== Layout for <code>duplicate data = false</code> ===

The DISA container has two partitions. Partition A is always configured as external IVFC level 4 disabled, and partition B is configured as it enabled. Components are stored among the two partitions as

* Partition A
** SAVE header at the beginning.
** directory hash table
** file hash table
** file allocation table
** directory entry table
** file entry table
* Partition B
** used as data region entirely, and only has file data allocated.

In this layout, all file system metadata is duplicated by partition A DPFS tree, but file data is not as partition B has external IVFC level 4.

=== SAVE Header ===

The SAVE header defines the rest components of the savegame. All "offsets" in the table below are relative to the beginning of partition A (inner content), while all "starting block index" are relative to the beginning of data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Magic "SAVE"
|-
| 0x04
| 4
| Magic 0x40000
|-
| 0x08
| 8
| File system Information offset (0x20)
|-
| 0x10
| 8
| Image size in blocks
|-
| 0x18
| 4
| Image block size
|-
| 0x1C
| 4
| Padding
|-
|

|

| Below is File system Information
|-
| 0x20
| 4
| Unknown
|-
| 0x24
| 4
| Data region block size
|-
| 0x28
| 8
| Directory hash table offset
|-
| 0x30
| 4
| Directory hash table bucket count
|-
| 0x34
| 4
| Padding
|-
| 0x38
| 8
| File hash table offset
|-
| 0x40
| 4
| File hash table bucket count
|-
| 0x44
| 4
| Padding
|-
| 0x48
| 8
| File allocation table offset
|-
| 0x50
| 4
| File allocation table entry count
|-
| 0x54
| 4
| Padding
|-
| 0x58
| 8
| Data region offset (if no partition B)
|-
| 0x60
| 4
| Data region block count (= File allocation table entry count)
|-
| 0x64
| 4
| Padding
|-
| 0x68
| 8
| If partition B exists: directory entry table offset;
|-
|

|

| otherwise: u32 directory entry table starting block index + u32 directory entry table block count
|-
| 0x70
| 4
| Maximum directory count
|-
| 0x74
| 4
| Padding
|-
| 0x78
| 8
| If partition B exists: file entry table offset;
|-
|

|

| otherwise: u32 file entry table starting block index + u32 file entry table block count
|-
| 0x80
| 4
| Maximum file count
|-
| 0x84
| 4
| Padding
|}

* The file/directory bucket count & maximum count are specified by the parameters of [[FS:FormatSaveData]] or [[FS:CreateSystemSaveData]].
* When partition B doesn't exist, directory & file entry tables are allocated in the data region, and while be marked allocated in file allocation table as if they are two normal files. However, only continuous allocation has been observed, so directly reading <code>block_count * block_size</code> bytes from <code>data_region + starting_block_index * block_size</code> should be safe. See the section [[#File Allocation Table]] below for more information.

=== Directory Entry Table ===

The directory entry table is an array of the entry type shown below. It describes the directory hierarchy of the file system.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index. 0 for root
|-
| 0x04
| 16
| ASCII directory name in. All zero for root
|-
| 0x14
| 4
| Next sibling directory index. 0 if this is the last one
|-
| 0x18
| 4
| First subdirectory index. 0 if not exists
|-
| 0x1C
| 4
| First file index in file entry table. 0 for empty directory
|-
| 0x20
| 4
| Padding / zero?
|-
| 0x24
| 4
| Index of the next directory in the same hash table bucket. 0 if this is the last one
|}

There are also some dummy entries in the array:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current Total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum directory count + 2
|-
| 0x08
| 28
| Padding / All zero
|-
| 0x24
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. The 1-st entry of the array is always the root. Therefore maximum entry count is two more than maximum directory count. Dummy entries are left there when deleting directories, and reserved for future use.

=== File Entry Table ===

The file entry table is an array of the entry type shown below. It contains information for each file.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Parent directory index in directory entry table
|-
| 0x04
| 16
| ASCII file name
|-
| 0x14
| 4
| Next sibling file index. 0 if this is the last one
|-
| 0x18
| 4
| Padding
|-
| 0x1C
| 4
| First block index in data region. 0x80000000 if the file is just created and has no data.
|-
| 0x20
| 8
| File Size
|-
| 0x28
| 4
| Padding?
|-
| 0x2C
| 4
| Index of the next file in the same hash table bucket. 0 if this is the last one
|}

Like directory entry table, file entry table also has some dummy entries:

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| Current total entry count
|-
| 0x04
| 4
| Maximum entry count = maximum file count + 1
|-
| 0x08
| 36
| Padding / All zero
|-
| 0x2C
| 4
| Index of the next dummy entry. 0 if this is the last one
|}

The 0-th entry of the array is always a dummy entry, which functions as the head of the dummy entry linked list. Therefore maximum entry count is one more than maximum file count. Dummy entries are left there when deleting files, and reserved for future use.

=== Directory Hash Table & File Hash Table ===

This is a u32 array of size = bucket count, each of which is an index to the directory / file entry table. The directory / file name is hashed and its entry index is put to the corresponding bucket. If there is already a directory/file entry in the bucket, then it appends to the linked list formed by <code>Index of the next directory/file in the same hash table bucket</code> field in the directory/file entry table. i.e. this is a hash table using separate chaining with linked lists

The hash function takes the parent index and the name as key. The function is equivalent to

<pre>uint32_t GetBucket(
char name[16], // takes all 16 bytes including trailing zeros
uint32_t parent_dir_index,
uint32_t bucket_count
) {
uint32_t hash = parent_dir_index ^ 0x091A2B3C;
for (int i = 0; i < 4; ++i) {
hash = (hash >> 1) | (hash << 31);
hash ^= (uint32_t)name[i * 4]
hash ^= (uint32_t)name[i * 4 + 1] << 8
hash ^= (uint32_t)name[i * 4 + 2] << 16
hash ^= (uint32_t)name[i * 4 + 3] << 24
}
return hash % bucket_count;
}
</pre>
=== File Allocation Table ===

The file allocation table is an array of a 8-byte entry shown below. The array size is actually ''one larger than'' the size recorded in the SAVE header. Each entry corresponds to a block in the data region (the block size is defined in SAVE header). However, the 0th entry corresponds to nothing, so the corresponding block index is off by one. e.g. entry 31 in this table corresponds to block 30 in the data region.

{| class="wikitable" border="1"
! Offset
! Length
! Description
|-
| 0x00
| 4
| bit[0:30]: Index U; bit[31]: Flag U
|-
| 0x04
| 4
| bit[0:30]: Index V; bit[31]: Flag V
|}

Entries in this table forms several chains, representing how blocks in the data region should be linked together. However, unlike normal FAT systems, which uses chains of entries, 3DS savegames use chain of ''nodes''. Each node spans one or multiple entries.

One node spanning <code>n</code> entries starting from <code>FAT[k]</code> is in the following format:

<pre>FAT[k + 0]:
Index_U = index of the first entry of the previous node. 0 if this is the first node.
Index_V = index of the first entry of the next node. 0 if this is the last node.
Flag_U set if this is the first node.
Flag_V set if this node has multiple entries.

FAT[k + 1]:
Index_U = k (the first entry index of this node)
Index_V = k + n - 1 (the last entry index of this node)
Flag_U always set
Flag_V always clear

FAT[k + 2] ~ FAT[k + n - 2]:
All these entries are uninitialized

FAT[k + n - 1]:
Index_U = k
Index_V = k + n - 1
Flag_U always set
Flag_V always clear
(Same values as FAT[k + 1])
</pre>
* Note: all indices above are entry indices (block index + 1)

All free blocks that are not allocated to any files also form a node chain in the allocation table. The head index of this "free chain" is recorded in <code>FAT[0].Index_V</code>. Other fields of <code>FAT[0]</code> are all zero

Here is an example: [https://raw.githubusercontent.com/wwylele/3ds-save-tool/master/disa-fat.png]

== Initialization ==

When a save FLASH contains all xFFFF blocks it's assumed uninitialized by the game cartridges and it initializes default data in place, without prompting the user. The 0xFFFFFFFF blocks are uninitialized data. When creating a non-gamecard savegame and other images/files, it's initially all 0xFFFFFFFF until it's formatted where some of the blocks are overwritten with encrypted data.

I got a new game SplinterCell3D-Pal and I downloaded the save and it was 128KB of 0xFF, except the first 0x10 bytes which were the letter 'Z' (uppercase) --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Fun Facts ==

If you have facts that you found out by looking at the binary files please share them here:

* From one save to another the game backups the last files that were in the partition and the entire image header in "random" locations.. --[[User:Elisherer|Elisherer]] 22:41, 15 October 2011 (CEST)

== Tools ==

* [https://github.com/3dshax/3ds/tree/master/3dsfuse 3dsfuse] supports reading and modifying savegames. In the mounted FUSE filesystem, the /output.sav is the raw FLASH save-image. When the save was modified, a separate tool to update the CMAC must be used with /clean.sav, prior to writing output.sav to a gamecard.
* [[3DSExplorer]] supports reading of savegames, it doesn't support reading the new encrypted savegames and maybe in the future it will support modifying (some of the modyfing code is already implemented).
* [https://github.com/wwylele/3ds-save-tool wwylele's 3ds-save-tool] supports extracting files from savegames and extdata. It properly reconstructs data from the DPFS tree and extracts files in directories hierarchy.
* [https://github.com/wwylele/3dsfuse-ex 3dsfuse-ex] similar to 3dsfuse, but supports savegame inner FS, proper DPFS handling, and automatic CMAC update. Still WIP.

[[セーブデータ|Japanese]]