3dbrew

Extdata: Difference between revisions

← Older edit
Wwylele (talk | contribs)
242 edits
Nuke the old content
Mt56 (talk | contribs)
2 edits
→SD Extdata: Add Swapnote JPN ExtdataID
 
(15 intermediate revisions by 7 users not shown)
Line 1: Line 1:
This page describes the format and encryption of extdata, "extra data" stored on [[SD_Filesystem|SD card]] and [[Flash_Filesystem|NAND]].
This page describes the format and encryption of extdata, "extra data" stored on SD card and NAND, at:
At:
* nand/data/<ID>/extdata/<ExtdataID-High>
* sdmc/Nintendo 3DS/<ID0>/<ID1>/extdata/<ExtdataID-High>


(ExtdataID-High is always 00000000 for SD, and always 00048000 for NAND) Some titles can have Quota.dat stored in these directories. The directory-name for these directories is the ExtdataID-Low. Then there's a sub-directory 00000000, which contains the actual extdata. Size and number of files in this dir varies per title.
* <code>nand/data/&lt;ID&gt;/extdata/&lt;ExtdataID-High&gt;</code>
NAND stores the shared extdata and is structured exactly the same way, see [[Flash Filesystem]].
* <code>sdmc/Nintendo 3DS/&lt;ID0&gt;/&lt;ID1&gt;/extdata/&lt;ExtdataID-High&gt;</code>


Extdata image 00000001 contains a VSXE partition for the FST, the actual file data is stored in the subsequent extdata images.
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.


Regular apps can only mount SD extdata using the same extdataID which is stored in the [[NCCH#CXI|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 data in this page is little-endian. All &quot;unused / padding&quot; fields can contain uninitialized data unless otherwise specified.
All NAND extdata is shared extdata, while all SD extdata is normal extdata. Thus, normal extdata doesn't exist on NAND, and shared extdata doesn't exist on SD. The extdataID high excluding that bitmask is always zero for shared extdata.


=== Format ===
= Format =


All extdata is stored in [[DISA and DIFF|DIFF container files]] (follow this link for the container format description). The format description below is for the inner content of the containers.
To avoid confusion, the terms '''device directory / file''' and '''virtual directory / file''' are used with the following meanings:


=== Filesystem ===
* '''Device directory / file''' are the real directory / file stored on SD / NAND that can be seen under path <code>nand/data/&lt;ID&gt;/extdata/</code> or <code>sdmc/Nintendo 3DS/&lt;ID0&gt;/&lt;ID1&gt;/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.


Title extdata contains a series of extdata images which comprise an independent file system. The first image (00000001) contains the VSXE (FST) partition, and subsequent images each containing a single file. Other extdata images, such as Quota.dat and [[Title Database|database extdata]], exist independent of a FS.
An extdata consists of several device directories and files, which forms a file system consisting of multiple virtual directories and files.


==== VSXE ====
An extdata with ID <code>ExtdataId</code> has the following device files:
{| class="wikitable"
 
|-
* <code>.../extdata/&lt;ExtdataID-High&gt;/&lt;ExtdataId-Low&gt;/Quota.dat</code> (optional)
! Start
* <code>.../extdata/&lt;ExtdataID-High&gt;/&lt;ExtdataId-Low&gt;/&lt;SubDirID&gt;/&lt;SubFileID&gt;</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>&lt;SubDirID&gt;</code> and <code>&lt;SubFileID&gt;</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
! Length
! Description
! Description
|-
|-
| 0x0
| 0x00
| 4
| Magic &quot;QUOT&quot;
|-
| 0x04
| 4
| 4
| Database Magic ("VSXE")
| Magic 0x30000
|-
|-
| 0x4
| 0x08
| 4
| 4
| Magic Number (0x30000)
| 0x1000, block size
|-
|-
| 0x8
| 0x0C
| 8
| 4
| Data Table Offset
| Always 126. Probably device directory capacity. See the [[#Device Directory Capacity]] more information.
|-
|-
| 0x10
| 0x10
| 8
| 4
| File Size, divided by the value at 0x18
| Always 0?
|-
| 0x14
| 4
| Max number of blocks
|-
|-
| 0x18
| 0x18
| 8
| 4
| Usually 0x1000
| Always 0?
|-
| 0x1C
| 4
| Free blocks remained
|-
|-
| 0x20
| 0x20
| 8
| 4
| Unknown
| Always 0?
|-
| 0x24
| 4
| Always 0?
|-
|-
| 0x28
| 0x28
| 4
| 4
| 'Action' made on most recently mounted Extdata image
| Free blocks remained + (blocks occupied by the recently mounted file, specified by the ID below (0 if recently deleted))
|-
|-
| 0x2C
| 0x2C
| 4
| 4
| Unknown
| Always 0?
|-
|-
| 0x30
| 0x30
| 4
| 4
| ID of most recently mounted Extdata image
| ID of most recently mounted file. Same as the one in [[Inner_FAT#Filesystem Header]]
|-
|-
| 0x34
| 0x34
| 4
| 4
| Unknown
| Always 0?
|-
|-
| 0x38
| 0x38
| 0x100
| 4
| Mount path, from most recently mounted Extdata image
| Always 0?
|}
 
Data Table:
 
{| class="wikitable"
|-
|-
! Start
| 0x3C
! Length
| 4
! Description
| Always 0?
|-
|-
| 0x0
| 0x40
| 0x38
| 4
| Unknown
| Size in bytes of most recently mounted file (device file size). 0 if recently deleted
|-
|-
| 0x38
| 0x44
| 8
| Folder Table Offset
|}
 
===== Folder Table =====
 
Header:
{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x0
| 0x4
| Equivalent to the Used Folder Entries + 1
|-
| 0x4
| 4
| 4
| Equivalent to the Maximum Folder Entries + 1
| Always 0?
|-
| 0x8
| 0x20
| Unused
|}
 
Folder Entry:
{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x0
| 0x4
| Parent Folder Index
|-
| 0x4
| 0x10
| Folder Name (ASCII)
|-
| 0x14
| 0x4
| Previous Folder's Index
|-
| 0x18
| 0x4
| Last Folder Index Entry
|-
| 0x1C
| 0x4
| Last File Index Entry
|-
| 0x20
| 0x4
| Unknown
|-
| 0x2C
| 0x4
| Unknown
|}
|}
* The folder id/index for the current entry is related to it's position in the Folder table. The folder table is accessed like an array of 0x28 byte chunks, with the header consuming index = 0, root directory at index = 1, and the subsequent folder entries following.


===== File Table =====
== Device Directory Capacity ==


The location of the File table is calculated by aligning the end offset of the folder table to 0x1000 bytes.
A device directory in an extdata (a <code>&lt;SubDirID&gt;</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.


Header:
The number 126 is probably from some kind of other capacity of 128 with <code>&quot;.&quot;</code> and <code>&quot;..&quot;</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.
{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x0
| 0x4
| Equivalent to the Used File Entries + 1
|-
| 0x4
| 4
| Equivalent to the Maximum File Entries + 1
|-
| 0x8
| 0x28
| Unused
|}


Folder Entry:
== VSXE Filesystem ==
{| class="wikitable"
|-
! Start
! Length
! Description
|-
| 0x0
| 0x4
| Parent Folder Index
|-
| 0x4
| 0x10
| File Name (ASCII)
|-
| 0x14
| 0x4
| Previous File's Index
|-
| 0x18
| 0x4
| Unknown
|-
| 0x1C
| 0x4
| Unknown
|-
| 0x20
| 0x8
| Unique Extdata ID
|-
| 0x28
| 0x4
| Unknown
|-
| 0x2C
| 0x4
| Unknown
|}
* The file id/index for the current entry is related to it's position in the File Table, much like the folder entries in the Folder Table. The file table is accessed like an array of 0x30 byte chunks, with the header consuming index = 0, and the subsequent file entries following. The relationship between the index value of the file entry, and the actual file name of the extdata image that contains it it = index+1. For instance icon (the only file in every extdata), comes right after the header, with an index value of '1', and the icon is stored in extdata image '00000002'.


* The Unique Extdata ID, is the same value found in the DIFF header of the referenced extdata image for that file. The value changes most times the file in question is modified. When mounting an extdata image in the VSXE filesystem, if the file's extdata image doesn't have the expected Unique Extdata ID, it won't be mounted.
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


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


When extdata is created, these are *always* created regardless of whether the title actually uses them.
<pre>// See previous section about this capacity
const uint32_t device_dir_capacity = 126;


* /icon This file contains the extdata [[SMDH|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]].
// entry index is the index in the file entry table, with the first dummy entry as
* /user/ Contains the title's actual extdata files.
// index = 0, which is never used for a real file.
* /boss/ Can contain [[SpotPass]] content. SpotPass content can only be downloaded to this /boss directory.
// 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;


User extdata and SpotPass extdata use separate [[FS:OpenArchive|mount]] points at /user and /boss. Therefore one mount can't access the other directory, and also can't access /icon.(The title's SpotPass extdata can be mounted by the title itself, if it uses SpotPass)
uint32_t SubDirID = file_index / device_dir_capacity;
uint32_t SubFileID = file_index % pdevice_dir_capacity;


char extdata_path[...]; // &quot;.../extdata/&lt;ExtdataID-High&gt;/&lt;ExtdataId-Low&gt;&quot;
char device_path[...]; // output path
sprintf(device_path, &quot;%s/%08x/%08x&quot;, 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.


Other optional but notable directories include:
== Virtual File System Structure ==
* /user/ExBanner This directory can optionally store [[Extended_Banner| extended banners]]. When this is available, this banner is displayed instead of the [[CXI]] ExeFS banner. COMMON.bin stores the common exbanner, while <regionlang_code>.bin stores an optional separate region/language specific banner.(regionlang_code can be "JPN_JP", "USA_EN", etc)


=== Extdata without an independent FS ===
When extdata is created, these are ''always'' created regardless of whether the title actually uses them.


==== Quota.dat ====
* <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.


* This is contained in the Quota.dat extdata image.
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)


{| class="wikitable"
Other optional but notable directories include:
|-
! Start
! Length
! Description
|-
| 0x0
| 4
| Magic ("QUOT")
|-
| 0x4
| 4
| Magic Number (0x30000)
|-
| 0x8
| 8
| Unknown
|-
| 0x10
| 0x38
| Unknown
|}
It's unknown what this is used for.


==== Database Extdata ====
* <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>&lt;regionlang_code&gt;.bin</code> stores an optional separate region/language specific banner.(regionlang_code can be &quot;JPN_JP&quot;, &quot;USA_EN&quot;, etc)


See [[Title Database|here]].
== SD Extdata ==
 
=== SD Extdata ===
Usually the ExtdataID low is in the format '00<Unique ID>'
Usually the ExtdataID low is in the format '00<Unique ID>'


Line 377: Line 272:
|  
|  
|-
|-
| ?
| 00000516
| 00000517
| 00000517
| 00000518
| 00000518
Line 481: Line 376:
|-
|-
| ?
| ?
| ?
| 00001132
| 00001131
| 00001131
| Fantasy Life
| Fantasy Life
Line 493: Line 388:
|-
|-
| ?
| ?
| ?
| 000012c8
| 000012ca
| 000012ca
| Mario vs. Donkey Kong: Tipping Stars
| Mario vs. Donkey Kong: Tipping Stars
Line 540: Line 435:
|  
|  
|-
|-
| ?
| 000016C6
| ?
| ?
| 00001678
| 00001678
Line 553: Line 448:
|-
|-
| ?
| ?
| ?
| 0000198e
| 0000198f
| 0000198f
| Animal Crossing: New Leaf - Welcome amiibo
| Animal Crossing: New Leaf - Welcome amiibo
Line 564: Line 459:
|  
|  
|-
|-
| ?
| 00001a2c
| ?
| ?
| 00001a2e
| 00001a2e
Line 571: Line 466:
|}
|}


=== NAND Shared Extdata ===
== NAND Shared Extdata ==
{| class="wikitable" border="1"
{| class="wikitable" border="1"
|-
|-
Line 651: Line 546:
Empty space is filled with 0xC-long sequences of 00 00 ... 07
Empty space is filled with 0xC-long sequences of 00 00 ... 07


=== Tools ===
== Tools ==
 
* [https://github.com/wwylele/3ds-save-tool 3ds-save-tool] - Extract/verifies extdata
* [https://github.com/ps3hen/ctr_toolkit/tree/master/extdata_tool extdata_tool] - Extract/verifies standalone extdata images and title extdata FS.
Retrieved from "https://www.3dbrew.org/wiki/Extdata"