nvm3.h File Reference

NVM3 API definition.

Version
5.4.0

License

(C) Copyright 2017 Silicon Labs, www.silabs.com

This file is licensed under the Silabs License Agreement. See the file "Silabs_License_Agreement.txt" for details. Before using this software for any purpose, you must agree to the terms of that agreement.

Definition in file nvm3.h.

#include <stdint.h>
#include <stdbool.h>
#include "nvm3_hal.h"
#include "nvm3_default.h"

Data Structures

struct  nvm3_CacheEntry
 The datatype for each cache entry. The cache must be an array of these.
 
struct  nvm3_Init_t
 NVM3 initialization data.
 

Macros

#define ECODE_NVM3_ERR_ALIGNMENT_INVALID   (ECODE_EMDRV_NVM3_BASE | 0x00000001U)
 Invalid data alignment.
 
#define ECODE_NVM3_ERR_ERASE_FAILED   (ECODE_EMDRV_NVM3_BASE | 0x0000000EU)
 Erase failed.
 
#define ECODE_NVM3_ERR_INT_ADDR_INVALID   (ECODE_EMDRV_NVM3_BASE | 0x00000021U)
 Internal error trying to access invalid memory.
 
#define ECODE_NVM3_ERR_INT_EMULATOR   (ECODE_EMDRV_NVM3_BASE | 0x00000024U)
 Internal Emulator error.
 
#define ECODE_NVM3_ERR_INT_KEY_MISMATCH   (ECODE_EMDRV_NVM3_BASE | 0x00000022U)
 Key validaton failure.
 
#define ECODE_NVM3_ERR_INT_SIZE_ERROR   (ECODE_EMDRV_NVM3_BASE | 0x00000023U)
 Internal size mismatch error.
 
#define ECODE_NVM3_ERR_INT_TEST   (ECODE_EMDRV_NVM3_BASE | 0x00000025U)
 Internal Test error.
 
#define ECODE_NVM3_ERR_INT_WRITE_TO_NOT_ERASED   (ECODE_EMDRV_NVM3_BASE | 0x00000020U)
 Write to memory that is not erased.
 
#define ECODE_NVM3_ERR_KEY_INVALID   (ECODE_EMDRV_NVM3_BASE | 0x0000000AU)
 Invalid key ID.
 
#define ECODE_NVM3_ERR_KEY_NOT_FOUND   (ECODE_EMDRV_NVM3_BASE | 0x0000000BU)
 Error, key not found.
 
#define ECODE_NVM3_ERR_NO_VALID_PAGES   (ECODE_EMDRV_NVM3_BASE | 0x00000003U)
 Initialisation aborded, no valid page found.
 
#define ECODE_NVM3_ERR_NOT_OPENED   (ECODE_EMDRV_NVM3_BASE | 0x00000007U)
 The module has not been sucessfully opened.
 
#define ECODE_NVM3_ERR_OBJECT_IS_NOT_A_COUNTER   (ECODE_EMDRV_NVM3_BASE | 0x0000000DU)
 Trying to access a counter object which is currently a data object.
 
#define ECODE_NVM3_ERR_OBJECT_IS_NOT_DATA   (ECODE_EMDRV_NVM3_BASE | 0x0000000CU)
 Trying to access a data object which is currently a counter object.
 
#define ECODE_NVM3_ERR_OBJECT_SIZE_NOT_SUPPORTED   (ECODE_EMDRV_NVM3_BASE | 0x00000005U)
 The object size is not supported.
 
#define ECODE_NVM3_ERR_OPENED_WITH_OTHER_PARAMETERS   (ECODE_EMDRV_NVM3_BASE | 0x00000008U)
 The module has already been opened with other parameters.
 
#define ECODE_NVM3_ERR_PAGE_SIZE_NOT_SUPPORTED   (ECODE_EMDRV_NVM3_BASE | 0x00000004U)
 The page size is not supported.
 
#define ECODE_NVM3_ERR_PARAMETER   (ECODE_EMDRV_NVM3_BASE | 0x00000009U)
 Error in parameter.
 
#define ECODE_NVM3_ERR_READ_COUNTER_SIZE   (ECODE_EMDRV_NVM3_BASE | 0x00000012U)
 Trying to read a counter with length different from 4.
 
#define ECODE_NVM3_ERR_READ_DATA_SIZE   (ECODE_EMDRV_NVM3_BASE | 0x00000011U)
 Trying to read more than the actual object size.
 
#define ECODE_NVM3_ERR_SIZE_TOO_SMALL   (ECODE_EMDRV_NVM3_BASE | 0x00000002U)
 Not enough nvm memory specified.
 
#define ECODE_NVM3_ERR_STORAGE_FULL   (ECODE_EMDRV_NVM3_BASE | 0x00000006U)
 No more space available.
 
#define ECODE_NVM3_ERR_WRITE_DATA_SIZE   (ECODE_EMDRV_NVM3_BASE | 0x0000000FU)
 The object is too large.
 
#define ECODE_NVM3_ERR_WRITE_FAILED   (ECODE_EMDRV_NVM3_BASE | 0x00000010U)
 Error, error during the write operation.
 
#define ECODE_NVM3_OK   (ECODE_OK)
 Success return value.
 
#define NVM3_DEFAULT_MAX_OBJECT_SIZE   NVM3_MAX_OBJECT_SIZE
 The default max object size.
 
#define NVM3_DEFINE_SECTION_INIT_DATA(name)
 NVM3 initialization data helper macro to be used with NVM3_DEFINE_SECTION_STATIC_DATA(). The name parameter in both macros must match.
Call nvm3_open() after this macro to initialize NVM3. See Examples section for code examples.
 
#define NVM3_DEFINE_SECTION_STATIC_DATA(name, nvmSize, cacheSize)
 NVM3 static data definition helper macro for applications using linker script placement of NVM memory area. This macro exports the section 'name'_section to the linker. The section name must be placed by the user in a linker script at an address aligned with the page size of the underlying memory system. The size of the NVM area must be a multiple of the page size.
This macro also allocates static NVM3 cache.
Use this macro with NVM3_DEFINE_SECTION_INIT_DATA() to create initialization data for nvm3_open(). See Examples section for usage examples.
 
#define NVM3_KEY_INVALID   0xFFFFFFFFU
 Invalid key identifier.
 
#define NVM3_KEY_MASK   ((1U << NVM3_KEY_SIZE) - 1U)
 Unique object key identifier mask.
 
#define NVM3_KEY_MAX   NVM3_KEY_MASK
 Maximum object key value.
 
#define NVM3_KEY_MIN   0U
 Minimum object key value.
 
#define NVM3_KEY_SIZE   20U
 Unique object key identifier size.
 
#define NVM3_MAX_OBJECT_SIZE   4096U
 NVM3 default maximum object size. Because the current NVM3 version only supports the maximum object size equal to NVM3_MAX_OBJECT_SIZE, this macro can be used to set the maxObjectSize in the initialization structure. Future versions of NVM3 may support other sizes.
 
#define NVM3_OBJECTTYPE_COUNTER   1U
 The object is a counter.
 
#define NVM3_OBJECTTYPE_DATA   0U
 The object is data.
 

Typedefs

typedef struct nvm3_CacheEntry nvm3_CacheEntry_t
 The datatype for each cache entry. The cache must be an array of these.
 
typedef uint32_t nvm3_ObjectKey_t
 The data type for object keys. Only the 20 least significant bits are used.
 

Functions

Ecode_t nvm3_close (nvm3_Handle_t *h)
 Close the NVM3 driver instance.
 
__STATIC_INLINE size_t nvm3_countObjects (nvm3_Handle_t *h)
 Count valid objects.
 
Ecode_t nvm3_deleteObject (nvm3_Handle_t *h, nvm3_ObjectKey_t key)
 Delete an object from NVM.
 
size_t nvm3_enumObjects (nvm3_Handle_t *h, nvm3_ObjectKey_t *keys, size_t sizeKeys, nvm3_ObjectKey_t keyMin, nvm3_ObjectKey_t keyMax)
 Create a list of object keys for valid objects in NVM.
 
Ecode_t nvm3_eraseAll (nvm3_Handle_t *h)
 Delete all objects in NVM.
 
Ecode_t nvm3_findObject (nvm3_Handle_t *h, nvm3_ObjectKey_t key, uint32_t *type, size_t *len)
 Find the type and size of an object in NVM.
 
Ecode_t nvm3_getEraseCount (nvm3_Handle_t *h, uint32_t *eraseCnt)
 Get the number of page erases of the most erased page in the NVM area since the first initialization.
 
Ecode_t nvm3_incrementCounter (nvm3_Handle_t *h, nvm3_ObjectKey_t key, uint32_t *value)
 Increment a counter object value by 1 and read out optionally.
 
Ecode_t nvm3_open (nvm3_Handle_t *h, const nvm3_Init_t *i)
 Open a NVM3 driver instance. A NVM3 instance is represented by a handle keeping information about the state. A successful open will initialize the cache with information about the objects already in the NVM-memory.
 
Ecode_t nvm3_readCounter (nvm3_Handle_t *h, nvm3_ObjectKey_t key, uint32_t *value)
 Read a counter value from NVM.
 
Ecode_t nvm3_readData (nvm3_Handle_t *h, nvm3_ObjectKey_t key, void *value, size_t maxLen)
 Read the object data identified with a given key from NVM.
 
Ecode_t nvm3_repack (nvm3_Handle_t *h)
 Execute a repack operation. NVM3 will copy data or erase pages when repacking is needed. A call to nvm3_repack() may block access to the non-volatile memory for up to one page erasure time plus an small execution overhead. Exact worst-case timing characteristics can be found in the data sheet for the part.
 
bool nvm3_repackNeeded (nvm3_Handle_t *h)
 Check the internal status of NVM3 and return true if a repack operation is required. The application must call nvm3_repack() to perform the actual repack operation.
 
Ecode_t nvm3_writeCounter (nvm3_Handle_t *h, nvm3_ObjectKey_t key, uint32_t value)
 Store a counter in NVM.
 
Ecode_t nvm3_writeData (nvm3_Handle_t *h, nvm3_ObjectKey_t key, const void *value, size_t len)
 Write the object value identified with the key to NVM.