nvm3.h File Reference

NVM3 API definition.

Version
5.5.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 <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.
 

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_INIT_WITH_FULL_NVM   (ECODE_EMDRV_NVM3_BASE | 0x00000012U)
 The module was opened with a full NVM.
 
#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 value.
 
#define ECODE_NVM3_ERR_KEY_NOT_FOUND   (ECODE_EMDRV_NVM3_BASE | 0x0000000BU)
 Key not found.
 
#define ECODE_NVM3_ERR_NO_VALID_PAGES   (ECODE_EMDRV_NVM3_BASE | 0x00000003U)
 Initialisation aborted, 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)
 Illegal parameter.
 
#define ECODE_NVM3_ERR_READ_DATA_SIZE   (ECODE_EMDRV_NVM3_BASE | 0x00000011U)
 Trying to read with a length different from actual object size.
 
#define ECODE_NVM3_ERR_RESIZE_NOT_ENOUGH_SPACE   (ECODE_EMDRV_NVM3_BASE | 0x00000014U)
 Not enough NVM to complete resize.
 
#define ECODE_NVM3_ERR_RESIZE_PARAMETER   (ECODE_EMDRV_NVM3_BASE | 0x00000013U)
 Illegal parameter.
 
#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 NVM 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 in the write operation.
 
#define ECODE_NVM3_OK   (ECODE_OK)
 Success return value.
 
#define FLASH_PAGE_SIZE_X   (FLASH_PAGE_SIZE - 20)
 
#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_FRAGMENT_COUNT   (((NVM3_MAX_OBJECT_SIZE_X - 1) / FLASH_PAGE_SIZE_X) + NVM3_MIN_FRAGMENT_COUNT)
 
#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 in number of bits.
 
#define NVM3_MAX_OBJECT_SIZE   NVM3_MAX_OBJECT_SIZE_DEFAULT
 
#define NVM3_MAX_OBJECT_SIZE_DEFAULT   1900U
 Default value for the max object size.
 
#define NVM3_MAX_OBJECT_SIZE_HIGH_LIMIT   4096U
 Maximum value for the max object size.
 
#define NVM3_MAX_OBJECT_SIZE_LOW_LIMIT   204U
 Minimum value for the max object size.
 
#define NVM3_MAX_OBJECT_SIZE_X   (NVM3_MAX_OBJECT_SIZE + 8)
 
#define NVM3_MIN_FRAGMENT_COUNT   (2U)
 
#define NVM3_MIN_PAGE_SIZE   512U
 Definitions of NVM3 constraints.
 
#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 *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.
 

Variables

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