3.10.1 NVMCTRL

Nonvolatile Memory Controller

3.10.1.1 Introduction

This NVM Controller (NVMCTRL) is the interface between the CPU and Nonvolatile Memories (Flash, EEPROM, Signature Row, User Row and fuses). These are reprogrammable memory blocks that retain their values even when they are not powered. The Flash is mainly used for program storage and can also be used for data storage. The EEPROM is used for data storage and can be programmed while the CPU is running the program from the Flash.

3.10.1.2 Supported Device Families

AVR® Dx

3.10.1.3 Required header files:

#include "mcc_generated_files/nvm/nvm.h"

3.10.1.4 How to use the Memory drivers

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.

3.10.1.5 Module Documentation

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

Version: NVM Driver Version 3.0.0
Typedefs
Functions

Definition Documentation

PROGMEM_BLOCK_SIZE[1/2]

#define PROGMEM_BLOCK_SIZE (512U)

Contains the program memory block size in bytes. The BOOTSIZE and CODESIZE fuses select the Flash section sizes in blocks of PROGMEM_BLOCK_SIZE bytes.

PROGMEM_BLOCK_SIZE[1/2]

#define PROGMEM_BLOCK_SIZE (512U)

Contains the program memory block size in bytes. The BOOTSIZE and CODESIZE fuses select the Flash section sizes in blocks of PROGMEM_BLOCK_SIZE bytes.

SERIAL_NUMBER_SIZE[1/2]

#define SERIAL_NUMBER_SIZE (16U)

Contains the serial number length in bytes.

SERIAL_NUMBER_SIZE[1/2]

#define SERIAL_NUMBER_SIZE (16U)

Contains the serial number length in bytes.

Typedef Documentation

device_id_data_t[1/2]

typedef uint32_t device_id_data_t

Data type for the Device ID data.

device_id_data_t[1/2]

typedef uint32_t device_id_data_t

Data type for the Device ID data.

eeprom_address_t[1/2]

typedef uint16_t eeprom_address_t

Data type for the EEPROM address.

eeprom_address_t[1/2]

typedef uint16_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 uint32_t flash_address_t

Data type for the Flash address.

flash_address_t[1/2]

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

fuse_address_t[1/2]

typedef uint16_t fuse_address_t

Data type for the Fuse address.

fuse_address_t[1/2]

typedef uint16_t fuse_address_t

Data type for the Fuse address.

fuse_data_t[1/2]

typedef uint8_t fuse_data_t

Data type for the Fuse data.

fuse_data_t[1/2]

typedef uint8_t fuse_data_t

Data type for the Fuse data.

sigrow_address_t[1/2]

typedef uint16_t sigrow_address_t

Data type for the Signature Row address.

sigrow_address_t[1/2]

typedef uint16_t sigrow_address_t

Data type for the Signature Row address.

sigrow_data_t[1/2]

typedef uint8_t sigrow_data_t

Data type for the Signature Row data.

sigrow_data_t[1/2]

typedef uint8_t sigrow_data_t

Data type for the Signature Row data.

Function Documentation

EEPROM_CallbackRegister()

void EEPROM_CallbackRegister (void(*)(void) CallbackHandler)

Setter function for the EEPROM Ready interrupt callback.

Parameters:
in CallbackHandler

- Pointer to a custom callback.

Returns:

None.

EEPROM_IsBusy()

bool EEPROM_IsBusy (void )

Checks if the EEPROM is busy.

Precondition:

NVM must be initialized with NVM_Initialize() before calling this API.

Parameters:
None.
Return values:
True

- The EEPROM operation is being performed.

False

- The EEPROM operation is not being performed.

EEPROM_Read()

eeprom_data_t EEPROM_Read (eeprom_address_t address)

Reads one byte from the given EEPROM address.

Precondition:

NVM must be initialized with NVM_Initialize() before calling this API.

Parameters:
in address

- Address of the EEPROM location to be read.

Returns:

Byte read from the given EEPROM address.

EEPROM_ReadyInterruptDisable()

void EEPROM_ReadyInterruptDisable (void )[inline]

Disables the EEREADY interrupt.

Precondition:

The interrupt can be disabled in the interrupt handler.

Parameters:
None.
Returns:

None.

EEPROM_ReadyInterruptEnable()

void EEPROM_ReadyInterruptEnable (void )[inline]

Enables the EEREADY interrupt.

Precondition:

The interrupt must be enabled only after triggering an NVM command. Global interrupt must be enabled for the EERADY interrupt to work.

Parameters:
None.
Returns:

None.

EEPROM_Write()

void EEPROM_Write (eeprom_address_t address, eeprom_data_t data)

Writes one byte to the given EEPROM address. The EEPROM Busy status must be checked using the EEPROM_IsBusy() API to know if the write operation is completed.

Use the NVM_StatusGet() API to see the result of the write operation.
Parameters:
in address

- Address of the EEPROM location to be written.

in data

- Byte to be written to the given EEPROM location.

Returns:

None.

FLASH_IsBusy()

bool FLASH_IsBusy (void )

Checks if the Flash is busy.

Precondition:

NVM must be initialized with NVM_Initialize() before calling this API.

Parameters:
None.
Return values:
True

- The Flash operation is being performed.

False

- The Flash operation is not being performed.

FLASH_PageAddressGet()

flash_address_t FLASH_PageAddressGet (flash_address_t address)

Returns the starting address of the page (the first byte location) containing the given Flash address.

Parameters:
in address

- Flash address for which the page starting address will be obtained.

Returns:

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 containing the given address.

Precondition:

NVM must be initialized with NVM_Initialize() before calling this API.

Parameters:
in address

- Starting address of the Flash page to be erased.

Returns:

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 (the first byte location).

Parameters:
in address

- Flash address for which the offset from the starting address of the page will be obtained.

Returns:

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

Precondition:

NVM must be initialized with NVM_Initialize() before calling this API.

Parameters:
in address

- Address of the Flash location from which data is to be read.

Returns:

Byte 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/page 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.

Precondition:

Erase Flash row before calling this function.

Parameters:
in address

- Starting address of the Flash row to be written.

in *dataBuffer

- Pointer to a buffer which holds the data to be written.

Returns:

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.

Precondition:

NVM must be initialized with NVM_Initialize() before calling this API. Erase the Flash location before writing.

Parameters:
in address

- Address of the Flash location at which data is to be written.

in data

- Word to be written.

Returns:

Status of the Flash write operation as described in nvm_status_t.

FUSE_Read()

fuse_data_t FUSE_Read (fuse_address_t address)

Reads a fuse.

Parameters:
in address

- Fuse address to be read.

Returns:

Fuse data.

NVM_Initialize()

void NVM_Initialize (void )

Initializes the NVM driver.

Parameters:
None.
Returns:

None.

NVM_StatusClear()

void NVM_StatusClear (void )

Clears the NVM error status.

Parameters:
None.
Returns:

None.

NVM_StatusGet()

nvm_status_t NVM_StatusGet (void )

Returns the status of the last NVM operation.

Parameters:
None.
Return values:
NVM_OK

- The NVM operation succeeded.

NVM_ERROR

- The NVM operation failed.

SIGROW_DeviceIDRead()

device_id_data_t SIGROW_DeviceIDRead (sigrow_address_t address)

Reads the Device ID.

Parameters:
in address

- Starting address of the Device ID.

Returns:

Device ID.

SIGROW_Read()

sigrow_data_t SIGROW_Read (sigrow_address_t address)

Reads one Signature Row byte.

Parameters:
in address

- Address of the Signature Row byte to be read.

Returns:

Signature Row data.

SIGROW_SerialNumberRead()

void SIGROW_SerialNumberRead (sigrow_address_t address, sigrow_data_t * serialNumber)

Reads the serial number. The size of the buffer must be equal to the size of the serial number.

Parameters:
in address

- Starting address of the serial number.

out *serialNumber

- Buffer to hold the serial number.

Returns:

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

Flash Examples

This example shows how to overwrite an entire Flash page with the new data using the row write feature:
#include "mcc_generated_files/system/system.h"

#define FLASH_ADDRESS (PROGMEM_END - 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];
    bool readError = false;

    //Get the starting address of the page containing the given address
    flashStartPageAddress = FLASH_PageAddressGet(FLASH_ADDRESS);

    //Erase the entire page
    if (FLASH_PageErase(flashStartPageAddress) == NVM_OK)
    {
        printf("FLASH_PageErase passed \r\n");
    }
    else
    {
        printf("FLASH_PageErase failed \r\n");
        NVM_StatusClear();
    }

    //Prepare the row data
    for (index = 0; index < PROGMEM_PAGE_SIZE; index++)
    {
        flashWriteData[index] = (flash_data_t) index;
    }

    //Write data to the Flash row
    if (FLASH_RowWrite(flashStartPageAddress, flashWriteData) == NVM_OK)
    {
        printf("FLASH_RowWrite passed \r\n");
    }
    else
    {
        printf("FLASH_RowWrite failed \r\n");
        NVM_StatusClear();
    }

    //Read and verify the 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:
#include "mcc_generated_files/system/system.h"

#define FLASH_ADDRESS (PROGMEM_END - 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 the entire page
    errorStatus = FLASH_PageErase(flashStartPageAddress);
    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
    errorStatus = FLASH_Write(flashStartPageAddress, 0xAAAA);
    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 without disturbing the other locations:
#include "mcc_generated_files/system/system.h"

#define FLASH_ADDRESS (PROGMEM_END - 5)  //Flash address at which data is to be written

void FLASH_Example_UpdateSelectiveLocations(void)
{
    flash_address_t flashStartPageAddress;
    uint16_t flashAddressOffset;
    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);

    //Read entire row
    for (flashAddressOffset = 0; flashAddressOffset < PROGMEM_PAGE_SIZE; flashAddressOffset++)
    {
        flashWriteData[flashAddressOffset] = FLASH_Read(flashStartPageAddress + flashAddressOffset);
    }

    //Get offset from the starting address of the page
    flashAddressOffset = FLASH_PageOffsetGet(FLASH_ADDRESS);

    //Update 4 bytes
    flashWriteData[flashAddressOffset] = 0xA0;
    flashWriteData[flashAddressOffset + 1] = 0xA1;
    flashWriteData[flashAddressOffset + 2] = 0xA2;
    flashWriteData[flashAddressOffset + 3] = 0xA3;

    //Erase the entire Flash page
    if (FLASH_PageErase(flashStartPageAddress) == NVM_OK)
    {
        printf("FLASH_PageErase passed \r\n");
    }
    else
    {
        printf("FLASH_PageErase failed \r\n");
        NVM_StatusClear();
    }

    //Write data to the Flash row
    errorStatus = FLASH_RowWrite(flashStartPageAddress, flashWriteData);
    if (errorStatus == NVM_OK)
    {
        printf("FLASH_RowWrite passed \r\n");
    }
    else
    {
        printf("FLASH_RowWrite failed \r\n");
        NVM_StatusClear();
    }

    //Read and verify the row data
    for (flashAddressOffset = 0; flashAddressOffset < PROGMEM_PAGE_SIZE; flashAddressOffset++)
    {
        //Verify
        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)  //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 the data
    for (count = 0; count < 8; count++)
    {
        eepromWriteData[count] = 0xA1 + count;
    }

    for (count = 0; count < 8; count++)
    {
        //Write EEPROM byte
        EEPROM_Write(EEPROM_ADDRESS + count, eepromWriteData[count]);
        while (EEPROM_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");
    }
}

SIGROW Examples

This example shows how to read the Signature Row:
#include "mcc_generated_files/system/system.h"

#define SIGROW_START_ADDRESS (0x1100U) //Compare with the device data sheet to see if the address is correctt
#define SIGROW_END_ADDRESS (0x111FU) //Compare with the device data sheet to see if the address is correct

void NVM_Example_Signature_Row_Read_All(void)
{
    sigrow_address_t address;
    
    for (address = SIGROW_START_ADDRESS; address <= SIGROW_END_ADDRESS; address++)
    {
        printf(" 0x%X \r\n", SIGROW_Read(address));
    }
}
This example shows how to read the Device ID:
#include "mcc_generated_files/system/system.h"

#define DEVICE_ID_ADDRESS (0x1100U) //Compare with the device data sheet to see if the address is correct

void NVM_Example_DeviceID_Read(void)
{
    printf("Device ID : 0x%lX \r\n", SIGROW_DeviceIDRead(DEVICE_ID_ADDRESS));
}
This example shows how to read the Serial Number:
#include "mcc_generated_files/system/system.h"

#define SERIAL_NUMBER_START_ADDRESS (0x1110U) //Compare with the device data sheet to see if the address is correct

void NVM_Example_Serial_Number_Read(void)
{
    sigrow_address_t address = SERIAL_NUMBER_START_ADDRESS;
    sigrow_data_t NVM_SerialNumberReadData[SERIAL_NUMBER_SIZE];
    uint8_t serialNumberIndex;
    
    SIGROW_SerialNumberRead(address, NVM_SerialNumberReadData);
      
    for (serialNumberIndex = 0; serialNumberIndex < SERIAL_NUMBER_SIZE; serialNumberIndex++)
    {
        printf("Serial Number %u : 0x%X \r\n", serialNumberIndex , NVM_SerialNumberReadData[serialNumberIndex]);
    }
}

Fuse Examples

This example shows how to read the Fuse:
#include "mcc_generated_files/system/system.h"

#define FUSE_START_ADDRESS (0x1050U) //Compare with the device data sheet to see if the address is correct
#define FUSE_END_ADDRESS (0x1058U) //Compare with the device data sheet to see if the address is correct

void NVM_Example_Fuse_Read_All(void)
{
    fuse_address_t address;
    
    for (address = FUSE_START_ADDRESS; address <= FUSE_END_ADDRESS; address++)
    {
        printf("0x%X \r\n", FUSE_Read(address));
    }
}

3.10.1.6 File Documentation

3.10.1.6.1 source/nvm_examples.dox File Reference

3.10.1.6.2 source/nvm_interrupt.c File Reference

#include <avr/pgmspace.h>
#include "../../system/ccp.h"
#include "../nvm.h"

Functions

Function Documentation

FLASH_SpmWriteWord()

static void FLASH_SpmWriteWord (flash_address_t address, uint16_t data)[static]

ISR()

ISR (NVMCTRL_EE_vect )

Variable Documentation

EEPROM_Callback

void(* EEPROM_Callback) (void) = NULL[static]

3.10.1.6.3 source/nvm_interrupt.h File Reference

#include "../system/utils/compiler.h"

Functions

Typedefs

3.10.1.6.4 source/nvm_polling.c File Reference

#include <avr/pgmspace.h>
#include "../../system/ccp.h"
#include "../nvm.h"

Functions

Function Documentation

FLASH_SpmWriteWord()

static void FLASH_SpmWriteWord (flash_address_t address, uint16_t data)[static]

3.10.1.6.5 source/nvm_polling.h File Reference

#include "../system/utils/compiler.h"

Functions

Typedefs

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.