emu_engine.h File Reference

Shared Unicorn engine access utilities for the board emulator. More...

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

Include dependency graph for emu_engine.h:

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

Go to the source code of this file.

Functions
static uint32_t	rd32 (uc_engine *uc, uint64_t addr)
	Read a 32-bit little-endian word from emulated memory.
static void	wr32 (uc_engine *uc, uint64_t addr, uint32_t v)
	Write a 32-bit little-endian word to emulated memory.
static uint32_t	reg_get (uc_engine *uc, int reg)
	Read a Unicorn 32-bit register by its UC_ARM_REG_* id.
static void	reg_set (uc_engine *uc, int reg, uint32_t v)
	Write a Unicorn 32-bit register by its UC_ARM_REG_* id.
void	emu_seam_request_relaunch (void)
	Mark the pending engine stop as a zero-time seam relaunch.
bool	emu_seam_take_relaunch (void)
	Consume the zero-time seam-relaunch latch.

Variables
const int	k_arm_reg_id [16]
	ARM register index (0..15) -> Unicorn register id.

Detailed Description

Shared Unicorn engine access utilities for the board emulator.

The tiny register/memory accessors every emulator module leans on: 32-bit little-endian reads/writes of emulated memory (the PPB words the exception and fault models poll/edit) and whole-register reads/writes by UC_ARM_REG_* id, plus the ARM register-index -> Unicorn-register-id mapping table shared by the instruction seams (conditional-select, LOB, long-shift, div-0). The accessors are static inline so each including translation unit gets a zero-overhead copy; the mapping table has one definition (emu_engine.c).

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_engine.h.

Function Documentation

emu_seam_request_relaunch()

void emu_seam_request_relaunch

(

void

)

Mark the pending engine stop as a zero-time seam relaunch.

A C-seam that returned to the firmware's caller (a –fast-sd block serve, an emulated armed divide) consumed no modelled time: the inner run loop must relaunch from the returned PC WITHOUT advancing SysTick or charging an outer chunk. The seam sets this latch right before stopping the engine; the run loop consumes it via emu_seam_take_relaunch().

Returns

Nothing.

Precondition

A seam is about to stop the engine after editing PC.

The run loop is mid-chunk (single-threaded).

Postcondition

The next engine stop is treated as a zero-time relaunch.

Note

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

See also

emu_seam_take_relaunch() The run-loop consumer.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Mark the pending engine stop as a zero-time seam relaunch.

Definition at line 52 of file emu_engine.c.

References s_seam_relaunch.

Referenced by emulate_div0_patched(), and internal_on_sdmmc_read_block().

emu_seam_take_relaunch()

bool emu_seam_take_relaunch

(

void

)

Consume the zero-time seam-relaunch latch.

Returns whether the latch was set and clears it, so the run loop can continue at the returned PC without advancing modelled time. Exactly one consumer (the inner run loop) per stop.

Returns

true if a seam requested a zero-time relaunch since the last take.

Return values

false

No seam relaunch is pending (normal stop handling proceeds).

Precondition

The engine just stopped (uc_emu_start returned).

The run loop is the only caller.

Postcondition

The latch is clear.

Note

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

See also

emu_seam_request_relaunch() The seam-side producer.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Consume the zero-time seam-relaunch latch.

Definition at line 58 of file emu_engine.c.

References s_seam_relaunch.

Referenced by internal_run_inner_check_stops().

rd32()

uint32_t rd32 ( uc_engine * uc, uint64_t addr )

inlinestatic

Read a 32-bit little-endian word from emulated memory.

Thin uc_mem_read wrapper; an unmapped/failed read yields 0, which every caller treats as the reset-default value of the polled word.

Parameters

[in,out]	uc	Unicorn engine to read from.
[in]	addr	Emulated address of the word.

Returns

The 32-bit word at addr, or 0 on a failed read.

Precondition

uc is an initialised engine.

addr is intended to be a mapped 4-byte word.

Postcondition

No engine state is modified beyond the read itself.

Note

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

Since

0.1.0

Return values

value

The operation-specific rd32 value.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 67 of file emu_engine.h.

References emu_mem_read().

Referenced by div0_synth_usagefault(), dwt_cyccnt_advance(), emu_cpu1_step(), emulate_div0_patched(), exc_return(), exc_take_pending(), exc_vector(), internal_exc_priority(), internal_exc_restore_fp_frame(), internal_exc_take_periph_irq(), internal_on_mpu_rlar_write(), and mpu_synth_memmanage().

reg_get()

uint32_t reg_get ( uc_engine * uc, int reg )

inlinestatic

Read a Unicorn 32-bit register by its UC_ARM_REG_* id.

Thin uc_reg_read wrapper returning the value directly so callers can use it in expressions; a failed read yields 0.

Parameters

[in,out]	uc	Unicorn engine.
[in]	reg	UC_ARM_REG_* register id.

Returns

The register's 32-bit value, or 0 on a failed read.

Precondition

uc is an initialised engine.

reg names a 32-bit-readable register.

Postcondition

No engine state is modified beyond the read itself.

Note

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

Since

0.1.0

Return values

value

The operation-specific reg get value.

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 113 of file emu_engine.h.

Referenced by exc_enter(), exc_return(), exc_take_pending(), internal_exc_restore_mode(), internal_exc_stack_frame(), and internal_on_mpu_ro_write().

reg_set()

void reg_set ( uc_engine * uc, int reg, uint32_t v )

inlinestatic

Write a Unicorn 32-bit register by its UC_ARM_REG_* id.

Thin uc_reg_write wrapper; a failed write is ignored, matching the original tolerant register-edit behaviour.

Parameters

[in,out]	uc	Unicorn engine.
[in]	reg	UC_ARM_REG_* register id.
[in]	v	Value to store.

Returns

Nothing.

Precondition

uc is an initialised engine.

reg names a 32-bit-writable register.

Postcondition

On success the register holds v.

Note

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

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 137 of file emu_engine.h.

Referenced by exc_enter(), exc_return(), internal_exc_restore_fp_frame(), and internal_exc_restore_mode().

wr32()

void wr32 ( uc_engine * uc, uint64_t addr, uint32_t v )

inlinestatic

Write a 32-bit little-endian word to emulated memory.

Thin uc_mem_write wrapper; a failed write (unmapped address) is ignored, matching the original tolerant PPB-word edit behaviour.

Parameters

[in,out]	uc	Unicorn engine to write into.
[in]	addr	Emulated address of the word.
[in]	v	Value to store.

Returns

Nothing.

Precondition

uc is an initialised engine.

addr is intended to be a mapped 4-byte word.

Postcondition

On success the word at addr holds v.

Note

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

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 91 of file emu_engine.h.

References emu_mem_write().

Referenced by div0_synth_usagefault(), dwt_cyccnt_advance(), exc_take_pending(), internal_exc_stack_frame(), internal_exc_take_periph_irq(), internal_main_open_engine(), and mpu_synth_memmanage().

Variable Documentation

k_arm_reg_id

const int k_arm_reg_id[16]

extern

ARM register index (0..15) -> Unicorn register id.

Unicorn's UC_ARM_REG_* enum is NOT contiguous (UC_ARM_REG_R0 + n != UC_ARM_REG_Rn), so every instruction seam that decodes a 4-bit register field maps it through this table. PC(15)/SP(13)/LR(14) are never CSx destinations in practice but are mapped for completeness.

Note

Read-only lookup table; safe to share across every module.

Warning

Do not index with a value above 15 (a decoded 4-bit field cannot produce one).

Since

0.1.0

Definition at line 17 of file emu_engine.c.

Referenced by emulate_div0_patched(), emulate_long_shift_reg(), internal_emulate_cond_select(), internal_emulate_lob(), internal_long_shift_amount(), internal_long_shift_begin(), internal_long_shift_commit(), and internal_mve_mem_exec().