Run-end report + finalize (see emu_run_internal.h). More...

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include "board_net.h"
#include "board_periph.h"
#include "board_periph_sd.h"
#include "board_view.h"
#include "emu_console.h"
#include "emu_cpu1.h"
#include "emu_elf_source_internal.h"
#include "emu_engine.h"
#include "emu_exc.h"
#include "emu_host_io_internal.h"
#include "emu_mmio.h"
#include "emu_prof.h"
#include "emu_run_internal.h"
#include "emu_seams.h"
#include "emu_view.h"

Include dependency graph for emu_run_report.c:

Data Structures
struct	run_stop_t
	How the run ended: final engine status plus every stop flag. More...

Functions
static RA8_INTERNAL void	internal_run_print_sd_summary (void)
	Print the attached microSD summary line of the run report.
static RA8_INTERNAL void	internal_run_print_stop_summary (uc_engine uc, const run_stop_t st)
	Print the stop banner, telemetry counters and peripheral summaries.
static RA8_INTERNAL void	internal_run_print_verdict (const run_stop_t *st)
	Print the run verdict: TRUNCATED warning or EXECUTED-to-budget.
static RA8_INTERNAL void	internal_run_print_dump_syms (uc_engine uc, const emu_run_cfg_t cfg)
	Print each –dump-sym probe's value from emulated memory.
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

Run-end report + finalize (see emu_run_internal.h).

The run-end report (stop banner, telemetry, peripheral / MMIO summaries, verdict, –dump-sym probes) plus the finalize steps (–ppm / –record outputs, holding the live window, saving the SD image, closing the raw presentation surface + engine, and mapping the #67 exit code). Split out of emu_run.c so each TU stays under the file-size bar. Output text and order are exactly the pre-split report's. The priv_run_report / priv_run_write_outputs / priv_run_hold_view / priv_run_cleanup contracts live on their declarations in emu_run_internal.h.

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

Since: 0.1.0

Definition in file emu_run_report.c.

Function Documentation

◆ internal_run_print_dump_syms()

RA8_INTERNAL void internal_run_print_dump_syms	(	uc_engine *	uc,
		const emu_run_cfg_t *	cfg )

static

Print each –dump-sym probe's value from emulated memory.

Reads every resolved 32-bit global out of Unicorn memory and prints name, address and value so a test can probe firmware state after the run without a debugger; unresolved or unreadable symbols say so.

Parameters

[in,out]	uc	The engine whose memory is probed.
[in]	cfg	The run configuration carrying the probe list.

Precondition: The run has ended (values are the firmware's final state).; cfg->dump_sym_addrs / names hold cfg->dump_sym_n entries.

Postcondition: One line per probe has been written to injected error sink.; The engine memory is unchanged (read-only probes).

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

Since: 0.1.0

Definition at line 239 of file emu_run_report.c.

References emu_run_cfg_t::dump_sym_addrs, emu_run_cfg_t::dump_sym_n, emu_run_cfg_t::dump_sym_names, emu_mem_read(), priv_emu_io_errf(), and RA8_INTERNAL.

Referenced by priv_run_report().

◆ internal_run_print_sd_summary()

RA8_INTERNAL void internal_run_print_sd_summary ( void )

static

Print the attached microSD summary line of the run report.

Surfaces the SD image's size / FAT format / label the same way the –view sidebar does, so a headless run records the storage setup. Prints nothing when no image is attached.

Precondition: The SD model is in its post-run state.; injected error sink is the report stream.

Postcondition: Zero or one summary line has been written to injected error sink.; The SD model is unchanged (read-only query).

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

Since: 0.1.0

Definition at line 82 of file emu_run_report.c.

References board_sd_info(), k_size_kib, priv_emu_io_errf(), and RA8_INTERNAL.

Referenced by internal_run_print_stop_summary().

◆ internal_run_print_stop_summary()

RA8_INTERNAL void internal_run_print_stop_summary	(	uc_engine *	uc,
		const run_stop_t *	st )

static

Print the stop banner, telemetry counters and peripheral summaries.

The first half of the run report: the "stopped" cause line, final PC / BKPT note, chunk + tick + seam counters, the profiler report, the exception / touch totals, the flushed console tail, the peripheral + network + MMIO observability reports, the SD summary and the MMIO table. Output text and order are exactly the pre-split report's.

Parameters

[in,out]	uc	The engine (read for the peripheral report).
[in]	st	How the run ended.

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

Postcondition: The summary section has been written to injected error sink.; The engine state is unchanged (read-only queries).

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

Since: 0.1.0

Definition at line 124 of file emu_run_report.c.

References board_net_report(), board_periph_report(), board_periph_sci_console_channel(), board_periph_touch_reported(), run_stop_t::chunks, console_flush_line(), emu_exc_bkpt_hit(), emu_exc_bkpt_pc(), emu_exc_pendsv_takes(), emu_exc_svc_takes(), emu_exc_systick_fires(), emu_lob_emulated_count(), emu_mmio_print_bgc_and_table(), emu_mmio_print_counts(), emu_mve_emulated_count(), run_stop_t::err, run_stop_t::idle_stopped, internal_run_print_sd_summary(), priv_emu_io_errf(), prof_report(), run_stop_t::prof_stopped, RA8_INTERNAL, run_stop_t::run_pc, run_stop_t::stop_sym_hit, run_stop_t::timed_out, and run_stop_t::usb_stopped.

Referenced by priv_run_report().

◆ internal_run_print_verdict()

RA8_INTERNAL void internal_run_print_verdict ( const run_stop_t * st )

static

Print the run verdict: TRUNCATED warning or EXECUTED-to-budget.

Distinguishes a wall-clock truncation (host overload, #168) from a genuine full-budget or early-stop completion, with the idle / USB stop variants; a BKPT run prints neither (the banner already carried it).

Parameters

[in] st How the run ended.

Precondition: st is the run's final stop snapshot.; injected error sink is the report stream.

Postcondition: Zero or one verdict paragraph has been written to injected error sink.; No process state changes (pure reporting).

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

Since: 0.1.0

Definition at line 186 of file emu_run_report.c.

References run_stop_t::chunks, emu_exc_bkpt_hit(), run_stop_t::err, run_stop_t::idle_stop_chunks, run_stop_t::idle_stopped, run_stop_t::max_chunks, priv_emu_io_errf(), run_stop_t::prof_stopped, RA8_INTERNAL, run_stop_t::stop_sym_hit, run_stop_t::timed_out, run_stop_t::usb_stopped, and run_stop_t::wall_s.

Referenced by priv_run_report().

◆ 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_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

◆ internal_run_print_dump_syms()

◆ internal_run_print_sd_summary()

◆ internal_run_print_stop_summary()

◆ internal_run_print_verdict()

◆ priv_run_cleanup()

◆ priv_run_hold_view()

◆ priv_run_report()

◆ priv_run_write_outputs()