littlefs Geometry Configuration: Match Read, Program and Erase Units Before Formatting

Choose littlefs geometry by reconciling three contracts: the flash chip’s command boundaries, the driver’s accepted requests, and the filesystem’s configuration constraints. A program page, a minimum write unit, and an erase block can have different sizes. Copying one of those numbers into every configuration field can produce a mountable system that later damages data.

The software reference here is littlefs v2.11.2. The concrete device reference is Microchip SST26VF064B/SST26VF064BA datasheet DS20005119K. Its dimensions illustrate the worksheet; they do not establish compatibility with your controller or driver. Complete the worksheet before any format operation. On deployed media, preserve the existing image and its original configuration rather than trying alternative geometries in place.

1. Separate the physical units

For the cited Microchip device, a sector erase covers 4 Kbytes. Page Program accepts 1–256 whole bytes, and a command crossing the 256-byte page boundary wraps within that page. Thus 256 is a command-boundary limit, not a requirement to program exactly 256 bytes every time. These facts come from sections 5.17 and 5.20 of the exact device datasheet.

A driver can expose a different interface. It may split a large request into page-contained commands, require aligned buffers for DMA, or reject requests that the bare chip could accept. Record those requirements separately. Never assume that the filesystem’s callback can send its entire input as one physical program command.

2. Fill a configuration worksheet

Field or boundary	Evidence to record	Reject when
Partition base and length	Authoritative memory map, ownership, device capacity, protected neighboring regions.	An erase can reach outside the owned partition.
read_size	Smallest chosen callback read granularity supported by the adapter.	The adapter cannot honor every legal offset and length.
prog_size	Chosen callback program granularity plus driver alignment and page-splitting behavior.	A legal callback can be rejected or wrap a physical page.
block_size	Filesystem erase unit and the exact physical erases used to implement it.	Erasing one logical block changes a neighbor.
block_count	Number of complete logical blocks inside the partition.	Address arithmetic exceeds the region or silently ignores an unexplained remainder.
cache_size	Chosen RAM budget and divisibility checks.	It is incompatible with read, program, or block sizes.

In the v2.11.2 configuration contract, block size is a multiple of read and program sizes; cache size is also a multiple of both and a factor of block size. A logical block may exceed the physical erase size, provided the adapter implements that larger erase correctly. The header does not make a larger logical block a free capacity optimization: non-inline files occupy at least one block.

Also record the lookahead buffer, metadata policy, maximum file size, and any static buffers. Those influence resource use and behavior, but they cannot repair a wrong address mapping. Keep byte units explicit throughout; do not mix bits, bytes, pages, and sectors in one unlabeled spreadsheet.

3. Review the adapter before touching persistent data

Check the mapping from logical block and offset to physical address with overflow-safe arithmetic. Validate the block index, offset, length, and the complete end address before performing I/O. If a request spans several physical program pages, prove that the adapter splits it without dropping or repeating bytes. If one logical erase covers several physical sectors, prove that all belong to the same authorized partition.

Confirm completion semantics as well as dimensions. An adapter must not report success while a required operation has failed or remains outside its promised completion contract. Preserve negative errors rather than turning them into an apparent successful write. Geometry tests cannot compensate for missing completion polling or ignored protection failures.

Do not rely solely on assertions inside littlefs. The v2.11.2 initialization implementation contains size and divisibility assertions, but a production build may configure assertions differently, and these checks cannot know your partition ownership or chip-command implementation. Validate the worksheet in the integration’s build or startup checks too.

4. Qualify boundary cases on disposable media

First inspect configuration and run address calculations without writing. For physical tests, use an explicitly authorized test partition or sacrificial device with no valuable data, and retain neighboring-region baselines. Do not format a field unit to find out whether the worksheet is correct.

1. Read at the first and last legal offsets and compare the driver’s result with the expected region limits.
2. Exercise legal callback lengths around read and program granularity boundaries.
3. Exercise a program request that ends exactly at a physical page boundary, then one that the adapter must split across it.
4. Verify the entire affected test range and adjacent sentinel regions, not just the newly written bytes.
5. Exercise the final logical block, including all physical sectors required for its erase.
6. Confirm that out-of-range or misaligned requests are rejected before issuing physical commands.

Only after those tests pass should a separate filesystem qualification create, remount, and verify a test volume using the recorded configuration. A successful mount is insufficient evidence of correct page splitting or boundary isolation.

Hypothetical worksheet review

Suppose a product reserves an aligned 1 MiB region on the cited flash. A proposed adapter chooses 16-byte read and program granularity, a 256-byte cache, and 4,096-byte logical blocks. That gives 256 logical blocks; 256 is divisible by 16, and 4,096 by 256. These arithmetic checks pass. They do not prove the adapter supports the selected granularity or correctly divides physical commands.

If the proposed implementation forwards a 256-byte callback starting at an offset not aligned to the physical page, the datasheet’s wrap behavior becomes decisive. The review must show that such callbacks are impossible under the verified contract or that the adapter splits them correctly. Merely increasing the cache will not fix an unsafe command path.

Approve a geometry only with the worksheet, driver revision, device revision, and boundary-test evidence attached. Revisit it when changing partition layout, flash parts, DMA behavior, or the filesystem port. If an existing volume fails after such a change, preserve it and investigate compatibility before authorizing any reinitialization.