Expand description
A FAT32 filesystem that spends memory to move data in whole runs.
Built for a bare-metal system with memory to spare — a board with a gigabyte of RAM and an SD card, rather than a microcontroller with kilobytes. It keeps the whole allocation table and every directory it has read in memory, which is what lets a contiguous file be moved in a single device transfer however large it is.
use resident_fat::{BlockDevice, FileSystem, Result};
// Reads the boot sector and loads the whole allocation table.
let mut volume = FileSystem::mount(device)?;
// Listing a directory. Parsed on the first look at it, and from then
// on this costs no device traffic at all.
for entry in volume.open_dir("/roms")?.iter() {
println!("{} ({} bytes)", entry.name(), entry.len());
}
// Reading a file: one transfer per contiguous run of its chain, so a
// file written in one go comes back in one call.
let file = volume.open("/roms/game.nes")?;
let data = volume.read_all(&file)?;
// Writing one. The length is known before a byte is written, so the
// whole chain is allocated at once and the file lands contiguous.
volume.write_file("/saves/game.sav", &data)?;
// Writes the table back and clears the volume's dirty flag. Until this
// happens, allocations exist only in memory.
volume.unmount()?;§Status
Early. A FAT32 volume can be mounted, walked, read, written, grown,
truncated and renamed; long names and directories are both read and
created, and files and directories move between directories. Every
claim below is checked against fsck.vfat and mtools, which are
independent implementations, including what an interruption at each
write leaves behind.
Block devices come from outside: implement BlockDevice for your
driver, use a HAL that already does — rpi-hal’s SD adapters do — or
bridge one you have for embedded-sdmmc through the bridge module,
behind the feature of that name. The version number should be read as
an early one, and the API will change.
§Getting a block device
Everything above starts with a device, and supplying one is the only
thing this crate asks of a consumer. Two ways:
- Implement
BlockDevice— four methods, two of which arereadandwriteover&[u8]whose length is a multiple ofBLOCK_SIZE. Transfers are byte slices rather than a block newtype so that a caller’s own buffer reaches the device without a copy, and so that the unit of transfer can be a whole run. - Enable the
embedded-sdmmcfeature and wrap a driver you already have inbridge::FromEmbeddedSdmmc. That covers most SD card drivers written for embedded Rust, unchanged.
An implementation should be cheap to call with large slices. One that
internally splits a long transfer into a command per block gives up most
of the reason to use this crate; if the hardware has a real limit, say
so with BlockDevice::max_transfer_blocks and long transfers are
split to fit.
§Mounting
Three ways in, so the common cases are not guesswork:
FileSystem::mount— the whole device is the volume, which is whatmkfs.vfaton a raw device produces.FileSystem::mount_at— the volume starts at a block number the caller already knows.FileSystem::mount_partition(with thembrfeature) — read the partition table and mount the volume in one of its slots. This is the one for a card an imaging tool wrote.
The third exists because telling a partition table from a boot sector is
not something every consumer should be reimplementing: both end with the
same 0x55AA signature, and reading one as the other yields block
numbers that are wrong but plausible.
§What makes this different
Embedded FAT implementations cache one 512-byte block, because they cannot assume memory exists. That single decision propagates: a file write becomes one device command per block, chain walking re-reads the table from the device, and looking a file up by name rescans the directory.
This crate assumes memory exists — a few megabytes of it — and keeps two structures resident:
- The whole file allocation table. A 32 GB volume with 32 KB clusters is about a million entries, four bytes each. Chain walking becomes array indexing, allocation becomes an array scan, and both on-disk copies of the table are written back once, on sync, rather than read-modify-written per entry.
- Parsed directories. Read once, in one transfer; enumeration is then a slice walk and lookup is a map hit.
The payoff is not the caching itself, it is what the caching enables: with the chain in memory, contiguous runs are free to discover. A file that occupies one unbroken run of clusters is read or written in a single device transfer, however large it is. An implementation that has to consult the device to learn where the next cluster lives cannot do better than one transfer per cluster, because it does not yet know that the next one is adjacent.
§What it costs
Memory, and the alloc crate — this is not a filesystem for a
microcontroller with kilobytes of RAM, and embedded-sdmmc remains the
right answer there. It is a filesystem for the increasingly common case
of a bare-metal system with a gigabyte sitting idle.
Four bytes per cluster, so the bill is set by the volume rather than by anything a program chooses: a 968 MB FAT32 partition with 4 KB clusters holds 247,955 of them and costs 968 KiB resident. The number grows with the volume and shrinks with the cluster size, and large cards use large clusters, so a 32 GB volume formatted the way such cards come is around 4 MB rather than 32.
Directories cost extra, and are kept once read rather than evicted; see
fs::FileSystem. A volume whose table will not fit reports that at
mount rather than aborting.
§Scope
FAT32. FAT12 and FAT16 are not implemented, but the design deliberately
does not assume 32-bit entries: the resident table is u32 regardless
of the on-disk width, so a narrower format would cost only pack and
unpack at load and sync. exFAT is a different filesystem wearing a
similar name, and is out of scope.
§Features
Neither is on by default.
mbr— reading partition tables, so mounting a card an imaging tool wrote does not need a second crate. About a hundred lines and no dependencies. AddsFileSystem::mount_partitionand thembrmodule. GPT is not supported; the protective record a GPT disk carries is recognised and declined rather than mounted.embedded-sdmmc— a blanket bridge from that crate’sBlockDevicetoBlockDevice, so an existing driver works here unchanged. Adds thebridgemodule. Enabling it makesembedded-sdmmca public dependency: a semver-breaking release there is one here too, which is why it is opt-in.
§Toolchain
Stable Rust 1.85 or newer, and no nightly, no -Zbuild-std and no
linker script: this is ordinary portable Rust that happens to be
no_std, and rustup ships a precompiled core and alloc for every
target it is meant to run on. alloc is required rather than optional.
Re-exports§
pub use blockdev::BLOCK_SIZE;pub use blockdev::BlockDevice;pub use boot::BootSector;pub use boot::FsInfo;pub use codepage::Codepage;pub use dir::Attributes;pub use dir::DirEntry;pub use dir::Directory;pub use dir::ShortName;pub use error::BootError;pub use error::Error;pub use error::FatError;pub use error::Format;pub use error::Geometry;pub use error::Result;pub use fat::Fat;pub use fat::Run;pub use file::File;pub use fs::FileSystem;pub use time::Clock;pub use time::DateTime;pub use time::EpochClock;pub use time::FnClock;pub use time::Packed;
Modules§
- blockdev
- The block device this filesystem is layered on.
- boot
- The boot sector, and the geometry derived from it.
- bridge
embedded-sdmmc - Using a device that implements
embedded-sdmmc’s block device trait. - codepage
- The optional hook for 8.3 names that are not ASCII.
- counted
target_has_atomic=32 - Counting what the device is actually asked to do.
- dir
- Directories: entries, long names, and the parsed form kept in memory.
- error
- What can go wrong, and enough detail to act on it.
- fat
- The file allocation table, held in memory.
- file
- Reading files.
- fs
- Mounting a volume, and what you get when you have.
- mbr
mbr - Master boot records, so that “mount the card” does not need a second crate.
- time
- Dates and times, in the shape FAT stores them.