Non-Volatile Storage driver interface.
The NVS module allows you to manage non-volatile memory. Using the NVS APIs, you can read and write data from and to persistent storage.
Each NVS object is used to manage a region of non-volatile memory. The size of the region is specified in the device specific driver's hardware attributes. A sector is the smallest unit of non-volatile storage that can be erased at one time. The size of the sector, or sector size, is hardware specific and may be meaningless for some non-volatile storage hardware. For flash memory devices, the region must be aligned with the sector size. That is, the region must start on a sector boundary. Additionally, the overall size of the region must be an integer multiple of the sector size.
This section provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the APIs are provided in subsequent sections.
The NVS driver interface provides device independent APIs, data types, and macros. The following code example opens an NVS region instance, writes a string into it, then prints the string after reading it back into a local buffer, and also prints the string from its directly addressable location in flash memory.
The following code example opens an NVS region instance, erases the first sector of that region, writes a string into it, then prints the string after reading it back into a local buffer. If the string is directly CPU addressable (i.e. not in SPI flash), the string is printed from its location in flash memory.
Refer to the Driver's Configuration section for driver configuration information.
Details for the Typical NVS region operations example code above are described in the following subsections.
In order to use the NVS APIs, the application is required to provide device-specific NVS configuration in the Board.c file. The NVS driver interface defines a configuration data structure, NVS_Config.
The application must declare an array of NVS_Config elements, named NVS_config
[]. Each element of NVS_config
[] is populated with pointers to a device specific NVS driver implementation's function table, driver object, and hardware attributes. The hardware attributes define properties such as the NVS region's base address and size, Each element in NVS_config
[] corresponds to a NVS instance, and none of the elements should have NULL pointers.
You will need to check the device-specific NVS driver implementation's header file for example configuration. Please also refer to the Board.c file of any of the provided examples to see the NVS configuration.
NVS_init() must be called before any other NVS APIs. This function calls the device implementation's NVS initialization function, for each element of NVS_config
[].
Opening a NVS requires four steps:
All NVS APIs are globally thread safe. Consequently, only one write, erase (or read in the case of SPI flash) operation is allowed to be performed at a time, even for distinct NVS regions. Threads initiating new NVS writes or erases will block until any current operation completes.
When writing to or erasing internal flash, interrupts must be disabled to avoid executing code in flash while the flash is being reprogrammed. This constraint is met internally by the driver. User code does not need to safeguard against this.
Care must be taken by the user to not perform flash write or erase operations during latency critical phases of an application. See the NVS_lock() and NVS_unlock() API descriptions for more information.
#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
Go to the source code of this file.
Data Structures | |
struct | NVS_Params |
NVS Parameters. More... | |
struct | NVS_Attrs |
NVS attributes. More... | |
struct | NVS_FxnTable |
The definition of an NVS function table that contains the required set of functions to control a specific NVS driver implementation. More... | |
struct | NVS_Config_ |
NVS Global configuration. More... | |
Macros | |
#define | NVS_CMD_RESERVED (32) |
#define | NVS_STATUS_RESERVED (-32) |
#define | NVS_STATUS_SUCCESS (0) |
Successful status code returned by: NVS_control(), NVS_read(), NVS_write(), NVS_erase(), or NVS_lock(). More... | |
#define | NVS_STATUS_ERROR (-1) |
Generic error status code returned by: NVS_control(), NVS_erase(), or NVS_write(),. More... | |
#define | NVS_STATUS_UNDEFINEDCMD (-2) |
An error status code returned by NVS_control() for undefined command codes. More... | |
#define | NVS_STATUS_TIMEOUT (-3) |
An error status code returned by NVS_lock() More... | |
#define | NVS_STATUS_INV_OFFSET (-4) |
An error status code returned by NVS_read(), NVS_write(), or NVS_erase() More... | |
#define | NVS_STATUS_INV_ALIGNMENT (-5) |
An error status code. More... | |
#define | NVS_STATUS_INV_SIZE (-6) |
An error status code returned by NVS_erase() and NVS_write() More... | |
#define | NVS_STATUS_INV_WRITE (-7) |
An error status code returned by NVS_write() More... | |
#define | NVS_WRITE_ERASE (0x1) |
NVS write flags. More... | |
#define | NVS_WRITE_PRE_VERIFY (0x2) |
Validate write flag. More... | |
#define | NVS_WRITE_POST_VERIFY (0x4) |
Validate write flag. More... | |
#define | NVS_LOCK_WAIT_FOREVER (~(0U)) |
Special NVS_lock() timeout values. More... | |
#define | NVS_LOCK_NO_WAIT (0U) |
NVS_lock() No wait define. More... | |
#define | NVS_REGION_NOT_ADDRESSABLE ((void *)(~(0U))) |
Special NVS_Attrs.regionBase value. More... | |
Typedefs | |
typedef struct NVS_Config_ * | NVS_Handle |
A handle that is returned from the NVS_open() call. More... | |
typedef void(* | NVS_CloseFxn) (NVS_Handle handle) |
A function pointer to a driver specific implementation of NVS_close(). More... | |
typedef int_fast16_t(* | NVS_ControlFxn) (NVS_Handle handle, uint_fast16_t cmd, uintptr_t arg) |
A function pointer to a driver specific implementation of NVS_control(). More... | |
typedef int_fast16_t(* | NVS_EraseFxn) (NVS_Handle handle, size_t offset, size_t size) |
A function pointer to a driver specific implementation of NVS_erase(). More... | |
typedef void(* | NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs) |
A function pointer to a driver specific implementation of NVS_getAttrs(). More... | |
typedef void(* | NVS_InitFxn) (void) |
A function pointer to a driver specific implementation of NVS_init(). More... | |
typedef NVS_Handle(* | NVS_OpenFxn) (uint_least8_t index, NVS_Params *params) |
A function pointer to a driver specific implementation of NVS_open(). More... | |
typedef int_fast16_t(* | NVS_ReadFxn) (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize) |
A function pointer to a driver specific implementation of NVS_read(). More... | |
typedef int_fast16_t(* | NVS_WriteFxn) (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, uint_fast16_t flags) |
A function pointer to a driver specific implementation of NVS_write(). More... | |
typedef int_fast16_t(* | NVS_LockFxn) (NVS_Handle handle, uint32_t timeout) |
A function pointer to a driver specific implementation of NVS_lock(). More... | |
typedef void(* | NVS_UnlockFxn) (NVS_Handle handle) |
A function pointer to a driver specific implementation of NVS_unlock(). More... | |
typedef struct NVS_Config_ | NVS_Config |
NVS Global configuration. More... | |
Functions | |
void | NVS_close (NVS_Handle handle) |
Function to close an NVS_Handle. More... | |
int_fast16_t | NVS_control (NVS_Handle handle, uint_fast16_t cmd, uintptr_t arg) |
Function performs implementation specific features on a given NVS_Handle. More... | |
int_fast16_t | NVS_erase (NVS_Handle handle, size_t offset, size_t size) |
Erase size bytes of the region beginning at offset bytes from the base of the region referenced by the NVS_Handle. More... | |
void | NVS_getAttrs (NVS_Handle handle, NVS_Attrs *attrs) |
Function to get the NVS attributes. More... | |
void | NVS_init (void) |
Function to initialize the NVS module. More... | |
int_fast16_t | NVS_lock (NVS_Handle handle, uint32_t timeout) |
Function to lock the NVS driver. More... | |
NVS_Handle | NVS_open (uint_least8_t index, NVS_Params *params) |
Open an NVS region for reading and writing. More... | |
void | NVS_Params_init (NVS_Params *params) |
Function to initialize the NVS_Params struct to its defaults. More... | |
int_fast16_t | NVS_read (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize) |
Read data from the NVS region associated with the NVS_Handle. More... | |
void | NVS_unlock (NVS_Handle handle) |
Function to unlock the NVS driver. More... | |
int_fast16_t | NVS_write (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, uint_fast16_t flags) |
Write data to the NVS region associated with the NVS_Handle. More... | |
#define NVS_WRITE_ERASE (0x1) |
NVS write flags.
The following flags can be or'd together and passed as a bit mask to NVS_write.
Erase write flag.
If NVS_WRITE_ERASE is set in the flags passed to NVS_write(), the affected destination flash sectors will be erased prior to the start of the write operation.
#define NVS_WRITE_PRE_VERIFY (0x2) |
Validate write flag.
If NVS_WRITE_PRE_VERIFY is set in the flags passed to NVS_write(), the destination address range will be pre-tested to guarantee that the source data can be successfully written. If NVS_WRITE_ERASE is also requested in the write flags, then the NVS_WRITE_PRE_VERIFY modifier is ignored.
#define NVS_WRITE_POST_VERIFY (0x4) |
Validate write flag.
If NVS_WRITE_POST_VERIFY is set in the flags passed to NVS_write(), the destination address range will be tested after the write is finished to verify that the write operation was completed successfully.
#define NVS_LOCK_WAIT_FOREVER (~(0U)) |
Special NVS_lock() timeout values.
NVS_lock() Wait forever define
#define NVS_LOCK_NO_WAIT (0U) |
NVS_lock() No wait define.
#define NVS_REGION_NOT_ADDRESSABLE ((void *)(~(0U))) |
Special NVS_Attrs.regionBase value.
This region is not directly addressable (e.g.,: SPI flash region)
The NVS_Attrs.regionBase field returned by NVS_getAttrs() is set to this value by the NVSSPI driver to indicate that the region is not directly addressable.
typedef struct NVS_Config_* NVS_Handle |
A handle that is returned from the NVS_open() call.
typedef void(* NVS_CloseFxn) (NVS_Handle handle) |
A function pointer to a driver specific implementation of NVS_close().
typedef int_fast16_t(* NVS_ControlFxn) (NVS_Handle handle, uint_fast16_t cmd, uintptr_t arg) |
A function pointer to a driver specific implementation of NVS_control().
typedef int_fast16_t(* NVS_EraseFxn) (NVS_Handle handle, size_t offset, size_t size) |
A function pointer to a driver specific implementation of NVS_erase().
typedef void(* NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs) |
A function pointer to a driver specific implementation of NVS_getAttrs().
typedef void(* NVS_InitFxn) (void) |
A function pointer to a driver specific implementation of NVS_init().
typedef NVS_Handle(* NVS_OpenFxn) (uint_least8_t index, NVS_Params *params) |
A function pointer to a driver specific implementation of NVS_open().
typedef int_fast16_t(* NVS_ReadFxn) (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize) |
A function pointer to a driver specific implementation of NVS_read().
typedef int_fast16_t(* NVS_WriteFxn) (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, uint_fast16_t flags) |
A function pointer to a driver specific implementation of NVS_write().
typedef int_fast16_t(* NVS_LockFxn) (NVS_Handle handle, uint32_t timeout) |
A function pointer to a driver specific implementation of NVS_lock().
typedef void(* NVS_UnlockFxn) (NVS_Handle handle) |
A function pointer to a driver specific implementation of NVS_unlock().
typedef struct NVS_Config_ NVS_Config |
NVS Global configuration.
The NVS_Config structure contains a set of pointers used to characterize the NVS driver implementation.
This structure needs to be defined before calling NVS_init() and it must not be changed thereafter.
void NVS_close | ( | NVS_Handle | handle | ) |
Function to close an NVS_Handle.
handle | A handle returned from NVS_open() |
int_fast16_t NVS_control | ( | NVS_Handle | handle, |
uint_fast16_t | cmd, | ||
uintptr_t | arg | ||
) |
Function performs implementation specific features on a given NVS_Handle.
handle | An NVS_Handle returned from NVS_open() |
cmd | A command value defined by the driver specific implementation |
arg | An optional read or write argument that is accompanied with cmd |
int_fast16_t NVS_erase | ( | NVS_Handle | handle, |
size_t | offset, | ||
size_t | size | ||
) |
Erase size
bytes of the region beginning at offset
bytes from the base of the region referenced by the NVS_Handle.
handle | A handle returned from NVS_open() |
offset | The byte offset into the NVS region to start erasing from (must be erase sector aligned) |
size | The number of bytes to erase (must be integer multiple of sector size) |
NVS_STATUS_SUCCESS | Success. |
NVS_STATUS_INV_ALIGNMENT | If offset is not aligned on a sector boundary |
NVS_STATUS_INV_OFFSET | If offset exceeds region size |
NVS_STATUS_INV_SIZE | If size or offset + size exceeds region size, or if size is not an integer multiple of the flash sector size. |
NVS_STATUS_ERROR | If an internal error occurred erasing the flash. |
void NVS_getAttrs | ( | NVS_Handle | handle, |
NVS_Attrs * | attrs | ||
) |
Function to get the NVS attributes.
This function will populate a NVS_Attrs structure with attributes specific to the memory region associated with the NVS_Handle.
handle | A handle returned from NVS_open() |
attrs | Location to store attributes. |
void NVS_init | ( | void | ) |
Function to initialize the NVS module.
int_fast16_t NVS_lock | ( | NVS_Handle | handle, |
uint32_t | timeout | ||
) |
Function to lock the NVS driver.
This function is provided in the event that the user needs to perform some flash related operation not provided by the NVS driver API set or if the user simply needs to block flash operations for a period of time.
For example, the interrupt latency introduced by an uncoordinated flash write operation could interfere with some critical operation being performed by the application.
NVS_lock() prevents any other thread from initiating read, write, or erase operations while the user is performing an operation which is incompatible with those functions.
When the application no longer needs to block flash operations by other threads, NVS_unlock() must be called to allow NVS write or erase APIs to complete.
handle | A handle returned from NVS_open() |
timeout | Timeout (in milliseconds) to wait, or NVS_LOCK_WAIT_FOREVER, NVS_LOCK_NO_WAIT |
NVS_STATUS_SUCCESS | Success. |
NVS_STATUS_TIMEOUT | If timeout has expired. |
NVS_Handle NVS_open | ( | uint_least8_t | index, |
NVS_Params * | params | ||
) |
Open an NVS region for reading and writing.
index | Index in the NVS_Config table of the region to manage. |
params | Pointer to a parameter region. If NULL, default parameter values will be used. |
void NVS_Params_init | ( | NVS_Params * | params | ) |
Function to initialize the NVS_Params struct to its defaults.
params | A pointer to NVS_Params structure for initialization. |
int_fast16_t NVS_read | ( | NVS_Handle | handle, |
size_t | offset, | ||
void * | buffer, | ||
size_t | bufferSize | ||
) |
Read data from the NVS region associated with the NVS_Handle.
handle | A handle returned from NVS_open() |
offset | The byte offset into the NVS region to start reading from. |
buffer | A buffer to copy the data to. |
bufferSize | The size of the buffer (number of bytes to read). |
NVS_STATUS_SUCCESS | Success. |
NVS_STATUS_INV_OFFSET | If offset + size exceed the size of the region. |
void NVS_unlock | ( | NVS_Handle | handle | ) |
Function to unlock the NVS driver.
This function allows NVS write and erase operations to proceed after being temporarily inhibited by a call to NVS_lock().
handle | A handle returned from NVS_open() |
int_fast16_t NVS_write | ( | NVS_Handle | handle, |
size_t | offset, | ||
void * | buffer, | ||
size_t | bufferSize, | ||
uint_fast16_t | flags | ||
) |
Write data to the NVS region associated with the NVS_Handle.
handle | A handle returned from NVS_open() |
offset | The byte offset into the NVS region to start writing. |
buffer | A buffer containing data to write to the NVS region. |
bufferSize | The size of the buffer (number of bytes to write). |
flags | Write flags (NVS_WRITE_ERASE, NVS_WRITE_PRE_VERIFY, NVS_WRITE_POST_VERIFY). |
NVS_STATUS_SUCCESS | Success. |
NVS_STATUS_ERROR | If the internal flash write operation failed, or if NVS_WRITE_POST_VERIFY was requested and the destination flash range does not match the source buffer data. |
NVS_STATUS_INV_OFFSET | If offset + size exceed the size of the region. |
NVS_STATUS_INV_WRITE | If NVS_WRITE_PRE_VERIFY is requested and the destination flash address range cannot be change to the values desired. |
NVS_STATUS_INV_ALIGNMENT | If NVS_WRITE_ERASE is requested and offset is not aligned on a sector boundary |