Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
SAM Non-Volatile Memory (NVM) Driver

This driver for Atmel® | SMART ARM®-based microcontrollers provides an interface for the configuration and management of non-volatile memories within the device, for partitioning, erasing, reading, and writing of data.

The following peripheral is used by this module:

The following devices can use this module:

The outline of this documentation is as follows:

Prerequisites

There are no prerequisites for this module.

Module Overview

The Non-Volatile Memory (NVM) module provides an interface to the device's Non-Volatile Memory controller, so that memory pages can be written, read, erased, and reconfigured in a standardized manner.

Driver Feature Macro Definition

Driver feature macro Supported devices
FEATURE_NVM_RWWEE SAM L21/L22, SAM D21-64K, SAM DA1, SAM C20/C21, SAM R30 , SAM R34/R35
FEATURE_BOD12 SAM L21, SAMR30/R34
Note
The specific features are only available in the driver when the selected device supports those features.

Memory Regions

The NVM memory space of the SAM devices is divided into two sections: a Main Array section, and an Auxiliary space section. The Main Array space can be configured to have an (emulated) EEPROM and/or boot loader section. The memory layout with the EEPROM and bootloader partitions is shown in the figure below.

The Main Array is divided into rows and pages, where each row contains four pages. The size of each page may vary from 8-1024 bytes dependent of the device. Device specific parameters such as the page size and total number of pages in the NVM memory space are available via the nvm_get_parameters() function.

An NVM page number and address can be computed via the following equations:

\[ PageNum = (RowNum \times 4) + PagePosInRow \]

\[ PageAddr = PageNum \times PageSize \]

The figure below shows an example of the memory page and address values associated with logical row 7 of the NVM memory space.

Region Lock Bits

As mentioned in Memory Regions, the main block of the NVM memory is divided into a number of individually addressable pages. These pages are grouped into 16 equal sized regions, where each region can be locked separately issuing an NVM_COMMAND_LOCK_REGION command or by writing the LOCK bits in the User Row. Rows reserved for the EEPROM section are not affected by the lock bits or commands.

Note
By using the NVM_COMMAND_LOCK_REGION or NVM_COMMAND_UNLOCK_REGION commands the settings will remain in effect until the next device reset. By changing the default lock setting for the regions, the auxiliary space must to be written, however the adjusted configuration will not take effect until the next device reset.
If the Security Bit is set, the auxiliary space cannot be written to. Clearing of the security bit can only be performed by a full chip erase.

Read/Write

Reading from the NVM memory can be performed using direct addressing into the NVM memory space, or by calling the nvm_read_buffer() function.

Writing to the NVM memory must be performed by the nvm_write_buffer() function - additionally, a manual page program command must be issued if the NVM controller is configured in manual page writing mode.

Before a page can be updated, the associated NVM memory row must be erased first via the nvm_erase_row() function. Writing to a non-erased page will result in corrupt data being stored in the NVM memory space.

Special Considerations

Page Erasure

The granularity of an erase is per row, while the granularity of a write is per page. Thus, if the user application is modifying only one page of a row, the remaining pages in the row must be buffered and the row erased, as an erase is mandatory before writing to a page.

Clocks

The user must ensure that the driver is configured with a proper number of wait states when the CPU is running at high frequencies.

Security Bit

The User Row in the Auxiliary Space cannot be read or written when the Security Bit is set. The Security Bit can be set by using passing NVM_COMMAND_SET_SECURITY_BIT to the nvm_execute_command() function, or it will be set if one tries to access a locked region. See Region Lock Bits.

The Security Bit can only be cleared by performing a chip erase.

Extra Information

For extra information, see Extra Information for NVM Driver. This includes:

Examples

For a list of examples related to this driver, see Examples for NVM Driver.

API Overview

Data Structures

struct  nvm_config
 NVM controller configuration structure. More...
 
struct  nvm_fusebits
 NVM user row fuse setting structure. More...
 
struct  nvm_parameters
 NVM memory parameter structure. More...
 

Enumerations

enum  nvm_bod33_action {
  NVM_BOD33_ACTION_NONE,
  NVM_BOD33_ACTION_RESET,
  NVM_BOD33_ACTION_INTERRUPT
}
 BOD33 Action. More...
 
enum  nvm_bootloader_size {
  NVM_BOOTLOADER_SIZE_128,
  NVM_BOOTLOADER_SIZE_64,
  NVM_BOOTLOADER_SIZE_32,
  NVM_BOOTLOADER_SIZE_16,
  NVM_BOOTLOADER_SIZE_8,
  NVM_BOOTLOADER_SIZE_4,
  NVM_BOOTLOADER_SIZE_2,
  NVM_BOOTLOADER_SIZE_0
}
 Bootloader size. More...
 
enum  nvm_cache_readmode {
  NVM_CACHE_READMODE_NO_MISS_PENALTY,
  NVM_CACHE_READMODE_LOW_POWER,
  NVM_CACHE_READMODE_DETERMINISTIC
}
 NVM controller cache readmode configuration. More...
 
enum  nvm_command {
  NVM_COMMAND_ERASE_ROW = NVMCTRL_CTRLA_CMD_ER,
  NVM_COMMAND_WRITE_PAGE = NVMCTRL_CTRLA_CMD_WP,
  NVM_COMMAND_ERASE_AUX_ROW = NVMCTRL_CTRLA_CMD_EAR,
  NVM_COMMAND_WRITE_AUX_ROW = NVMCTRL_CTRLA_CMD_WAP,
  NVM_COMMAND_LOCK_REGION = NVMCTRL_CTRLA_CMD_LR,
  NVM_COMMAND_UNLOCK_REGION = NVMCTRL_CTRLA_CMD_UR,
  NVM_COMMAND_PAGE_BUFFER_CLEAR = NVMCTRL_CTRLA_CMD_PBC,
  NVM_COMMAND_SET_SECURITY_BIT = NVMCTRL_CTRLA_CMD_SSB,
  NVM_COMMAND_ENTER_LOW_POWER_MODE = NVMCTRL_CTRLA_CMD_SPRM,
  NVM_COMMAND_EXIT_LOW_POWER_MODE = NVMCTRL_CTRLA_CMD_CPRM
}
 NVM controller commands. More...
 
enum  nvm_eeprom_emulator_size {
  NVM_EEPROM_EMULATOR_SIZE_16384,
  NVM_EEPROM_EMULATOR_SIZE_8192,
  NVM_EEPROM_EMULATOR_SIZE_4096,
  NVM_EEPROM_EMULATOR_SIZE_2048,
  NVM_EEPROM_EMULATOR_SIZE_1024,
  NVM_EEPROM_EMULATOR_SIZE_512,
  NVM_EEPROM_EMULATOR_SIZE_256,
  NVM_EEPROM_EMULATOR_SIZE_0
}
 EEPROM emulator size. More...
 
enum  nvm_error {
  NVM_ERROR_NONE = 0,
  NVM_ERROR_LOCK = NVMCTRL_STATUS_NVME | NVMCTRL_STATUS_LOCKE,
  NVM_ERROR_PROG = NVMCTRL_STATUS_NVME | NVMCTRL_STATUS_PROGE
}
 NVM error flags. More...
 
enum  nvm_sleep_power_mode {
  NVM_SLEEP_POWER_MODE_WAKEONACCESS = NVMCTRL_CTRLB_SLEEPPRM_WAKEONACCESS_Val,
  NVM_SLEEP_POWER_MODE_WAKEUPINSTANT = NVMCTRL_CTRLB_SLEEPPRM_WAKEUPINSTANT_Val,
  NVM_SLEEP_POWER_MODE_ALWAYS_AWAKE = NVMCTRL_CTRLB_SLEEPPRM_DISABLED_Val
}
 NVM controller power reduction mode configurations. More...
 
enum  nvm_wdt_early_warning_offset {
  NVM_WDT_EARLY_WARNING_OFFSET_8,
  NVM_WDT_EARLY_WARNING_OFFSET_16,
  NVM_WDT_EARLY_WARNING_OFFSET_32,
  NVM_WDT_EARLY_WARNING_OFFSET_64,
  NVM_WDT_EARLY_WARNING_OFFSET_128,
  NVM_WDT_EARLY_WARNING_OFFSET_256,
  NVM_WDT_EARLY_WARNING_OFFSET_512,
  NVM_WDT_EARLY_WARNING_OFFSET_1024,
  NVM_WDT_EARLY_WARNING_OFFSET_2048,
  NVM_WDT_EARLY_WARNING_OFFSET_4096,
  NVM_WDT_EARLY_WARNING_OFFSET_8192,
  NVM_WDT_EARLY_WARNING_OFFSET_16384
}
 WDT Early warning offset. More...
 
enum  nvm_wdt_window_timeout {
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_8,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_16,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_32,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_64,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_128,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_256,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_512,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_1024,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_2048,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_4096,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_8192,
  NVM_WDT_WINDOW_TIMEOUT_PERIOD_16384
}
 WDT Window time-out period. More...
 

Configuration and Initialization

static void nvm_get_config_defaults (struct nvm_config *const config)
 Initializes an NVM controller configuration structure to defaults. More...
 
enum status_code nvm_set_config (const struct nvm_config *const config)
 Sets the up the NVM hardware module based on the configuration. More...
 
static bool nvm_is_ready (void)
 Checks if the NVM controller is ready to accept a new command. More...
 

NVM Access Management

void nvm_get_parameters (struct nvm_parameters *const parameters)
 Reads the parameters of the NVM controller. More...
 
enum status_code nvm_write_buffer (const uint32_t destination_address, const uint8_t *buffer, uint16_t length)
 Writes a number of bytes to a page in the NVM memory region. More...
 
enum status_code nvm_read_buffer (const uint32_t source_address, uint8_t *const buffer, uint16_t length)
 Reads a number of bytes from a page in the NVM memory region. More...
 
enum status_code nvm_update_buffer (const uint32_t destination_address, uint8_t *const buffer, uint16_t offset, uint16_t length)
 Updates an arbitrary section of a page with new data. More...
 
enum status_code nvm_erase_row (const uint32_t row_address)
 Erases a row in the NVM memory space. More...
 
enum status_code nvm_execute_command (const enum nvm_command command, const uint32_t address, const uint32_t parameter)
 Executes a command on the NVM controller. More...
 
enum status_code nvm_get_fuses (struct nvm_fusebits *fusebits)
 Get fuses from user row. More...
 
enum status_code nvm_set_fuses (struct nvm_fusebits *fb)
 Set fuses from user row. More...
 
bool nvm_is_page_locked (uint16_t page_number)
 Checks whether the page region is locked. More...
 
static enum nvm_error nvm_get_error (void)
 Retrieves the error code of the last issued NVM operation. More...
 

BOD33 Action.

What action should be triggered when BOD33 is detected.

Enumerator
NVM_BOD33_ACTION_NONE 

No action.

NVM_BOD33_ACTION_RESET 

The BOD33 generates a reset.

NVM_BOD33_ACTION_INTERRUPT 

The BOD33 generates an interrupt.

Bootloader size.

Available bootloader protection sizes in kilobytes.

Enumerator
NVM_BOOTLOADER_SIZE_128 

Boot Loader Size is 32768 bytes.

NVM_BOOTLOADER_SIZE_64 

Boot Loader Size is 16384 bytes.

NVM_BOOTLOADER_SIZE_32 

Boot Loader Size is 8192 bytes.

NVM_BOOTLOADER_SIZE_16 

Boot Loader Size is 4096 bytes.

NVM_BOOTLOADER_SIZE_8 

Boot Loader Size is 2048 bytes.

NVM_BOOTLOADER_SIZE_4 

Boot Loader Size is 1024 bytes.

NVM_BOOTLOADER_SIZE_2 

Boot Loader Size is 512 bytes.

NVM_BOOTLOADER_SIZE_0 

Boot Loader Size is 0 bytes.

NVM controller cache readmode configuration.

Control how the NVM cache prefetch data from flash.

Enumerator
NVM_CACHE_READMODE_NO_MISS_PENALTY 

The NVM Controller (cache system) does not insert wait states on a cache miss.

Gives the best system performance.

NVM_CACHE_READMODE_LOW_POWER 

Reduces power consumption of the cache system, but inserts a wait state each time there is a cache miss.

NVM_CACHE_READMODE_DETERMINISTIC 

The cache system ensures that a cache hit or miss takes the same amount of time, determined by the number of programmed flash wait states.

NVM controller commands.

Enumerator
NVM_COMMAND_ERASE_ROW 

Erases the addressed memory row.

NVM_COMMAND_WRITE_PAGE 

Write the contents of the page buffer to the addressed memory page.

NVM_COMMAND_ERASE_AUX_ROW 

Erases the addressed auxiliary memory row.

Note
This command can only be given when the security bit is not set.
NVM_COMMAND_WRITE_AUX_ROW 

Write the contents of the page buffer to the addressed auxiliary memory row.

Note
This command can only be given when the security bit is not set.
NVM_COMMAND_LOCK_REGION 

Locks the addressed memory region, preventing further modifications until the region is unlocked or the device is erased.

NVM_COMMAND_UNLOCK_REGION 

Unlocks the addressed memory region, allowing the region contents to be modified.

NVM_COMMAND_PAGE_BUFFER_CLEAR 

Clears the page buffer of the NVM controller, resetting the contents to all zero values.

NVM_COMMAND_SET_SECURITY_BIT 

Sets the device security bit, disallowing the changing of lock bits and auxiliary row data until a chip erase has been performed.

NVM_COMMAND_ENTER_LOW_POWER_MODE 

Enter power reduction mode in the NVM controller to reduce the power consumption of the system.

NVM_COMMAND_EXIT_LOW_POWER_MODE 

Exit power reduction mode in the NVM controller to allow other NVM commands to be issued.

EEPROM emulator size.

Available space in flash dedicated for EEPROM emulator in bytes.

Enumerator
NVM_EEPROM_EMULATOR_SIZE_16384 

EEPROM Size for EEPROM emulation is 16384 bytes.

NVM_EEPROM_EMULATOR_SIZE_8192 

EEPROM Size for EEPROM emulation is 8192 bytes.

NVM_EEPROM_EMULATOR_SIZE_4096 

EEPROM Size for EEPROM emulation is 4096 bytes.

NVM_EEPROM_EMULATOR_SIZE_2048 

EEPROM Size for EEPROM emulation is 2048 bytes.

NVM_EEPROM_EMULATOR_SIZE_1024 

EEPROM Size for EEPROM emulation is 1024 bytes.

NVM_EEPROM_EMULATOR_SIZE_512 

EEPROM Size for EEPROM emulation is 512 bytes.

NVM_EEPROM_EMULATOR_SIZE_256 

EEPROM Size for EEPROM emulation is 256 bytes.

NVM_EEPROM_EMULATOR_SIZE_0 

EEPROM Size for EEPROM emulation is 0 bytes.

enum nvm_error

NVM error flags.

Possible NVM controller error codes, which can be returned by the NVM controller after a command is issued.

Enumerator
NVM_ERROR_NONE 

No errors.

NVM_ERROR_LOCK 

Lock error, a locked region was attempted accessed.

NVM_ERROR_PROG 

Program error, invalid command was executed.

NVM controller power reduction mode configurations.

Power reduction modes of the NVM controller, to conserve power while the device is in sleep.

Enumerator
NVM_SLEEP_POWER_MODE_WAKEONACCESS 

NVM controller exits low-power mode on first access after sleep.

NVM_SLEEP_POWER_MODE_WAKEUPINSTANT 

NVM controller exits low-power mode when the device exits sleep mode.

NVM_SLEEP_POWER_MODE_ALWAYS_AWAKE 

Power reduction mode in the NVM controller disabled.

WDT Early warning offset.

This setting determine how many GCLK_WDT cycles before a watchdog time-out period an early warning interrupt should be triggered.

Enumerator
NVM_WDT_EARLY_WARNING_OFFSET_8 

8 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_16 

16 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_32 

32 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_64 

64 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_128 

128 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_256 

256 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_512 

512 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_1024 

1024 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_2048 

2048 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_4096 

4096 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_8192 

8192 clock cycles

NVM_WDT_EARLY_WARNING_OFFSET_16384 

16384 clock cycles

WDT Window time-out period.

Window mode time-out period in clock cycles.

Enumerator
NVM_WDT_WINDOW_TIMEOUT_PERIOD_8 

8 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_16 

16 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_32 

32 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_64 

64 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_128 

128 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_256 

256 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_512 

512 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_1024 

1024 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_2048 

2048 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_4096 

4096 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_8192 

8192 clock cycles

NVM_WDT_WINDOW_TIMEOUT_PERIOD_16384 

16384 clock cycles

enum status_code nvm_erase_row ( const uint32_t  row_address)

Erases a row in the NVM memory space.

Erases a given row in the NVM memory region.

Parameters
[in]row_addressAddress of the row to erase
Returns
Status of the NVM row erase attempt.
Return values
STATUS_OKRequested NVM memory row was successfully erased
STATUS_BUSYNVM controller was busy when the operation was attempted
STATUS_ERR_BAD_ADDRESSThe requested row address was outside the acceptable range of the NVM memory region or not aligned to the start of a row
STATUS_ABORTEDNVM erased error

References _nvm_dev, _nvm_module::number_of_pages, NVM_COMMAND_ERASE_ROW, NVM_ERROR_NONE, nvm_is_ready(), NVM_MEMORY, _nvm_module::page_size, STATUS_ABORTED, STATUS_BUSY, STATUS_ERR_BAD_ADDRESS, and STATUS_OK.

Referenced by _eeprom_emulator_nvm_erase_row(), _rww_eeprom_emulator_nvm_erase_row(), and nvm_update_buffer().

enum status_code nvm_execute_command ( const enum nvm_command  command,
const uint32_t  address,
const uint32_t  parameter 
)

Executes a command on the NVM controller.

Executes an asynchronous command on the NVM controller, to perform a requested action such as an NVM page read or write operation.

Note
The function will return before the execution of the given command is completed.
Parameters
[in]commandCommand to issue to the NVM controller
[in]addressAddress to pass to the NVM controller in NVM memory space
[in]parameterParameter to pass to the NVM controller, not used for this driver
Returns
Status of the attempt to execute a command.
Return values
STATUS_OKIf the command was accepted and execution is now in progress
STATUS_BUSYIf the NVM controller was already busy executing a command when the new command was issued
STATUS_ERR_IOIf the command was invalid due to memory or security locking
STATUS_ERR_INVALID_ARGIf the given command was invalid or unsupported
STATUS_ERR_BAD_ADDRESSIf the given address was invalid

References _nvm_dev, _nvm_module::number_of_pages, NVM_COMMAND_ENTER_LOW_POWER_MODE, NVM_COMMAND_ERASE_AUX_ROW, NVM_COMMAND_ERASE_ROW, NVM_COMMAND_EXIT_LOW_POWER_MODE, NVM_COMMAND_LOCK_REGION, NVM_COMMAND_PAGE_BUFFER_CLEAR, NVM_COMMAND_SET_SECURITY_BIT, NVM_COMMAND_UNLOCK_REGION, NVM_COMMAND_WRITE_AUX_ROW, NVM_COMMAND_WRITE_PAGE, nvm_is_ready(), NVM_MEMORY, _nvm_module::page_size, STATUS_BUSY, STATUS_ERR_BAD_ADDRESS, STATUS_ERR_INVALID_ARG, STATUS_ERR_IO, and STATUS_OK.

Referenced by _eeprom_emulator_nvm_commit_cache(), _rww_eeprom_emulator_nvm_commit_cache(), nvm_set_fuses(), and nvm_write_buffer().

static void nvm_get_config_defaults ( struct nvm_config *const  config)
inlinestatic

Initializes an NVM controller configuration structure to defaults.

Initializes a given NVM controller configuration structure to a set of known default values. This function should be called on all new instances of these configuration structures before being modified by the user application.

The default configuration is as follows:

  • Power reduction mode enabled after sleep mode until first NVM access
  • Automatic page write mode disabled
  • Number of FLASH wait states left unchanged
Parameters
[out]configConfiguration structure to initialize to default values

References Assert, nvm_config::cache_readmode, nvm_config::disable_cache, nvm_config::manual_page_write, NVM_CACHE_READMODE_NO_MISS_PENALTY, NVM_SLEEP_POWER_MODE_WAKEONACCESS, nvm_config::sleep_power_mode, and nvm_config::wait_states.

Referenced by eeprom_emulator_init(), and rww_eeprom_emulator_init().

static enum nvm_error nvm_get_error ( void  )
inlinestatic

Retrieves the error code of the last issued NVM operation.

Retrieves the error code from the last executed NVM operation. Once retrieved, any error state flags in the controller are cleared.

Note
The nvm_is_ready() function is an exception. Thus, errors retrieved after running this function should be valid for the function executed before nvm_is_ready().
Returns
Error caused by the last NVM operation.
Return values
NVM_ERROR_NONENo error occurred in the last NVM operation
NVM_ERROR_LOCKThe last NVM operation attempted to access a locked region
NVM_ERROR_PROGAn invalid NVM command was issued
enum status_code nvm_get_fuses ( struct nvm_fusebits fusebits)

Get fuses from user row.

Read out the fuse settings from the user row.

Parameters
[in]fusebitsPointer to a 64-bit wide memory buffer of type struct nvm_fusebits
Returns
Status of read fuses attempt.
Return values
STATUS_OKThis function will always return STATUS_OK

References nvm_is_ready(), NVM_MEMORY, and STATUS_OK.

void nvm_get_parameters ( struct nvm_parameters *const  parameters)

Reads the parameters of the NVM controller.

Retrieves the page size, number of pages, and other configuration settings of the NVM region.

Parameters
[out]parametersParameter structure, which holds page size and number of pages in the NVM memory

References Assert, nvm_parameters::bootloader_number_of_pages, nvm_parameters::eeprom_number_of_pages, nvm_parameters::nvm_number_of_pages, NVM_USER_MEMORY, and nvm_parameters::page_size.

Referenced by eeprom_emulator_init(), and rww_eeprom_emulator_init().

bool nvm_is_page_locked ( uint16_t  page_number)

Checks whether the page region is locked.

Extracts the region to which the given page belongs and checks whether that region is locked.

Parameters
[in]page_numberPage number to be checked
Returns
Page lock status.
Return values
truePage is locked
falsePage is not locked

References _nvm_dev, Assert, and _nvm_module::number_of_pages.

static bool nvm_is_ready ( void  )
inlinestatic

Checks if the NVM controller is ready to accept a new command.

Checks the NVM controller to determine if it is currently busy execution an operation, or ready for a new command.

Returns
Busy state of the NVM controller.
Return values
trueIf the hardware module is ready for a new command
falseIf the hardware module is busy executing a command

Referenced by nvm_erase_row(), nvm_execute_command(), nvm_get_fuses(), nvm_read_buffer(), nvm_set_config(), and nvm_write_buffer().

enum status_code nvm_read_buffer ( const uint32_t  source_address,
uint8_t *const  buffer,
uint16_t  length 
)

Reads a number of bytes from a page in the NVM memory region.

Reads a given number of bytes from a given page address in the NVM memory space into a buffer.

Parameters
[in]source_addressSource page address to read from
[out]bufferPointer to a buffer where the content of the read page will be stored
[in]lengthNumber of bytes in the page to read
Returns
Status of the page read attempt.
Return values
STATUS_OKRequested NVM memory page was successfully read
STATUS_BUSYNVM controller was busy when the operation was attempted
STATUS_ERR_BAD_ADDRESSThe requested address was outside the acceptable range of the NVM memory region or not aligned to the start of a page
STATUS_ERR_INVALID_ARGThe supplied read length was invalid

References _nvm_dev, _nvm_module::number_of_pages, nvm_is_ready(), NVM_MEMORY, _nvm_module::page_size, STATUS_BUSY, STATUS_ERR_BAD_ADDRESS, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by _eeprom_emulator_nvm_read_page(), _rww_eeprom_emulator_nvm_read_page(), and nvm_update_buffer().

enum status_code nvm_set_config ( const struct nvm_config *const  config)

Sets the up the NVM hardware module based on the configuration.

Writes a given configuration of an NVM controller configuration to the hardware module, and initializes the internal device struct.

Parameters
[in]configConfiguration settings for the NVM controller
Note
The security bit must be cleared in order successfully use this function. This can only be done by a chip erase.
Returns
Status of the configuration procedure.
Return values
STATUS_OKIf the initialization was a success
STATUS_BUSYIf the module was busy when the operation was attempted
STATUS_ERR_IOIf the security bit has been set, preventing the EEPROM and/or auxiliary space configuration from being altered

References _nvm_dev, Assert, nvm_config::cache_readmode, nvm_config::disable_cache, _nvm_module::manual_page_write, nvm_config::manual_page_write, _nvm_module::number_of_pages, nvm_is_ready(), _nvm_module::page_size, nvm_config::sleep_power_mode, STATUS_BUSY, STATUS_ERR_IO, STATUS_OK, system_apb_clock_set_mask(), SYSTEM_CLOCK_APB_APBB, and nvm_config::wait_states.

Referenced by eeprom_emulator_init(), and rww_eeprom_emulator_init().

enum status_code nvm_set_fuses ( struct nvm_fusebits fb)

Set fuses from user row.

Set fuse settings from the user row.

Note
When writing to the user row, the values do not get loaded by the other modules on the device until a device reset occurs.
Parameters
[in]fusebitsPointer to a 64-bit wide memory buffer of type struct nvm_fusebits
Returns
Status of read fuses attempt.
Return values
STATUS_OKThis function will always return STATUS_OK
STATUS_BUSYIf the NVM controller was already busy executing a command when the new command was issued
STATUS_ERR_IOIf the command was invalid due to memory or security locking
STATUS_ERR_INVALID_ARGIf the given command was invalid or unsupported
STATUS_ERR_BAD_ADDRESSIf the given address was invalid

References nvm_fusebits::bod33_action, nvm_fusebits::bod33_enable, nvm_fusebits::bod33_hysteresis, nvm_fusebits::bod33_level, nvm_fusebits::bootloader_size, nvm_fusebits::eeprom_size, nvm_fusebits::lockbits, NVM_COMMAND_ERASE_AUX_ROW, NVM_COMMAND_PAGE_BUFFER_CLEAR, NVM_COMMAND_WRITE_AUX_ROW, nvm_execute_command(), STATUS_ERR_INVALID_ARG, STATUS_OK, nvm_fusebits::wdt_always_on, nvm_fusebits::wdt_early_warning_offset, nvm_fusebits::wdt_enable, nvm_fusebits::wdt_timeout_period, nvm_fusebits::wdt_window_mode_enable_at_poweron, and nvm_fusebits::wdt_window_timeout.

enum status_code nvm_update_buffer ( const uint32_t  destination_address,
uint8_t *const  buffer,
uint16_t  offset,
uint16_t  length 
)

Updates an arbitrary section of a page with new data.

Writes from a buffer to a given page in the NVM memory, retaining any unmodified data already stored in the page.

Note
If manual write mode is enable, the write command must be executed after this function, otherwise the data will not write to NVM from page buffer.
Warning
This routine is unsafe if data integrity is critical; a system reset during the update process will result in up to one row of data being lost. If corruption must be avoided in all circumstances (including power loss or system reset) this function should not be used.
Parameters
[in]destination_addressDestination page address to write to
[in]bufferPointer to buffer where the data to write is stored
[in]offsetNumber of bytes to offset the data write in the page
[in]lengthNumber of bytes in the page to update
Returns
Status of the attempt to update a page.
Return values
STATUS_OKRequested NVM memory page was successfully read
STATUS_BUSYNVM controller was busy when the operation was attempted
STATUS_ERR_BAD_ADDRESSThe requested address was outside the acceptable range of the NVM memory region
STATUS_ERR_INVALID_ARGThe supplied length and offset was invalid

References _nvm_dev, nvm_erase_row(), nvm_read_buffer(), nvm_write_buffer(), _nvm_module::page_size, STATUS_BUSY, STATUS_ERR_INVALID_ARG, STATUS_OK, system_interrupt_enter_critical_section(), and system_interrupt_leave_critical_section().

enum status_code nvm_write_buffer ( const uint32_t  destination_address,
const uint8_t *  buffer,
uint16_t  length 
)

Writes a number of bytes to a page in the NVM memory region.

Writes from a buffer to a given page address in the NVM memory.

Parameters
[in]destination_addressDestination page address to write to
[in]bufferPointer to buffer where the data to write is stored
[in]lengthNumber of bytes in the page to write
Note
If writing to a page that has previously been written to, the page's row should be erased (via nvm_erase_row()) before attempting to write new data to the page.
For SAM D21 RWW devices, see SAMD21_64K, command NVM_COMMAND_RWWEE_WRITE_PAGE must be executed before any other commands after writing a page, refer to errata 13588.
If manual write mode is enabled, the write command must be executed after this function, otherwise the data will not write to NVM from page buffer.
Returns
Status of the attempt to write a page.
Return values
STATUS_OKRequested NVM memory page was successfully read
STATUS_BUSYNVM controller was busy when the operation was attempted
STATUS_ERR_BAD_ADDRESSThe requested address was outside the acceptable range of the NVM memory region or not aligned to the start of a page
STATUS_ERR_INVALID_ARGThe supplied write length was invalid

References _nvm_dev, _nvm_module::manual_page_write, _nvm_module::number_of_pages, NVM_COMMAND_PAGE_BUFFER_CLEAR, NVM_COMMAND_WRITE_PAGE, nvm_execute_command(), nvm_is_ready(), NVM_MEMORY, _nvm_module::page_size, STATUS_BUSY, STATUS_ERR_BAD_ADDRESS, STATUS_ERR_INVALID_ARG, and STATUS_OK.

Referenced by _eeprom_emulator_nvm_fill_cache(), _rww_eeprom_emulator_nvm_fill_cache(), and nvm_update_buffer().