Functions

General Description

Functions
uint8_t	SelfTest_MPU (const stl_mpu_entry_t *entry)
	Runs the functional self-test for the ARM Cortex-M core MPU: temporarily configures a spare MPU region read-only over the supplied scratch word, attempts a denied write, recovers from the resulting MemManage fault, and verifies both the fault cause and the data integrity of the scratch word.
bool	SelfTest_MPU_HandleMemManage (uint32_t *stack)
	MemManage dispatch entry for the application's MemManage_Handler trampoline.

Function Documentation

SelfTest_MPU()

uint8_t SelfTest_MPU

(

const stl_mpu_entry_t *

entry

)

Runs the functional self-test for the ARM Cortex-M core MPU: temporarily configures a spare MPU region read-only over the supplied scratch word, attempts a denied write, recovers from the resulting MemManage fault, and verifies both the fault cause and the data integrity of the scratch word.

Parameters

entry

Pointer to stl_mpu_entry_t describing the scratch word under test and the spare MPU region to use.

Returns

OK_STATUS - The denied write raised a MemManage fault with CFSR.MMFSR equal to DACCVIOL | MMARVALID and MMFAR equal to testAddress, and the scratch word content is unchanged.
ERROR_STATUS - The scratch word did not hold expectedValue on entry, the expected fault was not observed, or the scratch word content changed during the test. A higher-numbered region overlapping the scratch block also causes this result (see stl_mpu_entry_t::regionNumber).
ERROR_INCORRECT_USAGE_STATUS - The ARM core MPU is disabled (MPU->CTRL.ENABLE = 0). Nothing is written, including the scratch word.
ERROR_BAD_PARAM - Invalid entry: null pointers, writeValue equal to expectedValue, regionNumber out of range or selecting an enabled region, or testAddress not aligned to MPU_TEST_BLOCK_BYTES. The MPU configuration and the scratch word are unchanged.

Note

Before calling this function the ARM core MPU must be enabled, the scratch word must hold stl_mpu_entry_t::expectedValue, and the application must have installed its MemManage_Handler trampoline. See Memory and Storage Integrity Tests.

Side effects on entry:

• SCB->SHCSR.MEMFAULTENA is forced on for the duration of the call (its prior state is saved and restored on exit) so the denied access reports as a MemManage fault instead of escalating to HardFault.
• All SCB->CFSR.MMFSR bits (and so MMFAR validity) left over from an earlier MemManage fault are cleared. BFSR and UFSR are untouched.
• The MPU region selected by stl_mpu_entry_t::regionNumber, which must be disabled, is reprogrammed read-only over the MPU_TEST_BLOCK_BYTES block at stl_mpu_entry_t::testAddress.

Side effects on exit:

• The borrowed MPU region is released (disabled); the rest of the MPU configuration is left untouched.
• SCB->SHCSR.MEMFAULTENA is restored to its value on entry.
• MPU->RNR is restored to its value on entry.
• The application's MemManage_Handler stays installed; after this call returns, SelfTest_MPU_HandleMemManage() will return false for any further MemManage fault so the application's normal policy runs.

This is a startup test: call it once during initialization (before an RTOS scheduler starts, if one is used) and before the final operational protection policy is armed. It is blocking (the denied write and its recovery complete before the function returns), is not reentrant, and must not be called from an ISR or any other exception handler.

Interrupts are not masked during the test. An interrupt cannot cause a false OK_STATUS. An interrupt that reprograms the borrowed region, disables the MPU or writes to the scratch block causes ERROR_STATUS or a MemManage fault handled by the application's policy. MemManage must not be masked when the function is called: no PRIMASK or FAULTMASK (for example inside __disable_irq() or Cy_SysLib_EnterCriticalSection()) and no BASEPRI at or above the MemManage priority. These conditions are not checked at runtime. If MemManage is masked, the deliberate fault escalates to HardFault, which cannot produce a false OK_STATUS.

Any other MemManage fault raised while this function runs is not consumed by SelfTest_MPU_HandleMemManage() and reaches the application's MemManage policy.

SelfTest_MPU_HandleMemManage()

bool SelfTest_MPU_HandleMemManage

(

uint32_t *

stack

)

MemManage dispatch entry for the application's MemManage_Handler trampoline.

Recovers the deliberate denied write driven by SelfTest_MPU (rewrites the stacked PC to the STL resume point) and returns true.

A fault is accepted as the deliberate one only if all of the following are true:

• SelfTest_MPU is inside its test window,
• the stacked PC is the denied STR in the STL write helper,
• CFSR.MMFSR is exactly DACCVIOL | MMARVALID, and
• MMFAR equals stl_mpu_entry_t::testAddress.

Any other MemManage fault, inside or outside the test window, is left untouched and false is returned so the application's normal policy handles it.

Parameters

stack

Pointer to the exception stack frame (r0, r1, r2, r3, r12, lr, pc, xpsr) that was active when the fault occurred, selected from MSP or PSP by the application trampoline. NULL is rejected (returns false).

Returns

true - Fault was the STL's deliberate denied write; stack[6] has been rewritten to resume execution after the store and CFSR.DACCVIOL / CFSR.MMARVALID have been cleared (other CFSR bits are preserved). The application trampoline must return normally so the exception return uses the (unchanged) EXC_RETURN value in LR.
false - stack is NULL, or the fault does not match the criteria above. stack, SCB->CFSR, SCB->MMFAR and the STL state are untouched. The application trampoline must invoke its own MemManage policy.

Note

This function is safe to call from the MemManage exception context. It must not be called from ordinary code and must not be treated as a general test API.