Sparse MMIO model implementation (see emu_mmio.h). More...

#include "emu_mmio.h"
#include <stdio.h>
#include "board_periph.h"
#include "emu_cpu1.h"
#include "emu_host_io_internal.h"

Include dependency graph for emu_mmio.c:

Enumerations
enum	emu_mmio_cfg_t : uint32_t { k_mmio_slots = 2048U , k_mmio_settle = 8U , k_mmio_print_max = 256U , k_u32_all_ones = 0xFFFFFFFFU }
	Sparse-model sizing and settle thresholds. More...
enum	mrms_quirk_t : uint64_t { k_mrms_mrcfreq = 0x4013C004UL , k_mrms_mrefreq = 0x4013C008UL , k_mrms_freq_mask = 0x00FFFFFFUL }

Functions
static RA8_INTERNAL void	internal_bgc_track (uint32_t value)
	Record a BG_BGC write; remember the value if it is a new colour.
static RA8_INTERNAL int	internal_mmio_index (uint64_t addr)
	Find (or add) a slot for a distinct MMIO address; -1 if table full.
uint64_t	mmio_read (uc_engine uc, uint64_t offset, unsigned size, void user)
	UC_MMIO read 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.
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	emu_mmio_reads (void)
	Implementation of emu_mmio_reads() – plain counter read.
uint32_t	emu_mmio_writes (void)
	Implementation of emu_mmio_writes() – plain counter read.
void	emu_mmio_print_counts (void)
	Implementation of emu_mmio_print_counts() – run-end report line.
void	emu_mmio_print_bgc_and_table (void)
	Implementation of emu_mmio_print_bgc_and_table() – run-end report.

Variables
static uint64_t	s_mmio_addr [k_mmio_slots]
static uint32_t	s_mmio_val [k_mmio_slots]
static bool	s_mmio_written [k_mmio_slots]
static uint32_t	s_mmio_rcount [k_mmio_slots]
static uint32_t	s_mmio_wcount [k_mmio_slots]
static uint32_t	s_mmio_n
static uint32_t	s_mmio_reads
static uint32_t	s_mmio_writes
static uint32_t	s_mmio_toggle
static int	s_mmio_cache = -1
	1-entry address->slot lookup cache.
static int	s_mmio_run_slot = -1
	Slot of the current read run.
static uint32_t	s_mmio_run
	Consecutive reads of that slot.
static uint32_t	s_bgc_writes
static uint32_t	s_bgc_distinct [k_bgc_track_max]
static uint32_t	s_bgc_distinct_n

Detailed Description

Sparse MMIO model implementation (see emu_mmio.h).

The slot table, settle toggle, MRMS readback quirk, BG_BGC witness and the run-end report – moved verbatim out of the ra8_emulator main translation unit. Modelled board_periph blocks always answer first; this model is the fallback for addresses no block owns.

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

Since: 0.1.0

Definition in file emu_mmio.c.

Enumeration Type Documentation

◆ emu_mmio_cfg_t

enum emu_mmio_cfg_t : uint32_t

Sparse-model sizing and settle thresholds.

Enumerator
k_mmio_slots	Distinct MMIO addresses tracked.
k_mmio_settle	Same-addr reads before a poll "settles".
k_mmio_print_max	Max MMIO rows printed in the summary.
k_u32_all_ones	All bits set (MMIO read toggle).

Definition at line 25 of file emu_mmio.c.

◆ mrms_quirk_t

enum mrms_quirk_t : uint64_t

Enumerator
k_mrms_mrcfreq	MRICLK freq latch (write key 0x1E).
k_mrms_mrefreq	MRPCLK freq latch (write key 0xE1).
k_mrms_freq_mask	Key byte (bits[31:24]) stripped.

Definition at line 42 of file emu_mmio.c.

Function Documentation

◆ emu_mmio_print_bgc_and_table()

void emu_mmio_print_bgc_and_table ( void )

Implementation of emu_mmio_print_bgc_and_table() – run-end report.

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 )

Implementation of emu_mmio_print_counts() – run-end report line.

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 )

Implementation of emu_mmio_reads() – plain counter read.

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 )

Implementation of emu_mmio_writes() – plain counter read.

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().

◆ internal_bgc_track()

RA8_INTERNAL void internal_bgc_track ( uint32_t value )

static

Record a BG_BGC write; remember the value if it is a new colour.

Record a bg_bgc write; remember the value if it is a new colour; this step is contained within the emu MMIO model and uses bounded caller or module-owned storage.

Parameters

[in] value Register or payload value involved in the operation.

Precondition: Arguments satisfy the ranges documented for bgc track.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu MMIO model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 86 of file emu_mmio.c.

References k_bgc_track_max, RA8_INTERNAL, s_bgc_distinct, s_bgc_distinct_n, and s_bgc_writes.

Referenced by mmio_write().

◆ internal_mmio_index()

RA8_INTERNAL int internal_mmio_index ( uint64_t addr )

static

Find (or add) a slot for a distinct MMIO address; -1 if table full.

Find (or add) a slot for a distinct mmio address; -1 if table full; this step is contained within the emu MMIO model and uses bounded caller or module-owned storage.

Parameters

[in] addr Guest address involved in the operation.

Returns: The MMIO index result produced by the emu MMIO model.

Return values

value The operation-specific MMIO index value.

Precondition: Arguments satisfy the ranges documented for MMIO index.; The call executes on the emulator's single owning thread.

Postcondition: State changes remain confined to the emu MMIO model and documented output objects.; Ownership of caller-supplied storage is unchanged.

Note: The operation is synchronous and does not transfer heap ownership.

Since: 0.1.0

Definition at line 110 of file emu_mmio.c.

References k_mmio_slots, RA8_INTERNAL, s_mmio_addr, s_mmio_cache, and s_mmio_n.

Referenced by mmio_read(), and mmio_write().

◆ 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. ::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().

Variable Documentation

◆ s_bgc_distinct

uint32_t s_bgc_distinct

static

Definition at line 70 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), and internal_bgc_track().

◆ s_bgc_distinct_n

uint32_t s_bgc_distinct_n

static

Definition at line 71 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), and internal_bgc_track().

◆ s_bgc_writes

uint32_t s_bgc_writes

static

Definition at line 69 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), and internal_bgc_track().

◆ s_mmio_addr

uint64_t s_mmio_addr[k_mmio_slots]

static

Definition at line 54 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), internal_mmio_index(), and mmio_peek().

◆ s_mmio_cache

int s_mmio_cache = -1

static

1-entry address->slot lookup cache.

Definition at line 64 of file emu_mmio.c.

Referenced by internal_mmio_index().

◆ s_mmio_n

uint32_t s_mmio_n

static

Definition at line 59 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), emu_mmio_print_counts(), internal_mmio_index(), and mmio_peek().

◆ s_mmio_rcount

uint32_t s_mmio_rcount[k_mmio_slots]

static

Definition at line 57 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), and mmio_read().

◆ s_mmio_reads

uint32_t s_mmio_reads

static

Definition at line 60 of file emu_mmio.c.

Referenced by emu_mmio_print_counts(), emu_mmio_reads(), and mmio_read().

◆ s_mmio_run

uint32_t s_mmio_run

static

Consecutive reads of that slot.

Definition at line 66 of file emu_mmio.c.

Referenced by mmio_read(), and mmio_write().

◆ s_mmio_run_slot

int s_mmio_run_slot = -1

static

Slot of the current read run.

Definition at line 65 of file emu_mmio.c.

Referenced by mmio_read(), and mmio_write().

◆ s_mmio_toggle

uint32_t s_mmio_toggle

static

Definition at line 62 of file emu_mmio.c.

Referenced by mmio_read().

◆ s_mmio_val

uint32_t s_mmio_val[k_mmio_slots]

static

Definition at line 55 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), mmio_peek(), mmio_read(), and mmio_write().

◆ s_mmio_wcount

uint32_t s_mmio_wcount[k_mmio_slots]

static

Definition at line 58 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), and mmio_write().

◆ s_mmio_writes

uint32_t s_mmio_writes

static

Definition at line 61 of file emu_mmio.c.

Referenced by emu_mmio_print_counts(), emu_mmio_writes(), and mmio_write().

◆ s_mmio_written

bool s_mmio_written[k_mmio_slots]

static

Definition at line 56 of file emu_mmio.c.

Referenced by emu_mmio_print_bgc_and_table(), mmio_peek(), mmio_read(), and mmio_write().

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ emu_mmio_cfg_t

◆ mrms_quirk_t

Function Documentation

◆ emu_mmio_print_bgc_and_table()

◆ emu_mmio_print_counts()

◆ emu_mmio_reads()

◆ emu_mmio_writes()

◆ internal_bgc_track()

◆ internal_mmio_index()

◆ mmio_peek()

◆ mmio_read()

◆ mmio_write()

Variable Documentation

◆ s_bgc_distinct

◆ s_bgc_distinct_n

◆ s_bgc_writes

◆ s_mmio_addr

◆ s_mmio_cache

◆ s_mmio_n

◆ s_mmio_rcount

◆ s_mmio_reads

◆ s_mmio_run

◆ s_mmio_run_slot

◆ s_mmio_toggle

◆ s_mmio_val

◆ s_mmio_wcount

◆ s_mmio_writes

◆ s_mmio_written