Non-volatile Storage APIs

Non-volatile Storage APIs. More...

Functions
int	nvs_mount (struct nvs_fs *fs)
	Mount an NVS file system onto the flash device specified in fs.
int	nvs_clear (struct nvs_fs *fs)
	Clear the NVS file system from flash.
ssize_t	nvs_write (struct nvs_fs *fs, uint16_t id, const void *data, size_t len)
	Write an entry to the file system.
int	nvs_delete (struct nvs_fs *fs, uint16_t id)
	Delete an entry from the file system.
ssize_t	nvs_read (struct nvs_fs *fs, uint16_t id, void *data, size_t len)
	Read an entry from the file system.
ssize_t	nvs_read_hist (struct nvs_fs *fs, uint16_t id, void *data, size_t len, uint16_t cnt)
	Read a history entry from the file system.
ssize_t	nvs_calc_free_space (struct nvs_fs *fs)
	Calculate the available free space in the file system.
size_t	nvs_sector_max_data_size (struct nvs_fs *fs)
	Tell how many contiguous free space remains in the currently active NVS sector.
int	nvs_sector_use_next (struct nvs_fs *fs)
	Close the currently active sector and switch to the next one.

Detailed Description

Non-volatile Storage APIs.

Function Documentation

nvs_calc_free_space()

ssize_t nvs_calc_free_space

(

struct nvs_fs *

fs

)

#include <zephyr/fs/nvs.h>

Calculate the available free space in the file system.

Parameters

fs	Pointer to file system

Returns

Number of bytes free. 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 errno.h defined error codes.

nvs_clear()

int nvs_clear

(

struct nvs_fs *

fs

)

#include <zephyr/fs/nvs.h>

Clear the NVS file system from flash.

Parameters

fs	Pointer to file system

Return values

0	Success
-ERRNO	errno code if error

nvs_delete()

int nvs_delete	(	struct nvs_fs *	fs,
		uint16_t	id )

#include <zephyr/fs/nvs.h>

Delete an entry from the file system.

Parameters

fs	Pointer to file system
id	Id of the entry to be deleted

Return values

0	Success
-ERRNO	errno code if error

nvs_mount()

int nvs_mount

(

struct nvs_fs *

fs

)

#include <zephyr/fs/nvs.h>

Mount an NVS file system onto the flash device specified in fs.

Parameters

fs	Pointer to file system

Return values

0	Success
-ERRNO	errno code if error

nvs_read()

ssize_t nvs_read	(	struct nvs_fs *	fs,
		uint16_t	id,
		void *	data,
		size_t	len )

#include <zephyr/fs/nvs.h>

Read an entry from the file system.

Parameters

fs	Pointer to file system
id	Id of the entry to be read
data	Pointer to data buffer
len	Number of bytes to be read

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 errno.h defined error codes.

nvs_read_hist()

ssize_t nvs_read_hist	(	struct nvs_fs *	fs,
		uint16_t	id,
		void *	data,
		size_t	len,
		uint16_t	cnt )

#include <zephyr/fs/nvs.h>

Read a history entry from the file system.

Parameters

fs	Pointer to 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 errno.h defined error codes.

nvs_sector_max_data_size()

size_t nvs_sector_max_data_size

(

struct nvs_fs *

fs

)

#include <zephyr/fs/nvs.h>

Tell how many contiguous free space remains in the currently active NVS sector.

Parameters

fs	Pointer to the file system.

Returns

Number of free bytes.

nvs_sector_use_next()

int nvs_sector_use_next

(

struct nvs_fs *

fs

)

#include <zephyr/fs/nvs.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 breaks the aim of the NVS to avoid any unnecessary flash erases. 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 errno.h defined error codes.

nvs_write()

ssize_t nvs_write	(	struct nvs_fs *	fs,
		uint16_t	id,
		const void *	data,
		size_t	len )

#include <zephyr/fs/nvs.h>

Write an entry to the file system.

Note

When len parameter is equal to 0 then entry is effectively removed (it is equivalent to calling of nvs_delete). Any calls to nvs_read for entries with data of length 0 will return error.
It is not possible to distinguish between deleted entry and entry with data of length 0.

Parameters

fs	Pointer to 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

Returns

Number of bytes written. On success, it will be equal to the number of bytes requested to be written. 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 errno.h defined error codes.