Skip to main content

resident_fat/
lib.rs

1//! A FAT32 filesystem that spends memory to move data in whole runs.
2//!
3//! Built for a bare-metal system with memory to spare — a board with a
4//! gigabyte of RAM and an SD card, rather than a microcontroller with
5//! kilobytes. It keeps the whole allocation table and every directory it
6//! has read in memory, which is what lets a contiguous file be moved in a
7//! single device transfer however large it is.
8//!
9//! ```no_run
10//! use resident_fat::{BlockDevice, FileSystem, Result};
11//!
12//! # fn example<D: BlockDevice>(device: D) -> Result<(), D::Error> {
13//! // Reads the boot sector and loads the whole allocation table.
14//! let mut volume = FileSystem::mount(device)?;
15//!
16//! // Listing a directory. Parsed on the first look at it, and from then
17//! // on this costs no device traffic at all.
18//! for entry in volume.open_dir("/roms")?.iter() {
19//!     println!("{} ({} bytes)", entry.name(), entry.len());
20//! }
21//!
22//! // Reading a file: one transfer per contiguous run of its chain, so a
23//! // file written in one go comes back in one call.
24//! let file = volume.open("/roms/game.nes")?;
25//! let data = volume.read_all(&file)?;
26//!
27//! // Writing one. The length is known before a byte is written, so the
28//! // whole chain is allocated at once and the file lands contiguous.
29//! volume.write_file("/saves/game.sav", &data)?;
30//!
31//! // Writes the table back and clears the volume's dirty flag. Until this
32//! // happens, allocations exist only in memory.
33//! volume.unmount()?;
34//! # Ok(())
35//! # }
36//! ```
37//!
38//! # Status
39//!
40//! **Early.** A FAT32 volume can be mounted, walked, read, written, grown,
41//! truncated and renamed; long names and directories are both read and
42//! created, and files and directories move between directories. Every
43//! claim below is checked against `fsck.vfat` and `mtools`, which are
44//! independent implementations, including what an interruption at each
45//! write leaves behind.
46//!
47//! Block devices come from outside: implement [`BlockDevice`] for your
48//! driver, use a HAL that already does — `rpi-hal`'s SD adapters do — or
49//! bridge one you have for `embedded-sdmmc` through the `bridge` module,
50//! behind the feature of that name. The version number should be read as
51//! an early one, and the API will change.
52//!
53//! # Getting a block device
54//!
55//! Everything above starts with a `device`, and supplying one is the only
56//! thing this crate asks of a consumer. Two ways:
57//!
58//! * **Implement [`BlockDevice`]** — four methods, two of which are
59//!   `read` and `write` over `&[u8]` whose length is a multiple of
60//!   [`BLOCK_SIZE`]. Transfers are byte slices rather than a block newtype
61//!   so that a caller's own buffer reaches the device without a copy, and
62//!   so that the unit of transfer can be a whole run.
63//! * **Enable the `embedded-sdmmc` feature** and wrap a driver you already
64//!   have in `bridge::FromEmbeddedSdmmc`. That covers most SD card drivers
65//!   written for embedded Rust, unchanged.
66//!
67//! An implementation should be cheap to call with *large* slices. One that
68//! internally splits a long transfer into a command per block gives up most
69//! of the reason to use this crate; if the hardware has a real limit, say
70//! so with [`BlockDevice::max_transfer_blocks`] and long transfers are
71//! split to fit.
72//!
73//! # Mounting
74//!
75//! Three ways in, so the common cases are not guesswork:
76//!
77//! * [`FileSystem::mount`] — the whole device is the volume, which is what
78//!   `mkfs.vfat` on a raw device produces.
79//! * [`FileSystem::mount_at`] — the volume starts at a block number the
80//!   caller already knows.
81//! * `FileSystem::mount_partition` (with the `mbr` feature) — read the
82//!   partition table and mount the volume in one of its slots. This is the
83//!   one for a card an imaging tool wrote.
84//!
85//! The third exists because telling a partition table from a boot sector is
86//! not something every consumer should be reimplementing: both end with the
87//! same `0x55AA` signature, and reading one as the other yields block
88//! numbers that are wrong but plausible.
89//!
90//! # What makes this different
91//!
92//! Embedded FAT implementations cache one 512-byte block, because they
93//! cannot assume memory exists. That single decision propagates: a file
94//! write becomes one device command per block, chain walking re-reads the
95//! table from the device, and looking a file up by name rescans the
96//! directory.
97//!
98//! This crate assumes memory exists — a few megabytes of it — and keeps
99//! two structures resident:
100//!
101//! * **The whole file allocation table.** A 32 GB volume with 32 KB
102//!   clusters is about a million entries, four bytes each. Chain walking
103//!   becomes array indexing, allocation becomes an array scan, and both
104//!   on-disk copies of the table are written back once, on sync, rather
105//!   than read-modify-written per entry.
106//! * **Parsed directories.** Read once, in one transfer; enumeration is
107//!   then a slice walk and lookup is a map hit.
108//!
109//! The payoff is not the caching itself, it is what the caching enables:
110//! with the chain in memory, **contiguous runs are free to discover**. A
111//! file that occupies one unbroken run of clusters is read or written in a
112//! single device transfer, however large it is. An implementation that has
113//! to consult the device to learn where the next cluster lives cannot do
114//! better than one transfer per cluster, because it does not yet know that
115//! the next one is adjacent.
116//!
117//! # What it costs
118//!
119//! Memory, and the [`alloc`] crate — this is not a filesystem for a
120//! microcontroller with kilobytes of RAM, and `embedded-sdmmc` remains the
121//! right answer there. It is a filesystem for the increasingly common case
122//! of a bare-metal system with a gigabyte sitting idle.
123//!
124//! Four bytes per cluster, so the bill is set by the volume rather than by
125//! anything a program chooses: a 968 MB FAT32 partition with 4 KB clusters
126//! holds 247,955 of them and costs **968 KiB** resident. The number grows
127//! with the volume and shrinks with the cluster size, and large cards use
128//! large clusters, so a 32 GB volume formatted the way such cards come is
129//! around 4 MB rather than 32.
130//!
131//! Directories cost extra, and are kept once read rather than evicted; see
132//! [`fs::FileSystem`]. A volume whose table will not fit reports that at
133//! mount rather than aborting.
134//!
135//! # Scope
136//!
137//! FAT32. FAT12 and FAT16 are not implemented, but the design deliberately
138//! does not assume 32-bit entries: the resident table is `u32` regardless
139//! of the on-disk width, so a narrower format would cost only pack and
140//! unpack at load and sync. exFAT is a different filesystem wearing a
141//! similar name, and is out of scope.
142//!
143//! # Features
144//!
145//! Neither is on by default.
146//!
147//! * **`mbr`** — reading partition tables, so mounting a card an imaging
148//!   tool wrote does not need a second crate. About a hundred lines and no
149//!   dependencies. Adds `FileSystem::mount_partition` and the `mbr` module.
150//!   GPT is not supported; the protective record a GPT disk carries is
151//!   recognised and declined rather than mounted.
152//! * **`embedded-sdmmc`** — a blanket bridge from that crate's
153//!   `BlockDevice` to [`BlockDevice`], so an existing driver works here
154//!   unchanged. Adds the `bridge` module. Enabling it makes
155//!   `embedded-sdmmc` a *public* dependency: a semver-breaking release
156//!   there is one here too, which is why it is opt-in.
157//!
158//! # Toolchain
159//!
160//! Stable Rust 1.85 or newer, and no nightly, no `-Zbuild-std` and no
161//! linker script: this is ordinary portable Rust that happens to be
162//! `no_std`, and `rustup` ships a precompiled `core` and `alloc` for every
163//! target it is meant to run on. `alloc` is required rather than optional.
164
165// `no_std` everywhere except under `cargo test`, where the unit tests want
166// the standard library for image fixtures and for shelling out to the
167// `fsck.vfat` and `mtools` oracles. Integration tests under `tests/` link
168// `std` regardless -- they are separate crates -- so this only affects
169// `#[cfg(test)]` modules inside `src/`.
170#![cfg_attr(not(test), no_std)]
171// Every public item carries rustdoc, enforced rather than reviewed. A
172// filesystem's API is the part consumers have to reason about without
173// reading the implementation, so an undocumented public item is a defect,
174// not a style lapse.
175#![deny(missing_docs)]
176// Feature-gate annotations in the rendered documentation. Enabled by
177// `make doc` and by the docs.rs metadata in `Cargo.toml`, ignored
178// otherwise, so this costs a normal build nothing.
179#![cfg_attr(docsrs, feature(doc_cfg))]
180
181extern crate alloc;
182
183/// Compiles the README's Rust blocks as doctests.
184///
185/// The front page of the repository is the first code most people read, and
186/// nothing else checks it — a signature that drifts there is wrong in the
187/// place it is most likely to be copied from.
188///
189/// Included only under `cfg(doctest)`, so this collects the examples without
190/// putting the README into the rendered documentation. Merging the two
191/// outright would drag the CI badges and the repository-relative licence
192/// links onto docs.rs, where the badges are noise and the links are 404s;
193/// the crate-level documentation above is written for a reader who has
194/// already decided to use this, which is a different job from the README's.
195#[cfg(doctest)]
196#[doc = include_str!("../README.md")]
197struct ReadmeExamples;
198
199pub mod blockdev;
200pub mod boot;
201#[cfg(feature = "embedded-sdmmc")]
202#[cfg_attr(docsrs, doc(cfg(feature = "embedded-sdmmc")))]
203pub mod bridge;
204pub mod codepage;
205#[cfg(target_has_atomic = "32")]
206pub mod counted;
207pub mod dir;
208pub mod error;
209pub mod fat;
210pub mod file;
211pub mod fs;
212#[cfg(feature = "mbr")]
213#[cfg_attr(docsrs, doc(cfg(feature = "mbr")))]
214pub mod mbr;
215pub mod time;
216
217mod name;
218
219// Everything a consumer names in ordinary use, at the crate root, so that a
220// program mounting a volume and reading a file need not know which module
221// each type lives in. The rule is that anything a root-exported method
222// takes or returns is itself root-exported -- `FileSystem::boot_sector`
223// hands back a `BootSector`, so `BootSector` belongs here too.
224//
225// The feature-gated modules are the exception: `mbr` and `bridge` stay
226// reached by their module path -- as does `counted`, which is gated on the
227// target having atomics -- which says which feature they need at the
228// use site rather than leaving a name to disappear from the root when a
229// feature is off.
230pub use blockdev::{BLOCK_SIZE, BlockDevice};
231pub use boot::{BootSector, FsInfo};
232pub use codepage::Codepage;
233pub use dir::{Attributes, DirEntry, Directory, ShortName};
234pub use error::{BootError, Error, FatError, Format, Geometry, Result};
235pub use fat::{Fat, Run};
236pub use file::File;
237pub use fs::FileSystem;
238pub use time::{Clock, DateTime, EpochClock, FnClock, Packed};