Update documentation

Author: Arsievert

Doxyfile

@@ -90,8 +90,8 @@ ENABLE_PREPROCESSING   = YES
 MACRO_EXPANSION        = NO
 EXPAND_ONLY_PREDEF     = NO
 SEARCH_INCLUDES        = YES
-INCLUDE_PATH           = include
-PREDEFINED             = CFGPACK_LZ4 CFGPACK_HEATSHRINK
+INCLUDE_PATH           = include third_party/littlefs
+PREDEFINED             = CFGPACK_LZ4 CFGPACK_HEATSHRINK CFGPACK_LITTLEFS
 
 #---------------------------------------------------------------------------
 # Graph configuration (requires Graphviz)

README.md

@@ -31,6 +31,7 @@ This checks for required tools (`clang`, `clang-format`, `make`, `ar`), installs
 - [API Reference](docs/source/api-reference.md) — Complete API documentation (errors, values, schema, runtime, typed functions)
 - [Schema Versioning](docs/source/versioning.md) — Version detection, migration, and type widening
 - [Compression](docs/source/compression.md) — LZ4/heatshrink decompression support
+- [LittleFS](docs/source/littlefs.md) — LittleFS flash storage wrappers
 - [Stack Analysis](docs/source/stack-analysis.md) — Per-function stack frame sizes for embedded budgeting
 - [Fuzz Testing](docs/source/fuzz-testing.md) — libFuzzer harnesses for parser and decode robustness
 
@@ -92,11 +93,12 @@ vehicle 1
   - `api.h` — main cfgpack runtime API (set/get/pagein/pageout/print/version/size).
   - `decompress.h` — optional LZ4/heatshrink decompression support.
   - `io_file.h` — optional FILE*-based convenience wrappers for desktop/POSIX systems.
-- `src/` — library implementation (`core.c`, `io.c`, `io_file.c`, `msgpack.c`, `schema_parser.c`, `tokens.c`, `wbuf.c`, `decompress.c`).
+  - `io_littlefs.h` — optional LittleFS-based convenience wrappers for flash storage.
+- `src/` — library implementation (`core.c`, `io.c`, `io_file.c`, `io_littlefs.c`, `msgpack.c`, `schema_parser.c`, `tokens.c`, `wbuf.c`, `decompress.c`).
 - `tests/` — C test programs plus sample data under `tests/data/`.
 - `tools/` — CLI tools source (`cfgpack-compress.c` for LZ4/heatshrink compression, `cfgpack-schema-pack.c` for converting schemas to msgpack binary).
-- `examples/` — complete usage examples (`allocate-once/`, `datalogger/`, `fleet_gateway/`, `low_memory/`, `sensor_hub/`).
-- `third_party/` — vendored dependencies (`lz4/`, `heatshrink/`).
+- `examples/` — complete usage examples (`allocate-once/`, `datalogger/`, `flash_config/`, `fleet_gateway/`, `low_memory/`, `sensor_hub/`).
+- `third_party/` — vendored dependencies (`lz4/`, `heatshrink/`, `littlefs/`).
 - `Makefile` — builds `build/out/libcfgpack.a`, test binaries, and tools.
 
 ## Building
@@ -130,21 +132,22 @@ Output:
 ```
 Running tests...
 
-  basic:         4/4 passed
-  core_edge:     11/11 passed
-  decompress:    8/8 passed
-  io_edge:       16/16 passed
-  json_edge:     8/8 passed
-  json_remap:    10/10 passed
-  measure:       15/15 passed
-  msgpack:       16/16 passed
+  basic:          4/4 passed
+  core_edge:      11/11 passed
+  decompress:     8/8 passed
+  io_edge:        16/16 passed
+  io_littlefs:    8/8 passed
+  json_edge:      8/8 passed
+  json_remap:     10/10 passed
+  measure:        15/15 passed
+  msgpack:        16/16 passed
   msgpack_schema: 17/17 passed
-  null_args:     40/40 passed
-  parser_bounds: 23/23 passed
-  parser:        3/3 passed
-  runtime:       24/24 passed
+  null_args:      40/40 passed
+  parser_bounds:  23/23 passed
+  parser:         3/3 passed
+  runtime:        24/24 passed
 
-TOTAL: 195/195 passed
+TOTAL: 203/203 passed
 ```
 
 ### Fuzz Testing
@@ -178,7 +181,7 @@ See [Fuzz Testing](docs/source/fuzz-testing.md) for detailed documentation on th
 
 ## Examples
 
-Five complete examples are provided in the `examples/` directory:
+Six complete examples are provided in the `examples/` directory:
 
 ### allocate-once
 
@@ -196,6 +199,14 @@ Basic data logger demonstrating schema parsing, typed convenience functions, and
 cd examples/datalogger && make run
 ```
 
+### flash_config
+
+Industrial sensor node demonstrating LittleFS flash storage with LZ4-compressed msgpack binary schemas and a v1 → v2 schema migration. Uses a RAM-backed LittleFS block device for desktop testing. Shows the composable I/O pattern: manual LFS read + `cfgpack_pagein_remap()` for cross-version migration, and `cfgpack_pageout_lfs()` / `cfgpack_pagein_lfs()` for same-version round-trips. Covers all five migration scenarios: keep, widen, move, remove, and add.
+
+```bash
+cd examples/flash_config && make run
+```
+
 ### fleet_gateway
 
 Fleet management gateway demonstrating LZ4-compressed msgpack binary schemas (pre-compiled from `.map` files via `cfgpack-schema-pack` and compressed with `cfgpack-compress lz4`) and a three-version migration chain (v1 -> v2 -> v3). Shows runtime LZ4 decompression of schema data before parsing, and uses `cfgpack_schema_measure_msgpack()` for right-sized heap allocation with no static buffer guessing. Covers all five migration scenarios: keep, widen, move, remove, and add.

docs/infrastructure.md

@@ -116,6 +116,12 @@ Two additional feature flags gate decompression library support:
 
 These are also passed to Doxygen as `PREDEFINED` macros so that conditional API surfaces appear in documentation.
 
+### Optional LittleFS Storage Wrappers
+
+- `-DCFGPACK_LITTLEFS` -- enables LittleFS storage wrappers (`cfgpack_pageout_lfs`, `cfgpack_pagein_lfs`)
+
+Unlike the compression flags, this is NOT on by default in `CFLAGS`. Applications that need LittleFS must explicitly pass `-DCFGPACK_LITTLEFS` and link `src/io_littlefs.c` along with the vendored LittleFS sources (`third_party/littlefs/lfs.c`, `third_party/littlefs/lfs_util.c`). This flag is also passed to Doxygen as a `PREDEFINED` macro.
+
 ### Compile-Time Limits
 
 Defined in `include/cfgpack/config.h` and overridable before including cfgpack headers:
@@ -145,6 +151,8 @@ third_party/heatshrink/heatshrink_decoder.c
 
 Notably, `src/io_file.c` is **excluded** from the core library because it depends on `<stdio.h>`. It is compiled separately with hosted flags and linked into tests and tools as needed. This preserves the embedded-friendly, zero-stdio core.
 
+Similarly, `src/io_littlefs.c` is **excluded** from the core library because it depends on LittleFS. It is compiled separately with `-DCFGPACK_LITTLEFS` and linked into applications, tests, and examples that use LittleFS storage.
+
 The archiver creates the library with `ar rcs`.
 
 ---
@@ -195,14 +203,15 @@ Each test binary links against: the core static library, `io_file.o`, the encode
 
 ### Test Binaries
 
-14 test files producing 13 test binaries (test.c is shared infrastructure, not a standalone binary):
+15 test files producing 14 test binaries (test.c is shared infrastructure, not a standalone binary):
 
 | Binary | Source | Area |
 |--------|--------|------|
 | `basic` | `tests/basic.c` | Core set/get/pageout/pagein, defaults, typed convenience functions |
 | `core_edge` | `tests/core_edge.c` | Edge cases in core API |
 | `decompress` | `tests/decompress.c` | LZ4 and heatshrink decompression |
 | `io_edge` | `tests/io_edge.c` | I/O edge cases |
+| `io_littlefs` | `tests/io_littlefs.c` | LittleFS I/O wrappers (RAM-backed block device) |
 | `json_edge` | `tests/json_edge.c` | JSON parser edge cases |
 | `json_remap` | `tests/json_remap.c` | JSON remapping functionality |
 | `measure` | `tests/measure.c` | Schema measure (pre-parse sizing) |
@@ -482,7 +491,20 @@ third_party/heatshrink/
 
 Heatshrink is an LZSS-based compression library designed for embedded systems with very low memory overhead. The decoder is compiled into the core library when `CFGPACK_HEATSHRINK` is defined. The encoder is used by tests (to generate compressed test data) and the `cfgpack-compress` tool.
 
-Both libraries are included via `-Ithird_party/lz4` and `-Ithird_party/heatshrink` in `CPPFLAGS`.
+### LittleFS
+
+```
+third_party/littlefs/
+    lfs.c
+    lfs.h
+    lfs_util.c
+    lfs_util.h
+    LICENSE.md
+```
+
+LittleFS is a little fail-safe filesystem designed for microcontrollers. The LittleFS sources are compiled directly into applications that use the cfgpack LittleFS wrappers (they are not part of the core `libcfgpack.a`).
+
+All three libraries are included via `-Ithird_party/lz4`, `-Ithird_party/heatshrink`, and `-Ithird_party/littlefs` in `CPPFLAGS`.
 
 ---
 
@@ -535,6 +557,7 @@ cfgpack/
 │   ├── config.h                #   Build configuration / compile-time limits
 │   ├── msgpack.h               #   MessagePack encode/decode
 │   ├── io_file.h               #   File I/O (hosted only)
+│   ├── io_littlefs.h           #   LittleFS I/O (optional, -DCFGPACK_LITTLEFS)
 │   └── decompress.h            #   Decompression API
 ├── src/                        # Library implementation
 │   ├── core.c                  #   Core get/set/init/pageout/pagein
@@ -543,6 +566,7 @@ cfgpack/
 │   ├── decompress.c            #   LZ4/heatshrink decompression
 │   ├── io.c                    #   Buffer I/O
 │   ├── io_file.c               #   File I/O (hosted, excluded from core lib)
+│   ├── io_littlefs.c           #   LittleFS I/O (optional, excluded from core lib)
 │   ├── tokens.c                #   Tokenizer for schema parsing
 │   └── wbuf.c                  #   Internal write buffer
 ├── tests/                      # Test files
@@ -565,12 +589,14 @@ cfgpack/
 ├── examples/                   # Usage examples
 │   ├── allocate-once/          #   One-shot allocation pattern
 │   ├── datalogger/             #   Data logger example
+│   ├── flash_config/           #   LittleFS + LZ4 + schema migration
 │   ├── fleet_gateway/          #   Fleet gateway with schema versioning
 │   ├── low_memory/             #   Low-memory embedded example
 │   └── sensor_hub/             #   Sensor hub example
 ├── third_party/                # Vendored dependencies
 │   ├── lz4/                    #   LZ4 compression library
-│   └── heatshrink/             #   Heatshrink compression library
+│   ├── heatshrink/             #   Heatshrink compression library
+│   └── littlefs/               #   LittleFS filesystem library
 ├── scripts/                    # Build/test/setup scripts
 │   ├── setup.sh                #   One-time project setup
 │   ├── run-tests.sh            #   Test runner with summary
@@ -585,6 +611,7 @@ cfgpack/
         ├── api.rst
         ├── api-reference.md
         ├── compression.md
+        ├── littlefs.md
         ├── fuzz-testing.md
         ├── stack-analysis.md
         └── versioning.md

docs/source/api-reference.md

@@ -574,6 +574,32 @@ cfgpack_err_t cfgpack_pagein_file(cfgpack_ctx_t *ctx, const char *path,
                                   uint8_t *scratch, size_t scratch_cap);
 ```
 
+## LittleFS I/O Wrappers (Optional)
+
+These functions use LittleFS operations and are provided for embedded systems with flash storage. The caller owns the `lfs_t` instance and must mount/unmount it externally. To use these, compile with `-DCFGPACK_LITTLEFS` and link `src/io_littlefs.c` and the LittleFS sources with your project.
+
+The scratch buffer serves double duty: the first `lfs->cfg->cache_size` bytes are used as the LittleFS file cache (via `lfs_file_opencfg`), and the remainder holds the serialized data. This avoids `lfs_malloc`, making the wrappers compatible with `LFS_NO_MALLOC` builds. See [LittleFS Storage Wrappers](littlefs.md) for the full scratch buffer layout and usage guide.
+
+```c
+#include "cfgpack/io_littlefs.h"
+
+/* Encode to a LittleFS file using caller scratch buffer (no heap).
+ * scratch must be >= cfg->cache_size + encoded size. */
+cfgpack_err_t cfgpack_pageout_lfs(const cfgpack_ctx_t *ctx,
+                                  lfs_t *lfs,
+                                  const char *path,
+                                  uint8_t *scratch,
+                                  size_t scratch_cap);
+
+/* Decode from a LittleFS file using caller scratch buffer (no heap).
+ * scratch must be >= cfg->cache_size + file size. */
+cfgpack_err_t cfgpack_pagein_lfs(cfgpack_ctx_t *ctx,
+                                 lfs_t *lfs,
+                                 const char *path,
+                                 uint8_t *scratch,
+                                 size_t scratch_cap);
+```
+
 ## MessagePack Helpers (Internal-Facing)
 
 These are lower-level functions used internally. They're exposed for advanced use cases.

docs/source/api.rst

@@ -39,6 +39,12 @@ File I/O Wrappers
 .. doxygenfile:: io_file.h
    :project: CFGPack
 
+LittleFS I/O Wrappers
+---------------------
+
+.. doxygenfile:: io_littlefs.h
+   :project: CFGPack
+
 Decompression
 -------------
 

docs/source/compression.md

@@ -75,7 +75,7 @@ Where `<algorithm>` is either `lz4` or `heatshrink`.
   [0..3]  4-byte little-endian original size
   [4..N]  LZ4-compressed data
   ```
-  This header is required because LZ4 decompression needs to know the output buffer size. The `examples/fleet_gateway/` example demonstrates reading this format at runtime.
+  This header is required because LZ4 decompression needs to know the output buffer size. The `examples/fleet_gateway/` example demonstrates reading this format at runtime. The `examples/flash_config/` example demonstrates the same pipeline with LittleFS flash storage.
 
 - **Heatshrink**: The output file contains raw compressed data only (no header). Heatshrink is a streaming decoder and does not require the original size up front.
 
@@ -108,15 +108,32 @@ The output binary can be parsed on-device with `cfgpack_schema_measure_msgpack()
 
 ## Third-Party Libraries
 
-LZ4 and heatshrink sources are vendored in `third_party/` for self-contained builds:
+LZ4, heatshrink, and LittleFS sources are vendored in `third_party/` for self-contained builds:
+
+### LZ4
 
 ```
-third_party/
-  lz4/
+third_party/lz4/
     lz4.h, lz4.c              # BSD-2-Clause license
-  heatshrink/
+```
+
+### Heatshrink
+
+```
+third_party/heatshrink/
     heatshrink_config.h       # window=8, lookahead=4
     heatshrink_decoder.h/c    # Used by library
     heatshrink_encoder.h/c    # Used by compression tool and tests
                               # ISC license
 ```
+
+### LittleFS
+
+```
+third_party/littlefs/
+    lfs.h, lfs.c              # Core filesystem implementation
+    lfs_util.h, lfs_util.c    # Utility functions
+    LICENSE.md                 # BSD-3-Clause license
+```
+
+LittleFS is a little fail-safe filesystem designed for microcontrollers. Unlike LZ4 and heatshrink, it is not compiled into the core library — it is linked directly by applications that use the LittleFS wrappers (`-DCFGPACK_LITTLEFS`). See [LittleFS Storage Wrappers](littlefs.md) for details.

docs/source/getting-started.rst

@@ -56,7 +56,9 @@ Include just ``cfgpack/cfgpack.h``; it re-exports the public API surface.
    the full measure-then-allocate pattern, ``examples/low_memory/`` for a
    complete example combining measure-then-allocate with schema migration, or
    ``examples/fleet_gateway/`` for msgpack binary schemas with a three-version
-   migration chain using ``cfgpack_schema_measure_msgpack()``.
+   migration chain using ``cfgpack_schema_measure_msgpack()``, or
+   ``examples/flash_config/`` for LittleFS flash storage with LZ4-compressed
+   msgpack schemas and a v1 → v2 remap migration.
 
 Map Format
 ----------

docs/source/index.rst

@@ -15,6 +15,7 @@ Hard caps: max 128 schema entries.
    api-reference
    versioning
    compression
+   littlefs
    stack-analysis
    fuzz-testing
 
@@ -29,6 +30,7 @@ Features
 - Schema versioning with embedded schema name for version detection
 - Index remapping and type widening for schema migrations
 - Optional LZ4/heatshrink decompression support
+- Optional LittleFS storage wrappers for flash-based embedded systems
 
 Indices and tables
 ==================