3.18.4 NVMCTRL with Sector Operations
Non-Volatile Memory Controller with Sector Read/Write/Erase
3.18.4.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. PFM includes the program memory and user ID space while DFM is also referred to as EEPROM which is accessed one byte at a time and the erase before write is automatic. This module features the ability to read, write, and erase sectors of the non-volatile memory.
3.18.4.2 Supported Device Families
PIC18F-Q10 |
3.18.4.3 Required header files:
#include "mcc_generated_files/nvm/nvm.h"
3.18.4.4 How to use the Memory Driver
The Memory driver can be used to access different types of memory. Click the links below to view examples on how to access the Flash and EEPROM memory.
- Accessing the Flash Memory
- Accessing the EEPROM Memory
- Accessing the Device ID
- Accessing the Configuration settings
3.18.4.5 Module Documentation
3.18.4.5.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 uint8_t flash_data_t
Data type for the Flash data.
typedef uint24_t flash_address_t
Data type for the Flash address.
typedef uint8_t eeprom_data_t
Data type for the EEPROM data.
typedef uint24_t eeprom_address_t
Data type for the EEPROM address.
typedef uint16_t device_id_data_t
Data type for the Device ID data.
typedef uint24_t device_id_address_t
Data type for the Device ID address.
typedef uint8_t configuration_data_t
Data type for the Configurations settings data.
typedef uint24_t configuration_address_t
Data type for the Configurations settings address.
typedef uint8_t flash_data_t
Data type for the Flash data.
typedef uint24_t flash_address_t
Data type for the Flash address.
typedef uint8_t eeprom_data_t
Data type for the EEPROM data.
typedef uint24_t eeprom_address_t
Data type for the EEPROM address.
typedef uint16_t device_id_data_t
Data type for the Device ID data.
typedef uint24_t device_id_address_t
Data type for the Device ID address.
typedef uint8_t configuration_data_t
Data type for the Configurations settings data.
typedef uint24_t configuration_address_t
Data type for the Configurations settings address.
Definitions
#define PROGMEM_PAGE_SIZE (256U)
#define PROGMEM_SIZE (0x020000U)
#define BUFFER_RAM_START_ADDRESS (0xD00U)
#define EEPROM_START_ADDRESS (0x310000U)
#define EEPROM_SIZE (1024U)
#define CONFIGURATION_ROW_SIZE (16U)
#define UNLOCK_KEY_WORD_BYTE_WRITE (0xAA55U)
#define UNLOCK_KEY_ROW_READ (0x44BBU)
#define UNLOCK_KEY_ROW_WRITE (0x22DDU)
#define UNLOCK_KEY_PAGE_ERASE (0x33CCU)
#define PROGMEM_PAGE_SIZE (256U)
#define PROGMEM_SIZE (0x020000U)
#define BUFFER_RAM_START_ADDRESS (0xD00U)
#define EEPROM_START_ADDRESS (0x310000U)
#define EEPROM_SIZE (1024U)
#define CONFIGURATION_ROW_SIZE (16U)
#define UNLOCK_KEY_WORD_BYTE_WRITE (0xAA55U)
#define UNLOCK_KEY_ROW_READ (0x44BBU)
#define UNLOCK_KEY_ROW_WRITE (0x22DDU)
#define UNLOCK_KEY_PAGE_ERASE (0x33CCU)
Enumerations
enum nvm_status_t { NVM_OK, NVM_ERROR, 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 byte from the given address of Flash.
nvm_status_t FLASH_RowRead (flash_address_t address, flash_data_t *dataBuffer)
Reads one entire Flash row/sector from the given starting address of the row (the first byte location). The size of the 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. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_Write (flash_address_t address, uint16_t data)
Writes a word at the given Flash address. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row/sector from the given starting address of the row (the first byte 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/sector containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/sector (the first byte location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/sector (the first byte location).
eeprom_data_t EEPROM_Read (eeprom_address_t address)
Reads one byte from the given EEPROM address.
void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)
Writes one byte to the given EEPROM address. The NVM busy status must be checked using the NVM_IsBusy() API to know if the write operation is completed.
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 byte.
nvm_status_t CONFIGURATION_RowRead (configuration_address_t address, configuration_data_t *dataBuffer)
Reads all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t CONFIGURATION_RowWrite (configuration_address_t address, configuration_data_t *dataBuffer)
Writes all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary (the first Configuration word location). Use FLASH_PageAddressGet() to obtain the starting address of the row.
void NVM_InterruptEnable (void)
Enables the NVM interrupt.
void NVM_InterruptDisable (void)
Disables the NVM interrupt.
void NVM_ISR (void)
NVM Interrupt Service Routine (ISR) function.
void NVM_CallbackRegister (void(*CallbackHandler)(void))
Setter function for the NVM interrupt callback.
Definition Documentation
BUFFER_RAM_START_ADDRESS[1/2]
#define BUFFER_RAM_START_ADDRESS (0xD00U)
Contains the starting address of the buffer/sector RAM.
BUFFER_RAM_START_ADDRESS[1/2]
#define BUFFER_RAM_START_ADDRESS (0xD00U)
Contains the starting address of the buffer/sector RAM.
CONFIGURATION_ROW_SIZE[1/2]
#define CONFIGURATION_ROW_SIZE (16U)
Contains the size of Configuration row/sector size in bytes. It is two times the number of Configuration Words.
CONFIGURATION_ROW_SIZE[1/2]
#define CONFIGURATION_ROW_SIZE (16U)
Contains the size of Configuration row/sector size in bytes. It is two times the number of Configuration Words.
EEPROM_SIZE[1/2]
#define EEPROM_SIZE (1024U)
Contains the size of EEPROM in bytes.
EEPROM_SIZE[1/2]
#define EEPROM_SIZE (1024U)
Contains the size of EEPROM in bytes.
EEPROM_START_ADDRESS[1/2]
#define EEPROM_START_ADDRESS (0x310000U)
Contains the starting address of EEPROM.
EEPROM_START_ADDRESS[1/2]
#define EEPROM_START_ADDRESS (0x310000U)
Contains the starting address of EEPROM.
PROGMEM_PAGE_SIZE[1/2]
#define PROGMEM_PAGE_SIZE (256U)
Contains the size of a Flash page/sector in bytes.
PROGMEM_PAGE_SIZE[1/2]
#define PROGMEM_PAGE_SIZE (256U)
Contains the size of a Flash page/sector in bytes.
PROGMEM_SIZE[1/2]
#define PROGMEM_SIZE (0x020000U)
Contains the size of Flash in bytes.
PROGMEM_SIZE[1/2]
#define PROGMEM_SIZE (0x020000U)
Contains the size of Flash in bytes.
UNLOCK_KEY_PAGE_ERASE[1/2]
#define UNLOCK_KEY_PAGE_ERASE (0x33CCU)
Contains the unlock key for the page/sector erase operation.
UNLOCK_KEY_PAGE_ERASE[1/2]
#define UNLOCK_KEY_PAGE_ERASE (0x33CCU)
Contains the unlock key for the page/sector erase operation.
UNLOCK_KEY_ROW_READ[1/2]
#define UNLOCK_KEY_ROW_READ (0x44BBU)
Contains the unlock key for the row/sector read operation.
UNLOCK_KEY_ROW_READ[1/2]
#define UNLOCK_KEY_ROW_READ (0x44BBU)
Contains the unlock key for the row/sector read operation.
UNLOCK_KEY_ROW_WRITE[1/2]
#define UNLOCK_KEY_ROW_WRITE (0x22DDU)
Contains the unlock key for the row/sector write operation.
UNLOCK_KEY_ROW_WRITE[1/2]
#define UNLOCK_KEY_ROW_WRITE (0x22DDU)
Contains the unlock key for the row/sector write operation.
UNLOCK_KEY_WORD_BYTE_WRITE[1/2]
#define UNLOCK_KEY_WORD_BYTE_WRITE (0xAA55U)
Contains the unlock key for the word or byte write operation.
UNLOCK_KEY_WORD_BYTE_WRITE[1/2]
#define UNLOCK_KEY_WORD_BYTE_WRITE (0xAA55U)
Contains the unlock key for the word or byte write operation.
Typedef Documentation
configuration_address_t[1/2]
typedef uint24_t configuration_address_t
Data type for the Configurations settings address.
configuration_address_t[1/2]
typedef uint24_t configuration_address_t
Data type for the Configurations settings address.
configuration_data_t[1/2]
typedef uint8_t configuration_data_t
Data type for the Configurations settings data.
configuration_data_t[1/2]
typedef uint8_t configuration_data_t
Data type for the Configurations settings data.
device_id_address_t[1/2]
typedef uint24_t device_id_address_t
Data type for the Device ID address.
device_id_address_t[1/2]
typedef uint24_t device_id_address_t
Data type for the Device ID address.
device_id_data_t[1/2]
typedef uint16_t device_id_data_t
Data type for the Device ID data.
device_id_data_t[1/2]
typedef uint16_t device_id_data_t
Data type for the Device ID data.
eeprom_address_t[1/2]
typedef uint24_t eeprom_address_t
Data type for the EEPROM address.
eeprom_address_t[1/2]
typedef uint24_t eeprom_address_t
Data type for the EEPROM address.
eeprom_data_t[1/2]
typedef uint8_t eeprom_data_t
Data type for the EEPROM data.
eeprom_data_t[1/2]
typedef uint8_t eeprom_data_t
Data type for the EEPROM data.
flash_address_t[1/2]
typedef uint24_t flash_address_t
Data type for the Flash address.
flash_address_t[1/2]
typedef uint24_t flash_address_t
Data type for the Flash address.
flash_data_t[1/2]
typedef uint8_t flash_data_t
Data type for the Flash data.
flash_data_t[1/2]
typedef uint8_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 byte.
|
Configuration byte data. |
CONFIGURATION_RowRead()
nvm_status_t CONFIGURATION_RowRead (configuration_address_t address, configuration_data_t * dataBuffer)
Reads all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
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. |
|
Status of the Configuration row/sector read operation as described in nvm_status_t. |
CONFIGURATION_RowWrite()
nvm_status_t CONFIGURATION_RowWrite (configuration_address_t address, configuration_data_t * dataBuffer)
Writes all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary (the first Configuration word location). Use FLASH_PageAddressGet() to obtain the starting address of the row.
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. |
|
Status of the Configuration row/sector write operation as described in nvm_status_t. |
DeviceID_Read()
device_id_data_t DeviceID_Read (device_id_address_t address)
Reads the Device ID.
|
Device ID. |
EEPROM_Read()
eeprom_data_t EEPROM_Read (eeprom_address_t address)
Reads one byte from the given EEPROM address.
|
Byte read from the given EEPROM address. |
EEPROM_Write()
void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)
Writes one byte to the given EEPROM address. The NVM busy status must be checked using the NVM_IsBusy() API to know if the write operation is completed.
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. |
|
None. |
FLASH_PageAddressGet()
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/sector (the first byte location) containing the given Flash address.
|
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/sector 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. |
|
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/sector (the first byte location).
|
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 byte from the given address of Flash.
|
Byte read from the given Flash address. |
FLASH_RowRead()
nvm_status_t FLASH_RowRead (flash_address_t address, flash_data_t * dataBuffer)
Reads one entire Flash row/sector from the given starting address of the row (the first byte location). The size of the 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. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
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. |
|
Status of the Flash row read operation as described in nvm_status_t. |
FLASH_RowWrite()
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t * dataBuffer)
Writes one entire Flash row/sector from the given starting address of the row (the first byte 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. |
|
Status of the Flash row write operation as described in nvm_status_t. |
FLASH_Write()
nvm_status_t FLASH_Write (flash_address_t address, uint16_t data)
Writes a word at the given Flash address. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
Erase the Flash location before writing. 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. |
|
Status of the Flash write operation as described in nvm_status_t. |
NVM_CallbackRegister()
void NVM_CallbackRegister (void(*)(void) CallbackHandler)
Setter function for the NVM interrupt callback.
|
None. |
NVM_Initialize()
void NVM_Initialize (void )
Initializes the NVM driver.
|
None. |
NVM_InterruptDisable()
void NVM_InterruptDisable (void )[inline]
Disables the NVM interrupt.
|
None. |
NVM_InterruptEnable()
void NVM_InterruptEnable (void )[inline]
Enables the NVM interrupt.
Enable the global interrupt. |
|
None. |
NVM_IsBusy()
bool NVM_IsBusy (void )
Checks if the NVM is busy with the read/write/erase commands.
|
|
NVM_ISR()
void NVM_ISR (void )
NVM Interrupt Service Routine (ISR) function.
|
None. |
NVM_StatusClear()
void NVM_StatusClear (void )
Clears the NVM error status.
|
None. |
NVM_StatusGet()
nvm_status_t NVM_StatusGet (void )
Returns the status of the last NVM operation.
|
|
NVM_UnlockKeyClear()
void NVM_UnlockKeyClear (void )
Clears the previously configured unlock keys.
|
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.
|
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. | |
NVM_OK |
0 - The NVM operation succeeded. | |
NVM_ERROR |
1 - The NVM operation failed. |
3.18.4.5.2 Nvm_example
Flash Examples
This example shows how to overwrite an entire Flash page/sector with the new data using the row write feature:
#include "../mcc_generated_files/system/system.h" #define FLASH_ADDRESS (PROGMEM_SIZE - 5) //Flash address at which data is to be written void FLASH_Example_PageErase_RowWrite_Read(void) { flash_address_t flashStartPageAddress; uint16_t index; flash_data_t flashWriteData[PROGMEM_PAGE_SIZE]; nvm_status_t errorStatus = NVM_OK; bool readError = false; //Get the starting address of the page containing the given address flashStartPageAddress = FLASH_PageAddressGet(FLASH_ADDRESS); //Erase entire page NVM_UnlockKeySet(UNLOCK_KEY_PAGE_ERASE); errorStatus = FLASH_PageErase(flashStartPageAddress); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_PageErase passed \r\n"); } else { printf("FLASH_PageErase failed \r\n"); NVM_StatusClear(); } //Prepare row data for (index = 0; index < PROGMEM_PAGE_SIZE; index++) { flashWriteData[index] = (flash_data_t) index; } //Write data to Flash row NVM_UnlockKeySet(UNLOCK_KEY_ROW_WRITE); errorStatus = FLASH_RowWrite(flashStartPageAddress, flashWriteData); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_RowWrite passed \r\n"); } else { printf("FLASH_RowWrite failed \r\n"); NVM_StatusClear(); } //Read and verify row data for (index = 0; index < PROGMEM_PAGE_SIZE; index++) { if (FLASH_Read(flashStartPageAddress + index) != flashWriteData[index]) { readError = true; break; } } if (readError == false) { printf("FLASH_Read passed \r\n"); } else { printf("FLASH_Read failed \r\n"); } }
This example shows how to write a word on an empty Flash page/sector:
#include "../mcc_generated_files/system/system.h" #define FLASH_ADDRESS (PROGMEM_SIZE - 5) //Flash address at which data is to be written void FLASH_Example_PageErase_Write_Read(void) { flash_address_t flashStartPageAddress; nvm_status_t errorStatus = NVM_OK; //Get the starting address of the page containing the given address flashStartPageAddress = FLASH_PageAddressGet(FLASH_ADDRESS); //Erase entire page NVM_UnlockKeySet(UNLOCK_KEY_PAGE_ERASE); errorStatus = FLASH_PageErase(flashStartPageAddress); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_PageErase passed \r\n"); } else { printf("FLASH_PageErase failed \r\n"); NVM_StatusClear(); } //Write one word (0xAAAA) at the beginning of the page NVM_UnlockKeySet(UNLOCK_KEY_WORD_BYTE_WRITE); errorStatus = FLASH_Write(flashStartPageAddress, 0xAAAA); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_Write passed \r\n"); } else { printf("FLASH_Write failed \r\n"); NVM_StatusClear(); } //Verify FLASH_WordWrite by reading if (0xAAAA == (uint16_t) (FLASH_Read(flashStartPageAddress + 1) << 8 | FLASH_Read(flashStartPageAddress))) { printf("FLASH_Read passed \r\n"); } else { printf("FLASH_Read failed \r\n"); } }
This example shows how to update the specific locations in a given Flash page/sector without disturbing the other locations:
#include "../mcc_generated_files/system/system.h" #define FLASH_ADDRESS (PROGMEM_SIZE - 5) //Flash address at which data is to be written flash_data_t flashWriteData[PROGMEM_PAGE_SIZE] __at(BUFFER_RAM_START_ADDRESS); void FLASH_Example_UpdateSelectiveLocations(void) { flash_address_t flashStartPageAddress; uint16_t flashAddressOffset; nvm_status_t errorStatus = NVM_OK; bool readError = false; //Get the starting address of the page containing the given address flashStartPageAddress = FLASH_PageAddressGet(FLASH_ADDRESS); //Read entire row in buffer RAM NVM_UnlockKeySet(UNLOCK_KEY_ROW_READ); errorStatus = FLASH_RowRead(flashStartPageAddress, flashWriteData); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_RowRead passed \r\n"); } else { printf("FLASH_RowRead failed \r\n"); NVM_StatusClear(); } //Get offset from the starting address of the page flashAddressOffset = FLASH_PageOffsetGet(FLASH_ADDRESS); //Update 4 bytes flashWriteData[flashAddressOffset] = 0x0A; flashWriteData[flashAddressOffset + 1] = 0x1A; flashWriteData[flashAddressOffset + 2] = 0x2A; flashWriteData[flashAddressOffset + 3] = 0x3A; //Erase entire Flash page NVM_UnlockKeySet(UNLOCK_KEY_PAGE_ERASE); errorStatus = FLASH_PageErase(flashStartPageAddress); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_PageErase passed \r\n"); } else { printf("FLASH_PageErase failed \r\n"); NVM_StatusClear(); } //Write data to Flash row NVM_UnlockKeySet(UNLOCK_KEY_ROW_WRITE); errorStatus = FLASH_RowWrite(flashStartPageAddress, flashWriteData); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("FLASH_RowWrite passed \r\n"); } else { printf("FLASH_RowWrite failed \r\n"); NVM_StatusClear(); } //Read and verify row data for (flashAddressOffset = 0; flashAddressOffset < PROGMEM_PAGE_SIZE; flashAddressOffset++) { if (FLASH_Read(flashStartPageAddress + flashAddressOffset) != flashWriteData[flashAddressOffset]) { readError = true; break; } } if (readError == false) { printf("FLASH_Read passed \r\n"); } else { printf("FLASH_Read failed \r\n"); } }
EEPROM Examples
This example shows how to perform the write and read operations on EEPROM:
#include "../mcc_generated_files/system/system.h" #define EEPROM_ADDRESS (EEPROM_START_ADDRESS) //EEPROM address at which data is to be written void EEPROM_Write_Read(void) { eeprom_data_t eepromWriteData[8]; uint8_t count; bool readError = false; //Prepare data for (count = 0; count < 8; count++) { eepromWriteData[count] = 0xA1 + count; } for (count = 0; count < 8; count++) { //Write EEPROM byte NVM_UnlockKeySet(UNLOCK_KEY_WORD_BYTE_WRITE); EEPROM_Write(EEPROM_ADDRESS + count, eepromWriteData[count]); NVM_UnlockKeyClear(); while (NVM_IsBusy()); if (NVM_StatusGet() == NVM_OK) { printf("EEPROM_Write passed \r\n"); } else { printf("EEPROM_Write failed \r\n"); NVM_StatusClear(); } } //Read and verify for (count = 0; count < 8; count++) { if (EEPROM_Read(EEPROM_ADDRESS + count) != eepromWriteData[count]) { readError = true; break; } } if (readError == false) { printf("EEPROM_Read passed \r\n"); } else { printf("EEPROM_Read failed \r\n"); } }
Device ID Examples
This example shows how to read the Device ID:
#include "mcc_generated_files/system/system.h" #define DEVICE_ID_ADDRESS (0x3FFFFEU) //Compare with the device data sheet to see if the address is correct void NVM_Example_DeviceID_Read(void) { printf("Device ID : 0x%X \r\n", DeviceID_Read(DEVICE_ID_ADDRESS)); }
Configuration Settings Examples
This example shows how to update the specific Configuration setting without disturbing the other settings:
#include "mcc_generated_files/system/system.h" #define CONFIG_TO_BE_UPDATED_ADDRESS (0x300000U) //CONFIG1L address (Compare with the device data sheet to see if the address is correct) #define FIRST_CONFIG_ADDRESS (0x300000U) //Compare with the device data sheet to see if the address is correct #define _CONFIG1_FEXTOSC_MASK (0b111) configuration_data_t configurationData[CONFIGURATION_ROW_SIZE] __at(BUFFER_RAM_START_ADDRESS); void NVM_Example_Configuration_UpdateSpecifcSetting(void) { configuration_address_t configurationToBeUpdatedAddress = CONFIG_TO_BE_UPDATED_ADDRESS; nvm_status_t errorStatus = NVM_OK; bool readError = false; configuration_address_t configurationIndex; //Read NVM_UnlockKeySet(UNLOCK_KEY_ROW_READ); errorStatus = CONFIGURATION_RowRead(FIRST_CONFIG_ADDRESS, configurationData); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("CONFIGURATION_RowRead passed \r\n"); } else { printf("CONFIGURATION_RowRead failed \r\n"); NVM_StatusClear(); } //Modify configurationData[configurationToBeUpdatedAddress - FIRST_CONFIG_ADDRESS] &= (~((configuration_data_t)_CONFIG1_FEXTOSC_MASK)); //Clear External Oscillator Mode Selection bits //Write NVM_UnlockKeySet(UNLOCK_KEY_ROW_WRITE); errorStatus = CONFIGURATION_RowWrite(FIRST_CONFIG_ADDRESS, configurationData); NVM_UnlockKeyClear(); if (errorStatus == NVM_OK) { printf("CONFIGURATION_RowWrite passed \r\n"); } else { printf("CONFIGURATION_RowWrite failed \r\n"); NVM_StatusClear(); } //Read again to verify for (configurationIndex = FIRST_CONFIG_ADDRESS; configurationIndex <= LAST_CONFIG_ADDRESS; configurationIndex++) { if (CONFIGURATION_Read(configurationIndex) != configurationData[configurationIndex - FIRST_CONFIG_ADDRESS]) { readError = true; break; } } if (readError == false) { printf("CONFIGURATION_Read passed \r\n"); } else { printf("CONFIGURATION_Read failed \r\n"); } }
3.18.4.6 File Documentation
3.18.4.6.1 source/nvm_example.dox File Reference
3.18.4.6.2 source/nvm_interrupt.c File Reference
#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 byte from the given address of Flash.
nvm_status_t FLASH_RowRead (flash_address_t address, flash_data_t *dataBuffer)
Reads one entire Flash row/sector from the given starting address of the row (the first byte location). The size of the 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. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_Write (flash_address_t address, uint16_t data)
Writes a word at the given Flash address. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row/sector from the given starting address of the row (the first byte 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/sector containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/sector (the first byte location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/sector (the first byte location).
eeprom_data_t EEPROM_Read (eeprom_address_t address)
Reads one byte from the given EEPROM address.
void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)
Writes one byte to the given EEPROM address. The NVM busy status must be checked using the NVM_IsBusy() API to know if the write operation is completed.
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 byte.
nvm_status_t CONFIGURATION_RowRead (configuration_address_t address, configuration_data_t *dataBuffer)
Reads all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t CONFIGURATION_RowWrite (configuration_address_t address, configuration_data_t *dataBuffer)
Writes all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary (the first Configuration word location). Use FLASH_PageAddressGet() to obtain the starting address of the row.
void NVM_InterruptEnable (void)
Enables the NVM interrupt.
void NVM_InterruptDisable (void)
Disables the NVM interrupt.
void NVM_ISR (void)
NVM Interrupt Service Routine (ISR) function.
void NVM_CallbackRegister (void(*CallbackHandler)(void))
Setter function for the NVM interrupt callback.
Variables
__near static volatile uint8_t unlockKeyLow
__near static volatile uint8_t unlockKeyHigh
static void(* NVM_Callback )(void) = NULL
Variable Documentation
NVM_Callback
void(* NVM_Callback) (void) = NULL[static]
unlockKeyHigh
__near static volatile uint8_t unlockKeyHigh[static]
unlockKeyLow
__near static volatile uint8_t unlockKeyLow[static]
3.18.4.6.3 source/nvm_interrupt.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 byte from the given address of Flash.
nvm_status_t FLASH_RowRead (flash_address_t address, flash_data_t *dataBuffer)
Reads one entire Flash row/sector from the given starting address of the row (the first byte location). The size of the 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. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_Write (flash_address_t address, uint16_t data)
Writes a word at the given Flash address. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row/sector from the given starting address of the row (the first byte 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/sector containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/sector (the first byte location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/sector (the first byte location).
eeprom_data_t EEPROM_Read (eeprom_address_t address)
Reads one byte from the given EEPROM address.
void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)
Writes one byte to the given EEPROM address. The NVM busy status must be checked using the NVM_IsBusy() API to know if the write operation is completed.
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 byte.
nvm_status_t CONFIGURATION_RowRead (configuration_address_t address, configuration_data_t *dataBuffer)
Reads all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t CONFIGURATION_RowWrite (configuration_address_t address, configuration_data_t *dataBuffer)
Writes all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary (the first Configuration word location). Use FLASH_PageAddressGet() to obtain the starting address of the row.
void NVM_InterruptEnable (void)
Enables the NVM interrupt.
void NVM_InterruptDisable (void)
Disables the NVM interrupt.
void NVM_ISR (void)
NVM Interrupt Service Routine (ISR) function.
void NVM_CallbackRegister (void(*CallbackHandler)(void))
Setter function for the NVM interrupt callback.
Macros
#define PROGMEM_PAGE_SIZE (256U)
#define PROGMEM_SIZE (0x020000U)
#define BUFFER_RAM_START_ADDRESS (0xD00U)
#define EEPROM_START_ADDRESS (0x310000U)
#define EEPROM_SIZE (1024U)
#define CONFIGURATION_ROW_SIZE (16U)
#define UNLOCK_KEY_WORD_BYTE_WRITE (0xAA55U)
#define UNLOCK_KEY_ROW_READ (0x44BBU)
#define UNLOCK_KEY_ROW_WRITE (0x22DDU)
#define UNLOCK_KEY_PAGE_ERASE (0x33CCU)
Typedefs
typedef uint8_t flash_data_t
Data type for the Flash data.
typedef uint24_t flash_address_t
Data type for the Flash address.
typedef uint8_t eeprom_data_t
Data type for the EEPROM data.
typedef uint24_t eeprom_address_t
Data type for the EEPROM address.
typedef uint16_t device_id_data_t
Data type for the Device ID data.
typedef uint24_t device_id_address_t
Data type for the Device ID address.
typedef uint8_t configuration_data_t
Data type for the Configurations settings data.
typedef uint24_t configuration_address_t
Data type for the Configurations settings address.
Enumerations
enum nvm_status_t { NVM_OK, NVM_ERROR, 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
3.18.4.6.4 source/nvm_polling.c File Reference
#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 byte from the given address of Flash.
nvm_status_t FLASH_RowRead (flash_address_t address, flash_data_t *dataBuffer)
Reads one entire Flash row/sector from the given starting address of the row (the first byte location). The size of the 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. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_Write (flash_address_t address, uint16_t data)
Writes a word at the given Flash address. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row/sector from the given starting address of the row (the first byte 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/sector containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/sector (the first byte location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/sector (the first byte location).
eeprom_data_t EEPROM_Read (eeprom_address_t address)
Reads one byte from the given EEPROM address.
void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)
Writes one byte to the given EEPROM address. The NVM busy status must be checked using the NVM_IsBusy() API to know if the write operation is completed.
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 byte.
nvm_status_t CONFIGURATION_RowRead (configuration_address_t address, configuration_data_t *dataBuffer)
Reads all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t CONFIGURATION_RowWrite (configuration_address_t address, configuration_data_t *dataBuffer)
Writes all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary (the first Configuration word location). Use FLASH_PageAddressGet() to obtain the starting address of the row.
Variables
__near static volatile uint8_t unlockKeyLow
__near static volatile uint8_t unlockKeyHigh
Variable Documentation
unlockKeyHigh
__near static volatile uint8_t unlockKeyHigh[static]
unlockKeyLow
__near static volatile uint8_t unlockKeyLow[static]
3.18.4.6.5 source/nvm_polling.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 byte from the given address of Flash.
nvm_status_t FLASH_RowRead (flash_address_t address, flash_data_t *dataBuffer)
Reads one entire Flash row/sector from the given starting address of the row (the first byte location). The size of the 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. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_Write (flash_address_t address, uint16_t data)
Writes a word at the given Flash address. As this is a non-portable API, it may not be supported by all 8-bit PIC® and AVR® devices.
nvm_status_t FLASH_RowWrite (flash_address_t address, flash_data_t *dataBuffer)
Writes one entire Flash row/sector from the given starting address of the row (the first byte 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/sector containing the given address.
flash_address_t FLASH_PageAddressGet (flash_address_t address)
Returns the starting address of the page/sector (the first byte location) containing the given Flash address.
uint16_t FLASH_PageOffsetGet (flash_address_t address)
Returns the offset from the starting address of the page/sector (the first byte location).
eeprom_data_t EEPROM_Read (eeprom_address_t address)
Reads one byte from the given EEPROM address.
void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)
Writes one byte to the given EEPROM address. The NVM busy status must be checked using the NVM_IsBusy() API to know if the write operation is completed.
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 byte.
nvm_status_t CONFIGURATION_RowRead (configuration_address_t address, configuration_data_t *dataBuffer)
Reads all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary. Use FLASH_PageAddressGet() to obtain the starting address of the row.
nvm_status_t CONFIGURATION_RowWrite (configuration_address_t address, configuration_data_t *dataBuffer)
Writes all the Configuration Words. The size of the buffer must be one Configuration row/sector and the address must be aligned with the row boundary (the first Configuration word location). Use FLASH_PageAddressGet() to obtain the starting address of the row.
Macros
#define PROGMEM_PAGE_SIZE (256U)
#define PROGMEM_SIZE (0x020000U)
#define BUFFER_RAM_START_ADDRESS (0xD00U)
#define EEPROM_START_ADDRESS (0x310000U)
#define EEPROM_SIZE (1024U)
#define CONFIGURATION_ROW_SIZE (16U)
#define UNLOCK_KEY_WORD_BYTE_WRITE (0xAA55U)
#define UNLOCK_KEY_ROW_READ (0x44BBU)
#define UNLOCK_KEY_ROW_WRITE (0x22DDU)
#define UNLOCK_KEY_PAGE_ERASE (0x33CCU)
Typedefs
typedef uint8_t flash_data_t
Data type for the Flash data.
typedef uint24_t flash_address_t
Data type for the Flash address.
typedef uint8_t eeprom_data_t
Data type for the EEPROM data.
typedef uint24_t eeprom_address_t
Data type for the EEPROM address.
typedef uint16_t device_id_data_t
Data type for the Device ID data.
typedef uint24_t device_id_address_t
Data type for the Device ID address.
typedef uint8_t configuration_data_t
Data type for the Configurations settings data.
typedef uint24_t configuration_address_t
Data type for the Configurations settings address.
Enumerations
enum nvm_status_t { NVM_OK, NVM_ERROR, NVM_OK, NVM_ERROR }
Macro Definition Documentation
FLASH_ErasePageAddressGet
#define FLASH_ErasePageAddressGet FLASH_PageAddressGet
FLASH_ErasePageOffsetGet
#define FLASH_ErasePageOffsetGet FLASH_PageOffsetGet
Enumeration Type Documentation
nvm_status_t
enum nvm_status_t
NVM_OK |
0 - The NVM operation succeeded. | |
NVM_ERROR |
1 - The NVM operation failed. | |
NVM_OK |
0 - The NVM operation succeeded. | |
NVM_ERROR |
1 - The NVM operation failed. |