littlefs2-pack

A Rust crate for building a file system into a LittleFS binary file to be flashed to an embedded device.

This crate wraps the LittleFS C library using the littlefs2-sys crate. The littlefs2 crate might have been an easier starting point but it doesn't currently allow setting the image configuration dynamically at runtime, such as the block size and count.

littlefs2-pack is tested for compatibility with the C++ mklittlefs project. This is ensured with the cross-compat.rs test that packs with one tool then unpack with the other, in both directions. These tests are ran against the version of mklittlefs in the submodule and requires that tool to be built prior to running the tests.

API

The crate can be called directly to create a LittleFS image from a target directory.

use littlefs2_pack::{LfsImage, LfsImageConfig};
let config = LfsImageConfig {
    block_size: 4096,
    block_count: 256,  // 1 MiB total
    read_size: 256,
    write_size: 256,
};
let mut image = LfsImage::new(config).unwrap();
image.format().unwrap();
image.mount_and_then(|fs| {
    fs.create_dir("/data")?;
    fs.write_file("/data/hello.txt", b"Hello from LittleFS!")?;
    Ok(())
}).unwrap();
let binary = image.into_data();
std::fs::write("filesystem.bin", &binary).unwrap();

Configuration

This crate handles loading and processing the LittleFS image configuration settings. These are stored in TOML files. This minimal crate can then be loaded by both the firmware project itself and build.rs to parse the settings from a single source of truth.

Example Configuration File

# This TOML sets the parameters for the LittleFS image
# This file is then read by both the firmware for use with
# the on-device bindings and the `littlefs` tool to create
# the image.
[image]

# Filesystem block (erase unit) size in bytes.
# Must be >= 128 and a multiple of both read-size and write-size.
# Power-of-two values recommended (e.g. 256, 4096).
block_size = 4096

# Minimum read size / page size in bytes.
# If only --page-size is given it sets both read and write size.
page_size = 256

# Minimum read size in bytes (overrides page_size for reads).
read_size = 16

# Minimum program (write) size in bytes (overrides page_size for writes).
write_size = 512

#!! Either block_count or image_size should be defined but not both
#!! image_size is block_size * block_count
#!! block_count is image_size / block_size
# Total number of blocks in the filesystem.
block_count = 3096
# Total image size in bytes (alternative to --block-count).
# Must be an exact multiple of --block-size.
# image_size = 15_998_976

# Block-cycle count for wear leveling.
# Higher values are more performant but less wear-leveled.
# -1 (the default) disables wear leveling entirely, which is fine for
# one-shot image creation. Add wear leveling if your application
# will be regularly writing to the partition.
# If this parameter is not set in the TOML file then the default
# of -1 will be applied.
block_cycles = -1


# The settings relevant to the local directory to be synced to
# the microcontroller, including path and ignores
[directory]

# The local root folder of the directory to be synced
root = "./website"

# The maximum recursive directory depth to sync.
# -1 is unlimited depth
depth = -1

# Ignore hidden files and folders
ignore_hidden = true

# Whether to ignore files and folders as specificed by
# the local .gitignore files
gitignore = true
# Check the repository level .gitignore and ignore files
# and folders defined there as well
repo_gitignore = true

# A list of global ignores to add to the ignore list
glob_ignores = ["*.bkup", "build"]

# A list of global includes that supersede all other
# ignores, both globs and gitignores
glob_includes = []