Skip to main content

Crate resident_fat

Crate resident_fat 

Source
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 are read and write over &[u8] whose length is a multiple of BLOCK_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-sdmmc feature and wrap a driver you already have in bridge::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 what mkfs.vfat on a raw device produces.
  • FileSystem::mount_at — the volume starts at a block number the caller already knows.
  • FileSystem::mount_partition (with the mbr feature) — 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. Adds FileSystem::mount_partition and the mbr module. 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’s BlockDevice to BlockDevice, so an existing driver works here unchanged. Adds the bridge module. Enabling it makes embedded-sdmmc a 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.
bridgeembedded-sdmmc
Using a device that implements embedded-sdmmc’s block device trait.
codepage
The optional hook for 8.3 names that are not ASCII.
countedtarget_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.
mbrmbr
Master boot records, so that “mount the card” does not need a second crate.
time
Dates and times, in the shape FAT stores them.