Expand description
Pure-Rust LittleFS v2 implementation.
This module implements the LittleFS v2 on-disk metadata format without any C
dependencies. Phase 1 covered read-only access to the root directory’s metadata
pair (blocks 0/1), including inline file data. Phase 1b adds subdirectory
traversal by following each directory entry’s DIRSTRUCT tag to its child
metadata pair, and decodes CTZ skip-lists for files too large to fit inline.
Phase 2 adds write support — write_file/delete_file/rename_file — real
device-round-trip verified (see TODO.md). All three accept a /-joined
path and operate inside any already-existing directory (root or
nested), not just root; rename_file is same-directory only (no
cross-directory moves). write_file transparently picks inline vs.
CTZ-skip-list encoding based on size (LittleFs::INLINE_MAX), so large
files are supported too — this is the one operation that needs to find
blocks to put the new data in, via used_blocks/allocate_free_blocks,
since littlefs keeps no on-disk free-block bitmap: the only safe way to
find an unused block is scanning every metadata pair and every file’s CTZ
chain in the entire filesystem for what’s referenced, and treating
everything else as free. That scan is a meaningfully bigger risk surface
than every other write operation here (which only ever rewrite an
already-known, already-referenced pair in place) — see the real-hardware
verification notes in TODO.md for how this was checked before ever
writing a large file to a real device. One thing remains deliberately out
of scope: no directory creation — writing into a path whose directory
doesn’t exist yet errors, since a brand-new directory’s metadata pair would
also need two blocks from that same allocator, and (unlike a file, whose
only reference is the one CTZSTRUCT tag this writer itself just wrote) a
new subdirectory immediately becomes something other code could try to
resolve into mid-construction — not worth the added complexity for this
pass.
Byte layout verified against the real mklittlefs reference tool (bundled with
the ESP32 Arduino board package) by building known-content images (including a
subdirectory and a >1KB file) and comparing this reader’s output byte-for-byte
against mklittlefs -l’s ground truth and the original source files. In
particular, the CTZ skip-list algorithm below (pointer count ctz(n) + 1 per
block index n, backward traversal via each block’s first pointer) was derived
by hex-dumping a real 2-block and a real 5-block file and matching offsets
against the pre-image source bytes, not guessed from the spec text alone. The
write path’s CRC/FCRC tag encoding was derived the same way: by brute-forcing
candidate algorithms/byte ranges against a real image’s stored values until an
exact match was found, then cross-checking the result by having the real
mklittlefs -u/-l tool itself read back files this writer produced.
Reference: https://github.com/littlefs-project/littlefs/blob/master/SPEC.md
Modules§
- superblock
- LittleFS v2 metadata-block layout constants.
- tag
- Tag type constants for LittleFS metadata-pair tags (see SPEC.md’s “Metadata
tags” section). Tags are 32-bit big-endian words, XOR-chained together within
a block starting from
0xffffffff, encoding a 1-bit parity flag, an 11-bit type, a 10-bit id, and a 10-bit length:[1][type:11][id:10][len:10].
Structs§
- DirEntry
- A directory entry in LittleFS.
- File
Entry - A file entry in LittleFS.
- Little
Fs - LittleFS filesystem representation.
Enums§
- FsEntry
- A file or directory entry from a directory listing.
- Little
FsError - Errors from LittleFS operations.