prevnext   » WIT: Wiimms ISO Tools » Guides » WDF (Wii Disc Archive)

WDF (Wii Disc Archive)

Contents

1.   Introduction and History

When I started with the devolpment of wwt in 2009, I missed a file format to store scrubbed Wii images efficiently as regular files. The idea with WBFS files was born later, and CISO has some disadvantages.

One way to reduce the disc space is to compress the data. But compressing works only for the holes, but not for encrypted data. And random access is very difficult for compressed data. The direct support of holes seems to be much better.

So I decided to create the file format WDF. WDF is an abbreviation of either »Wiimms Disc File« or shorter »Wii Disc File«. The file format manage holes (scrubbed areas) and stores only non zero data. The result is, that WDF images are smaller than WBFS or with RAR, ZIP or 7Z compressed ISO images.

1.1   WDF Versions

In October 2009, WDF v1 was implemented. The first file header contains data members to support an internal management of split files.

In early 2010 it was clear, that the internal split file support will never be used. It is more pratical to search for the continuation file, if the first opened file is to small to hold the complete WDF. The advantage of this external management is, that joining or spliting can be done at any file positions and does not need a change of the file data.

In September 2012 I thought about a new version of WDF without split file support. The new format should also support alignment, so that USB loaders are able to use this format like WBFS files. Because of this thoughts, the behaviour of the tools were changed in October 2012 with release v2.10a: The tools ignore the split members for validation checks.

In January 2014 I decided to complete the plans of WDF v2 and implemented it. WDF v2 files are a little bit smaller than v1 files, because of the removed split file support. In the following release of the tools (v2.27a), only the reading support was enabled. The tools (wit, wwt and wdf) are able to detect and read WDF files in versions v1 and v2, but can only create v1. To enable the experimental WDF v2 writing support, the environment variable WDF2 must be set before compiling the tools:

 WDF2=1 make

2.   File Format

All WDF support data is stored in network byte order (big endian). So the usage of endian coversion functions like ntohl() is mandatory.

The following table shows the general layout of a WDF file:

General WDF file layout
Size Name Description
0x38 header The file header with a magic and basic information about the WDF file.
* padding It is possible to add padding data here to force an alignment of the data blocks.
* data The data blocks. The blocks are referenced by the elements of the chunk list. Unused areas are also possible.
8 magic2 A copy of the magic to introduce the chunk table. It should be used to validate the beginning of the chunk list.
* chunk_list The list with the chunk entries.
If a WDF file grows, the header and the chunk table is read, new data appended overwriting the second magic and the chunk table. On closing, the new chunk table is written to the end of the file and a fixed header at the beginning.

2.1   WDF v1

WDF v1 use the follwing file header since its first implementation. The split file members were never used, are obsolete and should not longer used for validation.

File header of WDF v1 (big endian)
Offset Size Type Name Description
0x00 8 char[8] magic 8 characters to identify a WDF file. The string is »WII\1DISC«. The »\1« in the middle is the C notation for ASCII character 1. The hex dump of the string is: 57 49 49 01 44 49 53 43.
0x08 4 u32 version The WDF version. Always 1 for WDF v1.
0x0c 4 u32 split_file_id This member were planned for the split file support. It should help to find the correct continuation files. The value is a random number for split files.

Because split support was never implemented, the value is always 0 and ignored on reading. Since WDF v2, it has a new meaning.

0x10 4 u32 split_file_index This member were planned for the split file support. It contains the zero based split index of the file (always 0).

The value must be ignored on reading. Since WDF v2, it has a new meaning.

0x14 4 u32 split_file_total This member were planned for the split file support. It contains the total number of split files (always 1).

The value must be ignored on reading. Since WDF v2, it has a new meaning.

0x18 8 u64 file_size The total size of the unpacked file (virtual file size).
0x20 8 u64 data_size The size of all used data areas (a statistical value).
0x28 4 u32 chunk_split_file This member were planned for the split file support. It contains the index of the file, that contains the chunk list (always 0).
0x2c 4 u32 chunk_n Number of elements in the chunk list.
0x30 8 u64 chunk_off File offset of the magic before the chunk list. All offsets are always relative to the beginning of the file. This is also the end-of-data position.
0x38 56 bytes total

The chunk list is placed at the end of the file. Directly before the chunk list, a magic is inserted with 8 bytes.

Chunk list element of WDF v1 (big endian)
Offset Size Type Name Description
0x00 4 u32 split_file_index This member were planned for the split file support. It is ignored and always 0.
0x04 8 u64 file_pos File offset to the related data block. All offsets are always relative to the beginning of the file.
0x0c 8 u64 data_off Offset of the unpacked (virtual) file.
0x14 8 u64 block_size Size of the data block.
0x1c 28 bytes total

2.2   WDF v2

WDF v2 use the following file header. There are some unneeded members. But I decided to don't shrink the header, so that it looks like a minimal modified v1 header. The changed member names have a red background.

File header of WDF v2 (big endian)
Offset Size Type Name Description
0x00 8 char[8] magic 8 characters to identify a WDF file. The string is »WII\1DISC«. The »\1« in the middle is the C notation for ASCII character 1. The hex dump of the string is: 57 49 49 01 44 49 53 43.
0x08 4 u32 version The WDF version. Always 2 for WDF v2.
0x0c 4 u32 head_size The size of this WDF header. For WDF v2 it is always 0x38 (56 bytes).
0x10 4 u32 align_factor If not NULL, it gives an information about the user wanted alignment of the WDF file on creation time.
0x14 4 u32 compatible This version number is planned for future versions of WDF. If the number is 2, then reading is fully compatible to WDF v2. For WDF v2 it is always 2 (that means: not compatible with WDF v1).
0x18 8 u64 file_size The total size of the unpacked file (virtual file size).
0x20 8 u64 data_size The size of all used data areas (a statistical value).
0x28 4 u32 reserved Always 0.
0x2c 4 u32 chunk_n Number of elements in the chunk list.
0x30 8 u64 chunk_off File offset of the magic before the chunk list. All offsets are always relative to the beginning of the file. This is also the end-of-data position.
0x38 56 bytes total

The chunk list is placed at the end of the file. Directly before the chunk list, a magic is inserted with 8 bytes.

The only change since v1 is, that the usused split file index is removed and a chunk element is now 4 bytes smaller.

Chunk list element of WDF v2 (big endian)
Offset Size Type Name Description
0x00 8 u64 file_pos File offset to the related data block. All offsets are always relative to the beginning of the file.
0x08 8 u64 data_off Offset of the unpacked (virtual) file.
0x10 8 u64 block_size Size of the data block.
0x18 24 bytes total