Firmware profiler (RA8_EMU_PROFILE): sampling, hooks, reports. More...

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

Include dependency graph for emu_prof.h:

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

Enumerations
enum	prof_mode_t : uint8_t { k_prof_off = 0U , k_prof_wall = 1U , k_prof_insn = 2U }
	Profiler mode parsed from RA8_EMU_PROFILE. More...

Functions
double	board_now_s (void)
	Monotonic wall-clock seconds.
void	prof_load (const emu_elf_source_t *elf)
	Collect + sort FUNC symbols (RA8_EMU_PROFILE only) for PC bucketing.
void	prof_add (uint32_t pc, double dt)
	Attribute wall seconds to the function owning `pc` (wall mode).
void	prof_report (void)
	Print the top hot functions (by wall time or instruction count).
void	emu_prof_install (uc_engine *uc)
	Arm the per-instruction profiling hook (insn mode only).
prof_mode_t	emu_prof_mode (void)
	The latched profiler mode.
uint64_t	emu_prof_total_insns (void)
	Total instructions retired under the per-instruction hook.
void	emu_prof_set_stop_pc (uint32_t pc)
	Set the RA8_EMU_STOP_PC early-stop address (0 disables).
bool	emu_prof_stop_hit (void)
	Whether the RA8_EMU_STOP_PC address was reached.

Detailed Description

Firmware profiler (RA8_EMU_PROFILE): sampling, hooks, reports.

Two profiling modes, bucketed by ELF FUNC symbol:

RA8_EMU_PROFILE=1 – wall-time sample: charge each emulation chunk's wall time to the function its execution started in. Cheap (no per-instruction cost); a flat percentage list of the dominant cost.
RA8_EMU_PROFILE=full (or insn) – per-instruction: a code hook tallies every instruction + call entry AND reconstructs the live call chain, so the run end emits an Ozone-style breakdown: a boot timeline, an inclusive/self table, a speedscope JSON export, and a self-contained HTML flamechart. Accurate but ~10x slower; off by default.

The run loop reads the mode / instruction totals / RA8_EMU_STOP_PC state through the accessors here; everything else stays private to emu_prof.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_prof.h.

Enumeration Type Documentation

◆ prof_mode_t

enum prof_mode_t : uint8_t

Profiler mode parsed from RA8_EMU_PROFILE.

Selected once by prof_load() from the environment; the run loop branches its wall-sampling and idle-stop logic on the mode.

Invariant: The mode is fixed for the whole run after prof_load().

See also: prof_load() Parses the mode from the environment.

Since: 0.1.0

Enumerator
k_prof_off	Disabled (no env, zero cost).
k_prof_wall	=1: cheap chunk-start wall-time sampler.
k_prof_insn	=full/=insn: exact per-instruction + calls.

Definition at line 50 of file emu_prof.h.

Function Documentation

◆ board_now_s()

double board_now_s ( void )

Monotonic wall-clock seconds.

CLOCK_MONOTONIC as a double, the time base of the wall-sample profiler mode (and any other host-side wall measurement).

Returns: Monotonic seconds since an arbitrary epoch.

Return values

0.0	Only if the clock read fails (it does not on supported hosts).

Precondition: None (safe at any time).; The host provides CLOCK_MONOTONIC.

Postcondition: No state is modified.

Note: Thread-safe (pure system-clock read).

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Definition at line 31 of file emu_prof.c.

References s_nsec_per_sec.

Referenced by internal_run_loop_prologue().

◆ emu_prof_install()

void emu_prof_install ( uc_engine * uc )

Arm the per-instruction profiling hook (insn mode only).

Installs the UC_HOOK_CODE that tallies every instruction, call entry, and call-chain sample. A no-op in off/wall modes so those runs pay nothing.

Parameters

[in,out] uc Unicorn engine to hook.

Returns: Nothing.

Precondition: prof_load() ran (the mode is latched).; uc is initialised.

Postcondition: In insn mode the code hook is armed for the whole run.; In other modes uc is untouched.

Note: Not thread-safe; call once during setup.

Since: 0.1.0

Arm the per-instruction profiling hook (insn mode only).

Definition at line 940 of file emu_prof.c.

References internal_prof_insn_hook(), k_prof_insn, and s_prof_mode.

Referenced by internal_main_install_run_seams().

◆ emu_prof_mode()

prof_mode_t emu_prof_mode ( void )

The latched profiler mode.

Returns: The mode RA8_EMU_PROFILE selected.

Return values

k_prof_off	Profiling disabled.
k_prof_wall	Wall-time sampling.
k_prof_insn	Per-instruction profiling.

Precondition: prof_load() ran.; None otherwise.

Postcondition: No state is modified.

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

Since: 0.1.0

The latched profiler mode; this step is contained within the emu prof model and uses bounded caller or module-owned storage.

Postcondition: Ownership of caller-supplied storage is unchanged.

The latched profiler mode.

Definition at line 949 of file emu_prof.c.

References s_prof_mode.

Referenced by internal_run_loop_prologue(), and internal_run_stop_prof_idle().

◆ emu_prof_set_stop_pc()

void emu_prof_set_stop_pc ( uint32_t pc )

Set the RA8_EMU_STOP_PC early-stop address (0 disables).

The per-instruction hook ends the run the first time PC reaches this address, letting a profile span exactly the boot path. The caller clears the Thumb bit before passing.

Parameters

[in] pc Stop address (Thumb bit already cleared), or 0 to disable.

Returns: Nothing.

Precondition: The address (when non-zero) is a code address of the loaded image.; Called during setup, before the run loop.

Postcondition: The stop address is latched for the run.

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

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Set the RA8_EMU_STOP_PC early-stop address (0 disables).

Definition at line 961 of file emu_prof.c.

References s_prof_stop_pc.

Referenced by internal_guard_apply_stop_pc().

◆ emu_prof_stop_hit()

bool emu_prof_stop_hit ( void )

Whether the RA8_EMU_STOP_PC address was reached.

Returns: true once the per-instruction hook saw PC hit the stop address.

Return values

false The stop PC is disabled or not yet reached.

Precondition: None.; None.

Postcondition: No state is modified.

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

Since: 0.1.0

Whether the ra8_emu_stop_pc address was reached; this step is contained within the emu prof model and uses bounded caller or module-owned storage.

Postcondition: Ownership of caller-supplied storage is unchanged.

Whether the RA8_EMU_STOP_PC address was reached.

Definition at line 967 of file emu_prof.c.

References s_prof_stop_hit.

Referenced by internal_run_inner_check_stops(), and internal_run_loop_run_chunk().

◆ emu_prof_total_insns()

uint64_t emu_prof_total_insns ( void )

Total instructions retired under the per-instruction hook.

The run loop's compute-idle auto-stop differences this counter per chunk to detect the steady idle frame loop.

Returns: Instructions counted so far (0 outside insn mode).

Return values

0	No instructions counted yet (or not in insn mode).

Precondition: None.; None.

Postcondition: No state is modified.

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

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Total instructions retired under the per-instruction hook.

Definition at line 955 of file emu_prof.c.

References s_prof_total_i.

Referenced by internal_run_stop_prof_idle().

◆ prof_add()

void prof_add	(	uint32_t	pc,
		double	dt )

Attribute wall seconds to the function owning pc (wall mode).

A no-op outside wall-sample mode. The run loop calls this once per chunk with the previous chunk's start PC and elapsed wall time.

Parameters

[in]	pc	Chunk-start program counter (bucketing key).
[in]	dt	Elapsed wall seconds to charge.

Returns: Nothing.

Precondition: prof_load() ran (the mode and symbol table are latched).; dt is a non-negative wall-time delta.

Postcondition: In wall mode the owning function's total (and the run total) grew by dt; otherwise nothing changed.

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

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Attribute wall seconds to the function owning pc (wall mode).

Definition at line 210 of file emu_prof.c.

References internal_prof_find(), k_prof_wall, s_prof, s_prof_mode, s_prof_n, and s_prof_total_s.

Referenced by internal_run_loop_prologue().

◆ prof_load()

void prof_load ( const emu_elf_source_t * elf )

Collect + sort FUNC symbols (RA8_EMU_PROFILE only) for PC bucketing.

Reads RA8_EMU_PROFILE to pick the mode; when enabled, walks the ELF .symtab for sized FUNC symbols, records each one's [entry, end) range and name, and sorts by entry address so per-PC lookup can binary-search. With the variable unset the profiler stays off at zero cost.

Parameters

[in] elf Open ELF source; symbol names are retained as source offsets.

Returns: Nothing.

Precondition: elf is a validated ELF32 source.; The source remains open through the run-end profiler report.

Postcondition: The symbol table is loaded and the mode is latched.; One [profile] injected error sink line is printed when profiling is enabled.

Note: Not thread-safe; call once during setup.

See also: emu_prof_install() Arms the per-instruction hook afterwards.

Since: 0.1.0

Definition at line 160 of file emu_prof.c.

References elf_foreach_symbol(), internal_prof_cmp(), internal_prof_symbol(), k_prof_insn, k_prof_off, k_prof_wall, priv_emu_io_errf(), s_prof, s_prof_elf, s_prof_mode, s_prof_n, and strcmp().

Referenced by internal_main_install_run_seams().

◆ prof_report()

void prof_report ( void )

Print the top hot functions (by wall time or instruction count).

The run-end report. In per-instruction mode it additionally emits the speedscope JSON export, the local HTML flamechart, the boot timeline, and the inclusive/self table. A no-op when profiling was off or nothing was sampled.

Returns: Nothing.

Precondition: The run has ended (totals are final).; injected error sink is writable.

Postcondition: The report (if any) has been written; per-symbol counters are consumed by the top-N selection.

Note: Not thread-safe; call once at run end.

Since: 0.1.0

Postcondition: Ownership of caller-supplied storage is unchanged.

Print the top hot functions (by wall time or instruction count).

Definition at line 892 of file emu_prof.c.

References internal_prof_name(), internal_prof_report_flamechart(), k_prof_insn, k_prof_off, k_prof_top_n, priv_emu_io_err_text(), priv_emu_io_errf(), s_percent_scale, s_prof, s_prof_mode, s_prof_n, s_prof_total_i, s_prof_total_s, and s_samp_n.

Referenced by internal_run_print_stop_summary().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ prof_mode_t

Function Documentation

◆ board_now_s()

◆ emu_prof_install()

◆ emu_prof_mode()

◆ emu_prof_set_stop_pc()

◆ emu_prof_stop_hit()

◆ emu_prof_total_insns()

◆ prof_add()

◆ prof_load()

◆ prof_report()