Shared run-loop state + cross-TU run helpers (ra8_emulator internal). More...

#include <stdint.h>
#include <time.h>
#include <unicorn/unicorn.h>
#include "board_overlay.h"
#include "board_view.h"
#include "emu_run.h"
#include "ra8_attributes.h"

Include dependency graph for emu_run_internal.h:

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

Go to the source code of this file.

Data Structures
struct	run_loop_t
	The whole run's mutable state, threaded through the phase helpers. More...

Functions
bool	priv_run_inner (uc_engine uc, uint32_t vtor_base, uint32_t run_pc_io, uc_err *err_out)
	Run one outer chunk's inner exception-resolve loop.
void	priv_run_report (const run_loop_t *st)
	Print the run-end report (stop summary, verdict, –dump-sym probes).
void	priv_run_write_outputs (const run_loop_t *st)
	Write the –ppm snapshot and the –record summary line.
void	priv_run_hold_view (const run_loop_t *st)
	Hold the live window on the final frame until the user closes it.
int	priv_run_cleanup (const run_loop_t *st)
	Save the SD image, close owned descriptors + engine, map the exit code.

Detailed Description

Shared run-loop state + cross-TU run helpers (ra8_emulator internal).

The chunked run phase is split across three translation units to keep each under the file-size bar: emu_run.c (setup + the per-chunk phase helpers + the driver), emu_run_inner.c (the inner exception-resolve loop) and emu_run_report.c (the run-end report + finalize). This internal header carries the pieces those TUs share: the run_loop_t mutable state bundle and the RA8_PRIV declarations of the helpers called across the split. It is NOT part of the ra8_emulator public surface (unlike emu_run.h).

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

Since: 0.1.0

Definition in file emu_run_internal.h.

Function Documentation

◆ priv_run_cleanup()

int priv_run_cleanup ( const run_loop_t * st )

Save the SD image, close owned descriptors + engine, map the exit code.

Defined in emu_run_report.c; called by emu_run_and_report as the final teardown step.

Parameters

[in] st The run state (surface, engine, stop flags).

Returns: The process exit status (emu_exit_t).

Return values

k_emu_exit_ok	Clean run-to-budget.
k_emu_exit_bkpt	Firmware executed a BKPT.
k_emu_exit_fault	Emulation fault ended the run.
k_emu_exit_timeout	Wall-clock budget reached.

Precondition: The run loop has ended and outputs have been written.; st owns the surface descriptor, engine, and image being closed.

Postcondition: The surface descriptor, image, and engine have been closed.

Note: Not thread-safe; part of the single-threaded teardown.

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 328 of file emu_run_report.c.

References board_sd_save(), run_loop_t::cfg, emu_run_cfg_t::elf, emu_cpu1_close(), emu_exc_bkpt_hit(), emu_memmap_close(), emu_memmap_detach(), emu_presentation_close(), run_loop_t::err, k_emu_exit_bkpt, k_emu_exit_fault, k_emu_exit_ok, k_emu_exit_timeout, emu_run_cfg_t::memory, emu_run_cfg_t::presentation, priv_emu_elf_source_close(), emu_run_cfg_t::save_sd_path, run_loop_t::timed_out, and emu_run_cfg_t::uc.

Referenced by emu_run_and_report().

◆ priv_run_hold_view()

void priv_run_hold_view ( const run_loop_t * st )

Hold the live window on the final frame until the user closes it.

Defined in emu_run_report.c; called by emu_run_and_report. Inert in headless mode.

Parameters

[in] st The run state (window + presentation surface).

Returns: void

Precondition: The run loop has ended and st reflects its outcome.; st->view is a live window or NULL.

Postcondition: Any live window has been presented (if needed) and closed.; No engine or process state changes beyond the window.

Note: Not thread-safe; part of the single-threaded report.

Since: 0.1.0

Definition at line 309 of file emu_run_report.c.

References board_view_close(), board_view_present(), board_view_pump(), build_composite(), run_loop_t::cfg, run_loop_t::closed, k_view_idle_us, run_loop_t::presentation, priv_emu_io_errf(), emu_run_cfg_t::uc, run_loop_t::view, and emu_run_cfg_t::win_title.

Referenced by emu_run_and_report().

◆ priv_run_inner()

bool priv_run_inner	(	uc_engine *	uc,
		uint32_t	vtor_base,
		uint32_t *	run_pc_io,
		uc_err *	err_out )

Run one outer chunk's inner exception-resolve loop.

Runs a chunk, then services exceptions to a steady state before the next chunk (zero-time relaunches, EXC_RETURN unstack + tail-chain, MPU / div-0 fault synthesis, tick / PendSV take). Returns once the full budget elapsed with nothing pending, or on a fault / BKPT / stop request. Defined in emu_run_inner.c; called by the run loop in emu_run.c.

Parameters

[in,out]	uc	Unicorn engine.
[in]	vtor_base	VTOR fallback for exception vectoring.
[in,out]	run_pc_io	Resume PC in, final PC out.
[out]	err_out	Final uc_emu_start status for the report.

Returns: true when the run must end (fault or BKPT), false to continue.

Return values

true	The outer loop breaks and reports the stop cause.
false	The chunk resolved cleanly; the outer loop continues.

Precondition: The engine is set up and run_pc_io holds a valid resume PC.; The seams / exception hooks are installed.

Postcondition: run_pc_io and err_out reflect the loop's final state.

Note: Not thread-safe; this is the single-threaded run core.

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 217 of file emu_run_inner.c.

References emu_exc_clear_pendsv_stop(), internal_run_inner_budget(), internal_run_inner_check_stops(), internal_run_inner_take_exception(), k_inner_break, k_inner_continue, and k_run_inner_max.

Referenced by internal_run_loop_run_chunk().

◆ priv_run_report()

void priv_run_report ( const run_loop_t * st )

Print the run-end report (stop summary, verdict, –dump-sym probes).

Defined in emu_run_report.c; called by emu_run_and_report after the run loop returns.

Parameters

[in] st The run state (final counters + flags).

Returns: void

Precondition: The run loop has ended and st reflects its outcome.; injected error sink is the report stream.

Postcondition: The report section has been written to injected error sink.; No engine or process state changes beyond output.

Note: Not thread-safe; part of the single-threaded report.

Since: 0.1.0

Definition at line 264 of file emu_run_report.c.

References run_loop_t::cfg, run_loop_t::chunks, emu_view_mark_stopped(), run_loop_t::err, run_loop_t::guards, run_guards_t::idle_stop_chunks, run_loop_t::idle_stopped, internal_run_print_dump_syms(), internal_run_print_stop_summary(), internal_run_print_verdict(), run_guards_t::max_chunks, run_loop_t::prof_stopped, run_loop_t::run_pc, run_loop_t::stop_sym_hit, run_loop_t::timed_out, emu_run_cfg_t::uc, run_loop_t::usb_stopped, and run_guards_t::wall_s.

Referenced by emu_run_and_report().

◆ priv_run_write_outputs()

void priv_run_write_outputs ( const run_loop_t * st )

Write the –ppm snapshot and the –record summary line.

Defined in emu_run_report.c; called by emu_run_and_report.

Parameters

[in] st The run state (presentation surface + output paths).

Returns: void

Precondition: The run loop has ended and st reflects its outcome.; injected error sink is the report stream.

Postcondition: The –ppm file is written and/or the –record line printed as requested.; No engine or process state changes beyond output.

Note: Not thread-safe; part of the single-threaded report.

Since: 0.1.0

Definition at line 285 of file emu_run_report.c.

References build_composite(), run_loop_t::cfg, run_loop_t::comp_h, run_loop_t::comp_w, emu_presentation_workspace_t::fd, k_record_fps, emu_run_cfg_t::ppm_path, run_loop_t::presentation, priv_emu_io_errf(), run_loop_t::rec_frames, emu_run_cfg_t::record_dir, emu_run_cfg_t::uc, emu_run_cfg_t::win_title, and write_ppm().

Referenced by emu_run_and_report().

Data Structures

Functions

Detailed Description

Function Documentation

◆ priv_run_cleanup()

◆ priv_run_hold_view()

◆ priv_run_inner()

◆ priv_run_report()

◆ priv_run_write_outputs()