nvm3.h File Reference

NVM3 API definition.



(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 <stddef.h>
#include <assert.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.


 Invalid data alignment.
 Erase failed.
 The module was opened with a full NVM.
 Internal error trying to access invalid memory.
 Internal Emulator error.
 Key validaton failure.
 Internal size mismatch error.
 Internal Test error.
 Write to memory that is not erased.
 Invalid key value.
 Key not found.
 Initialisation aborted, no valid page found.
 The module has not been sucessfully opened.
 Trying to access a counter object which is currently a data object.
 Trying to access a data object which is currently a counter object.
 The object size is not supported.
 The module has already been opened with other parameters.
 The page size is not supported.
 Illegal parameter.
 Trying to read with a length different from actual object size.
 Not enough NVM to complete resize.
 Illegal parameter.
 Not enough NVM memory specified.
 No more NVM space available.
 The object is too large.
 Error in the write operation.
#define ECODE_NVM3_OK   (ECODE_OK)
 Success return value.
 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.
 Invalid key identifier.
#define NVM3_KEY_MASK   ((1U << NVM3_KEY_SIZE) - 1U)
 Unique object key identifier mask.
 Maximum object key value.
#define NVM3_KEY_MIN   0U
 Minimum object key value.
#define NVM3_KEY_SIZE   20U
 Unique object key identifier size in number of bits.
 Default value for the max object size.
 Maximum value for the max object size.
 Minimum value for the max object size.
#define NVM3_MIN_PAGE_SIZE   512U
 Definitions of NVM3 constraints.
 The object is a counter.
 The object is data.


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.


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 *keyListPtr, size_t keyListSize, 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_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_getObjectInfo (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_incrementCounter (nvm3_Handle_t *h, nvm3_ObjectKey_t key, uint32_t *newValue)
 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_resize (nvm3_Handle_t *h, nvm3_HalPtr_t newAddr, size_t newSize)
 Resize the NVM area used by an open NVM3 instance. The area can be resized by changing the start or end address either up or down in memory. Because the input parameters to NVM3 are start address and size, care must be taken. One can either move the start address up or down in memory and adjust the size accordingly to keep the end address, or keep address and just change the size. It is not possible to resize the area by doing changes in both ends of the NVM address range at the same time. If the resize operation return ECODE_NVM3_OK, the instance is still open and can be used to access objects in the resized NVM. If the resize operation fails, the instance will still be open, but with unchanged size.
void nvm3_setEraseCount (uint32_t eraseCnt)
 Set the page erase count. Normally the application should not be conserned with the erase count value. But if NVM3 is substituting a previous solution, it is possible to transfer the erase count to NVM3 when initializing the NVM for the first time. The erase count must be set before the nvm3_open is called, and it will only take effect if the NVM is completely erased or contains unknown data to NVM3. In that case all pages will be initialized with the supplied erase count. After nvm3_open has been called, the value will be consumed and have no effect on further calls to nvm3_open.
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.


nvm3_Obj_t nvm3_internalObjectHandleA
 A variable used by the nvm3 functions.
nvm3_Obj_t nvm3_internalObjectHandleB
 A variable used by the nvm3 functions.
nvm3_Obj_t nvm3_internalObjectHandleC
 A variable used by the nvm3 functions.
nvm3_Obj_t nvm3_internalObjectHandleD
 A variable used by the nvm3 functions.
const uint8_t nvm3_maxFragmentCount
 A variable that must contain the maximum number of object fragments.
const size_t nvm3_objHandleSize