It's FAST, FFS! [1]

FASTFFS is a small NOR flash filesystem prototype for embedded systems that create, replace, list, and read named files. It is aimed at workloads with many small to medium files, from a few bytes to tens of KB, a few larger files in the hundreds of KB, and whole file updates rather than POSIX style random write/update capabilities.

The target storage shape is roughly 2-12 MB of NOR flash with hundreds to low thousands of files.

The core idea is simple: file data is written copy-on-write into flash sectors, then a compact append-only index record commits the namespace update. On remount, the index is replayed to recover the current set of names. Old file versions and interrupted writes are left as obsolete or orphaned data for later reclamation.

Like most flash filesystems FASTFFS is designed to be safe for use in the face of unexpected power failures and crashes. It's designed to preserve committed data across interrupted writes.

Unlike most flash filesystems, FASTFFS is designed to be fast. FASTFFS systems usually run GC (garbage collection) opportunistically in small background steps, keeping file operations as fast as possible. It still works without background GC, but is much faster with it.

1. Embedded / microcontroller environments: limited static RAM, lightweight code.
2. Safe, crash/power failure resilient, atomic updates of file data and metadata.
3. Fast, reduce file read/write overhead as much as possible.
4. Optimal for its designed workload.
5. Reasonable flash wear leveling.
6. Usable in a variety of use cases, without trying to be everything.

• A portable C core API in include/fastffs/fastffs.h.
• Format, mount, open, read, write, close, stat, exists, list, delete, and directory iteration operations.
• Caller owned filesystem, file, directory, cache, scratch, and allocation-map state; the core does not allocate from the heap.
• A sector based flash format with index sectors, compact namespace records, file metadata, forward extent links, overwrite/delete commits, index rotation/compaction, small background GC steps, and inline GC under pressure.
• Packed small-file storage so tiny files do not each consume a whole sector.
• Configurable index cache modes, including no cache, hash table, and full table builds.
• A host verification flash backend derived from the LittleFS emulator, with NOR programming rules, operation accounting, fake timing, failure injection, crash/reopen snapshots, and image inspection support.
• Host tools for creating, loading, dumping, checking, probing, and sweeping FASTFFS images.
• ESP32 S3 benchmark harnesses used to compare candidate filesystems against LittleFS, FatFs, JesFS, and SPIFFS.

• Optional CRC32 protected file data + metadata.
• Multi file atomic transactions.
• Accelerated directory listing. FASTFFS already supports prefix filtering.
• Sector compaction of live data.
• Attribute and long name support.
• Append oriented workloads like logs, data loggers, etc.
• Key Value optimized workloads, like extra tiny files.

FASTFFS uses "sector" as its allocation, metadata, scan, and reclaim unit. The default sector size is 4 KB, with the encoded sector size stored in the index headers so mounted images can discover the format.

The namespace index is an append-only log of small records. Each record stores a collision resolved 16 bit slot and a head sector. A head of zero is a delete tombstone; otherwise the head points at the sector containing the root metadata for the current file version. Later records win during replay.

File replacement is intentionally commit oriented. New data and metadata are written first, and the namespace changes only when the new index record is appended. That keeps the old committed file visible if an interrupted write does not reach the commit point.

make test
make test-sanitize

Additional targets in the Makefile exercise cache variants, churn workloads, timing probes, and crash sweeps.

See design.md for the deeper design notes.

This is a comparison of other permissively licensed filesystems that were reasonably easy to port/integrate. There are many others, but most appeared to be glued to a whole operating system.

Across the captured benchmark stats, FASTFFS leads every write-throughput measurement from 64 B through 350 KB. It writes tiny files about 5x faster than the fastest tested non-FASTFFS result, writes 50 KB files about 1.9x faster, and completes the churn workload simulation about 1.2x faster than LittleFS, 1.5x faster than JesFS, and 1.8x faster than FATFS.

FASTFFS has the fastest tiny-file reads and stays stable across early, middle, and late index positions.

FASTFFS mounts quickly after churn, even though it replays its compact index log on mount, at about 2x faster than the next tested non-FASTFFS result.

FASTFFS completes a small file stress test about 12x faster than SPIFFS, while LittleFS, FATFS, and JesFS failed before reaching the write target and were much slower before failing. This test writes many 1 B-5 KB files while keeping live payload around 55% of the partition size.

By default, FASTFFS uses RAM to speed up certain operations, but these are configurable. Even a minimal-RAM configuration stays faster than the other tested filesystems on the fixed 64 B and 50 KB write tests, completes the small files stress test, and remains competitive in other aspects.

FASTFFS runs measured GC steps between foreground operations; that GC time is included in total churn runtime. This roughly simulates spending some idle cycles on GC opportunistically, instead of forcing foreground writes to pay the whole reclaim cost when free space is tight.

The churn benchmark writes about 8.2 MB of creates/replaces/deletes while keeping 105 files and about 2.4 MB live, measuring mutation throughput during the run and final live-set read/list behavior.

Tested on ESP32-S3, ESP-IDF v6.0-beta2, 4 MB data partition.

FASTFFS avoids corruption by ordering writes so new file data is not reachable until the final index record is appended. If power fails while writing file payload or file metadata, the old committed file remains and the incomplete write is left as orphaned data for later GC. If power fails while appending the final index record, the last record may be invalid and is checked on mount. If recovery is allowed and the bad record is provably the end of the index, the partial record is effectively removed by overwriting it, leaving the filesystem in the previous valid state. This ensures that committed data remains intact and readable, and partial writes do not corrupt any previous data.

FASTFFS builds upon the LittleFS test flash emulation and fault-injection system.

The verifier models more than simple before/after operation failure. It uses a NOR-like backend derived from LittleFS emubd to simulate multiple possible persisted state outcomes at every possible program/erase. By randomizing eligible bits inside sampled program and erase operations, it fuzzes single and multi-bit partial write outcomes across index records, metadata, payloads, footers, and lifecycle fields. Each sampled crash branch is remounted and checked against the expected committed namespace. Visible files are read back byte-for-byte through a deterministic namespace hash. Thorough sweeps also run the internal sector inspector. High-volume sweeps can run namespace-only to spend the time on more crash points and partial-program branches.

Recent host sweep evidence:

The 256 B sector run intentionally creates frequent index rotation, index compaction, GC pressure, and long file chains. The 4 KiB sector run matches a more typical NOR erase-sector geometry.

JesFS really punches above it's weight. It's simple and lightweight.

LittleFS has some really solid test/verification stuff, and has really improved over time. I've borrowed their flash emulation framework to verify FASTFFS.

Some design concepts were borrowed from Zephyr ZMS.