PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Data Structures | Enumerations | Functions
NVM (Onboard Non-Volatile Memory)
HAL API Reference » HAL Drivers

## General Description

High level interface to the onboard Non-Volatile memory (Internal Flash, RRAM, OTP region).

Onboard NVM provides non-volatile storage for factory settings, secure data, user firmware, configuration, and bulk data.

This driver allows data to be read from and written to NVM. It also provides the ability to obtain information about the address and characteristics of the NVM block(s) contained on the device. During NVM write time, the device should not be reset (including XRES pin, software reset, and watchdog) or unexpected changes may be made to portions of the NVM. Also, the low-voltage detect circuits should be configured to generate an interrupt instead of a reset.

Note
  A Read while Write violation may occur for some devices when a NVM Read operation is initiated in the same or neighboring NVM sector/region where the NVM Write, Erase(if applicable), or Program operation is working. Refer the device datasheet for more information. This violation may cause a HardFault exception. To avoid the Read while Write violation, the user must carefully split the Read and Write operations on NVM sectors/regions which are not neighboring, considering all cores in a multi-processor device. User may edit the linker script to place the code into neighboring sectors/regions. For example, use sectors number 0 and 1 for code and sectors 2 and 3 for data storage.

# Features

- NVM operations are performed on a per-block (program) or per-sector (erase if applicable) basis (Refer the device datasheet for more information on the block size)
- Supports Blocking or Non-Blocking erase(if applicable), program, and write

# Code Snippets

## Snippet 1: Get NVM Characteristics

Following code snippet demonstrates how to fetch NVM characteristics. Refer mtb_hal_nvm_info_t for more information.

mtb_hal_nvm_t nvm_obj;
mtb_hal_nvm_info_t nvm_info;
mtb_hal_nvm_type_t nvm_type = MTB_HAL_NVM_TYPE_FLASH;
uint32_t nvm_start_address = 0;
uint32_t nvm_size = 0;
uint32_t nvm_sector_size = 0;
uint32_t nvm_block_size = 0;
uint8_t nvm_erase_value = 0;
bool is_erase_required = false;
mtb_hal_nvm_setup(&nvm_obj, NULL);
// Get NVM characteristics like NVM type, number of NVM regions and their organization
mtb_hal_nvm_get_info(&nvm_obj, &nvm_info);
for (int index = 0; index < nvm_info.region_count; index++)
{
const mtb_hal_nvm_region_info_t* region_info = nvm_info.regions;
region_info += index;
nvm_type = region_info->nvm_type;
nvm_start_address = region_info->start_address;
nvm_size = region_info->size;
nvm_sector_size = region_info->sector_size;
nvm_block_size = region_info->block_size;
is_erase_required = region_info->is_erase_required;
nvm_erase_value = region_info->erase_value;
}
mtb_hal_nvm_t
NVM object.
Definition: mtb_hal_hw_types_nvm.h:67
mtb_hal_nvm_info_t::regions
const mtb_hal_nvm_region_info_t * regions
Array of the distinct NVM regions.
Definition: mtb_hal_nvm.h:139
mtb_hal_nvm_region_info_t::sector_size
uint32_t sector_size
Sector size of the distinct NVM region.
Definition: mtb_hal_nvm.h:127
mtb_hal_nvm_info_t::region_count
uint8_t region_count
The number of distinct NVM regions.
Definition: mtb_hal_nvm.h:138
mtb_hal_nvm_region_info_t::size
uint32_t size
Size of the distinct NVM region.
Definition: mtb_hal_nvm.h:126
mtb_hal_nvm_region_info_t::nvm_type
mtb_hal_nvm_type_t nvm_type
NVM type.
Definition: mtb_hal_nvm.h:122
mtb_hal_nvm_region_info_t::is_erase_required
bool is_erase_required
true = erase required before program, false = erase not required before program.
Definition: mtb_hal_nvm.h:130
mtb_hal_nvm_region_info_t::block_size
uint32_t block_size
Block size (programming granularity) of the distinct NVM region.
Definition: mtb_hal_nvm.h:128
mtb_hal_nvm_region_info_t::erase_value
uint8_t erase_value
NVM erase value (if applicable).
Definition: mtb_hal_nvm.h:132
mtb_hal_nvm_region_info_t::start_address
uint32_t start_address
Base address of the distinct NVM region.
Definition: mtb_hal_nvm.h:123
mtb_hal_nvm_type_t
mtb_hal_nvm_type_t
Enum of Non-volatile memory (NVM) types.
Definition: mtb_hal_nvm.h:112
mtb_hal_nvm_get_info
void mtb_hal_nvm_get_info(mtb_hal_nvm_t *obj, mtb_hal_nvm_info_t *info)
Get details about the NVM memory regions such as NVM type, start address, size, is_erase_required,...
Definition: mtb_hal_nvm.c:46
MTB_HAL_NVM_TYPE_FLASH
@ MTB_HAL_NVM_TYPE_FLASH
Internal Flash.
Definition: mtb_hal_nvm.h:114
mtb_hal_nvm_info_t
Information about all of the regions of NVM memory.
Definition: mtb_hal_nvm.h:137
mtb_hal_nvm_region_info_t
Information about a single region of NVM memory.
Definition: mtb_hal_nvm.h:121

## Snippet 2: Blocking NVM Erase-Write and Read

Following code snippet demonstrates blocking NVM write. It uses a constant array with a size equaling the size of one NVM row/block. It uses blocking NVM write operation which blocks the caller until the write is completed. It then verifies the NVM data by comparing the NVM data with the written data.

mtb_hal_nvm_t nvm_obj;
mtb_hal_nvm_info_t nvm_info;
cy_rslt_t result = CY_RSLT_SUCCESS; // NVM Write Status
uint8_t ram_data[512]; // RAM data to be written to NVM
uint8_t nvm_read_data[512]; // RAM data read from NVM for validation
bool compare_status = false; // Compare Status
uint32_t nvm_addr;
mtb_hal_nvm_setup(&nvm_obj, NULL);
// Get NVM characteristics like number of NVM regions, type, and their organization
mtb_hal_nvm_get_info(&nvm_obj, &nvm_info);
// NVM region 0 last block
uint32_t block_num = (nvm_info.regions[0].size/nvm_info.regions[0].block_size) - 1;
// NVM region 0 last block address
nvm_addr = nvm_info.regions[0].start_address + (block_num * nvm_info.regions[0].block_size);
// Initialize the data in RAM that will be written into NVM
for (size_t index = 0; index < sizeof(ram_data); index++)
{
ram_data[index] = (uint8_t)index;
}
if (nvm_info.regions[0].is_erase_required) // Check if erase is required on the given NVM type
{
// Blocking NVM erase prior to NVM write
result = mtb_hal_nvm_erase(&nvm_obj, nvm_addr);
}
if (result == CY_RSLT_SUCCESS)
{
// Blocking NVM write
result = mtb_hal_nvm_program(&nvm_obj, nvm_addr, (const uint32_t*)ram_data);
if (result == CY_RSLT_SUCCESS)
{
// Read NVM data
result =
mtb_hal_nvm_read(&nvm_obj, (uint32_t)nvm_addr, nvm_read_data,
sizeof(nvm_read_data));
if (result == CY_RSLT_SUCCESS)
{
// Verify the data written into NVM by comparing it with the RAM data
if (0 == memcmp(ram_data, nvm_read_data, sizeof(nvm_read_data)))
{
compare_status = true;
}
}
}
}
else
{
// Error erasing NVM
}
mtb_hal_nvm_erase
cy_rslt_t mtb_hal_nvm_erase(mtb_hal_nvm_t *obj, uint32_t address)
Erase one block of NVM starting at the given address.
Definition: mtb_hal_nvm.c:118
mtb_hal_nvm_program
cy_rslt_t mtb_hal_nvm_program(mtb_hal_nvm_t *obj, uint32_t address, const uint32_t *data)
Program one block with the provided data starting at the given address.
Definition: mtb_hal_nvm.c:238
mtb_hal_nvm_read
cy_rslt_t mtb_hal_nvm_read(mtb_hal_nvm_t *obj, uint32_t address, uint8_t *data, size_t size)
Read size amount of data starting from the given address of NVM.
Definition: mtb_hal_nvm.c:60
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
CY_RSLT_SUCCESS
#define CY_RSLT_SUCCESS
cy_rslt_t return value indicating success
Definition: cy_result.h:486

## API Reference
| NVM HAL Results
| NVM specific return codes.

## Data Structures
struct | mtb_hal_nvm_region_info_t
| Information about a single region of NVM memory. More...
struct | mtb_hal_nvm_info_t
| Information about all of the regions of NVM memory. More...

## Enumerations
enum | mtb_hal_nvm_type_t { MTB_HAL_NVM_TYPE_INVALID = 0U , MTB_HAL_NVM_TYPE_FLASH = 1U , MTB_HAL_NVM_TYPE_RRAM = 2U , MTB_HAL_NVM_TYPE_OTP = 3U }
| Enum of Non-volatile memory (NVM) types. More...

## Functions
void | mtb_hal_nvm_get_info (mtb_hal_nvm_t *obj, mtb_hal_nvm_info_t *info)
| Get details about the NVM memory regions such as NVM type, start address, size, is_erase_required, and erase values etc. More...
cy_rslt_t | mtb_hal_nvm_read (mtb_hal_nvm_t *obj, uint32_t address, uint8_t *data, size_t size)
| Read size amount of data starting from the given address of NVM. More...
cy_rslt_t | mtb_hal_nvm_erase (mtb_hal_nvm_t *obj, uint32_t address)
| Erase one block of NVM starting at the given address. More...
cy_rslt_t | mtb_hal_nvm_write (mtb_hal_nvm_t *obj, uint32_t address, const uint32_t *data)
| This function erases the block, if required, and writes the new data into the block starting at the given address. More...
cy_rslt_t | mtb_hal_nvm_program (mtb_hal_nvm_t *obj, uint32_t address, const uint32_t *data)
| Program one block with the provided data starting at the given address. More...
const mtb_hal_nvm_region_info_t * | mtb_hal_nvm_get_region_for_address (mtb_hal_nvm_t *obj, uint32_t addr, uint32_t length)
| Find the nvm region based on given address and length. More...

## Data Structure Documentation

## ◆ mtb_hal_nvm_region_info_t

struct mtb_hal_nvm_region_info_t

Data Fields
mtb_hal_nvm_type_t | nvm_type | NVM type.
uint32_t | start_address | Base address of the distinct NVM region.
uint32_t | offset | Offset to the address in the distinct NVM region.
uint32_t | size | Size of the distinct NVM region.
uint32_t | sector_size | Sector size of the distinct NVM region.
uint32_t | block_size | Block size (programming granularity) of the distinct NVM region.
bool | is_erase_required | true = erase required before program, false = erase not required before program.
uint8_t | erase_value | NVM erase value (if applicable).

## ◆ mtb_hal_nvm_info_t

struct mtb_hal_nvm_info_t

Data Fields
uint8_t | region_count | The number of distinct NVM regions.
const mtb_hal_nvm_region_info_t * | regions | Array of the distinct NVM regions.

## Enumeration Type Documentation

## ◆ mtb_hal_nvm_type_t

enum mtb_hal_nvm_type_t

Enum of Non-volatile memory (NVM) types.

Enumerator
MTB_HAL_NVM_TYPE_INVALID | Invalid type of NVM.
MTB_HAL_NVM_TYPE_FLASH | Internal Flash.
MTB_HAL_NVM_TYPE_RRAM | RRAM.
MTB_HAL_NVM_TYPE_OTP | OTP.

## Function Documentation

## ◆ mtb_hal_nvm_get_info()

void mtb_hal_nvm_get_info | ( | mtb_hal_nvm_t * | obj,
|  | mtb_hal_nvm_info_t * | info
| ) |  |

Get details about the NVM memory regions such as NVM type, start address, size, is_erase_required, and erase values etc.

Refer mtb_hal_nvm_info_t, mtb_hal_nvm_region_info_t for more information.

Parameters

  [in] | obj | The NVM object.
  [out] | info | The NVM characteristic info.

Refer Snippet 1: Get NVM Characteristics for more information.

Get details about the NVM memory regions such as NVM type, start address, size, is_erase_required, and erase values etc.

Description: Provides a high level interface for interacting with the Infineon embedded non-volatile memory (NVM). This is wrapper around the lower level PDL API.

Copyright
  Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or an affiliate of Cypress Semiconductor Corporation

SPDX-License-Identifier: Apache-2.0

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

## ◆ mtb_hal_nvm_read()

cy_rslt_t mtb_hal_nvm_read | ( | mtb_hal_nvm_t * | obj,
|  | uint32_t | address,
|  | uint8_t * | data,
|  | size_t | size
| ) |  |

Read size amount of data starting from the given address of NVM.

Parameters

  [in] | obj | The NVM object.
  [in] | address | Address to begin reading from.
  [out] | data | The buffer to read data into.
  [in] | size | The number of bytes to read.

Returns
  The status of the read request. Returns CY_RSLT_SUCCESS on successful operation.

Refer Snippet 2: Blocking NVM Erase-Write and Read for more information.

## ◆ mtb_hal_nvm_erase()

cy_rslt_t mtb_hal_nvm_erase | ( | mtb_hal_nvm_t * | obj,
|  | uint32_t | address
| ) |  |

Erase one block of NVM starting at the given address.

The address must be at block boundary. This will block until the erase operation is complete.

See also
  mtb_hal_nvm_get_info() to get the NVM characteristics for legal address values, is erase required/applicable, and the erase block size(if applicable).

Parameters

  [in] | obj | The NVM object
  [in] | address | The block address to be erased

Returns
  The status of the erase request. Returns CY_RSLT_SUCCESS on successful operation.

Refer Snippet 2: Blocking NVM Erase-Write and Read for more information.

## ◆ mtb_hal_nvm_write()

cy_rslt_t mtb_hal_nvm_write | ( | mtb_hal_nvm_t * | obj,
|  | uint32_t | address,
|  | const uint32_t * | data
| ) |  |

This function erases the block, if required, and writes the new data into the block starting at the given address.

The address must be at block boundary. This will block until the write operation is complete.

See also
  mtb_hal_nvm_get_info() to get the NVM characteristics for legal address values and the write block size. The provided data buffer must be at least as large as the NVM block_size.

Note
  Generally the `data` to be written must be located in the SRAM memory region.

Parameters

  [in] | obj | The NVM object
  [in] | address | The address of the block to be written
  [in] | data | The data buffer to be written to the NVM block

Returns
  The status of the write request. Returns CY_RSLT_SUCCESS on successful operation.

Refer Snippet 2: Blocking NVM Erase-Write and Read for more information.

## ◆ mtb_hal_nvm_program()

cy_rslt_t mtb_hal_nvm_program | ( | mtb_hal_nvm_t * | obj,
|  | uint32_t | address,
|  | const uint32_t * | data
| ) |  |

Program one block with the provided data starting at the given address.

The address must be at block boundary. This will block until the write operation is complete.

Note
  This function does not erase the block prior to writing. The block must be erased first via a separate call to erase.

See also
  mtb_hal_nvm_get_info() to get the NVM characteristics for legal address values and the total block size. The provided data buffer must be at least as large as the NVM block_size.

Note
  Generally the `data` to be programmed must be located in the SRAM memory region.

Parameters

  [in] | obj | The NVM object
  [in] | address | The address of the block to be programmed
  [in] | data | The data buffer to be programmed to the NVM block

Returns
  The status of the program request. Returns CY_RSLT_SUCCESS on successful operation.

## ◆ mtb_hal_nvm_get_region_for_address()

const mtb_hal_nvm_region_info_t * mtb_hal_nvm_get_region_for_address | ( | mtb_hal_nvm_t * | obj,
|  | uint32_t | addr,
|  | uint32_t | length
| ) |  |

Find the nvm region based on given address and length.

If "length is zero and address is not in any nvm region" or if "length is not zero and address is not in any nvm region" or if "length is not zero and address is one nvm region but address + length goes into another nvm region", the function will return Null.

Parameters

  [in] | obj | The NVM object
  [in] | addr | The start address of the block
  [in] | length | The legnth to block

Returns
  pointer, mtb_hal_nvm_region_info_t, to nvm region