Typedefs
typedef uint32_t	zms_id_t
	ID type used in the ZMS API.

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.

Detailed Description

Typedef Documentation

◆ zms_id_t

typedef uint32_t zms_id_t

#include <zephyr/kvss/zms.h>

ID type used in the ZMS API.

Note: The width of this type depends on CONFIG_ZMS_ID_64BIT.

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_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.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ zms_id_t

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_mount()

◆ zms_mount_force()

◆ zms_read()

◆ zms_read_hist()

◆ zms_sector_use_next()

◆ zms_write()