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 "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.
 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 ID.
 Error, key not found.
 Initialisation aborded, 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.
 Error in parameter.
 Trying to read a counter with length different from 4.
 Trying to read more than the actual object size.
 Not enough nvm memory specified.
 No more space available.
 The object is too large.
 Error, error during the write operation.
#define ECODE_NVM3_OK   (ECODE_OK)
 Success return value.
 The default max object size.
 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.
#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.
 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 *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.