Functions

General Description

This section describes the public APIs defined by the Emulated EEPROM.

Functions
E_EEPROM_PSC1_STATUS_t	E_EEPROM_PSC1_Init (E_EEPROM_PSC1_t *const handle_ptr)
	Initializes E_EEPROM_PSC1 APP with the associated configuration handle. More...
E_EEPROM_PSC1_OPERATION_STATUS_t	E_EEPROM_PSC1_Write (uint8_t block_number, uint8_t *data_buffer_ptr)
	Programs the user defined data block into the flash. More...
E_EEPROM_PSC1_OPERATION_STATUS_t	E_EEPROM_PSC1_Read (uint8_t block_number, uint32_t block_offset, uint8_t *data_buffer_ptr, uint32_t length)
	Reads the data block contents from flash for the requested block number. More...
E_EEPROM_PSC1_OPERATION_STATUS_t	E_EEPROM_PSC1_StartGarbageCollection (void)
	Executes garbage collection at runtime. More...
E_EEPROM_PSC1_OPERATION_STATUS_t	E_EEPROM_PSC1_InvalidateBlock (uint8_t block_number)
	Invalidate the user defined data block that was written into the flash. More...
E_EEPROM_PSC1_STATUS_t	E_EEPROM_PSC1_GetStatus (void)
	Checks the status of APP. More...
bool	E_EEPROM_PSC1_IsGarbageCollectionNeeded (uint8_t block_number)
	Check the availability of space in flash bank to write the data block. More...
E_EEPROM_PSC1_OPERATION_STATUS_t	E_EEPROM_PSC1_GetPreviousData (uint8_t block_number, uint32_t block_offset, uint8_t *data_buffer_ptr, uint32_t length)
	Reads the just previous copy of the block from flash for the requested block number. More...

Function Documentation

E_EEPROM_PSC1_Init()

E_EEPROM_PSC1_STATUS_t E_EEPROM_PSC1_Init

(

E_EEPROM_PSC1_t *const

handle_ptr

)

Initializes E_EEPROM_PSC1 APP with the associated configuration handle.

Parameters

handle_ptr

: Pointer to the handler of the instance for which this API is called

Returns

E_EEPROM_PSC1_STATUS_SUCCESS if initialization is successful else E_EEPROM_PSC1_STATUS_FAILURE

Description:

Configures and initializes the micro-controller flash as an EEPROM associated with the instance handler. Performs three basic functionalities to support EEPROM related operations.

1. Detection of active flash bank and process selection
   Reading the marker states from first page of each flash bank detects the active bank and the free bank. Detection of active flash bank decides the respective process of state machine
   
   
2. State machine process handling
   The state machine process finds free space in the flash for writing user data blocks. If the detection of active bank fails due to corrupted markers, the state machine results in a non recoverable state. If the configuration option "Erase all and recover" is enabled, the state machine process will bring the flash to normal state by formatting the flash banks. Else it stalls the initialization until the flash banks are erased by calling the cy_flash low level driver API's.
   
   
3. Building RAM look up table
   The RAM lookup table keeps the track of the user data blocks written into flash. The lookup table has the complete information about a configured user data block.
   
   

IMPORTANT : This API must be successfully called before calling any other E_EEPROM_PSC1 API.

E_EEPROM_PSC1_Write()

E_EEPROM_PSC1_OPERATION_STATUS_t E_EEPROM_PSC1_Write	(	uint8_t	block_number,
		uint8_t *	data_buffer_ptr
	)

Programs the user defined data block into the flash.

Parameters

block_number	: Block ID Name/Number configured in the block table. Use the names defined in E_EEPROM_PSC1_BLOCK_t configuration structure array.
data_buffer_ptr	: Pointer to the user data buffer which need to be stored in flash

Returns

E_EEPROM_PSC1_OPERATION_STATUS_SUCCESS, if the write operation is successful
E_EEPROM_PSC1_OPERATION_STATUS_NOT_ALLOWED, if APP initialization is not completed or flash is busy
E_EEPROM_PSC1_OPERATION_STATUS_MEMORY_BANK_FULL, if no space available in flash bank to write the block
E_EEPROM_PSC1_OPERATION_STATUS_FAILURE, if write failed due to internal flash errors

Description:

The requested data block is written into the flash immediately, only when free space is available in flash bank. On non availability of space in active flash bank, the write gets delayed due to Garbage Collection. IMPORTANT : This API shall be called only after the successful completion of E_EEPROM_PSC1_Init() API.
While flash programming operation is in progress, the flash array will be busy and no access to flash is possible. Hence all other critical functionalities shall be done prior to the execution of this function.

NOTE :
It is advised to call this API when the APP in is IDLE state. This can be checked by calling E_EEPROM_PSC1_GetStatus() API and verifying the status.

Related APIs :
None

E_EEPROM_PSC1_Read()

E_EEPROM_PSC1_OPERATION_STATUS_t E_EEPROM_PSC1_Read	(	uint8_t	block_number,
		uint32_t	block_offset,
		uint8_t *	data_buffer_ptr,
		uint32_t	length
	)

Reads the data block contents from flash for the requested block number.

Parameters

block_number	: Block ID Name/Number configured in the block table. Use the names defined in E_EEPROM_PSC1_BLOCK_t configuration structure array.
block_offset	: Offset position to start the read operation Range [0 - (Block size - 1)]
data_buffer_ptr	: Pointer to the data buffer where data has to be stored after read
length	: Number of the data block elements to be read from the FLASH Range [1 - (block size - block_offset)]

Returns

E_EEPROM_PSC1_OPERATION_STATUS_SUCCESS, if read operation from flash is successful
E_EEPROM_PSC1_OPERATION_STATUS_FAILURE, if read failed due to ECC errors
E_EEPROM_PSC1_OPERATION_STATUS_NOT_ALLOWED, if APP initialization is not completed or flash is busy
E_EEPROM_PSC1_OPERATION_STATUS_INCONSISTENT_BLOCK, if the targeted block was not written properly
E_EEPROM_PSC1_OPERATION_STATUS_INVALID_BLOCK, if the targeted block was invalidated

Description:

Reads the data elements starting from the specified offset location. The number of elements read from the flash is equal to the length specified as input parameter.

IMPORTANT : This API do not perform any CRC verification for the read data.

NOTE :
If the flash is in busy state, the read will not be accepted.

E_EEPROM_PSC1_StartGarbageCollection()

E_EEPROM_PSC1_OPERATION_STATUS_t E_EEPROM_PSC1_StartGarbageCollection

(

void

)

Executes garbage collection at runtime.

Parameters

Returns

E_EEPROM_PSC1_OPERATION_STATUS_SUCCESS, if garbage collection is successful
Else return E_EEPROM_PSC1_OPERATION_STATUS_FAILURE on internal flash errors

Description:

Performs an explicit Garbage collection any time during the execution of APP. The function is accepted only if the E_EEPROM_PSC1 is in IDLE state.

NOTE :
If the flash is busy this will not be processed. It will check for any read write or erase errors and if any errors present it will return error.

E_EEPROM_PSC1_InvalidateBlock()

E_EEPROM_PSC1_OPERATION_STATUS_t E_EEPROM_PSC1_InvalidateBlock

(

uint8_t

block_number

)

Invalidate the user defined data block that was written into the flash.

Parameters

block_number

: Block ID Name/Number configured in the block table

Returns

E_EEPROM_PSC1_OPERATION_STATUS_SUCCESS, if the write operation is successful
E_EEPROM_PSC1_OPERATION_STATUS_NOT_ALLOWED, if APP initialization is not completed or flash is busy
E_EEPROM_PSC1_OPERATION_STATUS_MEMORY_BANK_FULL, if no space available in flash bank to write the block
E_EEPROM_PSC1_OPERATION_STATUS_FAILURE, else failed due to internal flash errors

Description:

The invalidated block is written into the flash immediately, only when free space is available in flash bank. On non availability of space in active flash bank, the invalidate write gets delayed due to Garbage Collection. IMPORTANT : This API shall be called only after the successful completion of E_EEPROM_PSC1_Init() API.
While flash programming operation is in progress, the flash array will be busy and no access to flash is possible. Hence all other critical functionalities shall be done prior to the execution of this function.

NOTE :
It is advised to call this API when the APP in is IDLE state. This can be checked by calling E_EEPROM_PSC1_GetStatus() API and verifying the status.

Related APIs :
None

E_EEPROM_PSC1_GetStatus()

E_EEPROM_PSC1_STATUS_t E_EEPROM_PSC1_GetStatus

(

void

)

Checks the status of APP.

Parameters

Returns

E_EEPROM_PSC1_STATUS_IDLE, if APP is in IDLE state to accept any request
E_EEPROM_PSC1_STATUS_FAILURE, if any previous operation on APP failed due to some internal error
E_EEPROM_PSC1_STATUS_BUSY, Else APP is in busy state because of flash operations

Description:

Read the current status of APP.

E_EEPROM_PSC1_IsGarbageCollectionNeeded()

bool E_EEPROM_PSC1_IsGarbageCollectionNeeded

(

uint8_t

block_number

)

Check the availability of space in flash bank to write the data block.

Parameters

block_number

: Block ID Name/Number configured in the block table. Use the names defined in E_EEPROM_PSC1_BLOCK_t configuration structure array.

Returns

true, if the bank has no space to write the requested block, else returns false.

Description:

During any time of the execution,the need for Garbage collection can be decided by calling this API. This will help to save time in the runtime write process which triggers a garbage collection automatically.

IMPORTANT : This API shall be called only after the successful completion of E_EEPROM_PSC1_Init() API.

NOTE :
After initialization of the APP, calling this API can decide the need for Garbage collection. If this API returns true an explicit garbage collection can be done by calling the API E_EEPROM_PSC1_StartGarbageCollection().

E_EEPROM_PSC1_GetPreviousData()

E_EEPROM_PSC1_OPERATION_STATUS_t E_EEPROM_PSC1_GetPreviousData	(	uint8_t	block_number,
		uint32_t	block_offset,
		uint8_t *	data_buffer_ptr,
		uint32_t	length
	)

Reads the just previous copy of the block from flash for the requested block number.

Parameters

block_number	: Block ID Name/Number configured in the block table. Use the names defined in E_EEPROM_PSC1_BLOCK_t configuration structure array.
block_offset	: Offset position to start the read operation Range [0 - (Block size - 1)]
data_buffer_ptr	: Pointer to the data buffer where data has to be stored after read
length	: Number of the data block elements to be read from the FLASH Range [1 - (block size - block_offset)]

Returns

E_EEPROM_PSC1_OPERATION_STATUS_SUCCESS, if read operation from flash is successful
E_EEPROM_PSC1_OPERATION_STATUS_FAILURE, if read failed due to ECC errors
E_EEPROM_PSC1_OPERATION_STATUS_NOT_ALLOWED, if APP initialization is not completed or flash is busy
E_EEPROM_PSC1_OPERATION_STATUS_INCONSISTENT_BLOCK, if the targeted block was not written properly
E_EEPROM_PSC1_OPERATION_STATUS_INVALID_BLOCK, if the targeted block was invalidated

Description:

It is useful when the latest write is interrupted due to power failures and flash errors. If a block read results in error, calling this API will search for the very next previous copy in the same bank. If the block is available then the user buffer will be filled with the data as per the requested length and offset. If the just previous copy of the data block is also inconsistent or invalid, no search will be done further.

IMPORTANT : This API do not perform any CRC verification for the read data.

NOTE :
If the flash is in busy state, the read will not be accepted.