Data Structures | Macros | Typedefs | Functions
NVS.h File Reference

Detailed Description

Non-Volatile Storage driver interface.


Overview

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.


Usage

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.

Synopsis

// Import NVS Driver definitions
#include <ti/drivers/NVS.h>
// One time init of NVS driver
// Initialize optional NVS parameters
NVS_Params_init(&nvsParams);
// Open NVS driver instance
nvsRegion = NVS_open(config_NVS0, &nvsParams);
// write "Hello" to the base address of region 0, verify after write
status = NVS_write(nvsRegion, 0, "Hello", strlen("Hello")+1, NVS_POST_VERIFY);
// Close NVS region
NVS_close(nvsRegion);

Examples

Opening an NVS region instance

NVS_Handle nvsRegion;
NVS_Params nvsParams;
NVS_Params_init(&nvsParams);
nvsRegion = NVS_open(CONFIG_NVS0, &nvsParams);

Erasing, writing, reading an NVS region

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.

// Import NVS Driver definitions
#include <ti/drivers/NVS.h>
NVS_Handle nvsRegion;
NVS_Attrs regionAttrs;
uint_fast16_t status;
char buf[32];
// initialize the NVS driver
//
// Open the NVS region specified by the 0th element in the NVS_config[]
// array defined in ti_drivers_config.c.
//
// Use default NVS_Params to open this memory region, hence 'NULL'
//
nvsRegion = NVS_open(CONFIG_NVS0, NULL);
// Confirm that the NVS region opened properly
if (nvsRegion == NULL) {
// Error handling code
}
// Fetch the generic NVS region attributes for nvsRegion
NVS_getAttrs(nvsRegion, &regionAttrs);
// Erase the first sector of nvsRegion
status = NVS_erase(nvsRegion, 0, regionAttrs.sectorSize);
if (status != NVS_STATUS_SUCCESS) {
// Error handling code
}
// Write "Hello" to the base address of nvsRegion, verify after write
status = NVS_write(nvsRegion, 0, "Hello", strlen("Hello")+1, NVS_POST_VERIFY);
if (status != NVS_STATUS_SUCCESS) {
// Error handling code
}
// Copy "Hello" from nvsRegion into local 'buf'
status = NVS_read(nvsRegion, 0, buf, strlen("Hello")+1);
if (status != NVS_STATUS_SUCCESS) {
// Error handling code
}
// Print the string from fetched NVS storage
System_printf("%s\n", buf);
//
// Print the string using direct flash address reference if valid
//
// When the NVS driver is managing SPI flash non volatile
// storage, the regionBase attribute will be `NVS_REGION_NOT_ADDRESSABLE`
//
System_printf("%s\n", regionAttrs.regionBase);
}
// close the region
NVS_close(nvsRegion);

Configuration

Refer to the Driver's Configuration section for driver configuration information.


Example discussion

Details for the Typical NVS region operations example code above are described in the following subsections.

NVS Driver Configuration

In order to use the NVS APIs, the application is required to provide device-specific NVS configuration in the ti_drivers_config.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 ti_drivers_config.c file of any of the examples to see the NVS configuration.

Initializing the NVS Driver

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 the NVS Driver

Opening a NVS requires four steps:

  1. Optionally create and initialize a NVS_Params structure.
  2. Fill in the desired parameters.
  3. Call NVS_open(), passing the index of the NVS region in the NVS_Config structure, and the address of the NVS_Params structure.
  4. Check that the NVS_Handle returned by NVS_open() is non-NULL, and save it. The handle will be used to read and write to the NVS you just opened.
Note
Each NVS index can only be opened exclusively. Calling NVS_open() multiple times with the same index will result in an error. The index can be re-used if NVS_close() is called first.

Thread Safety

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.

Interrupt Latency During Flash Operations

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>
Include dependency graph for NVS.h:
This graph shows which files directly or indirectly include this file:

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

Macro Definition Documentation

§ NVS_WRITE_ERASE

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

§ NVS_WRITE_PRE_VERIFY

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

§ NVS_WRITE_POST_VERIFY

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

§ NVS_LOCK_WAIT_FOREVER

#define NVS_LOCK_WAIT_FOREVER   (~(0U))

Special NVS_lock() timeout values.

NVS_lock() Wait forever define

§ NVS_LOCK_NO_WAIT

#define NVS_LOCK_NO_WAIT   (0U)

NVS_lock() No wait define.

§ NVS_REGION_NOT_ADDRESSABLE

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

§ NVS_Handle

typedef struct NVS_Config_* NVS_Handle

A handle that is returned from the NVS_open() call.

§ NVS_CloseFxn

typedef void(* NVS_CloseFxn) (NVS_Handle handle)

A function pointer to a driver specific implementation of NVS_close().

§ NVS_ControlFxn

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

§ NVS_EraseFxn

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

§ NVS_GetAttrsFxn

typedef void(* NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs)

A function pointer to a driver specific implementation of NVS_getAttrs().

§ NVS_InitFxn

typedef void(* NVS_InitFxn) (void)

A function pointer to a driver specific implementation of NVS_init().

§ NVS_OpenFxn

typedef NVS_Handle(* NVS_OpenFxn) (uint_least8_t index, NVS_Params *params)

A function pointer to a driver specific implementation of NVS_open().

§ NVS_ReadFxn

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

§ NVS_WriteFxn

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

§ NVS_LockFxn

typedef int_fast16_t(* NVS_LockFxn) (NVS_Handle handle, uint32_t timeout)

A function pointer to a driver specific implementation of NVS_lock().

§ NVS_UnlockFxn

typedef void(* NVS_UnlockFxn) (NVS_Handle handle)

A function pointer to a driver specific implementation of NVS_unlock().

§ NVS_Config

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.

See also
NVS_init()

Function Documentation

§ NVS_close()

void NVS_close ( NVS_Handle  handle)

Function to close an NVS_Handle.

Parameters
handleA handle returned from NVS_open()
See also
NVS_open()

§ NVS_control()

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.

Precondition
NVS_open() must be called first.
Parameters
handleAn NVS_Handle returned from NVS_open()
cmdA command value defined by the driver specific implementation
argAn optional read or write argument that is accompanied with cmd
Returns
Implementation specific return codes. Negative values indicate unsuccessful operations.
See also
NVS_open()

§ NVS_erase()

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.

Warning
Erasing internal flash on most devices can introduce significant interrupt latencies while the erase operation is in in progress. The user may want to surround certain real-time critical code sections with NVS_lock() and NVS_unlock() calls in order to prevent uncoordinated flash erase operations from negatively impacting performance.
Parameters
handleA handle returned from NVS_open()
offsetThe byte offset into the NVS region to start erasing from (must be erase sector aligned)
sizeThe number of bytes to erase (must be integer multiple of sector size)
Return values
NVS_STATUS_SUCCESSSuccess.
NVS_STATUS_INV_ALIGNMENTIf offset is not aligned on a sector boundary
NVS_STATUS_INV_OFFSETIf offset exceeds region size
NVS_STATUS_INV_SIZEIf size or offset + size exceeds region size, or if size is not an integer multiple of the flash sector size.
NVS_STATUS_ERRORIf an internal error occurred erasing the flash.

§ NVS_getAttrs()

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.

Parameters
handleA handle returned from NVS_open()
attrsLocation to store attributes.

§ NVS_init()

void NVS_init ( void  )

Function to initialize the NVS module.

Precondition
The NVS_config structure must exist and be persistent before this function can be called. This function must also be called before any other NVS APIs.

§ NVS_lock()

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.

Parameters
handleA handle returned from NVS_open()
timeoutTimeout (in milliseconds) to wait, or NVS_LOCK_WAIT_FOREVER, NVS_LOCK_NO_WAIT
Return values
NVS_STATUS_SUCCESSSuccess.
NVS_STATUS_TIMEOUTIf timeout has expired.

§ NVS_open()

NVS_Handle NVS_open ( uint_least8_t  index,
NVS_Params params 
)

Open an NVS region for reading and writing.

Precondition
NVS_init() was called.
Parameters
indexIndex in the NVS_Config table of the region to manage.
paramsPointer to a parameter region. If NULL, default parameter values will be used.
Returns
A non-zero handle on success, else NULL.

§ NVS_Params_init()

void NVS_Params_init ( NVS_Params params)

Function to initialize the NVS_Params struct to its defaults.

Parameters
paramsA pointer to NVS_Params structure for initialization.

§ NVS_read()

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.

Parameters
handleA handle returned from NVS_open()
offsetThe byte offset into the NVS region to start reading from.
bufferA buffer to copy the data to.
bufferSizeThe size of the buffer (number of bytes to read).
Return values
NVS_STATUS_SUCCESSSuccess.
NVS_STATUS_INV_OFFSETIf offset + size exceed the size of the region.

§ NVS_unlock()

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

Parameters
handleA handle returned from NVS_open()

§ NVS_write()

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.

Warning
Writing to internal flash on most devices can introduce significant interrupt latencies while the write operation is in in progress. The user may want to surround certain real-time critical code sections with NVS_lock() and NVS_unlock() calls in order to prevent uncoordinated flash write operations from negatively impacting performance.
Parameters
handleA handle returned from NVS_open()
offsetThe byte offset into the NVS region to start writing.
bufferA buffer containing data to write to the NVS region.
bufferSizeThe size of the buffer (number of bytes to write).
flagsWrite flags (NVS_WRITE_ERASE, NVS_WRITE_PRE_VERIFY, NVS_WRITE_POST_VERIFY).
Return values
NVS_STATUS_SUCCESSSuccess.
NVS_STATUS_ERRORIf 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_OFFSETIf offset + size exceed the size of the region.
NVS_STATUS_INV_WRITEIf NVS_WRITE_PRE_VERIFY is requested and the destination flash address range cannot be change to the values desired.
NVS_STATUS_INV_ALIGNMENTIf NVS_WRITE_ERASE is requested and offset is not aligned on a sector boundary
Remarks
This call may lock a region to ensure atomic access to the region.
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale