# LittleFS — Fail-Safe Filesystem for Microcontrollers

> A lightweight, power-loss-resilient filesystem designed for microcontrollers with limited RAM and flash storage.

## Install

Save in your project root:

# LittleFS — Fail-Safe Filesystem for Microcontrollers

## Quick Use

```bash
git clone https://github.com/littlefs-project/littlefs.git
cd littlefs
make test
# To embed: copy lfs.h and lfs.c into your project
# and implement the block-device callbacks:
#   lfs_read, lfs_prog, lfs_erase, lfs_sync
```

## 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

---
Source: https://tokrepo.com/en/workflows/asset-a480cf1e
Author: AI Open Source