NVM
[EM_Drivers]

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

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...
enum  NVM_Result_t {
  nvmResultOk = 0,
  nvmResultAddrInvalid = 1,
  nvmResultInputInvalid = 2,
  nvmResultDataInvalid = 3,
  nvmResultWriteLock = 4,
  nvmResultNoPages = 5,
  nvmResultNoPage = 6,
  nvmResultErrorInitial = 7,
  nvmResultError = 8
}
 

Result type for all the API functions.

More...

Functions

NVM_Result_t NVM_Init (NVM_Config_t const *config)
 Initialize the NVM manager.
NVM_Result_t NVM_Erase (uint32_t erasureCount)
 Erase the entire NVM.
NVM_Result_t NVM_Write (uint16_t pageId, uint8_t objectId)
 Write an object or a page.
NVM_Result_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.

Typedef Documentation

A collection of object descriptors that make up a page.

Definition at line 152 of file nvm.h.

The list of pages registered for use.

Definition at line 164 of file nvm.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 137 of file nvm.h.

Result type for all the API functions.

Enumerator:
nvmResultOk 

Flash read/write/erase successful.

nvmResultAddrInvalid 

Invalid address.

Write to an address out of bounds.

nvmResultInputInvalid 

Invalid input data.

nvmResultDataInvalid 

Invalid data.

nvmResultWriteLock 

A write is currently in progress, and any concurrent operations might cause problems.

nvmResultNoPages 

Initialization didn't find any pages.

nvmResultNoPage 

Could not find the specified page.

It might not have been saved yet.

nvmResultErrorInitial 

Result not changed to OK.

nvmResultError 

General error.

Definition at line 175 of file nvm.h.


Function Documentation

NVM_Result_t NVM_Erase ( uint32_t  erasureCount  ) 

Erase the entire NVM.

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 NVM_Result_t.

Definition at line 419 of file nvm.c.

References NVM_Config_t::nvmArea, NVMHAL_PageErase(), NVMHAL_Read(), NVMHAL_Write(), nvmResultErrorInitial, nvmResultOk, and NVM_Config_t::pages.

Here is the call graph for this function:

NVM_Result_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 NVM_Result_t.

If nvmResultOk is returned, everything went according to plan and you can use the API right away. If nvmResultNoPages 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 nvmResultError, 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 using a NVM_InitResult_TypeDef.

Definition at line 234 of file nvm.c.

References NVM_Config_t::nvmArea, NVMHAL_Init(), NVMHAL_Read(), NVM_Config_t::nvmPages, nvmPageTypeNormal, nvmPageTypeWear, nvmResultError, nvmResultErrorInitial, nvmResultNoPages, nvmResultOk, 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:

NVM_Result_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 NVM_Result_t.

Definition at line 843 of file nvm.c.

References NVMHAL_Read(), nvmPageTypeWear, nvmResultDataInvalid, nvmResultNoPage, nvmResultOk, 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 951 of file nvm.c.

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

Here is the call graph for this function:

NVM_Result_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 NVM_Result_t.

Definition at line 493 of file nvm.c.

References NVMHAL_Read(), NVMHAL_Write(), nvmPageTypeNormal, nvmPageTypeWear, nvmResultError, nvmResultErrorInitial, nvmResultOk, NVM_Page_Descriptor_t::page, and NVM_Page_Descriptor_t::pageType.

Here is the call graph for this function: