General Description

The Emulated EEPROM (Em_EEPROM) middleware emulates an EEPROM storage in the MCU's non volatile memory and it is built on top of a block storage devie that abstracts the underlying memory architecture so that the middleware is portable to a wide range of devices.

Use the Em_EEPROM to store non-volatile data on a target device when increasing flash memory endurance and restoring corrupted data from a redundant copy is required.

Features:

EEPROM-Like Non-Volatile Storage
Easy to use Read and Write
Optional Wear Leveling
Optional Redundant Data Storage

For quick start guide, configuration considerations, storage placement, operating modes, limitations, and migration information, see the 'How to Use' and 'Configuration Considerations' sections in README.md.

Data Structures
struct	cy_stc_eeprom_config_t
	Em_EEPROM configuration structure. More...
struct	cy_stc_eeprom_config2_t
	Em_EEPROM new configuration structure. More...
struct	cy_stc_eeprom_context_t
	The Em_EEPROM context data structure. More...

Macros
#define	MTB_EM_EEPROM_BAD_PARAM CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_EM_EEPROM, 0)
	An invalid parameter value is passed in.
#define	MTB_EM_EEPROM_BAD_CHECKSUM CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_EM_EEPROM, 1)
	The data in EM_EEPROM is corrupted, the checksum failed.
#define	MTB_EM_EEPROM_BAD_DATA CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_EM_EEPROM, 2)
	The provided configuration is invalid or placing Em_EEPROM in NVM failed.
#define	MTB_EM_EEPROM_WRITE_FAIL CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_EM_EEPROM, 3)
	Write to Em_EEPROM failed.
#define	MTB_EM_EEPROM_REDUNDANT_COPY_USED CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_MIDDLEWARE_EM_EEPROM, 4)
	When redundant copy is enabled and one of the copies has bad CRC and other one valid CRC.
#define	CY_EM_EEPROM_MW_VERSION_MAJOR (2)
	Library major version.
#define	CY_EM_EEPROM_MW_VERSION_MINOR (80)
	Library minor version.

Enumerations
enum	cy_en_em_eeprom_status_t { CY_EM_EEPROM_SUCCESS = 0x00uL , CY_EM_EEPROM_BAD_PARAM = MTB_EM_EEPROM_BAD_PARAM , CY_EM_EEPROM_BAD_CHECKSUM = MTB_EM_EEPROM_BAD_CHECKSUM , CY_EM_EEPROM_BAD_DATA = MTB_EM_EEPROM_BAD_DATA , CY_EM_EEPROM_WRITE_FAIL = MTB_EM_EEPROM_WRITE_FAIL , CY_EM_EEPROM_REDUNDANT_COPY_USED = MTB_EM_EEPROM_REDUNDANT_COPY_USED }
	The Em_EEPROM return enumeration type. More...

Functions
cy_en_em_eeprom_status_t	Cy_Em_EEPROM_Init_BD (const cy_stc_eeprom_config2_t config, cy_stc_eeprom_context_t context, mtb_block_storage_t *block_device)
	Initializes the Emulated EEPROM library by filling the context structure.
cy_en_em_eeprom_status_t	Cy_Em_EEPROM_Init (const cy_stc_eeprom_config_t config, cy_stc_eeprom_context_t context)
	This function was the entry point up until version 2.20.
cy_en_em_eeprom_status_t	Cy_Em_EEPROM_Read (uint32_t addr, void eepromData, uint32_t size, cy_stc_eeprom_context_t context)
	Reads data from a specified location.
cy_en_em_eeprom_status_t	Cy_Em_EEPROM_Write (uint32_t addr, const void eepromData, uint32_t size, cy_stc_eeprom_context_t context)
	Writes data to a specified location.
cy_en_em_eeprom_status_t	Cy_Em_EEPROM_Erase (cy_stc_eeprom_context_t *context)
	This function erases the entire content of Em_EEPROM.
uint32_t	Cy_Em_EEPROM_NumWrites (cy_stc_eeprom_context_t *context)
	Returns the number of the Em_EEPROM Writes completed so far.

Data Structure Documentation

◆ cy_stc_eeprom_config_t

struct cy_stc_eeprom_config_t

Data Fields
uint32_t	eepromSize	The logical size of data in bytes to store in the Em_EEPROM. The size is rounded up to a full Em_EEPROM row size physically. The row size is specific for a device family. Refer to the specific PSOC device datasheet. Note this size is often smaller than the total amount of nvm used for the Em_EEPROM storage. The Em_EEPROM storage size depends on the Em_EEPROM configuration and can be bigger because increasing nvm endurance (wear-leveling) and restoring corrupted data from a redundant copy. See section 'Storage Variable Location and Size' in README.md for size calculation equations.
uint8_t	simpleMode	Simple mode, when enabled (1 - enabled, 0 - disabled), means no additional service information is stored by the Em_EEPROM middleware like checksums, headers, a number of writes, etc. Data is stored directly by the specified address. The size of Em_EEPROM storage is equal to the number of byte specified in the eepromSize parameter rounded up to a full row size. The wear leveling and redundant copy features are disabled, i.e. wearLevelingFactor and redundantCopy parameters are ignored.
uint8_t	wearLevelingFactor	The higher the factor is, the more nvm is used, but a higher number of erase/write cycles can be done on Em_EEPROM. Multiply this number by the datasheet write endurance spec to determine the max of write cycles. The amount of wear leveling from 1 to 10. 1 means no wear leveling is used.
uint8_t	redundantCopy	If enabled (1 - enabled, 0 - disabled), a checksum (stored in a row) is calculated on each row of data, while a redundant copy of Em_EEPROM is stored in another location. When data is read, first the checksum is checked. If that checksum is bad, and the redundant copy's checksum is good, the copy is restored.
uint8_t	blockingWrite	If enabled (1 - enabled, 0 - disabled), the blocking writes to nvm are used in the design. Otherwise, non-blocking nvm writes are used. From the user's perspective, the behavior of blocking and non-blocking writes are the same - the difference is that the non-blocking writes do not block the interrupts. Note Non-blocking nvm write is only supported on limited device list: PSOC Control PSC3/PSC3M8, PSOC6, XMC7xxx, and T2G-B-H. For other devices, the blocking write is used by default. See section 'Non-Blocking Operation' in README.md for details on the interrupt requirements when using non-blocking operation.
uint32_t	userFlashStartAddr	The address of the nvm storage. The storage start address is filled to the Emulated EEPROM configuration structure and then the structure is passed to the Cy_Em_EEPROM_Init() function.

◆ cy_stc_eeprom_config2_t

struct cy_stc_eeprom_config2_t

Data Fields
uint32_t	eepromSize	The logical size of data in bytes to store in the Em_EEPROM. The size is rounded up to a full Em_EEPROM row size physically. The row size is specific for a device family. Refer to the specific PSOC device datasheet. Note this size is often smaller than the total amount of nvm used for the Em_EEPROM storage. The Em_EEPROM storage size depends on the Em_EEPROM configuration and can be bigger because increasing nvm endurance (wear-leveling) and restoring corrupted data from a redundant copy. See section 'Storage Variable Location and Size' in README.md for size calculation equations.
uint8_t	simpleMode	Simple mode, when enabled (1 - enabled, 0 - disabled), means no additional service information is stored by the Em_EEPROM middleware like checksums, headers, a number of writes, etc. Data is stored directly by the specified address. The size of Em_EEPROM storage is equal to the number of byte specified in the eepromSize parameter rounded up to a full row size. The wear leveling and redundant copy features are disabled, i.e. wearLevelingFactor and redundantCopy parameters are ignored.
uint8_t	wearLevelingFactor	The higher the factor is, the more nvm is used, but a higher number of erase/write cycles can be done on Em_EEPROM. Multiply this number by the datasheet write endurance spec to determine the max of write cycles. The amount of wear leveling from 1 to 10. 1 means no wear leveling is used.
uint8_t	redundantCopy	If enabled (1 - enabled, 0 - disabled), a checksum (stored in a row) is calculated on each row of data, while a redundant copy of Em_EEPROM is stored in another location. When data is read, first the checksum is checked. If that checksum is bad, and the redundant copy's checksum is good, the copy is restored.
uint8_t	blockingWrite	If enabled (1 - enabled, 0 - disabled), the blocking writes to nvm are used in the design. Otherwise, non-blocking nvm writes are used. From the user's perspective, the behavior of blocking and non-blocking writes are the same - the difference is that the non-blocking writes do not block the interrupts. Note Non-blocking nvm write is only supported on limited device list: PSOC Control PSC3/PSC3M8, PSOC6, XMC7xxx, and T2G-B-H. For other devices, the blocking write is used by default. See section 'Non-Blocking Operation' in README.md for details on the interrupt requirements when using non-blocking operation.
uint32_t	userNvmStartAddr	The address of the nvm storage. The storage start address is filled to the Emulated EEPROM configuration structure and then the structure is passed to the Cy_Em_EEPROM_Init() function.

◆ cy_stc_eeprom_context_t

struct cy_stc_eeprom_context_t

Data Fields
uint16_t	numberOfRows	The number of nvm rows allocated for the Em_EEPROM excluding the number of rows allocated for wear-leveling and a redundant copy overhead.
uint16_t	rowSize	The size of a EEPROM row in bytes, equal to the program size of the NVM or a multiple of it that is >= than CY_EM_EEPROM_MINIMUM_ROW_SIZE for devices whose program size is too small.
uint32_t	secSize	The size of a EEPROM sector in bytes, equal to the erase size of the NVM. It is larger or equal to program size.
uint32_t	eepromSize	The number of bytes to store in Em_EEPROM.
uint8_t	wearLevelingFactor	The amount of wear leveling from 1 to 10. 1 means no wear leveling is used.
uint8_t	simpleMode	No headers configured.
uint8_t	redundantCopy	If not zero, a redundant copy of the Em_EEPROM is included.
uint8_t	blockingWrite	If not zero, a blocking write to nvm is used. Otherwise, a non-blocking write is used. This parameter is used only for PSOC 6.
uint32_t	userNvmStartAddr	The start address for the Em_EEPROM memory in nvm.
uint16_t	byteInRow	The number of user's data bytes in one row for non simple mode. It is equal to half the row size as in non simple mode half of the row is reserved for the headers data portion and the other half is reserved for the actual user's data.
uint16_t	headerDataLength	Defines the length of data that can be stored in the Em_EEPROM header.
uint32_t *	ptrLastWrittenRow	The pointer to the last written row.
const mtb_block_storage_t *	bd	The block storage object holding the information on prototypes for the necessary operations.

Enumeration Type Documentation

◆ cy_en_em_eeprom_status_t

enum cy_en_em_eeprom_status_t

The Em_EEPROM return enumeration type.

Enumerator
CY_EM_EEPROM_SUCCESS	The operation executed successfully.
CY_EM_EEPROM_BAD_PARAM	An invalid parameter value is passed in.
CY_EM_EEPROM_BAD_CHECKSUM	The data in EM_EEPROM is corrupted, the checksum failed.
CY_EM_EEPROM_BAD_DATA	The provided configuration is invalid or placing Em_EEPROM in NVM failed.
CY_EM_EEPROM_WRITE_FAIL	Write to Em_EEPROM failed.
CY_EM_EEPROM_REDUNDANT_COPY_USED	When redundant copy is enabled and one of the copies has bad CRC and other one valid CRC.

Function Documentation

◆ Cy_Em_EEPROM_Init_BD()

cy_en_em_eeprom_status_t Cy_Em_EEPROM_Init_BD	(	const cy_stc_eeprom_config2_t *	config,
		cy_stc_eeprom_context_t *	context,
		mtb_block_storage_t *	block_device )

Initializes the Emulated EEPROM library by filling the context structure.

This function is called by the application program prior to calling any other function of the Em_EEPROM middleware.

Do not modify the context structure after it is filled with this function. Modification of the context structure may cause unexpected behavior of the Cy_Em_EEPROM functions that rely on this context structure.

This function does the following:

Checks the provided configuration for correctness.
Copies the provided configuration into the context structure.

Parameters

[in]	config	The pointer to the configuration structure Configuration to use to initialize the em_eeprom object
[out]	context	Pointer to a em_eeprom object. The caller must allocate the memory for this object but the init function will initialize its contents. The pointer to the Em_EEPROM context structure to be filled by the function.
[in]	block_device	Block device interface for the underlying memory to be used.

Returns

Result of the initialization operation.

CY_RSLT_SUCCESS - The operation is successfully completed.
MTB_EM_EEPROM_BAD_PARAM - The input parameter is invalid.
MTB_EM_EEPROM_BAD_DATA - The configuration is incorrect.

◆ Cy_Em_EEPROM_Init()

cy_en_em_eeprom_status_t Cy_Em_EEPROM_Init	(	const cy_stc_eeprom_config_t *	config,
		cy_stc_eeprom_context_t *	context )

This function was the entry point up until version 2.20.

All devices supported (PSOC6 based devices, PSOC4 based devices, XMC7xxx and T2G-B-H based devices) will continue to work as expected when using this function, however it still introduces a distinction between memory architectures that should not be a concern for the Em_EEPROM library Users should start using Cy_Em_EEPROM_Init_BD instead by defining a block storage device beforehand. Using this function on version 2.30 onwards will imply that all devices use block storage implementation based on cyhal_nvm except for cat2 devices which will use block storage implementation specific to cat2 devices. This function is kept for backwards compatibility.

Initializes the Emulated EEPROM library by filling the context structure.

This function is called by the application program prior to calling any other function of the Em_EEPROM middleware.

This function does the following:

Selects the appropriate block storage solution based on the DUT
Calls Cy_Em_EEPROM_Init_BD

Parameters

[in]	config	The pointer to the configuration structure Configuration to use to initialize the em_eeprom object
[out]	context	Pointer to a em_eeprom object. The caller must allocate the memory for this object but the init function will initialize its contents. The pointer to the Em_EEPROM context structure to be filled by the function.

Returns

Result of the initialization operation.

CY_RSLT_SUCCESS - The operation is successfully completed.
MTB_EM_EEPROM_BAD_PARAM - The input parameter is invalid.
MTB_EM_EEPROM_BAD_DATA - The configuration is incorrect.

◆ Cy_Em_EEPROM_Read()

cy_en_em_eeprom_status_t Cy_Em_EEPROM_Read	(	uint32_t	addr,
		void *	eepromData,
		uint32_t	size,
		cy_stc_eeprom_context_t *	context )

Reads data from a specified location.

This function takes a logical Em_EEPROM address, converts it to an actual physical address where data is stored and returns the data to the user.

This function uses a buffer of the flash row size to perform the read operation. For the size of the row, refer to the specific PSOC device datasheet.

There are restrictions on using the read-while-write (RWW) feature for EEPROM emulation. There are also multiple constraints for blocking and nonblocking flash operations, relating to interrupts, power modes, IPC usage, etc. Refer to the "Flash (Flash System Routine)" section of the CAT1 Peripheral Driver Library (mtb-pdl-cat1) API Reference Manual or Device Support library documentation.

Parameters

[in]	addr	The logical start address in the Em_EEPROM storage to start reading data from.
[out]	eepromData	The pointer to a user array to write data to.
[in,out]	size	The amount of data to read in bytes.
[in]	context	Pointer to a em_eeprom object

Returns

Result of the read operation.

CY_RSLT_SUCCESS - The operation is successfully completed.
MTB_EM_EEPROM_BAD_CHECKSUM - One of the row the data read from contains bad checksum.
MTB_EM_EEPROM_REDUNDANT_COPY_USED - Some data were read from redundant copy.
MTB_EM_EEPROM_BAD_PARAM - The function input parameter is invalid.

◆ Cy_Em_EEPROM_Write()

cy_en_em_eeprom_status_t Cy_Em_EEPROM_Write	(	uint32_t	addr,
		const void *	eepromData,
		uint32_t	size,
		cy_stc_eeprom_context_t *	context )

Writes data to a specified location.

This function takes the logical Em_EEPROM address and converts it to an actual physical address and writes data there. If wear leveling is enabled, the writing process uses the wear leveling techniques.

This is a blocking function and it does not return until the write operation is completed. The user's application program cannot enter Hibernate mode until the write is completed. The write operation is allowed in CPU Sleep mode. Do not reset your device during the flash operation, including the XRES pin, a software reset, and watchdog reset sources. Also, configure low-voltage detect circuits to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

This function uses a buffer of the row size to perform the write operation. All write operations are done for row size. For the size of the row, refer to the specific device datasheet.

If the blocking write option is used (PSOC 6), and write or erase operations are performed by CM4, the user's code on CM0P and CM4 is blocked until the operations are completed. If the operations are performed by CM0P, the user's code on CM4 is not blocked and the user code's on CM0P is blocked until the operation is completed. Plan your task allocation accordingly.

There are restrictions on using the read-while-write (RWW) feature for EEPROM emulation. There are also multiple constraints for blocking and nonblocking flash operations, relating to interrupts, Power modes, IPC usage, etc. Refer to the "Flash (Flash System Routine)" section of the CAT1 Peripheral Driver Library (mtb-pdl-cat1) API Reference Manual or Device Support library documentation.

Parameters

[in]	addr	The logical start address in the Em_EEPROM storage to start writing data to.
[in]	eepromData	Pointer to the start of the data to be writtento Em_EEPROM.
[in]	size	Total size of the data in bytes.
[in]	context	Pointer to a em_eeprom object

Returns

Result of the write operation.

CY_RSLT_SUCCESS - The operation is successfully completed.
MTB_EM_EEPROM_BAD_CHECKSUM - One of the row the data read from contains bad checksum.
MTB_EM_EEPROM_REDUNDANT_COPY_USED - Some data were read from redundant copy.
MTB_EM_EEPROM_WRITE_FAIL - The write operation is failed.
MTB_EM_EEPROM_BAD_PARAM - The function input parameter is invalid.

◆ Cy_Em_EEPROM_Erase()

cy_en_em_eeprom_status_t Cy_Em_EEPROM_Erase ( cy_stc_eeprom_context_t * context )

This function erases the entire content of Em_EEPROM.

Erased values are all zeros.

In simple mode (see section 'Simple Mode' in README.md) the function just erases the entire content of Em_EEPROM.

When Simple Mode is disabled, the function first performs one write operation to keep the number of writes completed so far and then erases all rest content of Em_EEPROM memory. So, the Cy_Em_EEPROM_NumWrites() function returns the correct value. Refer to the Cy_Em_EEPROM_Write() function for the side effect of the write operation. If the write operation is failed then corresponding status is returned and no erase operation is executed.

This function uses a buffer of the flash row size to perform the erase operation. For the size of the row, refer to the specific PSOC device datasheet.

This is a blocking function and it does not return until the erase operation is completed. The user's application program cannot enter Hibernate mode until the write is completed. The write operation is allowed in CPU Sleep mode. Do not reset your device during the flash operation, including the XRES pin, a software reset, and watchdog reset sources. Also, configure low-voltage detect circuits to generate an interrupt instead of a reset. Otherwise, portions of flash may undergo unexpected changes.

If the blocking write option is used, and write or erase operations are performed by CM4, the user's code on CM0P and CM4 is blocked until the operations are completed. If the operations are performed by CM0P, the user's code on CM4 is not blocked and the user code's on CM0P is blocked until the operation is completed. Plan your task allocation accordingly.

There are restrictions on using the read-while-write (RWW) feature for EEPROM emulation. There are also multiple constraints for blocking and nonblocking flash operations, relating to interrupts, power mode, IPC usage, etc. Refer to the "Flash (Flash System Routine)" section of the CAT1 Peripheral Driver Library (mtb-pdl-cat1) API Reference Manual or Device Support library documentation.
Also, refer to the section 'Limitations and Restrictions' in README.md for the different Em_EEPROM middleware restrictions and limitations.

Parameters

[in] context Pointer to a em_eeprom object

Returns

Result of the erase operation.

CY_RSLT_SUCCESS - The operation is successfully completed.
CY_EM_EEPROM_WRITE_FAIL - The either Write or Erase operation is failed.

◆ Cy_Em_EEPROM_NumWrites()

uint32_t Cy_Em_EEPROM_NumWrites ( cy_stc_eeprom_context_t * context )

Returns the number of the Em_EEPROM Writes completed so far.

This function returns zero in simple mode (see section 'Simple Mode' in README.md) since the number of writes is not available in this case.

Use this function to monitor the flash memory endurance. The higher the value, the less the flash memory endurance. Refer to the datasheet write endurance spec to determine the maximum number of write cycles. If the Wear Leveling feature is enabled, then the maximum of write cycles is increased by cy_stc_eeprom_context_t::wearLevelingFactor.

The returned number does not include the number of writes into the redundant copy if enabled.

This function does the following:

Returns the number of writes stored in the the last written row if the checksum of the row is correct.
If the checksum of the last written row is invalid and the redundant copy feature is enabled, then the row checksum of the redundant copy is verified for correctness and corresponding number of writes is returned.
If the checksum of the last written row is incorrect, then a special algorithm of searching the last written is executed and a corresponding number of writes is reported.
If the algorithm is unable to find the last written row (there is no row with the correct checksum), then zero is returned.

Parameters

[in] context Pointer to a em_eeprom object

Returns: The number of writes performed to the Em_EEPROM.

General Description

Data Structures

Macros

Enumerations

Functions

Data Structure Documentation

◆ cy_stc_eeprom_config_t

◆ cy_stc_eeprom_config2_t

◆ cy_stc_eeprom_context_t

Enumeration Type Documentation

◆ cy_en_em_eeprom_status_t

Function Documentation

◆ Cy_Em_EEPROM_Init_BD()

◆ Cy_Em_EEPROM_Init()

◆ Cy_Em_EEPROM_Read()

◆ Cy_Em_EEPROM_Write()

◆ Cy_Em_EEPROM_Erase()

◆ Cy_Em_EEPROM_NumWrites()