License

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

nvm3.h File Reference

License

Data Structures

Macros

Typedefs

Functions

Variables