TI-RTOS Drivers
tidrivers_tivac_2_16_01_13
|
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:
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>
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... | |
#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 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().
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.
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.
void NVS_close | ( | NVS_Handle | handle | ) |
Function to close an NVS handle.
handle | A handle returned from NVS_open() |
int NVS_control | ( | NVS_Handle | handle, |
unsigned int | 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 R/W (read/write) argument that is accompanied with cmd |
int NVS_erase | ( | NVS_Handle | handle | ) |
Erase the block of storage reference by an NVS handle.
handle | A handle returned from NVS_open() |
void NVS_exit | ( | void | ) |
Function to de-initialize the NVS module.
int NVS_getAttrs | ( | NVS_Handle | handle, |
NVS_Attrs * | attrs | ||
) |
Function to get the NVS attributes.
handle | A handle returned from NVS_open() |
attrs | Location to store attributes. |
void NVS_init | ( | void | ) |
Function to initialize the NVS module.
NVS_Handle NVS_open | ( | int | index, |
NVS_Params * | params | ||
) |
Get an NVS block for reading and writing.
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.
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). |
int NVS_write | ( | NVS_Handle | handle, |
size_t | offset, | ||
void * | buffer, | ||
size_t | bufferSize, | ||
unsigned int | flags | ||
) |
Write data to an NVS block.
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). |