ZMS API

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 <zephyr/fs/zms.h>

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

Parameters

fs	Pointer to the file system.

Returns

Number of free bytes.

zms_calc_free_space()

ssize_t zms_calc_free_space

(

struct zms_fs *

fs

)

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

zms_clear()

int zms_clear

(

struct zms_fs *

fs

)

#include <zephyr/fs/zms.h>

Clear the ZMS file system from device.

Parameters

fs	Pointer to the file system.

Return values

0	Success
-ERRNO	Negative errno code on error

zms_delete()

int zms_delete	(	struct zms_fs *	fs,
		uint32_t	id )

#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	Success
-ERRNO	Negative errno code on error

zms_get_data_length()

ssize_t zms_get_data_length	(	struct zms_fs *	fs,
		uint32_t	id )

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

zms_mount()

int zms_mount

(

struct zms_fs *

fs

)

#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	Success
-ERRNO	Negative errno code on error

zms_read()

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

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

zms_read_hist()

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

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

zms_sector_use_next()

int zms_sector_use_next

(

struct zms_fs *

fs

)

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

Returns

0 on success. On error, returns negative value of error codes defined in errno.h.

zms_write()

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

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