Arduino Core for Renesas

littlefs is a fail-safe filesystem specifically designed for microcontrollers. It addresses the unique constraints of embedded systems, such as limited RAM/ROM and the physical characteristics of flash memory (where erasing is expensive and programming is granular).

Use littlefs when your project requires:

1. Power-loss resilience: The filesystem is designed to recover from power loss during any write operation, preventing data corruption that could render a device unrecoverable.
2. Wear leveling: It prevents premature hardware failure by distributing writes across the flash storage, avoiding the exhaustion of specific blocks used for frequently updated metadata.
3. Bounded RAM/ROM usage: Unlike many filesystems that require large amounts of memory to manage metadata, littlefs uses a bounded amount of RAM. This means RAM usage does not grow as the filesystem size or the number of files increases.

The library provides two background classes for custom memory management:

EERef

An EERef object acts like a single byte of RAM but is backed by EEPROM. It has a 2-byte overhead. You can create one using the subscript operator.

EEPtr

An EEPtr is a bidirectional pointer to EERef objects. It supports standard pointer arithmetic like increment (++) and decrement (--) operators and dereferencing (*).

To facilitate iteration, use EEPROM.begin() to get an EEPtr pointing to the first cell, and EEPROM.end() to get an EEPtr pointing to the location after the last cell (note: EEPROM.end() points to the first cell due to hardware address wrapping).

// EERef example
EERef ref = EEPROM[ 10 ];
ref = 4; // write
unsigned char val = ref; // read

// EEPtr example
EEPtr ptr = 10;
*ptr = 4; // dereference and write
unsigned char val2 = *ptr; // dereference and read
ptr++; // move to next cell

Because littlefs uses a threaded linked-list that is not strictly bound to the directory tree's COW operations, certain states can occur during power loss:

• Orphaned metadata pairs: Metadata pairs that exist in the threaded linked-list but have no parent in the actual directory tree. This happens when a directory is added or removed, but the power is lost before the parent directory's pointer is updated.
• Half-orphans: A specific type of orphan that occurs during block eviction (e.g., when a bad block is detected and a replacement is allocated). A half-orphan exists when the filesystem tree has been updated to reference a new replacement block, but the threaded linked-list still points to the old, evicted block due to an interrupted operation.

Recovery: Finding orphans and half-orphans requires an $O(n^2)$ comparison of every metadata pair against every directory entry. To maintain performance, littlefs typically only checks for orphans during the first allocation after a boot sequence. Read-only mounts can ignore the threaded linked-list entirely.

In littlefs, moving a file between two directories cannot be done in a single atomic commit because a commit cannot span multiple directories. To prevent file duplication or loss during power-loss events, littlefs uses a mechanism called global state.

The Mechanism: Global State

Global state is a small set of data distributed across the filesystem as deltas (stored in metadata pairs). The actual global state is reconstructed by performing a bitwise XOR operation on all deltas found in the filesystem during the mount process.

Solving the Move Problem

To move a file (or directory) atomically:

1. Begin Move: Create a new reference in the destination directory and update the global state with a delta describing the move (e.g., gstate = moving file D in dir A).
2. Complete Move: Remove the old reference from the source directory and update the global state with a delta that cancels out the previous move delta (e.g., gstate = no move).

Power-Loss Recovery

If power is lost mid-move, the file may exist in both the source and destination directories. Upon the next mount, littlefs reconstructs the global state from the deltas. If the reconstructed state indicates an ongoing move, the filesystem uses that information to identify and resolve the duplication (e.g., by removing the redundant file).

A metadata block is structured as a series of commits. Each commit contains a variable number of metadata entries followed by a 32-bit CRC.

Layout Components

• Revision Count (32-bit): Incremented per erase cycle.
• Entries: Metadata entries consist of a 32-bit tag followed by a variable-length data blob. Entries are not necessarily word-aligned, though writes must align with the program block size.
• CRC (32-bit): Used to detect corruption. Uses a CRC-32 polynomial of 0x04c11db7 initialized with 0xffffffff.

Iteration Mechanism

To support both forward and backward iteration without duplicating tag space, neighboring entries have their tags XORed together, starting with 0xffffffff.

• Forward Iteration: tag ~A $\rightarrow$ xor $\rightarrow$ tag A $\rightarrow$ xor $\rightarrow$ tag AxB...
• Backward Iteration: tag ~A $\rightarrow$ xor $\rightarrow$ 0xffffffff...