emu_mpu.h File Reference

Armv8-M MPU enforcement model for ra8_emulator. More...

#include <stdint.h>
#include <unicorn/unicorn.h>
#include "ra8_attributes.h"

Include dependency graph for emu_mpu.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Functions
void	emu_mpu_install (uc_engine *uc)
	Arm the MPU register watchers (RLAR capture + CTRL edge hooks).
bool	emu_mpu_fault_pending (void)
	Whether an RO-region write violation is latched.
void	emu_mpu_clear_fault (void)
	Clear the latched MPU violation.
void	mpu_synth_memmanage (uc_engine *uc, uint32_t vtor_base)
	Synthesise a MemManage (#4) fault for a trapped RO-region write.

Detailed Description

Armv8-M MPU enforcement model for ra8_emulator.

The firmware programs the MPU via ra8_mpu (RNR -> RBAR -> RLAR per region, then CTRL). ra8_emulator watches those writes (no banked per-region storage in the flat-RAM PPB, so each region is captured at its RLAR write) and, while CTRL.ENABLE is set, faults a privileged store into any read-only region with a synthesised MemManage – the part Unicorn's core does not model. Inert unless the firmware enables the MPU.

Split out of the ra8_emulator main translation unit; behaviour unchanged.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since

0.1.0

Definition in file emu_mpu.h.

Function Documentation

emu_mpu_clear_fault()

void emu_mpu_clear_fault

(

void

)

Clear the latched MPU violation.

The run loop clears the latch right before synthesising the MemManage; the warm-reboot path clears it so a rebooted image starts clean.

Returns

Nothing.

Precondition

A violation was latched (or the call is a harmless reset).

None otherwise.

Postcondition

No MPU violation is pending.

Note

Not thread-safe; the emulator is single-threaded host-side.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Clear the latched MPU violation.

Definition at line 326 of file emu_mpu.c.

References s_mpu_fault.

Referenced by internal_run_inner_take_exception(), and warm_reboot().

emu_mpu_fault_pending()

bool emu_mpu_fault_pending

(

void

)

Whether an RO-region write violation is latched.

Returns

true while a trapped store awaits its synthesised MemManage.

Return values

false

No MPU violation is pending.

Precondition

None.

None.

Postcondition

No state is modified.

Note

Not thread-safe; the emulator is single-threaded host-side.

Since

0.1.0

Whether an ro-region write violation is latched; this step is contained within the emu MPU model and uses bounded caller or module-owned storage.

Postcondition

Ownership of caller-supplied storage is unchanged.

Whether an RO-region write violation is latched.

Definition at line 320 of file emu_mpu.c.

References s_mpu_fault.

Referenced by internal_run_inner_take_exception().

emu_mpu_install()

void emu_mpu_install

(

uc_engine *

uc

)

Arm the MPU register watchers (RLAR capture + CTRL edge hooks).

Returns

Nothing.

Precondition

uc is initialised with the PPB mapped as RAM.

Called once during single-threaded setup.

Postcondition

The MPU_RLAR and MPU_CTRL write hooks are installed.

Note

Apps that never program the MPU pay nothing beyond the two hooks.

Since

0.1.0

Arm the mpu register watchers (rlar capture + ctrl edge hooks); this step is contained within the emu MPU model and uses bounded caller or module-owned storage.

Parameters

[in,out]

uc

Unicorn engine whose emulated state is read or updated.

Postcondition

Ownership of caller-supplied storage is unchanged.

Arm the MPU register watchers (RLAR capture + CTRL edge hooks).

Definition at line 295 of file emu_mpu.c.

References internal_on_mpu_ctrl_write(), internal_on_mpu_rlar_write(), k_mpu_ctrl, and k_mpu_rlar.

Referenced by internal_main_install_core_seams().

mpu_synth_memmanage()

void mpu_synth_memmanage	(	uc_engine *	uc,
		uint32_t	vtor_base )

Synthesise a MemManage (#4) fault for a trapped RO-region write.

Called by the run loop after the RO-write hook latched a violation. Latches CFSR.MMFSR.DACCVIOL + MMARVALID and MMFAR (so a fault handler – and the HIL alive probe – see the architectural status), forces PC back to the faulting store so the exception entry stacks that address (a recovering handler skips exactly one store), and vectors into the application's MemManage_Handler. If no handler is installed the violation is dropped (no escalation modelled).

Parameters

[in,out]	uc	Unicorn engine.
[in]	vtor_base	Fallback vector base if VTOR reads as 0.

Returns

Nothing.

Precondition

A violation is latched (PC / address captured at the trapped store).

The PPB CFSR / MMFAR words and the vector table are mapped as RAM.

Postcondition

On a valid vector, the core is in the MemManage handler with the basic frame stacked (stacked PC == the faulting store).

Note

Faithful to the recovering-handler contract of mpu_partition_simple.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Called by the run loop after internal_on_mpu_ro_write latched a violation. Latches CFSR.MMFSR.DACCVIOL + MMARVALID and MMFAR (so a fault handler – and the HIL alive probe – see the architectural status), forces PC back to the faulting store so exc_enter stacks that address (a recovering handler skips exactly one store), and vectors into the application's MemManage_Handler. If no handler is installed the violation is dropped (no escalation modelled).

Parameters

[in,out]	uc	Unicorn engine.
[in]	vtor_base	Fallback vector base if VTOR reads as 0.

Returns

Nothing.

Precondition

s_mpu_fault_pc / s_mpu_fault_addr hold the trapped store.

The PPB CFSR / MMFAR words and the vector table are mapped as RAM.

Postcondition

On a valid vector, the core is in the MemManage handler with the basic frame stacked (stacked PC == the faulting store).

CFSR.MMFSR and MMFAR reflect a data-access violation.

Note

Faithful to the recovering-handler contract of mpu_partition_simple.

Since

0.1.0

Definition at line 281 of file emu_mpu.c.

References exc_enter(), exc_vector(), k_cfsr_mmfsr_daccviol, k_cfsr_mmfsr_mmarvalid, k_exc_memmanage, k_scb_cfsr, k_scb_mmfar, rd32(), s_mpu_fault_addr, s_mpu_fault_pc, and wr32().

Referenced by internal_run_inner_take_exception().