3.18.5 NVMCTRL with HEF
Non-Volatile Memory Controller with High-Endurance Flash
3.18.5.1 Introduction
The NVM module provides run-time read and write access to the Program Flash Memory (PFM), Data Flash Memory (DFM) and Configuration bits. This NVM module features High-Endurance Flash (HEF) memory instead of the standard EEPROM.
3.18.5.2 Supported Device Families
| PIC12F150x | PIC16F150x | PIC12F157x | PIC16F157x |
| PIC12F155x | PIC16F155x | PIC12F161x | PIC16F161x |
| PIC16F151x | PIC16F152x | PIC16F170x | PIC16F171x |
| PIC16LF156x | PIC16LF190x |
3.18.5.3 Required header files:
#include "mcc_generated_files/nvm/nvm.h"3.18.5.4 Module Documentation
3.18.5.4.1 Non-Volatile Memory
This file contains API prototypes and other data types for the Non-Volatile Memory (NVM) driver.
Module description
This file contains API prototypes and other data types for the Non-Volatile Memory (NVM) driver.
Typedefs
typedef uint16_t flash_data_t
Data type for the Flash data.
typedef uint16_t flash_address_t
Data type for the Flash address.
typedef uint16_t device_id_data_t
Data type for the Device ID data.
typedef uint16_t device_id_address_t
Data type for the Device ID address.
typedef uint16_t configuration_data_t
Data type for the Configurations Settings data.
typedef uint16_t configuration_address_t
Data type for the Configurations Settings address.
Definitions
#define PROGMEM_PAGE_SIZE (32U)
#define PROGMEM_SIZE (0x2000U)
#define UNLOCK_KEY (0xAA55U)
Enumerations
enum nvm_status_t { NVM_OK, NVM_ERROR }
Contains the return codes for the NVM driver APIs.
Functions
void NVM_Initialize (void)
Initializes the NVM driver.
bool NVM_IsBusy (void)
Checks if the NVM is busy with the read/write/erase commands.
nvm_status_t NVM_StatusGet (void)
Returns the status of the last NVM operation.
void NVM_StatusClear (void)
Clears the NVM error status.
void NVM_UnlockKeySet (uint16_t unlockKey)
Sets the unlock keys required to perform any erase or write operations on Flash and EEPROM.
void NVM_UnlockKeyClear (void)
Clears the previously configured unlock keys.
flash_data_t FLASH_Read (flash_address_t address)
Reads a 14-bit word from the given Flash address.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row from the given starting address of the row (the first word location). The size of the input buffer must be one Flash row and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t FLASH_PageErase (flash_address_t address)
Erases one Flash page/row containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/row (the first word location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/row (the first word location).
device_id_data_t DeviceID_Read (device_id_address_t address)
Reads the Device ID.
configuration_data_t CONFIGURATION_Read (configuration_address_t address)
Reads one Configuration Word.
Definition Documentation
PROGMEM_PAGE_SIZE
#define PROGMEM_PAGE_SIZE (32U)
Contains the size of a Flash page/row in 14-bit words.
PROGMEM_SIZE
#define PROGMEM_SIZE (0x2000U)
Contains the size of Flash in 14-bit words.
UNLOCK_KEY
#define UNLOCK_KEY (0xAA55U)
Contains the unlock key required for the NVM operations.
Typedef Documentation
configuration_address_t
typedef uint16_t configuration_address_t
Data type for the Configurations Settings address.
configuration_data_t
typedef uint16_t configuration_data_t
Data type for the Configurations Settings data.
device_id_address_t
typedef uint16_t device_id_address_t
Data type for the Device ID address.
device_id_data_t
typedef uint16_t device_id_data_t
Data type for the Device ID data.
flash_address_t
typedef uint16_t flash_address_t
Data type for the Flash address.
flash_data_t
typedef uint16_t flash_data_t
Data type for the Flash data.
Function Documentation
CONFIGURATION_Read()
configuration_data_t CONFIGURATION_Read (configuration_address_t address)
Reads one Configuration Word.
| in | address |
- Configuration Word address to be read. |
Configuration Word data. |
DeviceID_Read()
device_id_data_t DeviceID_Read (device_id_address_t address)
Reads the Device ID.
| in | address |
- Starting address of the Device ID. |
Device ID. |
FLASH_PageAddressGet()
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/row (the first word location) containing the given Flash address.
| in | address |
- Flash address for which the page starting address will be obtained. |
Starting address of the page containing the given Flash address. |
FLASH_PageErase()
nvm_status_t FLASH_PageErase (flash_address_t address)
Erases one Flash page/row containing the given address.
Set the unlock key using the NVM_UnlockKeySet() API, if the key has been cleared before. AoU: Address Qualifiers must be configured to Require under Project Properties>XC8 Compiler>Optimizations. |
| in | address |
- Any address in the Flash page to be erased. |
Status of the Flash page erase operation as described in nvm_status_t. |
FLASH_PageOffsetGet()
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/row (the first word location).
| in | address |
- Flash address for which the offset from the starting address of the page will be obtained. |
Offset of the given address from the starting address of the page. |
FLASH_Read()
flash_data_t FLASH_Read (flash_address_t address)
Reads a 14-bit word from the given Flash address.
| in | address |
- Address of the Flash location from which data is to be read. |
14-bit word read from the given Flash address. |
FLASH_RowWrite()
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t * dataBuffer)
Writes one entire Flash row from the given starting address of the row (the first word location). The size of the input buffer must be one Flash row and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
Erase Flash row before calling this function. Set the unlock key using the NVM_UnlockKeySet() API, if the key has been cleared before. AoU: Address Qualifiers must be configured to Require under Project Properties>XC8 Compiler>Optimizations. |
| in | address |
- Starting address of the Flash row to be written. |
| in | *data |
- Pointer to a buffer which holds the data to be written. |
Status of the Flash row write operation as described in nvm_status_t. |
NVM_Initialize()
void NVM_Initialize (void )
Initializes the NVM driver.
| None. |
None. |
NVM_IsBusy()
bool NVM_IsBusy (void )
Checks if the NVM is busy with the read/write/erase commands.
| None. |
| True |
- The NVM operation is being performed. |
| False |
- The NVM operation is not being performed. |
NVM_StatusClear()
void NVM_StatusClear (void )
Clears the NVM error status.
| None. |
None. |
NVM_StatusGet()
nvm_status_t NVM_StatusGet (void )
Returns the status of the last NVM operation.
| None. |
| NVM_OK |
- The NVM operation succeeded. |
| NVM_ERROR |
- The NVM operation failed. |
NVM_UnlockKeyClear()
void NVM_UnlockKeyClear (void )
Clears the previously configured unlock keys.
| None. |
None. |
NVM_UnlockKeySet()
void NVM_UnlockKeySet (uint16_t unlockKey)
Sets the unlock keys required to perform any erase or write operations on Flash and EEPROM.
| in | unlockKey |
- Unlock key value as specified in the device data sheet. |
None. |
Enumeration Type Documentation
nvm_status_t
enum nvm_status_t
Contains the return codes for the NVM driver APIs.
| NVM_OK |
0 - The NVM operation succeeded. |
| NVM_ERROR |
1 - The NVM operation failed. |
3.18.5.5 File Documentation
3.18.5.5.1 source/nvm.c File Reference
Contains the implementation file for the NVM driver.
#include "../nvm.h"
Functions
void NVM_Initialize (void)
Initializes the NVM driver.
bool NVM_IsBusy (void)
Checks if the NVM is busy with the read/write/erase commands.
nvm_status_t NVM_StatusGet (void)
Returns the status of the last NVM operation.
void NVM_StatusClear (void)
Clears the NVM error status.
void NVM_UnlockKeySet (uint16_t unlockKey)
Sets the unlock keys required to perform any erase or write operations on Flash and EEPROM.
void NVM_UnlockKeyClear (void)
Clears the previously configured unlock keys.
flash_data_t FLASH_Read (flash_address_t address)
Reads a 14-bit word from the given Flash address.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row from the given starting address of the row (the first word location). The size of the input buffer must be one Flash row and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t FLASH_PageErase (flash_address_t address)
Erases one Flash page/row containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/row (the first word location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/row (the first word location).
device_id_data_t DeviceID_Read (device_id_address_t address)
Reads the Device ID.
configuration_data_t CONFIGURATION_Read (configuration_address_t address)
Reads one Configuration Word.
Variables
__near static volatile uint8_t unlockKeyLow
__near static volatile uint8_t unlockKeyHigh
Detailed Description
Contains the implementation file for the NVM driver.
Variable Documentation
unlockKeyHigh
__near static volatile uint8_t unlockKeyHigh[static]
unlockKeyLow
__near static volatile uint8_t unlockKeyLow[static]
3.18.5.5.2 source/nvm.h File Reference
#include <xc.h> #include <stdbool.h>
Functions
void NVM_Initialize (void)
Initializes the NVM driver.
bool NVM_IsBusy (void)
Checks if the NVM is busy with the read/write/erase commands.
nvm_status_t NVM_StatusGet (void)
Returns the status of the last NVM operation.
void NVM_StatusClear (void)
Clears the NVM error status.
void NVM_UnlockKeySet (uint16_t unlockKey)
Sets the unlock keys required to perform any erase or write operations on Flash and EEPROM.
void NVM_UnlockKeyClear (void)
Clears the previously configured unlock keys.
flash_data_t FLASH_Read (flash_address_t address)
Reads a 14-bit word from the given Flash address.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row from the given starting address of the row (the first word location). The size of the input buffer must be one Flash row and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t FLASH_PageErase (flash_address_t address)
Erases one Flash page/row containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/row (the first word location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/row (the first word location).
device_id_data_t DeviceID_Read (device_id_address_t address)
Reads the Device ID.
configuration_data_t CONFIGURATION_Read (configuration_address_t address)
Reads one Configuration Word.
Macros
#define PROGMEM_PAGE_SIZE (32U)
#define PROGMEM_SIZE (0x2000U)
#define UNLOCK_KEY (0xAA55U)
Typedefs
typedef uint16_t flash_data_t
Data type for the Flash data.
typedef uint16_t flash_address_t
Data type for the Flash address.
typedef uint16_t device_id_data_t
Data type for the Device ID data.
typedef uint16_t device_id_address_t
Data type for the Device ID address.
typedef uint16_t configuration_data_t
Data type for the Configurations Settings data.
typedef uint16_t configuration_address_t
Data type for the Configurations Settings address.
Enumerations
enum nvm_status_t { NVM_OK, NVM_ERROR }
Contains the return codes for the NVM driver APIs.
Macro Definition Documentation
FLASH_ErasePageAddressGet
#define FLASH_ErasePageAddressGet FLASH_PageAddressGet
FLASH_ErasePageOffsetGet
#define FLASH_ErasePageOffsetGet FLASH_PageOffsetGet