Skip to main content

Crate tpt_basestation_littlefs

Crate tpt_basestation_littlefs 

Source
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.
FileEntry
A file entry in LittleFS.
LittleFs
LittleFS filesystem representation.

Enums§

FsEntry
A file or directory entry from a directory listing.
LittleFsError
Errors from LittleFS operations.