Repository files navigation

A little fail-safe filesystem designed for microcontrollers.

   | | |     .---._____  .-----.   |          |--|o    |---| littlefs |--|     |---|          |  '-----'   '----------'   | | |

Power-loss resilience - littlefs is designed to handle random powerfailures. All file operations have strong copy-on-write guarantees and ifpower is lost the filesystem will fall back to the last known good state.

Dynamic wear leveling - littlefs is designed with flash in mind, andprovides wear leveling over dynamic blocks. Additionally, littlefs candetect bad blocks and work around them.

Bounded RAM/ROM - littlefs is designed to work with a small amount ofmemory. RAM usage is strictly bounded, which means RAM consumption does notchange as the filesystem grows. The filesystem contains no unboundedrecursion and dynamic memory is limited to configurable buffers that can beprovided statically.

Here's a simple example that updates a file namedboot_count every timemain runs. The program can be interrupted at any time without losing trackof how many times it has been booted and without corrupting the filesystem:

#include"lfs.h"// variables used by the filesystemlfs_tlfs;lfs_file_tfile;// configuration of the filesystem is provided by this structconststructlfs_configcfg= {// block device operations    .read=user_provided_block_device_read,    .prog=user_provided_block_device_prog,    .erase=user_provided_block_device_erase,    .sync=user_provided_block_device_sync,// block device configuration    .read_size=16,    .prog_size=16,    .block_size=4096,    .block_count=128,    .cache_size=16,    .lookahead_size=16,    .block_cycles=500,};// entry pointintmain(void) {// mount the filesysteminterr=lfs_mount(&lfs,&cfg);// reformat if we can't mount the filesystem// this should only happen on the first bootif (err) {lfs_format(&lfs,&cfg);lfs_mount(&lfs,&cfg);    }// read current countuint32_tboot_count=0;lfs_file_open(&lfs,&file,"boot_count",LFS_O_RDWR |LFS_O_CREAT);lfs_file_read(&lfs,&file,&boot_count,sizeof(boot_count));// update boot countboot_count+=1;lfs_file_rewind(&lfs,&file);lfs_file_write(&lfs,&file,&boot_count,sizeof(boot_count));// remember the storage is not updated until the file is closed successfullylfs_file_close(&lfs,&file);// release any resources we were usinglfs_unmount(&lfs);// print the boot countprintf("boot_count: %d\n",boot_count);}

Detailed documentation (or at least as much detail as is currently available)can be found in the comments inlfs.h.

littlefs takes in a configuration structure that defines how the filesystemoperates. The configuration struct provides the filesystem with the blockdevice operations and dimensions, tweakable parameters that tradeoff memoryusage for performance, and optional static buffers if the user wants to avoiddynamic memory.

The state of the littlefs is stored in thelfs_t type which is left upto the user to allocate, allowing multiple filesystems to be in usesimultaneously. With thelfs_t and configuration struct, a user canformat a block device or mount the filesystem.

Once mounted, the littlefs provides a full set of POSIX-like file anddirectory functions, with the deviation that the allocation of filesystemstructures must be provided by the user.

All POSIX operations, such as remove and rename, are atomic, even in eventof power-loss. Additionally, file updates are not actually committed tothe filesystem until sync or close is called on the file.

Littlefs is written in C, and specifically should compile with any compilerthat conforms to theC99 standard.

All littlefs calls have the potential to return a negative error code. Theerrors can be either one of those found in theenum lfs_error inlfs.h, or an error returned by the user's block device operations.

In the configuration struct, theprog anderase function provided by theuser may return aLFS_ERR_CORRUPT error if the implementation already candetect corrupt blocks. However, the wear leveling does not depend on the returncode of these functions, instead all data is read back and checked forintegrity.

If your storage caches writes, make sure that the providedsync functionflushes all the data to memory and ensures that the next read fetches the datafrom memory, otherwise data integrity can not be guaranteed. If thewritefunction does not perform caching, and therefore eachread orwrite callhits the memory, thesync function can simply return 0.

At a high level, littlefs is a block based filesystem that uses small logs tostore metadata and larger copy-on-write (COW) structures to store file data.

In littlefs, these ingredients form a sort of two-layered cake, with the smalllogs (called metadata pairs) providing fast updates to metadata anywhere onstorage, while the COW structures store file data compactly and without anywear amplification cost.

Both of these data structures are built out of blocks, which are fed by acommon block allocator. By limiting the number of erases allowed on a blockper allocation, the allocator provides dynamic wear leveling over the entirefilesystem.

                    root                   .--------.--------.                   | A'| B'|         |                   |   |   |->       |                   |   |   |         |                   '--------'--------'                .----'   '--------------.       A       v                 B       v      .--------.--------.       .--------.--------.      | C'| D'|         |       | E'|new|         |      |   |   |->       |       |   | E'|->       |      |   |   |         |       |   |   |         |      '--------'--------'       '--------'--------'      .-'   '--.                  |   '------------------.     v          v              .-'                        v.--------.  .--------.        v                       .--------.|   C    |  |   D    |   .--------.       write       | new E  ||        |  |        |   |   E    |        ==>        |        ||        |  |        |   |        |                   |        |'--------'  '--------'   |        |                   '--------'                         '--------'                   .-'    |                         .-'    '-.    .-------------|------'                        v          v  v              v                   .--------.  .--------.       .--------.                   |   F    |  |   G    |       | new F  |                   |        |  |        |       |        |                   |        |  |        |       |        |                   '--------'  '--------'       '--------'

More details on how littlefs works can be found inDESIGN.md andSPEC.md.

• DESIGN.md - A fully detailed dive into how littlefs works.I would suggest reading it as the tradeoffs at work are quite interesting.

• SPEC.md - The on-disk specification of littlefs with all thenitty-gritty details. May be useful for tooling development.

The littlefs comes with a test suite designed to run on a PC using theemulated block device found in thebd directory.The tests assume a Linux environment and can be started with make:

maketest

Tests are implemented in C in the .toml files found in thetests directory.When developing a feature or fixing a bug, it is frequently useful to run asingle test case or suite of tests:

./scripts/test.py -l runners/test_runner# list available test suites./scripts/test.py -L runners/test_runner test_dirs# list available test cases./scripts/test.py runners/test_runner test_dirs# run a specific test suite

If an assert fails in a test, test.py will try to print information about thefailure:

tests/test_dirs.toml:1:failure: test_dirs_root:1g12gg2 (PROG_SIZE=16, ERASE_SIZE=512) failedtests/test_dirs.toml:5:assert: assert failed with 0, expected eq 42    lfs_mount(&lfs, cfg) => 42;

This includes the test id, which can be passed to test.py to run only thatspecific test permutation:

./scripts/test.py runners/test_runner test_dirs_root:1g12gg2# run a specific test permutation./scripts/test.py runners/test_runner test_dirs_root:1g12gg2 --gdb# drop into gdb on failure

Some other flags that may be useful:

./scripts/test.py runners/test_runner -b -j# run tests in parallel./scripts/test.py runners/test_runner -v -O-# redirect stdout to stdout./scripts/test.py runners/test_runner -ddisk# capture resulting disk image

See-h/--help for a full list of available flags:

./scripts/test.py --help

The littlefs is provided under theBSD-3-Clause license. SeeLICENSE.md for more information. Contributions to this projectare accepted under the same license.

Individual files contain the following tag instead of the full license text.

SPDX-License-Identifier:    BSD-3-Clause

This enables machine processing of license information based on the SPDXLicense Identifiers that are here available:http://spdx.org/licenses/

• littlefs-fuse - AFUSE wrapper for littlefs. The project allows you tomount littlefs directly on a Linux machine. Can be useful for debugginglittlefs if you have an SD card handy.

• littlefs-js - A javascript wrapper for littlefs. I'm not sure why you wouldwant this, but it is handy for demos. You can see it in actionhere.

• littlefs-python - A Python wrapper for littlefs. The project allows youto create images of the filesystem on your PC. Check if littlefs will fityour needs, create images for a later download to the target memory orinspect the content of a binary image of the target memory.

• littlefs2-rust - A Rust wrapper for littlefs. This project allows youto use littlefs in a Rust-friendly API, reaping the benefits of Rust's memorysafety and other guarantees.

• nim-littlefs - A Nim wrapper and API for littlefs. Includes a fuseimplementation based onlittlefs-fuse

• chamelon - A pure-OCaml implementation of (most of) littlefs, designed foruse with the MirageOS library operating system project. It is interoperablewith the reference implementation, with some caveats.

• littlefs-disk-img-viewer - A memory-efficient web application for viewinglittlefs disk images in your web browser.

• mklfs - A command line tool for creating littlefs images. Used in the LuaRTOS ecosystem.

• mklittlefs - A command line tool for creating littlefs images. Used in theESP8266 and RP2040 ecosystem.

• pico-littlefs-usb - An interface for littlefs that emulates a FAT12filesystem over USB. Allows mounting littlefs on a host PC without additionaldrivers.

• ramcrc32bd - An example block device using littlefs's 32-bit CRC forerror-correction.

• ramrsbd - An example block device using Reed-Solomon codes forerror-correction.

• Mbed OS - The easiest way to get started with littlefs is to jump into Mbedwhich already has block device drivers for most forms of embedded storage.littlefs is available in Mbed OS as theLittleFileSystem class.

• SPIFFS - Another excellent embedded filesystem for NOR flash. As a moretraditional logging filesystem with full static wear-leveling, SPIFFS willlikely outperform littlefs on small memories such as the internal flash onmicrocontrollers.

• Dhara - An interesting NAND flash translation layer designed for smallMCUs. It offers static wear-leveling and power-resilience with only a fixedO(|address|) pointer structure stored on each block and in RAM.

• ChaN's FatFs - A lightweight reimplementation of the infamous FAT filesystemfor microcontroller-scale devices. Due to limitations of FAT it can't providepower-loss resilience, but it does allow easy interop with PCs.