# 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

typedef NVM_Object_Descriptor_t NVM_Page_t[]

A collection of object descriptors that make up a page.

Definition at line 152 of file nvm.h.

typedef NVM_Page_Descriptor_t NVM_Page_Table_t[]

The list of pages registered for use.

Definition at line 164 of file nvm.h.

## Enumeration Type Documentation

enum NVM_Page_Type_t

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.

enum NVM_Result_t

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: