NVM
[EM_Drivers]

NVM Non-volatile Memory driver, see NVM Non-volatile Memory driver page for detailed documentation. More...

Collaboration diagram for NVM:

Data Structures

struct  NVM_Object_Descriptor_t
 Describes the properties of an object in a page. More...
struct  NVM_Page_Descriptor_t
 Describes the properties of a page. More...
struct  NVM_Config_t
 Configuration structure. More...

Defines

#define ECODE_EMDRV_NVM_OK   ( ECODE_OK )
 Return/error codes.
#define ECODE_EMDRV_NVM_ADDR_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000001 )
 Invalid address.
#define ECODE_EMDRV_NVM_ALIGNMENT_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000002 )
 Invalid data alignment.
#define ECODE_EMDRV_NVM_DATA_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000003 )
 Invalid input data or format.
#define ECODE_EMDRV_NVM_WRITE_LOCK   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000004 )
 A write is currently in progress.
#define ECODE_EMDRV_NVM_NO_PAGES_AVAILABLE   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000005 )
 Initialization didn't find any pages available to allocate.
#define ECODE_EMDRV_NVM_PAGE_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000006 )
 Could not find the page specified.
#define ECODE_EMDRV_NVM_ERROR   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000007 )
 General error.
#define NVM_WRITE_ALL_CMD   0xff
 All objects are written from RAM.
#define NVM_WRITE_NONE_CMD   0xfe
 All objects are copied from the old page.
#define NVM_READ_ALL_CMD   0xff
 All objects are read to RAM.
#define NVM_ERASE_RETAINCOUNT   0xffffffffUL
 Retains the registered erase count when eraseing a page.
#define NVM_PAGE_TERMINATION   { NULL, 0, (NVM_Object_Ids) 0 }
 Structure defining end of pages table.
#define NVM_FEATURE_WEAR_PAGES_ENABLED   true
 Without this define the wear pages are no longer supported.
#define NVM_FEATURE_STATIC_WEAR_ENABLED   true
 Include and activate the static wear leveling functionality.
#define NVM_STATIC_WEAR_THRESHOLD   100
 The threshold used to decide when to do static wear leveling.
#define NVM_FEATURE_READ_VALIDATION_ENABLED   true
 Validate data against checksums on every read operation.
#define NVM_FEATURE_WRITE_VALIDATION_ENABLED   true
 Validate data against checksums after every write operation.
#define NVM_FEATURE_WEARLEVELGET_ENABLED   true
 Include the NVM_WearLevelGet function.
#define NVM_FEATURE_WRITE_NECESSARY_CHECK_ENABLED   true
 Check if data has been updated before writing update to the NVM.
#define NVM_MAX_NUMBER_OF_PAGES   32
 define maximum number of flash pages that can be used as NVM
#define NVM_PAGES_SCRATCH   1
 Configure extra pages to allocate for data security and wear leveling.
#define NVM_PAGE_SIZE   FLASH_PAGE_SIZE
 Set the NVM driver page size to the size of the EFM32 flash.

Typedefs

typedef NVM_Object_Descriptor_t NVM_Page_t []
 A collection of object descriptors that make up a page.
typedef NVM_Page_Descriptor_t NVM_Page_Table_t []
 The list of pages registered for use.

Enumerations

enum  NVM_Page_Type_t {
  nvmPageTypeNormal = 0,
  nvmPageTypeWear = 1
}
 

Enum describing the type of logical page we have; normal or wear.

More...

Functions

Ecode_t NVM_Init (NVM_Config_t const *nvmConfig)
 Initialize the NVM manager.
Ecode_t NVM_Erase (uint32_t erasureCount)
 Erase the entire allocated NVM area.
Ecode_t NVM_Write (uint16_t pageId, uint8_t objectId)
 Write an object or a page.
Ecode_t NVM_Read (uint16_t pageId, uint8_t objectId)
 Read an object or an entire page.
uint32_t NVM_WearLevelGet (void)
 Get maximum wear level.
NVM_Config_t const * NVM_ConfigGet (void)
 Return a pointer to the config data.

Detailed Description

NVM Non-volatile Memory driver, see NVM Non-volatile Memory driver page for detailed documentation.


Define Documentation

#define ECODE_EMDRV_NVM_ADDR_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000001 )

Invalid address.

Definition at line 48 of file nvm.h.

Referenced by NVMHAL_ReturnTypeConvert().

#define ECODE_EMDRV_NVM_ALIGNMENT_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000002 )

Invalid data alignment.

Definition at line 49 of file nvm.h.

Referenced by NVMHAL_ReturnTypeConvert().

#define ECODE_EMDRV_NVM_DATA_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000003 )

Invalid input data or format.

Definition at line 50 of file nvm.h.

Referenced by NVM_Read().

#define ECODE_EMDRV_NVM_ERROR   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000007 )

General error.

Definition at line 54 of file nvm.h.

Referenced by NVM_Erase(), NVM_Init(), NVM_Write(), and NVMHAL_ReturnTypeConvert().

#define ECODE_EMDRV_NVM_NO_PAGES_AVAILABLE   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000005 )

Initialization didn't find any pages available to allocate.

Definition at line 52 of file nvm.h.

Referenced by NVM_Init().

#define ECODE_EMDRV_NVM_OK   ( ECODE_OK )

Return/error codes.

Success return value

Definition at line 47 of file nvm.h.

Referenced by NVM_Erase(), NVM_Init(), NVM_Read(), NVM_Write(), and NVMHAL_ReturnTypeConvert().

#define ECODE_EMDRV_NVM_PAGE_INVALID   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000006 )

Could not find the page specified.

Definition at line 53 of file nvm.h.

Referenced by NVM_Read().

#define ECODE_EMDRV_NVM_WRITE_LOCK   ( ECODE_EMDRV_SPIDRV_BASE | 0x00000004 )

A write is currently in progress.

Definition at line 51 of file nvm.h.

#define NVM_ERASE_RETAINCOUNT   0xffffffffUL

Retains the registered erase count when eraseing a page.

Definition at line 64 of file nvm.h.

Referenced by NVM_Erase().

#define NVM_FEATURE_READ_VALIDATION_ENABLED   true

Validate data against checksums on every read operation.

Definition at line 49 of file nvm_config.h.

#define NVM_FEATURE_STATIC_WEAR_ENABLED   true

Include and activate the static wear leveling functionality.

Definition at line 43 of file nvm_config.h.

Referenced by NVM_Write().

#define NVM_FEATURE_WEAR_PAGES_ENABLED   true

Without this define the wear pages are no longer supported.

Definition at line 40 of file nvm_config.h.

#define NVM_FEATURE_WEARLEVELGET_ENABLED   true

Include the NVM_WearLevelGet function.

Definition at line 55 of file nvm_config.h.

#define NVM_FEATURE_WRITE_NECESSARY_CHECK_ENABLED   true

Check if data has been updated before writing update to the NVM.

Definition at line 58 of file nvm_config.h.

#define NVM_FEATURE_WRITE_VALIDATION_ENABLED   true

Validate data against checksums after every write operation.

Definition at line 52 of file nvm_config.h.

#define NVM_MAX_NUMBER_OF_PAGES   32

define maximum number of flash pages that can be used as NVM

Definition at line 61 of file nvm_config.h.

Referenced by NVM_Init().

#define NVM_PAGE_SIZE   FLASH_PAGE_SIZE

Set the NVM driver page size to the size of the EFM32 flash.

Definition at line 68 of file nvm_config.h.

Referenced by NVM_Erase(), NVM_Init(), NVM_WearLevelGet(), and NVM_Write().

#define NVM_PAGE_TERMINATION   { NULL, 0, (NVM_Object_Ids) 0 }

Structure defining end of pages table.

Definition at line 67 of file nvm.h.

#define NVM_PAGES_SCRATCH   1

Configure extra pages to allocate for data security and wear leveling.

Minimum 1, but the more you add the better lifetime your system will have.

Definition at line 65 of file nvm_config.h.

#define NVM_READ_ALL_CMD   0xff

All objects are read to RAM.

Definition at line 61 of file nvm.h.

Referenced by NVM_Read().

#define NVM_STATIC_WEAR_THRESHOLD   100

The threshold used to decide when to do static wear leveling.

Definition at line 46 of file nvm_config.h.

#define NVM_WRITE_ALL_CMD   0xff

All objects are written from RAM.

Definition at line 57 of file nvm.h.

Referenced by NVM_Write().

#define NVM_WRITE_NONE_CMD   0xfe

All objects are copied from the old page.

Definition at line 59 of file nvm.h.


Typedef Documentation

A collection of object descriptors that make up a page.

Definition at line 90 of file nvm_config.h.

The list of pages registered for use.

Definition at line 102 of file nvm_config.h.


Enumeration Type Documentation

Enum describing the type of logical page we have; normal or wear.

Enumerator:
nvmPageTypeNormal 

Normal page, always rewrite.

nvmPageTypeWear 

Wear page.

Can be used several times before rewrite.

Definition at line 75 of file nvm_config.h.


Function Documentation

NVM_Config_t const* NVM_ConfigGet ( void   ) 

Return a pointer to the config data.

Returns:
A pointer to the configuration

Definition at line 177 of file nvm_config.c.

Ecode_t NVM_Erase ( uint32_t  erasureCount  ) 

Erase the entire allocated NVM area.

Use this function to erase the entire non-volatile memory area allocated to the NVM system. It is possible to set a fixed erasure count for all the pages, or retain the existing one. To retain the erasure count might not be advisable if an error has occurred since this data may also have been damaged.

Parameters:
[in] erasureCount Specifies which erasure count to set for the blank pages. Pass NVM_ERASE_RETAINCOUNT to retain the erasure count.
Returns:
Returns the result of the erase operation using a Ecode_t.

Definition at line 369 of file nvm.c.

References ECODE_EMDRV_NVM_ERROR, ECODE_EMDRV_NVM_OK, NVM_ERASE_RETAINCOUNT, NVM_PAGE_SIZE, NVM_Config_t::nvmArea, NVMHAL_PageErase(), NVMHAL_Read(), NVMHAL_Write(), and NVM_Config_t::pages.

Here is the call graph for this function:

Ecode_t NVM_Init ( NVM_Config_t const *  config  ) 

Initialize the NVM manager.

Use this function to initialize and validate the NVM. Should be run on startup. The result of this process is then returned in the form of a Ecode_t.

If ECODE_EMDRV_NVM_OK is returned, everything went according to plan and you can use the API right away. If ECODE_EMDRV_NVM_NO_PAGES_AVAILABLE is returned this is a device that validates, but is empty. The proper way to handle this is to first reset the memory using NVM_Erase, and then write any initial data.

If a ECODE_EMDRV_NVM_ERROR, or anything more specific, is returned something irreparable happened, and the system cannot be used reliably. A simple solution to this would be to erase and reinitialize, but this will then cause data loss.

Parameters:
[in] config Pointer to structure defining NVM area.
Returns:
Returns the result of the initialization

Definition at line 184 of file nvm.c.

References ECODE_EMDRV_NVM_ERROR, ECODE_EMDRV_NVM_NO_PAGES_AVAILABLE, ECODE_EMDRV_NVM_OK, NVM_MAX_NUMBER_OF_PAGES, NVM_PAGE_SIZE, NVM_Config_t::nvmArea, NVMHAL_Init(), NVMHAL_Read(), NVM_Config_t::nvmPages, nvmPageTypeNormal, nvmPageTypeWear, NVM_Page_Descriptor_t::page, NVM_Config_t::pages, NVM_Page_Descriptor_t::pageType, and NVM_Config_t::userPages.

Here is the call graph for this function:

Ecode_t NVM_Read ( uint16_t  pageId,
uint8_t  objectId 
)

Read an object or an entire page.

Use this function to read an object or an entire page from memory. It takes a page id and an object id (or the NVM_READ_ALL constant to read everything) and reads data from flash and puts it in the memory locations given in the page specification.

Parameters:
[in] pageId Identifier of the page to read from.
[in] objectId Identifier of the object to read. Can be set to NVM_READ_ALL to read an entire page.
Returns:
Returns the result of the read operation using a Ecode_t.

Definition at line 791 of file nvm.c.

References ECODE_EMDRV_NVM_DATA_INVALID, ECODE_EMDRV_NVM_OK, ECODE_EMDRV_NVM_PAGE_INVALID, NVM_READ_ALL_CMD, NVMHAL_Read(), nvmPageTypeWear, NVM_Page_Descriptor_t::page, and NVM_Page_Descriptor_t::pageType.

Here is the call graph for this function:

uint32_t NVM_WearLevelGet ( void   ) 

Get maximum wear level.

This function returns the amount of erase cycles for the most erased page in memory. This can be used as a rough measure of health for the device.

Returns:
Returns the wear level as a uint32_t.

Definition at line 899 of file nvm.c.

References NVM_PAGE_SIZE, NVM_Config_t::nvmArea, NVMHAL_Read(), and NVM_Config_t::pages.

Here is the call graph for this function:

Ecode_t NVM_Write ( uint16_t  pageId,
uint8_t  objectId 
)

Write an object or a page.

Use this function to write an object or an entire page to NVM. It takes a page and an object and updates this object with the data pointed to by the corresponding page entry. All the objects in a page can be written simultaneously by using NVM_WRITE_ALL instead of an object ID. For "normal" pages it simply finds not used page in flash (with lowest erase counter) and copies all objects belonging to this page updating objects defined by objectId argument. For "wear" pages function tries to find spare place in already used page and write object here - if there is no free space it uses new page invalidating previously used one.

Parameters:
[in] pageId Identifier of the page you want to write to NVM.
[in] objectId Identifier of the object you want to write. May be set to NVM_WRITE_ALL to write the entire page to memory.
Returns:
Returns the result of the write operation using a Ecode_t.

Definition at line 441 of file nvm.c.

References ECODE_EMDRV_NVM_ERROR, ECODE_EMDRV_NVM_OK, NVM_FEATURE_STATIC_WEAR_ENABLED, NVM_PAGE_SIZE, NVM_WRITE_ALL_CMD, NVMHAL_Read(), NVMHAL_Write(), nvmPageTypeNormal, nvmPageTypeWear, NVM_Page_Descriptor_t::page, and NVM_Page_Descriptor_t::pageType.

Here is the call graph for this function: