Functions

General Description

This section describes the Emulated EEPROM Function Prototypes.

Functions
cy_en_em_eeprom_status_t	Cy_Em_EEPROM_Init (const cy_stc_eeprom_config_t *config, cy_stc_eeprom_context_t *context)
	Initializes the Emulated EEPROM library by filling the context structure. More...
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. More...
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. More...
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. More...
uint32_t	Cy_Em_EEPROM_NumWrites (cy_stc_eeprom_context_t *context)
	Returns the number of the Em_EEPROM Writes completed so far. More...

Function Documentation

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
	)

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:

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

Parameters

config	The pointer to the configuration structure. See cy_stc_eeprom_config_t.
context	The pointer to the Em_EEPROM context structure to be filled by the function. See cy_stc_eeprom_context_t.

Returns

Returns the status of the operation cy_en_em_eeprom_status_t :

• CY_EM_EEPROM_SUCCESS - The operation is successfully completed.
• CY_EM_EEPROM_BAD_PARAM - The input parameter is invalid.
• CY_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.

Parameters

addr	The logical start address in the Em_EEPROM storage to start reading data from.
eepromData	The pointer to a user array to write data to.
size	The amount of data to read in bytes.
context	The pointer to the Em_EEPROM context structure cy_stc_eeprom_context_t.

Returns

Returns the status of the operation cy_en_em_eeprom_status_t :

• CY_EM_EEPROM_SUCCESS - The operation is successfully completed.
• CY_EM_EEPROM_BAD_CHECKSUM - One of the row the data read from contains bad checksum.
• CY_EM_EEPROM_REDUNDANT_COPY_USED - Some data were read from redundant copy.
• CY_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 flash row size to perform the write operation. All write operations are done for flash row size. For the size of the row, refer to the specific PSoC 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.

Parameters

addr	The logical start address in the Em_EEPROM storage to start writing data to.
eepromData	Data to write to Em_EEPROM.
size	The amount of data to write to Em_EEPROM in bytes.
context	The pointer to the Em_EEPROM context structure cy_stc_eeprom_context_t.

Returns

Returns the status of the operation cy_en_em_eeprom_status_t :

• CY_EM_EEPROM_SUCCESS - The operation is successfully completed.
• CY_EM_EEPROM_BAD_CHECKSUM - One of the row the data read from contains bad checksum.
• CY_EM_EEPROM_REDUNDANT_COPY_USED - Some data were read from redundant copy.
• CY_EM_EEPROM_WRITE_FAIL - The write operation is failed.
• CY_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 the Simple Mode 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.
Also, refer to the Limitations and Restrictions section for the different Em_EEPROM middleware restrictions and limitations.

Parameters

context

The pointer to the Em_EEPROM context structure cy_stc_eeprom_context_t.

Returns

Returns the status of the operation cy_en_em_eeprom_status_t :

• CY_EM_EEPROM_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 the Simple Mode 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_config_t::wearLevelingFactor.

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

This function does the following:

1. Returns the number of writes stored in the the last written row if the checksum of the row is correct.
2. 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.
3. 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.
4. If the algorithm is unable to find the last written row (there is no row with the correct checksum), then zero is returned.

Parameters

context

The pointer to the Em_EEPROM context structure cy_stc_eeprom_context_t.

Returns

The number of writes performed to the Em_EEPROM.