Skip to content

Zephyr Memory Storage (ZMS)

lbuild module: modm:zms

A key-value store for small values on flash, from the Zephyr RTOS, with 32-bit IDs. ZMS writes entries round-robin into sectors: the data grows from the start of a sector, the allocation table entries (ATE) with ID, length, CRCs and a cycle counter grow from the end. Full sectors are closed and their newest entries are moved by the garbage collector into the current sector, one sector always stays erased. Values of up to 8 bytes are stored inside the ATE.

#include <modm/ext/zms/zms.hpp>

zms_fs fs;
// Four sectors at the end of the flash, each of the largest page size
modm::zms::setup(fs, Flash::Size - 4*Flash::MaxPageSize, 4, Flash::MaxPageSize);
if (zms_mount(&fs)) { /* error */ }

uint32_t boot_count{};
zms_read(&fs, 1, &boot_count, sizeof(boot_count));
boot_count++;
zms_write(&fs, 1, &boot_count, sizeof(boot_count));

ZMS works on any modm::BlockDevice, for example a range of the internal flash or an external flash, with offsets relative to the block device:

modm::platform::BdFlash<Flash::Size - 16*1024> storage;
// Four sectors of one erase block each
modm::zms::setup<storage>(fs, 0, 4);

zms_mount() formats an erased area. modm::zms::setup() without a block device returns false if the sectors overlap the program image.

For storage written at runtime, put the sectors at the end of the internal flash. On dual-bank devices this is the second bank, which the program does not run from, so writes and erases don't stall the CPU (see modm:platform:flash). On single-bank devices every flash operation stalls the CPU and by default masks interrupts. A sector size of Flash::MaxPageSize works for both bank modes of devices with a dual-bank option byte, like the G4 with 2 kB pages in dual-bank and 4 kB pages in single-bank mode. On devices with large sectors at the end, like the 128 kB sectors of the F2/F4/F7, an external flash may be the better choice.

The API is documented in <zephyr/kvss/zms.h>, see also the Zephyr documentation.

On the internal flash ZMS relies on BdFlash, whose program() refuses non-erased targets and skips units of only erased bytes, and on modm::readMarked(), which reads words with a double ECC error as invalid.

Sectors must consist of whole erase blocks of the same size. Every value costs one ATE of 16 bytes (or BlockSizeWrite, if larger) plus the value rounded up to BlockSizeWrite bytes. A sector holds at most sector_size - 5 ATEs bytes of data.

ZMS logs nothing by default. With the modm:debug module, define CONFIG_ZMS_LOG_LEVEL to forward its messages to the modm logger: 1 for errors, 2 also for warnings, 3 also for info and 4 also for debug messages, for example:

<collect name="modm:build:cppdefines">CONFIG_ZMS_LOG_LEVEL=2</collect>

Most errors are about an invalid configuration, which the functions only report as -EINVAL. A blocking logger changes the timing, so log via RTT or a large buffer when testing power losses.

The ZMS functions are not thread-safe. If several fibers or interrupts access the same zms_fs, implement k_mutex_lock() and k_mutex_unlock(), which are weak empty functions.

Options

lookup_cache

Entries of the ID lookup cache in each zms_fs, 8 bytes each

Default: 32
Inputs: [0 .. 32 .. 1024]

Dependencies

modm:zms modm_zms modm: zms modm_architecture_block_device modm: architecture: block.device modm_zms->modm_architecture_block_device modm_math_utils modm: math: utils modm_zms->modm_math_utils