YAFFS Binary Format

On NAND hardware, the data area of a chunk is stored in a page and the spare data is stored in the page’s out of band (OOB) area. When YAFFS is stored as an image file, each chunk’s data area is followed immediately by its spare data area. Chunks appear in order within a block, and blocks appear in order.

A freshly erased block reads as all 0xFF bytes. Anything that would be all 0xFF (a whole block, a single chunk, or the tags of a chunk) is considered unwritten.

All structures described in this document are byte packed: fields are stored consecutively with no implicit alignment padding. Where padding exists on disk, it is listed explicitly as a field.

YAFFS stores all integers in the native byte order of the system that wrote the filesystem. Images are most commonly little endian, and all layouts in this document assume little endian storage. A reader that supports both byte orders can detect a byte-swapped filesystem by sanity checking values it reads (for example, sequence numbers and object types have small valid ranges).

Except for the optional Tag ECC covering the tags themselves, error correction is not part of the YAFFS2 format: ECC for the data area of a chunk is the responsibility of the flash driver or MTD layer. When reading an image file rather than physical flash, no ECC processing is needed.

Each of the three timestamps is stored twice: as a 32 bit unix timestamp in atime/mtime/ctime, and as a 64 bit unix timestamp split across the two u32 values of the corresponding _64 field (low half first).

To read a timestamp, look at the second (high) u32 of the _64 field:

The 64 bit fields were a later addition (originally holding WinCE timestamps), which is why they are stored as pairs of u32 values, apart from the 32 bit fields and in a different order.

Despite its name, the access time does not track reads. Timestamps are only stored in object headers, and updating the access time on every read would mean writing a new object header for every read: far too much writing (and erasing) for a write-once log. Instead, the access time is set equal to the modification time when the object is created, and changes after that only through an explicit request to set file times (e.g. utime()), which writes a new object header.

For regular files, the file size is split across file_size_low and file_size_high:

For a file smaller than 4 GiB, a writer may store either the actual high 32 bits (0) or 0xFFFFFFFF in file_size_high; both are equally valid and decode to the same size. Current reference writers store the actual high bits; 0xFFFFFFFF is what implementations that predate the field leave behind (erased fill), which is why it means "use file_size_low only".

Extended attributes are stored in the object header chunk’s data area, immediately following the header structure, and may use the rest of the data area:

(This means the chunk data area must be larger than the object header structure for extended attributes to be usable.)

The area holds a sequence of name/value records, packed with no padding:

The list ends at the first position where a record cannot be read:

The last condition is strict: a record ending exactly at the last byte of the area is not readable, and also ends the list. Writers must therefore never write a record that ends exactly at the end of the area.

Because a new object header is written whenever an object changes, the extended attributes are rewritten with every header; there is no separate versioning for them.

First, read the tags of the first chunk of every block:

Then sort the data blocks by sequence number and scan them in decreasing order.

If Block Summaries are in use, first try to read and validate the block’s summary; on success, the tags of the data chunks come from the summary instead of their spare areas. The exception is all-zero summary entries, which record nothing about their chunk: the tags of such a chunk must still be read from its spare area (see Block Summaries).

Then, for each chunk from the last data chunk down to chunk 0, read its tags and:

A data chunk with id n holds the file’s bytes starting at offset (n - 1) * data_bytes_per_chunk, of which the first n_bytes are populated.

Missing chunks are holes: any part of a file not covered by a current data chunk reads as zero bytes. A file can be larger than its last data chunk extends; truncating a file to a larger size, or writing after seeking past the end, produces this.

A data chunk can also be partially populated (n_bytes < data_bytes_per_chunk), and not only at the end of the file: writes only rewrite the chunks they touch, so a chunk written while the file was short stays partial even after later writes grow the file past it. Only the first n_bytes bytes of the chunk are file contents; the rest of the chunk’s range is a hole, and reads as zero bytes. Readers should not depend on the stored bytes beyond n_bytes being zero, and should treat that range as a hole. The kernel implementation, however, reads the stored bytes directly, so writers must fill the data area beyond n_bytes with zero bytes.

The first (newest) object header seen for an object provides all of its metadata: type, parent, name, permissions, timestamps and size. Older headers for the same object are ignored, with one exception: shrink information must still be extracted from stale file headers (see Shrink Headers).

If the header carries Extra Tag Info, a scanner can build the full directory tree from the tags alone (type, parent, and file size / hardlink target), deferring the read of the header’s data area until the name or other details are needed. The reference implementation calls this lazy loading.

On a clean unmount, the reference implementation can write a checkpoint: a serialized dump of its runtime state that allows the next mount to skip scanning entirely. Checkpoint data is written to otherwise erased blocks using the reserved sequence number 0x21, which is the only marker identifying a checkpoint block. The tags of checkpoint chunks do not follow the normal rules described in this document; even the obj_id field is repurposed for checkpoint-internal bookkeeping.

The checkpoint format is not specified here: it is a direct serialization of implementation structures and changes between versions and configurations. The checkpoint is invalidated (its blocks erased) as soon as the filesystem is written to again, so readers can always treat checkpoint blocks as opaque, skip them, and reconstruct the filesystem by scanning as described above.

The chunk’s tags, stored in the first 16 bytes of its spare data area (image offset 2048):

This writer does not use Extra Tag Info: the most significant bit of chunk_id is clear, and the object’s type and parent are stored only in the header structure itself.

The tags are followed by the 12 byte tag ECC:

Three tag bytes have an odd number of bits set: the 0x10 at index 1 and the two 0x01 bytes at indexes 4 and 5. line_parity is therefore 1 ^ 4 ^ 5 = 0, and line_parity_inv is ~1 ^ ~4 ^ ~5 = 0xFFFFFFFF.

The data area of the chunk (image offset 0) begins with the 512 byte Object Header structure:

The rest of the data area (offsets 0x200 to 0x7FF) is 0xFF: the file has no extended attributes.

The tags of the second chunk (image offset 2112 + 2048 = 4160):

followed by its tag ECC:

The odd-parity tag bytes are at indexes 1, 4, 5 and 8, so line_parity = 1 ^ 4 ^ 5 ^ 8 = 8. With an even number of contributing indexes the inversions cancel out, so line_parity_inv has the same value.

The data area (image offset 2112) begins with the file contents:

A backwards scan of this image finds one data block, with sequence number 0x1000, and processes its two chunks from last to first:

The result is a root directory containing the single 15 byte file hello.txt.