Functions
int	zms_mount (struct zms_fs *fs)
	Mount a ZMS file system onto the device specified in `fs`.

int	zms_clear (struct zms_fs *fs)
	Clear the ZMS file system from device.

ssize_t	zms_write (struct zms_fs fs, uint32_t id, const void data, size_t len)
	Write an entry to the file system.

int	zms_delete (struct zms_fs *fs, uint32_t id)
	Delete an entry from the file system.

ssize_t	zms_read (struct zms_fs fs, uint32_t id, void data, size_t len)
	Read an entry from the file system.

ssize_t	zms_read_hist (struct zms_fs fs, uint32_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, uint32_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.

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

Detailed Description

Function Documentation

◆ zms_active_sector_free_space()

size_t zms_active_sector_free_space ( struct zms_fs * fs )

#include <include/zephyr/fs/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
-EACCES	if ZMS is still not initialized.

◆ zms_calc_free_space()

ssize_t zms_calc_free_space ( struct zms_fs * fs )

#include <include/zephyr/fs/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.

Return values

Number	of free bytes (>= 0) on success.
-EACCES	if ZMS is still not initialized.
-EIO	if there is a memory read/write error.

◆ zms_clear()

int zms_clear ( struct zms_fs * fs )

#include <include/zephyr/fs/zms.h>

Clear the ZMS file system from device.

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.

◆ zms_delete()

int zms_delete	(	struct zms_fs *	fs,
		uint32_t	id
	)

#include <include/zephyr/fs/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.

◆ zms_get_data_length()

ssize_t zms_get_data_length	(	struct zms_fs *	fs,
		uint32_t	id
	)

#include <include/zephyr/fs/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.

Return values

Length	of the entry with the given `id` (> 0) on success.
-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.

◆ zms_mount()

int zms_mount ( struct zms_fs * fs )

#include <include/zephyr/fs/zms.h>

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

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 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,
		uint32_t	id,
		void *	data,
		size_t	len
	)

#include <include/zephyr/fs/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.

Return values

Number	of bytes read (> 0) on success.
-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`.

◆ zms_read_hist()

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

#include <include/zephyr/fs/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.

Return values

Number	of bytes read (> 0) on success.
-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.

◆ zms_sector_use_next()

int zms_sector_use_next ( struct zms_fs * fs )

#include <include/zephyr/fs/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.

◆ zms_write()

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

#include <include/zephyr/fs/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.

Return values

Number	of bytes written (`len` or 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 `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_mount()

◆ zms_read()

◆ zms_read_hist()

◆ zms_sector_use_next()

◆ zms_write()