Detailed Description

PRELIMINARY Non-Volatile Storage Driver.

==========================================================================

WARNING These APIs are PRELIMINARY, and subject to change in the next few months.

The NVS header file should be included in an application as follows:

Operation

The NVS module allows you to manage non-volatile memory. Using the NVS APIs, you can read and write data to persistant storage. Each NVS object manages a 'block' of non-volatile memory of a size specified in the NVS object's hardware attributes. A 'page' will refer to the smallest unit of non-volatile storage that can be erased at one time, and the page size is the size of this unit. This is hardware specific and may be meaningless for some persistant storage systems. However, in the case of flash memory, page size should be taken into account when deciding the block size for NVS to manage. For example on TM4C129x devices, a page size is 16KB.

When page size is relevant (e.g. for flash memory), the size of an NVS block size must be less than or equal to the page size. The block size can be less than the page size, however, care must be taken not to use the area in the page outside of the block. When the block is erased, the entire page will be erased, clearing anything in the page that was written outside of the block.

See the device specific NVS header file for configuration details.

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

Include dependency graph for NVS.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(). More...

#define	NVS_STATUS_ERROR -1
	Generic error status code returned by NVS_control(). More...

#define	NVS_STATUS_UNDEFINEDCMD -2
	An error status code returned by NVS_control() for undefined command codes. More...

#define	NVS_SOK (0)
	Success return code. More...

#define	NVS_EFAIL (-1)
	General failure return code. More...

#define	NVS_EOFFSET (-3)

#define	NVS_EALIGN (-4)

#define	NVS_ENOTENOUGHBYTES (-5)

#define	NVS_EALREADYWRITTEN (-6)

#define	NVS_ECOPYBLOCK (-7)

#define	NVS_WRITE_EXCLUSIVE (0x1)
	NVS write flags. More...

#define	NVS_WRITE_ERASE (0x2)
	Erase write flag. More...

#define	NVS_WRITE_VALIDATE (0x4)
	Validate write flag. More...

Typedefs
typedef struct NVS_Params	NVS_Params
	NVS Parameters. More...

typedef struct NVS_Attrs	NVS_Attrs
	NVS attributes. More...

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(*	NVS_ControlFxn) (NVS_Handle handle, unsigned int cmd, uintptr_t arg)
	A function pointer to a driver specific implementation of NVS_control(). More...

typedef void(*	NVS_ExitFxn) (NVS_Handle handle)
	A function pointer to a driver specific implementation of NVS_exit(). More...

typedef int(*	NVS_GetAttrsFxn) (NVS_Handle handle, NVS_Attrs *attrs)
	A function pointer to a driver specific implementation of NVS_getAttrs(). More...

typedef void(*	NVS_InitFxn) (NVS_Handle handle)
	A function pointer to a driver specific implementation of NVS_init(). More...

typedef NVS_Handle(*	NVS_OpenFxn) (NVS_Handle handle, NVS_Params *params)
	A function pointer to a driver specific implementation of NVS_open(). More...

typedef int(*	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(*	NVS_WriteFxn) (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, unsigned int flags)
	A function pointer to a driver specific implementation of NVS_write(). More...

typedef struct NVS_FxnTable	NVS_FxnTable
	The definition of an NVS function table that contains the required set of functions to control a specific NVS driver implementation. 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	NVS_control (NVS_Handle handle, unsigned int cmd, uintptr_t arg)
	Function performs implementation specific features on a given NVS_Handle. More...

int	NVS_erase (NVS_Handle handle)
	Erase the block of storage reference by an NVS handle. More...

void	NVS_exit (void)
	Function to de-initialize the NVS module. More...

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

NVS_Handle	NVS_open (int index, NVS_Params *params)
	Get an NVS block for reading and writing. More...

int	NVS_read (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize)
	Read data from an NVS block. More...

int	NVS_write (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, unsigned int flags)
	Write data to an NVS block. More...

Macro Definition Documentation

#define NVS_SOK (0)

Success return code.

#define NVS_EFAIL (-1)

General failure return code.

#define NVS_EOFFSET (-3)

#define NVS_EALIGN (-4)

#define NVS_ENOTENOUGHBYTES (-5)

#define NVS_EALREADYWRITTEN (-6)

#define NVS_ECOPYBLOCK (-7)

#define NVS_WRITE_EXCLUSIVE (0x1)

NVS write flags.

The following flags can be or'd together and passed as a bit mask to NVS_write.

Exclusive write flag

Only write if the area has not already been written to since the last erase. In the case of flash memory on some devices, once data is written to a location, that location cannot be written to again without first erasing the entire flash page. If the NVS_WRITE_EXCLUSIVE flag is set in the flags passed to NVS_write(), the location where the data will be written to is first checked if it has been modified since the last time the NVS block was erarsed. If that is the case, NVS_write() will return an error.

#define NVS_WRITE_ERASE (0x2)

Erase write flag.

If NVS_WRITE_ERASE is set in the flags passed to NVS_write(), the entire NVS block will be erased before being written to.

#define NVS_WRITE_VALIDATE (0x4)

Validate write flag.

If NVS_WRITE_VALIDATE is set in the flags passed to NVS_write(), the region in the NVS block that was written to will be validated (i.e., compared against the data buffer passed to NVS_write()).

Typedef Documentation

typedef struct NVS_Params NVS_Params

NVS Parameters.

NVS parameters are used with the NVS_open() call. Default values for these parameters are set using NVS_Params_init().

See also: NVS_Params_init()

typedef struct NVS_Attrs NVS_Attrs

NVS attributes.

The address of an NVS_Attrs structure can be passed to NVS_getAttrs() to fill in the fields.

pageSize is the size of the smallest erase page. This is hardware specific. For example, all TM4C123x devices use 1KB pages, but TM4C129x devices use 16KB pages. Please consult the device datasheet to determine the pageSize to use.

blockSize is the actual size of the NVS storage block that the application chooses to manage. If pageSize is greater than blockSize, care should be taken not to use the storage on the page that is outside of the block, since it may be erased when writing to the block. The block size must not be greater than the page size.

See also: NVS_getAttrs()

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(* NVS_ControlFxn) (NVS_Handle handle, unsigned int cmd, uintptr_t arg)

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

typedef void(* NVS_ExitFxn) (NVS_Handle handle)

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

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

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

typedef void(* NVS_InitFxn) (NVS_Handle handle)

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

typedef NVS_Handle(* NVS_OpenFxn) (NVS_Handle handle, NVS_Params *params)

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

typedef int(* 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(* NVS_WriteFxn) (NVS_Handle handle, size_t offset, void *buffer, size_t bufferSize, unsigned int flags)

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

typedef struct NVS_FxnTable NVS_FxnTable

The definition of an NVS function table that contains the required set of functions to control a specific NVS driver implementation.

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

void NVS_close ( NVS_Handle handle )

Function to close an NVS handle.

Parameters

handle A handle returned from NVS_open()

See also: NVS_open()

int NVS_control	(	NVS_Handle	handle,
		unsigned int	cmd,
		uintptr_t	arg
	)

Function performs implementation specific features on a given NVS_Handle.

Precondition: NVS_open() must be called first.

Parameters

handle	An NVS handle returned from NVS_open()
cmd	A command value defined by the driver specific implementation
arg	An optional R/W (read/write) argument that is accompanied with cmd

Returns: Implementation specific return codes. Negative values indicate unsuccessful operations.

See also: NVS_open()

int NVS_erase ( NVS_Handle handle )

Erase the block of storage reference by an NVS handle.

Parameters

handle A handle returned from NVS_open()

Returns: NVS_SOK Success.; NVS_EFAIL An error occurred erasing the flash.

void NVS_exit ( void )

Function to de-initialize the NVS module.

Precondition: NVS_init() was called.

int NVS_getAttrs	(	NVS_Handle	handle,
		NVS_Attrs *	attrs
	)

Function to get the NVS attributes.

Parameters

handle	A handle returned from NVS_open()
attrs	Location to store attributes.

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_Handle NVS_open	(	int	index,
		NVS_Params *	params
	)

Get an NVS block for reading and writing.

Precondition: NVS_init() was called.

Parameters

index	Index in the NVS_config table of the block to manage.
params	Pointer to a parameter block. If NULL, default parameter values will be used.

int NVS_read	(	NVS_Handle	handle,
		size_t	offset,
		void *	buffer,
		size_t	bufferSize
	)

Read data from an NVS block.

Parameters

handle	A handle returned from NVS_open()
offset	The byte offset into the NVS block to start reading from.
buffer	A buffer to copy the data to.
bufferSize	The size of the buffer (number of bytes to read).

Returns: NVS_SOK Success.; NVS_EOFFSET The location and size to read from does not lie completely within the NVS block.

Remarks: This call may block to ensure atomic access to the block.

int NVS_write	(	NVS_Handle	handle,
		size_t	offset,
		void *	buffer,
		size_t	bufferSize,
		unsigned int	flags
	)

Write data to an NVS block.

Parameters

handle	A handle returned from NVS_open()
offset	The byte offset into the NVS block to start writing. offset must be 4-byte aligned.
buffer	A buffer conntaining data to write to the NVS block. If buffer is NULL, the block will be erased. A non-NULL buffer must be aligned on a 4-byte boundary.
bufferSize	The size of the buffer (number of bytes to write). bufferSize must be a multiple of 4 bytes.
flags	Write flags (NVS_WRITE_EXCLUSIVE, NVS_WRITE_ERASE, NVS_WRITE_VALIDATE).

Returns: NVS_SOK Success.; NVS_EOFFSET The location and size to write to does not lie completely within the NVS block.; NVS_EALIGN The offset or bufferSize is not 4-byte aligned.; NVS_ALREADYWRITTEN The region to write to (the bufferSize region starting at offset into the block) has already been written to since the last erase, and NVS_WRITE_EXCLUSIVE is set in the flags parameter.

Remarks: This call may block to ensure atomic access to the block.

Detailed Description

Operation

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

Typedef Documentation

Function Documentation