Functions

General Description

Functions
uint8_t	SelfTest_ECC (cy_en_ecc_error_mode_t eccErrorMode)
	Performs ECC hardware self-test for Flash memory on XMC devices.
uint8_t	SelfTest_ECC_Flash (uint32_t addr, cy_en_ecc_error_mode_t eccErrorMode)
	Performs ECC hardware self-test for Flash memory on PSOC Control devices.
uint8_t	SelfTest_ECC_Ram (uint32_t addr, cy_en_ecc_error_mode_t eccErrorMode)
	Performs ECC hardware self-test for RAM memory on PSOC Control devices.
uint8_t	SelfTest_ECC_Flash_ConfigVerify (const stl_ecc_flash_cfg_t *expected)
	Verifies that the Flash ECC configuration still matches the expected contract.
uint8_t	SelfTest_ECC_Flash_SnapshotCapture (stl_ecc_flash_snapshot_t *snapshot)
	Captures the fault record and Flash ECC register evidence for one event.
uint8_t	SelfTest_ECC_Flash_Decode (const stl_ecc_flash_snapshot_t *snapshot, stl_ecc_flash_event_t *event)
	Decodes a captured fault record into a Flash ECC event.
void	SelfTest_ECC_Flash_Accumulate (stl_ecc_flash_counters_t *counters, const stl_ecc_flash_event_t *event)
	Adds one decoded event to a set of application-owned counters.
uint8_t	SelfTest_ECC_Flash_ProvokeNc (uint32_t addr)
	Provokes a real non-correctable Flash ECC error in one reserved row.
uint8_t	SelfTest_ECC_Flash_RestoreRow (uint32_t addr)
	Erases the reserved row and programs it with consistent data and parity.
uint8_t	SelfTest_ECC_Ram_ConfigVerify (RAMC_Type *ramc, const stl_ecc_ram_cfg_t *expected)
	Verifies the RAM ECC runtime configuration for one RAMC instance without writing any hardware register.
uint8_t	SelfTest_ECC_Ram_SnapshotCapture (stl_ecc_ram_snapshot_t *snapshot)
	Captures one FAULT_STRUCT0 record and RAM ECC register evidence.
uint8_t	SelfTest_ECC_Ram_Decode (const stl_ecc_ram_snapshot_t *snapshot, stl_ecc_ram_event_t *event)
	Decodes captured RAM ECC evidence.
void	SelfTest_ECC_Ram_Accumulate (stl_ecc_ram_counters_t *counters, const stl_ecc_ram_event_t *event)
	Adds a decoded RAM ECC event to caller-owned saturating counters.
uint8_t	SelfTest_ECC_Ram_Provoke (RAMC_Type *ramc, uint32_t wordAddr, stl_ecc_ram_inject_mode_t mode)
	Destructively provokes a RAM ECC event in an application-owned sacrificial word, then repairs the word and restores the RAMC configuration.

Function Documentation

SelfTest_ECC()

uint8_t SelfTest_ECC

(

cy_en_ecc_error_mode_t

eccErrorMode

)

Performs ECC hardware self-test for Flash memory on XMC devices.

The self-test configures SysFault for both correctable and non-correctable Flash ECC sources, then injects ECC corruption into the internal flash test location and reads that location to validate that the non-correctable source is reported.

The API passes when the observed SysFault source matches the expected non-correctable Flash ECC source.

Parameters

eccErrorMode

Error injection mode cy_en_ecc_error_mode_t

Returns

OK_STATUS (0) - Test passed
ERROR_STATUS (1) - Test failed

Note

This API is destructive: it erases and programs the internal flash test row. Any previous content at the test address is permanently overwritten. It also changes ECC SysFault configuration and intentionally injects an ECC fault. Do not call it while application fault handling cannot tolerate this controlled fault injection sequence.

This API is applicable only to XMC devices.

SelfTest_ECC_Flash()

uint8_t SelfTest_ECC_Flash	(	uint32_t	addr,
		cy_en_ecc_error_mode_t	eccErrorMode )

Performs ECC hardware self-test for Flash memory on PSOC Control devices.

The self-test configures SysFault for Flash ECC sources, programs conflicting flash data/ECC information to inject corruption, re-enables ECC check, and reads the provided flash row to trigger ECC fault reporting.

The API passes when the observed SysFault source matches the expected non-correctable Flash ECC source.

Parameters

addr	Aligned flash row address.
eccErrorMode	Error injection mode cy_en_ecc_error_mode_t

Returns

OK_STATUS (0) - Test passed
ERROR_STATUS (1) - Test failed

Note

This API is destructive: it erases and reprograms the flash row at addr. Any previous content at that address is permanently overwritten. It also changes ECC SysFault configuration and intentionally injects an ECC fault. Do not call it while application fault handling cannot tolerate this controlled fault injection sequence.

This API is applicable only to PSOC Control devices.

SelfTest_ECC_Ram()

uint8_t SelfTest_ECC_Ram	(	uint32_t	addr,
		cy_en_ecc_error_mode_t	eccErrorMode )

Performs ECC hardware self-test for RAM memory on PSOC Control devices.

The self-test configures SysFault for RAM ECC sources, writes baseline data with ECC enabled, corrupts data with ECC disabled, re-enables ECC check, and reads memory to trigger ECC fault reporting.

On devices with multiple RAMC instances, the API selects the RAMC instance based on addr and accepts the non-correctable source from the corresponding RAMC block.

The API passes when the observed SysFault source matches the expected non-correctable RAM ECC source.

Parameters

addr	RAM address.
eccErrorMode	Error injection mode cy_en_ecc_error_mode_t

Returns

OK_STATUS (0) - Test passed
ERROR_STATUS (1) - Test failed

Note

This API is destructive: it overwrites the RAM location at addr with test data. The caller must ensure addr does not hold live application data during the test. It also changes ECC SysFault configuration and intentionally injects an ECC fault. Do not call it while application fault handling cannot tolerate this controlled fault injection sequence.

This API assumes that RAM address range is continuous and does not have gaps between address ranges of different RAM controllers

This API is applicable only to devices that have RAM ECC.

SelfTest_ECC_Flash_ConfigVerify()

uint8_t SelfTest_ECC_Flash_ConfigVerify

(

const stl_ecc_flash_cfg_t *

expected

)

Verifies that the Flash ECC configuration still matches the expected contract.

Checks that FLASH_CTL.ECC_EN is set, FLASH_CTL.RBUS_ERR_SILENT is cleared, and that ECC error injection is neither enabled nor latched. When stl_ecc_flash_cfg_t::checkFlashMacroEncoder is true, the Flash Macro encoder disable bit is additionally verified to be cleared.

This API performs no register write, so it is intended for periodic runtime invocation as a configuration integrity diagnostic. It does not read ECC_LOGIR: threshold and counter state are application-owned monitoring policy, not a configuration invariant.

Parameters

expected

Expected configuration. ECC must be enabled and RBUS error silence must be disabled.

Returns

OK_STATUS (0) - Configuration matches
ERROR_STATUS (1) - Configuration does not match
ERROR_BAD_PARAM (9) - Invalid or unsupported request

Note

Reading the Flash Macro register block requires the Secure Main CM33 context. Pass stl_ecc_flash_cfg_t::checkFlashMacroEncoder as false from any image that does not have that access.

This API is applicable only to PSOC Control C3 devices.

SelfTest_ECC_Flash_SnapshotCapture()

uint8_t SelfTest_ECC_Flash_SnapshotCapture

(

stl_ecc_flash_snapshot_t *

snapshot

)

Captures the fault record and Flash ECC register evidence for one event.

Intended to be called from the application fault handler before the record is acknowledged. The API is read-only: it performs no register write, does not clear the fault status or interrupt, does not touch the NVIC, and keeps no internal state. Applications with their own fault framework may fill stl_ecc_flash_snapshot_t directly instead of calling this function.

Parameters

snapshot

Destination for the captured evidence.

Returns

OK_STATUS (0) - Snapshot captured
ERROR_BAD_PARAM (9) - snapshot is NULL

Note

This API is applicable only to PSOC Control C3 devices.

SelfTest_ECC_Flash_Decode()

uint8_t SelfTest_ECC_Flash_Decode	(	const stl_ecc_flash_snapshot_t *	snapshot,
		stl_ecc_flash_event_t *	event )

Decodes a captured fault record into a Flash ECC event.

This is a pure function: it reads and writes no register, performs no acknowledgement, keeps no internal state, and never blocks. It is reentrant and can be called from any context.

A record that belongs to another fault source, or that is not valid, is a successfully decoded result reported as STL_ECC_FLASH_EVENT_NONE, so the application drain loop needs no error handling for foreign sources.

Parameters

snapshot	Evidence captured for one fault record.
event	Destination for the decoded event. Always fully written on success.

Returns

OK_STATUS (0) - Snapshot decoded
ERROR_BAD_PARAM (9) - snapshot or event is NULL

Note

stl_ecc_flash_event_t::ecc1Cnt and stl_ecc_flash_event_t::eccThreshold are reported as evidence only. The hardware counter saturates at the threshold, so it is not a lifetime count of corrected errors.

This API is applicable only to PSOC Control C3 devices.

SelfTest_ECC_Flash_Accumulate()

void SelfTest_ECC_Flash_Accumulate	(	stl_ecc_flash_counters_t *	counters,
		const stl_ecc_flash_event_t *	event )

Adds one decoded event to a set of application-owned counters.

This is the runtime monitoring accumulator. It reads and writes no register, keeps no internal state, and never blocks. All storage belongs to the caller, so an application can keep several independent counter sets, reset them at will, and place them in memory that survives a reset.

An event of kind STL_ECC_FLASH_EVENT_NONE increments stl_ecc_flash_counters_t::other and leaves stl_ecc_flash_counters_t::last untouched, so a drain loop can pass every record it sees without filtering foreign fault sources first.

Parameters

counters	Counter set to update. Ignored when NULL.
event	Decoded event to account for. Ignored when NULL.

Note

The counters saturate at their maximum value instead of wrapping, so a long-running system never reports fewer events than it observed.

The caller owns concurrency. A counter set updated from an interrupt handler must not be updated concurrently from another context.

This API is applicable only to PSOC Control C3 devices.

SelfTest_ECC_Flash_ProvokeNc()

uint8_t SelfTest_ECC_Flash_ProvokeNc

(

uint32_t

addr

)

Provokes a real non-correctable Flash ECC error in one reserved row.

This is the destructive stimulus of the application-managed self test. It disables Flash ECC, erases the row, programs a first pattern, programs a second pattern into the same row without an intervening erase, re-enables Flash ECC and reads the row. The stored data no longer matches the stored parity, so the read reports a non-correctable event.

The row content is destroyed. The caller must supply a row that is reserved for this purpose and that holds no code or data of the application, and must call SelfTest_ECC_Flash_RestoreRow afterwards.

With the baseline configuration of this module the resulting bus error is precise and escalates to a CPU exception, so this function does not return to its caller unless the application fault handler resumes execution. The application owns that policy; the STL installs no handler, configures no fault structure, touches no NVIC state and provides no recovery. Cleanup of the row is therefore a separate entry point that stays reachable after a reset.

A normal return means either that the application fault handler resumed execution, or that no error was reported at all. The two cases are distinguished by the evidence the application captured with SelfTest_ECC_Flash_SnapshotCapture, not by this return value.

Flash ECC is enabled on return. The rest of the configuration verified by SelfTest_ECC_Flash_ConfigVerify is not restored by this function.

Parameters

addr	Row-aligned address of the reserved row.

Returns

OK_STATUS (0) - Stimulus applied and the row was read
ERROR_STATUS (1) - Flash initialization, erase or first program failed

Note

Requires write access to the Flash macro. On a device with a protected Secure Main region this means the Secure Main CM33 image.

There is no correctable counterpart. Storing a single-bit mismatch needs a Flash macro page-latch parity sequence that the PDL does not expose.

This API is applicable only to PSOC Control C3 devices.

SelfTest_ECC_Flash_RestoreRow()

uint8_t SelfTest_ECC_Flash_RestoreRow

(

uint32_t

addr

)

Erases the reserved row and programs it with consistent data and parity.

Removes the mismatch stored by SelfTest_ECC_Flash_ProvokeNc so that the row can be read again with ECC enabled. Separate from the stimulus because the stimulus does not return on a device that escalates the bus error, so cleanup has to be reachable from the next boot.

Flash ECC is left in the state the caller had; the application should restore its runtime configuration and call SelfTest_ECC_Flash_ConfigVerify.

Parameters

addr	Row-aligned address of the reserved row.

Returns

OK_STATUS (0) - Row restored
ERROR_STATUS (1) - Flash initialization, erase or program failed

Note

This API is applicable only to PSOC Control C3 devices.

SelfTest_ECC_Ram_ConfigVerify()

uint8_t SelfTest_ECC_Ram_ConfigVerify	(	RAMC_Type *	ramc,
		const stl_ecc_ram_cfg_t *	expected )

Verifies the RAM ECC runtime configuration for one RAMC instance without writing any hardware register.

Parameters

ramc	RAMC controller to verify. The pointer must identify a supported main-SRAM RAMC instance.
expected	Expected configuration. ECC and automatic correction must be enabled.

Returns

OK_STATUS (0) - Configuration matches
ERROR_STATUS (1) - Configuration does not match
ERROR_BAD_PARAM (9) - Invalid request

SelfTest_ECC_Ram_SnapshotCapture()

uint8_t SelfTest_ECC_Ram_SnapshotCapture

(

stl_ecc_ram_snapshot_t *

snapshot

)

Captures one FAULT_STRUCT0 record and RAM ECC register evidence.

This API is read-only; acknowledgement and fault handling remain application-owned.

Parameters

snapshot

Destination for the captured evidence.

Returns

OK_STATUS (0) - Snapshot captured
ERROR_BAD_PARAM (9) - snapshot is NULL

SelfTest_ECC_Ram_Decode()

uint8_t SelfTest_ECC_Ram_Decode	(	const stl_ecc_ram_snapshot_t *	snapshot,
		stl_ecc_ram_event_t *	event )

Decodes captured RAM ECC evidence.

This is a pure function and reports unrelated fault sources as STL_ECC_RAM_EVENT_NONE.

Parameters

snapshot	Captured fault and RAMC evidence.
event	Destination for the decoded RAM ECC event.

Returns

OK_STATUS (0) - Snapshot decoded
ERROR_BAD_PARAM (9) - snapshot or event is NULL

SelfTest_ECC_Ram_Accumulate()

void SelfTest_ECC_Ram_Accumulate	(	stl_ecc_ram_counters_t *	counters,
		const stl_ecc_ram_event_t *	event )

Adds a decoded RAM ECC event to caller-owned saturating counters.

Parameters

counters	Counter set to update. Ignored when NULL.
event	Decoded event to account for. Ignored when NULL.

SelfTest_ECC_Ram_Provoke()

uint8_t SelfTest_ECC_Ram_Provoke	(	RAMC_Type *	ramc,
		uint32_t	wordAddr,
		stl_ecc_ram_inject_mode_t	mode )

Destructively provokes a RAM ECC event in an application-owned sacrificial word, then repairs the word and restores the RAMC configuration.

The caller supplies the RAMC controller and must ensure the address belongs to it.

The library does not claim the memory is protected while ECC_CTL is 0. The caller must prevent DMA and other bus masters from storing to that RAMC while the generation-off window is active.

Parameters

ramc	RAMC controller that owns wordAddr. The pointer must identify a supported main-SRAM RAMC instance.
wordAddr	32-bit-aligned address of the application-owned sacrificial word.
mode	Requested correctable or non-correctable ECC error class.

Returns

OK_STATUS (0) - Stimulus applied and word repaired
ERROR_BAD_PARAM (9) - Invalid RAMC pointer, address, or mode