LittleFS — Fail-Safe Filesystem for Microcontrollers

Introduction

LittleFS is a small fail-safe filesystem for microcontrollers with constrained RAM and flash. It uses copy-on-write logging to survive power loss without requiring fsck. The entire implementation is two files (lfs.c and lfs.h).

What LittleFS Does

• Provides a POSIX-like file and directory API for embedded targets
• Guarantees consistency after power loss via copy-on-write commits
• Performs automatic wear leveling across flash blocks
• Operates within a bounded, configurable RAM footprint
• Supports NOR and NAND-like block devices via pluggable callbacks

Architecture Overview

LittleFS uses a hybrid log-structured and COW B-tree design. Metadata lives in logging blocks that compact in place; file data uses COW block chains. Directories are linked metadata pairs. Every commit is atomic: either the full update lands or the prior state is retained.

Self-Hosting & Configuration

• Copy lfs.c and lfs.h into your project; implement read, program, erase, and sync callbacks
• Set block size, block count, and buffer sizes in lfs_config to match your flash chip
• Tune read and program sizes to your flash's minimum I/O granularity
• Optionally define LFS_NO_MALLOC and provide static buffers for deterministic memory use
• Run the test suite on a host machine using the built-in RAM block device

Key Features

• Power-loss resilience without journaling overhead or recovery passes
• Bounded RAM: works with as little as a few hundred bytes
• Automatic wear leveling extending flash lifetime
• Two-file implementation with no external dependencies
• Configurable block and cache sizes balancing performance and memory

Comparison with Similar Tools

• SPIFFS — flat structure with no directories; simpler but lacks wear leveling and has consistency edge cases
• FatFs — widely compatible FAT layer; larger footprint and not power-loss safe without extra journaling
• JFFS2 — Linux kernel flash filesystem; mature but needs a full OS and significant RAM
• NVS (ESP-IDF) — key-value store for ESP32; not a general-purpose filesystem

FAQ

Q: How much RAM does it need? A: A minimal config uses around 1-2 KB for buffers. The footprint does not grow with filesystem size.

Q: Can it run on external SPI flash? A: Yes. Implement the four callbacks to talk to your SPI chip and LittleFS handles the rest.

Q: Does it support timestamps? A: Not natively. Custom attributes can be attached to files for metadata like timestamps.

Q: What happens on power loss during a write? A: The filesystem rolls back to the last committed state. Partial writes are discarded and the directory structure stays consistent.

Sources

• Repository: https://github.com/littlefs-project/littlefs
• Design doc: https://github.com/littlefs-project/littlefs/blob/master/DESIGN.md