Functions
int	zms_mount (struct zms_fs *fs)
	Mount a ZMS file system onto the device specified in fs.
int	zms_mount_force (struct zms_fs *fs)
	Mount a ZMS file system onto the device specified in fs, wiping the partition if mounting fails the first time.
int	zms_clear (struct zms_fs *fs)
	Clear the ZMS file system from device.
ssize_t	zms_write (struct zms_fs fs, zms_id_t id, const void data, size_t len)
	Write an entry to the file system.
int	zms_delete (struct zms_fs *fs, zms_id_t id)
	Delete an entry from the file system.
ssize_t	zms_read (struct zms_fs fs, zms_id_t id, void data, size_t len)
	Read an entry from the file system.
ssize_t	zms_read_hist (struct zms_fs fs, zms_id_t id, void data, size_t len, uint32_t cnt)
	Read a history entry from the file system.
ssize_t	zms_get_data_length (struct zms_fs *fs, zms_id_t id)
	Gets the length of the data that is stored in an entry with a given id.
ssize_t	zms_calc_free_space (struct zms_fs *fs)
	Calculate the available free space in the file system.
ssize_t	zms_active_sector_free_space (struct zms_fs *fs)
	Tell how much contiguous free space remains in the currently active ZMS sector.
int	zms_sector_use_next (struct zms_fs *fs)
	Close the currently active sector and switch to the next one.
int	zms_get_num_cycles (struct zms_fs fs, uint32_t cycles)
	Return the maximum sector recycle count across all sectors.
int	zms_get_sector_num_cycles (struct zms_fs fs, uint32_t sector, uint32_t cycles)
	Return the recycle count for a specific sector.
int	zms_iter_init_with_config (const struct zms_fs fs, struct zms_iter iter, const struct zms_iter_config *config)
	Initialise a ZMS iterator with filtering configuration.
int	zms_iter_init (const struct zms_fs fs, struct zms_iter iter)
	Initialise a ZMS iterator.
int	zms_iter_next (struct zms_fs fs, struct zms_iter iter, zms_id_t id, size_t len, void *data, size_t data_len)
	Advance the iterator to the next live entry.
int	zms_iter_next_all (struct zms_fs fs, struct zms_iter iter, zms_id_t id, size_t len, void *data, size_t data_len)
	Advance the iterator to the next matching ATE.

Detailed Description

Function Documentation

◆ zms_active_sector_free_space()

ssize_t zms_active_sector_free_space ( struct zms_fs * fs )

#include <zephyr/kvss/zms.h>

Tell how much contiguous free space remains in the currently active ZMS sector.

Parameters

fs	Pointer to the file system.

Return values

>=0	Number of free bytes in the currently active sector. On success, it will be equal to the number of bytes that can be written without automatically advancing to the next sector.
-EACCES	if ZMS is still not initialized.
-EINVAL	if fs is NULL.

◆ zms_calc_free_space()

ssize_t zms_calc_free_space ( struct zms_fs * fs )

#include <zephyr/kvss/zms.h>

Calculate the available free space in the file system.

Parameters

fs	Pointer to the file system.

Returns: Number of free bytes. On success, it will be equal to the number of bytes that can still be written to the file system. Calculating the free space is a time-consuming operation, especially on SPI flash. On error, returns negative value of error codes defined in errno.h.; Number of free bytes (>= 0) on success.

Return values

-EACCES	if ZMS is still not initialized.
-EIO	if there is a memory read/write error.
-EINVAL	if fs is NULL.

◆ zms_clear()

int zms_clear ( struct zms_fs * fs )

#include <zephyr/kvss/zms.h>

Clear the ZMS file system from device.

The ZMS file system must be re-mounted after this operation.

Parameters

fs	Pointer to the file system.

Return values

0	on success.
-EACCES	if fs is not mounted.
-ENXIO	if there is a device error.
-EIO	if there is a memory read/write error.
-EINVAL	if fs is NULL.

◆ zms_delete()

int zms_delete	(	struct zms_fs *	fs,
		zms_id_t	id )

#include <zephyr/kvss/zms.h>

Delete an entry from the file system.

Parameters

fs	Pointer to the file system.
id	ID of the entry to be deleted.

Return values

0	on success.
-EACCES	if ZMS is still not initialized.
-ENXIO	if there is a device error.
-EIO	if there is a memory read/write error.
-EINVAL	if fs is NULL.

◆ zms_get_data_length()

ssize_t zms_get_data_length	(	struct zms_fs *	fs,
		zms_id_t	id )

#include <zephyr/kvss/zms.h>

Gets the length of the data that is stored in an entry with a given id.

Parameters

fs	Pointer to the file system.
id	ID of the entry whose data length to retrieve.

Returns: Data length contained in the ATE. On success, it will be equal to the number of bytes in the ATE. On error, returns negative value of error codes defined in errno.h.; Length of the entry with the given id (> 0) on success.

Return values

-EACCES	if ZMS is still not initialized.
-EIO	if there is a memory read/write error.
-ENOENT	if there is no entry with the given id.
-EINVAL	if fs is NULL.

◆ zms_get_num_cycles()

int zms_get_num_cycles	(	struct zms_fs *	fs,
		uint32_t *	cycles )

#include <zephyr/kvss/zms.h>

Return the maximum sector recycle count across all sectors.

Iterates all sectors and stores the highest 32-bit cycle counter found in each sector's empty ATE in cycles. This can be used to estimate write-cycle consumption during testing.

Parameters

fs	Pointer to the file system.
cycles	Pointer to store the maximum 32-bit cycle count across sectors.

Return values

0	on success.
-EINVAL	if `fs` or `cycles` is NULL.
-EACCES	if the file system is not mounted.

◆ zms_get_sector_num_cycles()

int zms_get_sector_num_cycles	(	struct zms_fs *	fs,
		uint32_t	sector,
		uint32_t *	cycles )

#include <zephyr/kvss/zms.h>

Return the recycle count for a specific sector.

Parameters

fs	Pointer to the file system.
sector	Sector index (0-based, must be less than `fs->sector_count`).
cycles	Pointer to store the 32-bit cycle count.

Return values

0	on success.
-EINVAL	if `fs` or `cycles` is NULL, or `sector` is out of range.
-EACCES	if the file system is not mounted.
-ENOENT	if the sector has no valid empty ATE.

◆ zms_iter_init()

int zms_iter_init	(	const struct zms_fs *	fs,
		struct zms_iter *	iter )

#include <zephyr/kvss/zms.h>

Initialise a ZMS iterator.

Captures the current write position of the file system as the iteration boundary. Entries written or deleted after this call will not appear in subsequent calls to zms_iter_next.

Note: The caller must not write to or delete from fs between zms_iter_init() and the last zms_iter_next() call.

Parameters

fs	Mounted file system instance.
iter	Iterator state to initialise.

Return values

0	Success.
-EINVAL	`fs` or `iter` is NULL, or `fs` is not mounted.

◆ zms_iter_init_with_config()

int zms_iter_init_with_config	(	const struct zms_fs *	fs,
		struct zms_iter *	iter,
		const struct zms_iter_config *	config )

#include <zephyr/kvss/zms.h>

Initialise a ZMS iterator with filtering configuration.

Captures the current write position of the file system as the iteration boundary. Entries written or deleted after this call will not appear in subsequent calls to zms_iter_next.

When config->use_mask is true, an entry is returned only if (id & config->mask_id) == id. When config->use_range is true, an entry is returned only if its ID lies in the inclusive range [config->min_id, config->max_id]. When config->use_predicate is true, an entry is returned only if config->predicate_func(id) returns true.

If either filter is disabled, the iterator falls back to the default value: ZMS_ITER_MASK_ALL for the mask and the full [ZMS_ITER_ID_MIN, ZMS_ITER_ID_MAX] range. Predicate filtering is disabled by default.

Note: The caller must not write to or delete from fs between zms_iter_init_with_config() and the last zms_iter_next() call.

Parameters

fs	Mounted file system instance.
iter	Iterator state to initialise.
config	Iterator configuration supplied by the caller.

Return values

0	Success.
-EINVAL	`fs`, `iter`, or `config` is NULL, `fs` is not mounted, `config->predicate_func` is NULL while `use_predicate` is enabled, or the configured range is invalid.

◆ zms_iter_next()

int zms_iter_next	(	struct zms_fs *	fs,
		struct zms_iter *	iter,
		zms_id_t *	id,
		size_t *	len,
		void *	data,
		size_t	data_len )

#include <zephyr/kvss/zms.h>

Advance the iterator to the next live entry.

Walks the ATE ring from newest to oldest. For each ID, only the most recently written, non-deleted (len > 0) entry is yielded; older history revisions and delete-markers are skipped transparently.

Note: When the returned len (the data length stored in the ATE) does not exceed ZMS_DATA_IN_ATE_SIZE, the entry's data is held inside the ATE itself. In that case, and only if a data buffer is provided, the data is copied into it directly (no extra flash read). At most data_len bytes are copied, so provide a buffer with data_len greater than or equal to len to receive the complete data. Entries whose len exceeds ZMS_DATA_IN_ATE_SIZE are not copied and must be read with zms_read.

Parameters

fs	Mounted file system instance.
iter	Iterator state (must be initialised with zms_iter_init or zms_iter_init_with_config).
id	On success (return value 1): populated with the entry ID.
len	On success (return value 1): populated with the stored data length in bytes.
data	Optional caller-allocated buffer. When non-NULL and the entry's data is stored directly inside the ATE (its length does not exceed ZMS_DATA_IN_ATE_SIZE), that data is copied here (at most `data_len` bytes). Data that is not stored inside the ATE (larger entries) is not copied; use zms_read to retrieve it. Pass NULL to skip copying.
data_len	Size in bytes of the buffer pointed to by `data`. Ignored when `data` is NULL.

Return values

1	Entry found; `id` and `len` are valid.
0	No more entries; the walk is complete.
-EINVAL	`fs`, `iter`, `id`, or `len` is NULL, or `fs` is not mounted.
-EIO	Flash read error.
-ENXIO	Device error.

◆ zms_iter_next_all()

int zms_iter_next_all	(	struct zms_fs *	fs,
		struct zms_iter *	iter,
		zms_id_t *	id,
		size_t *	len,
		void *	data,
		size_t	data_len )

#include <zephyr/kvss/zms.h>

Advance the iterator to the next matching ATE.

Walks the ATE ring from newest to oldest and returns all matching ATEs, including delete markers (len == 0) and older history revisions.

This function does not perform ID uniqueness filtering. IDs can therefore appear multiple times during traversal.

Note: When the returned len (the data length stored in the ATE) does not exceed ZMS_DATA_IN_ATE_SIZE, the entry's data is held inside the ATE itself. In that case, and only if a data buffer is provided, the data is copied into it directly (no extra flash read). At most data_len bytes are copied, so provide a buffer with data_len greater than or equal to len to receive the complete data. Entries whose len exceeds ZMS_DATA_IN_ATE_SIZE, and delete markers (len == 0), are not copied; use zms_read for the latest value or zms_read_hist to retrieve older revisions.

Parameters

fs	Mounted file system instance.
iter	Iterator state (must be initialised with zms_iter_init or zms_iter_init_with_config).
id	On success (return value 1): populated with the entry ID.
len	On success (return value 1): populated with the stored data length in bytes (0 means delete marker).
data	Optional caller-allocated buffer. When non-NULL and the entry's data is stored directly inside the ATE (its length does not exceed ZMS_DATA_IN_ATE_SIZE), that data is copied here (at most `data_len` bytes). Data that is not stored inside the ATE (larger entries) and delete markers (len == 0) are not copied; use zms_read to retrieve stored data. Pass NULL to skip copying.
data_len	Size in bytes of the buffer pointed to by `data`. Ignored when `data` is NULL.

Return values

1	Entry found; `id` and `len` are valid.
0	No more entries; the walk is complete.
-EINVAL	`fs`, `iter`, `id`, or `len` is NULL, or `fs` is not mounted.
-EIO	Flash read error.
-ENXIO	Device error.

◆ zms_mount()

int zms_mount ( struct zms_fs * fs )

#include <zephyr/kvss/zms.h>

Mount a ZMS file system onto the device specified in fs.

If the flash area is erased and no valid ZMS header is found, mount will format the area and create a valid header by default. Set ZMS_MOUNT_FLAG_NO_FORMAT in fs->mount_flags to disable this auto-format behavior and fail the mount instead.

Parameters

fs	Pointer to the file system.

Return values

0	on success.
-ENOTSUP	if the detected file system is not ZMS.
-EPROTONOSUPPORT	if the ZMS version is not supported.
-EINVAL	if fs is NULL or any of the flash parameters or the sector layout is invalid.
-ENXIO	if there is a device error.
-EIO	if there is a memory read/write error.

◆ zms_mount_force()

int zms_mount_force ( struct zms_fs * fs )

#include <zephyr/kvss/zms.h>

Mount a ZMS file system onto the device specified in fs, wiping the partition if mounting fails the first time.

Parameters

fs	Pointer to the file system.

Return values

0	on success.
-ENOTSUP	if the detected file system is not ZMS.
-EPROTONOSUPPORT	if the ZMS version is not supported.
-EINVAL	if fs is NULL or any of the flash parameters or the sector layout is invalid.
-ENXIO	if there is a device error.
-EIO	if there is a memory read/write error.

◆ zms_read()

ssize_t zms_read	(	struct zms_fs *	fs,
		zms_id_t	id,
		void *	data,
		size_t	len )

#include <zephyr/kvss/zms.h>

Read an entry from the file system.

Parameters

fs	Pointer to the file system.
id	ID of the entry to be read.
data	Pointer to data buffer.
len	Number of bytes to read at most.

Returns: Number of bytes read. On success, it will be equal to the number of bytes requested to be read or less than that if the stored data has a smaller size than the requested one. On error, returns negative value of error codes defined in errno.h.; Number of bytes read (> 0) on success.

Return values

-EACCES	if ZMS is still not initialized.
-EIO	if there is a memory read/write error.
-ENOENT	if there is no entry with the given id.
-EINVAL	if fs is NULL.

◆ zms_read_hist()

ssize_t zms_read_hist	(	struct zms_fs *	fs,
		zms_id_t	id,
		void *	data,
		size_t	len,
		uint32_t	cnt )

#include <zephyr/kvss/zms.h>

Read a history entry from the file system.

Parameters

fs	Pointer to the file system.
id	ID of the entry to be read.
data	Pointer to data buffer.
len	Number of bytes to be read.
cnt	History counter: 0: latest entry, 1: one before latest ...

Returns: Number of bytes read. On success, it will be equal to the number of bytes requested to be read. When the return value is larger than the number of bytes requested to read this indicates not all bytes were read, and more data is available. On error, returns negative value of error codes defined in errno.h.; Number of bytes read (> 0) on success.

Return values

-EACCES	if ZMS is still not initialized.
-EIO	if there is a memory read/write error.
-ENOENT	if there is no entry with the given id and history counter.
-EINVAL	if fs is NULL.

◆ zms_sector_use_next()

int zms_sector_use_next ( struct zms_fs * fs )

#include <zephyr/kvss/zms.h>

Close the currently active sector and switch to the next one.

Note: The garbage collector is called on the new sector.

Warning: This routine is made available for specific use cases. It collides with ZMS's goal of avoiding any unnecessary flash erase operations. Using this routine extensively can result in premature failure of the flash device.

Parameters

fs	Pointer to the file system.

Return values

0	on success.
-EACCES	if ZMS is still not initialized.
-EIO	if there is a memory read/write error.
-EINVAL	if fs is NULL.

◆ zms_write()

ssize_t zms_write	(	struct zms_fs *	fs,
		zms_id_t	id,
		const void *	data,
		size_t	len )

#include <zephyr/kvss/zms.h>

Write an entry to the file system.

Note: When the len parameter is equal to 0 the entry is effectively removed (it is equivalent to calling zms_delete()). It is not possible to distinguish between a deleted entry and an entry with data of length 0.

Parameters

fs	Pointer to the file system.
id	ID of the entry to be written.
data	Pointer to the data to be written.
len	Number of bytes to be written (maximum 64 KiB).

Returns: Number of bytes written. On success, it will be equal to the number of bytes requested to be written or 0. When a rewrite of the same data already stored is attempted, nothing is written to flash, thus 0 is returned. On error, returns negative value of error codes defined in errno.h.; Number of bytes written (len or 0) on success.

Return values

-EACCES	if ZMS is still not initialized.
-ENXIO	if there is a device error.
-EIO	if there is a memory read/write error.
-EINVAL	if fs is NULL or len is invalid.
-ENOSPC	if no space is left on the device.

Functions

Detailed Description

Function Documentation

◆ zms_active_sector_free_space()

◆ zms_calc_free_space()

◆ zms_clear()

◆ zms_delete()

◆ zms_get_data_length()

◆ zms_get_num_cycles()

◆ zms_get_sector_num_cycles()

◆ zms_iter_init()

◆ zms_iter_init_with_config()

◆ zms_iter_next()

◆ zms_iter_next_all()

◆ zms_mount()

◆ zms_mount_force()

◆ zms_read()

◆ zms_read_hist()

◆ zms_sector_use_next()

◆ zms_write()