NVM (Onboard Non-Volatile Memory)

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;
    }
 

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
    }

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