emu_mmio.h File Reference

Sparse MMIO model of the Renesas peripheral space. More...

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

Include dependency graph for emu_mmio.h:

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

Go to the source code of this file.

Enumerations
enum	periph_map_t : uint64_t {   k_periph_base = 0x40000000UL ,   k_periph_size = 0x10000000UL }
	Renesas peripheral window (modelled as logged MMIO). More...
enum	glcdc_obs_t : uint64_t {   k_glcdc_bg_bgc = 0x40343014UL ,   k_bgc_track_max = 32UL }

Functions
uint64_t	mmio_read (uc_engine *uc, uint64_t offset, unsigned size, void *user)
	UC_MMIO read callback for the peripheral window.
void	mmio_write (uc_engine *uc, uint64_t offset, unsigned size, uint64_t value, void *user)
	UC_MMIO write callback for the peripheral window.
uint32_t	mmio_peek (uint64_t addr)
	Side-effect-free read of the last value written to a peripheral reg.
uint32_t	emu_mmio_reads (void)
	Total peripheral MMIO reads this run (monotonic).
uint32_t	emu_mmio_writes (void)
	Total peripheral MMIO writes this run (monotonic).
void	emu_mmio_print_counts (void)
	Print the run-end MMIO counters line to injected error sink.
void	emu_mmio_print_bgc_and_table (void)
	Print the BG_BGC witness and the per-address MMIO table to injected error sink.

Detailed Description

Sparse MMIO model of the Renesas peripheral space.

The fallback register model behind board_periph's block registry: each touched address gets a slot; control writes are reflected back on read so "configure then verify" works, and a spin-poll on one address eventually alternates 0 / all-ones so a single-bit ready/idle poll completes either way. Also owns the MRMS frequency-latch readback quirk, the BG_BGC colour-cycle witness, the access counters the idle-stop signature and the board view read, and the run-end MMIO report. The read/write callbacks are installed by emu_memmap on the Secure window and its bit[28] Non-secure alias (and again on the cpu1 engine), all dispatching to one model.

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

Enumeration Type Documentation

glcdc_obs_t

enum glcdc_obs_t : uint64_t

Enumerator
k_glcdc_bg_bgc	GLCDC BG.BGC background colour.
k_bgc_track_max	Distinct BG_BGC values remembered.

Definition at line 56 of file emu_mmio.h.

periph_map_t

enum periph_map_t : uint64_t

Renesas peripheral window (modelled as logged MMIO).

The Secure physical window; the IDAU bit[28] alias adds 0x10000000. Reads of unmodelled registers return all-ones/0 alternation so "wait for ready bit" polls fall through instead of spinning forever.

Invariant

The window covers every Renesas peripheral block.

See also

emu_memmap_attach() Installs the callbacks over this window.

Since

0.1.0

Enumerator
k_periph_base	Peripheral window base.
k_periph_size	0x40000000-0x4FFFFFFF: all Renesas peripherals.

Definition at line 46 of file emu_mmio.h.

Function Documentation

emu_mmio_print_bgc_and_table()

void emu_mmio_print_bgc_and_table

(

void

)

Print the BG_BGC witness and the per-address MMIO table to injected error sink.

Emits the GLCDC colour-cycle witness line (write count + distinct colours) followed by the per-address reads/writes/last-write table, capped at the print maximum with a ... (N more) trailer – exactly as the run-end report always printed them.

Returns

Nothing.

Precondition

The run has ended (the shadow is final).

injected error sink is writable.

Postcondition

The witness + table lines were written.

Note

Not thread-safe; call once at run end.

See also

emu_mmio_print_counts() The counters line printed just before.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Print the BG_BGC witness and the per-address MMIO table to injected error sink.

Definition at line 243 of file emu_mmio.c.

References k_mmio_print_max, priv_emu_io_errf(), s_bgc_distinct, s_bgc_distinct_n, s_bgc_writes, s_mmio_addr, s_mmio_n, s_mmio_rcount, s_mmio_val, s_mmio_wcount, and s_mmio_written.

Referenced by internal_run_print_stop_summary().

emu_mmio_print_counts()

void emu_mmio_print_counts

(

void

)

Print the run-end MMIO counters line to injected error sink.

Emits the MMIO reads : ... writes: ... distinct addrs: ... report line, exactly as the run-end report always printed it.

Returns

Nothing.

Precondition

The run has ended (counters are final).

injected error sink is writable.

Postcondition

One report line was written.

Note

Not thread-safe; call once at run end.

See also

emu_mmio_print_bgc_and_table() The rest of the MMIO report.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Print the run-end MMIO counters line to injected error sink.

Definition at line 234 of file emu_mmio.c.

References priv_emu_io_errf(), s_mmio_n, s_mmio_reads, and s_mmio_writes.

Referenced by internal_run_print_stop_summary().

emu_mmio_reads()

uint32_t emu_mmio_reads

(

void

)

Total peripheral MMIO reads this run (monotonic).

Returns

The read counter.

Return values

0	No peripheral read has happened yet.

Precondition

None.

None.

Postcondition

No state is modified.

Note

Feeds the idle-stop signature and the board-view telemetry.

Since

0.1.0

Total peripheral mmio reads this run (monotonic); this step is contained within the emu MMIO model and uses bounded caller or module-owned storage.

Postcondition

Ownership of caller-supplied storage is unchanged.

Total peripheral MMIO reads this run (monotonic).

Definition at line 222 of file emu_mmio.c.

References s_mmio_reads.

Referenced by internal_fill_status_console(), and internal_run_stop_idle().

emu_mmio_writes()

uint32_t emu_mmio_writes

(

void

)

Total peripheral MMIO writes this run (monotonic).

Returns

The write counter.

Return values

0	No peripheral write has happened yet.

Precondition

None.

None.

Postcondition

No state is modified.

Note

Feeds the idle-stop signature and the board-view telemetry.

Since

0.1.0

Total peripheral mmio writes this run (monotonic); this step is contained within the emu MMIO model and uses bounded caller or module-owned storage.

Postcondition

Ownership of caller-supplied storage is unchanged.

Total peripheral MMIO writes this run (monotonic).

Definition at line 228 of file emu_mmio.c.

References s_mmio_writes.

Referenced by internal_fill_status_console(), and internal_run_stop_idle().

mmio_peek()

uint32_t mmio_peek

(

uint64_t

addr

)

Side-effect-free read of the last value written to a peripheral reg.

Returns the value last written to addr, or 0 if it was never written – searching the MMIO shadow WITHOUT allocating a slot and WITHOUT advancing the spin-settle toggle that mmio_read() uses. ra8_emulator's own introspection (e.g. the panel composer reading GLCDC registers) must see stable state: a firmware that never programs the GLCDC would otherwise read the status-poll fallthrough (an alternating 0/0xFFFFFFFF), which made the panel strobe black<->white every frame. A real read of an unwritten register reset-defaults to 0 here, so the panel is a steady background.

Parameters

[in]

addr

Absolute peripheral register address.

Returns

The last written value, or 0 when never written.

Return values

0	The register was never written (reset default).

Precondition

The sparse model is live (any time after setup).

addr is a peripheral-window address.

Postcondition

No counters or settle state changed (pure lookup).

Note

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

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Returns the value last written to addr, or 0 if it was never written – searching the MMIO shadow WITHOUT allocating a slot and WITHOUT advancing the spin-settle toggle that mmio_read uses. ra8_emulator's own introspection (e.g. ::build_frame reading GLCDC registers to compose the panel) must see stable state: a firmware that never programs the GLCDC (blink, USB, UART demos) would otherwise read the status-poll fallthrough (an alternating 0/0xFFFFFFFF), which made the panel strobe black<->white every frame. A real read of an unwritten register reset-defaults to 0 here, so the panel is a steady background.

Definition at line 177 of file emu_mmio.c.

References s_mmio_addr, s_mmio_n, s_mmio_val, and s_mmio_written.

Referenced by internal_layer(), and priv_emu_view_surface_build().

mmio_read()

uint64_t mmio_read	(	uc_engine *	uc,
		uint64_t	offset,
		unsigned	size,
		void *	user )

UC_MMIO read callback for the peripheral window.

A modelled board_periph block answers first; the sparse fallback reflects written control values until a spin-poll settles, then alternates 0 / all-ones. The MRMS frequency latches strip their key byte on readback.

Parameters

[in,out]	uc	Unicorn engine performing the read.
[in]	offset	Byte offset within the mapped window.
[in]	size	Access width in bytes.
[in]	user	Hook cookie (unused).

Returns

The value the firmware reads.

Return values

0	One phase of the settle toggle (with all-ones as the other).

Precondition

The window was installed by emu_memmap_attach().

offset lies inside the mapped window.

Postcondition

The access counters and per-slot read runs are updated.

Note

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

See also

mmio_write() The write-side counterpart.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 129 of file emu_mmio.c.

References board_periph_read(), internal_mmio_index(), k_mmio_settle, k_mrms_freq_mask, k_mrms_mrcfreq, k_mrms_mrefreq, k_periph_base, k_u32_all_ones, s_mmio_rcount, s_mmio_reads, s_mmio_run, s_mmio_run_slot, s_mmio_toggle, s_mmio_val, and s_mmio_written.

Referenced by internal_map_periph_mmio().

mmio_write()

void mmio_write	(	uc_engine *	uc,
		uint64_t	offset,
		unsigned	size,
		uint64_t	value,
		void *	user )

UC_MMIO write callback for the peripheral window.

Notifies the dual-core release watcher, tracks the BG_BGC colour-cycle witness, offers the write to the modelled board_periph blocks first, and otherwise records it in the sparse shadow for readback and the run-end table.

Parameters

[in,out]	uc	Unicorn engine performing the write.
[in]	offset	Byte offset within the mapped window.
[in]	size	Access width in bytes.
[in]	value	Value being written.
[in]	user	Hook cookie (unused).

Returns

Nothing.

Precondition

The window was installed by emu_memmap_attach().

offset lies inside the mapped window.

Postcondition

The write landed in a block model or the sparse shadow.

Note

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

See also

mmio_read() The read-side counterpart.

Since

0.1.0

Postcondition

Ownership of caller-supplied storage is unchanged.

Definition at line 187 of file emu_mmio.c.

References board_periph_write(), emu_cpu1_notify_mmio_write(), internal_bgc_track(), internal_mmio_index(), k_glcdc_bg_bgc, k_periph_base, s_mmio_run, s_mmio_run_slot, s_mmio_val, s_mmio_wcount, s_mmio_writes, and s_mmio_written.

Referenced by internal_map_periph_mmio().