Run-guard environment knob reader (see emu_run.h). More...

#include <stdio.h>
#include <stdlib.h>
#include <sys/stat.h>
#include "emu_host_io_internal.h"
#include "emu_prof.h"
#include "emu_run.h"
#include "emu_view.h"

Include dependency graph for emu_run_guards.c:

Enumerations
enum	: uint32_t { k_click_settle_chunks = 512U }
	Default post-click drain window used when the env override is unset. More...

Functions
static RA8_INTERNAL uint32_t	internal_guard_env_u32 (const char *name, uint32_t dflt)
	Read a RA8_EMU_* env var as a positive decimal uint32.
static RA8_INTERNAL uint32_t	internal_guard_env_u32_headless (const char name, uint32_t dflt, const board_view_t view)
	Read a headless-only RA8_EMU_* positive uint32 knob.
static RA8_INTERNAL void	internal_guard_read_wall (double wall_s, bool wall_guard_on)
	Apply the RA8_EMU_WALL_S CPU-time guard override.
static RA8_INTERNAL void	internal_guard_setup_record (const emu_run_cfg_t cfg, const board_view_t view, uint32_t *max_chunks)
	Apply the –record chunk bound and create the frame directory.
static RA8_INTERNAL const char *	internal_guard_read_stop_on (const board_view_t *view)
	Resolve the RA8_EMU_STOP_ON console-banner stop substring.
static RA8_INTERNAL void	internal_guard_apply_stop_pc (void)
	Hand RA8_EMU_STOP_PC (if set) to the profiler stop hook.
static RA8_INTERNAL void	internal_guard_read_prof_idle (uint32_t insns, uint32_t need, uint32_t *arm)
	Read the profiler compute-idle early-stop tunables.
run_guards_t	run_read_guards (const emu_run_cfg_t cfg, const board_view_t view)
	Read the run-guard environment knobs (see run_guards_t).

Detailed Description

Run-guard environment knob reader (see emu_run.h).

The RA8_EMU_* budget / stop-condition environment parsing that precedes the chunked run loop – moved verbatim out of the run TU so each of the two stays under the file-size bar. The contract lives on the declaration of run_read_guards() in emu_run.h.

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

Since: 0.1.0

Definition in file emu_run_guards.c.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum : uint32_t

Default post-click drain window used when the env override is unset.

Enumerator
k_click_settle_chunks	Extra chunks after the click lands.

Definition at line 26 of file emu_run_guards.c.

Function Documentation

◆ internal_guard_apply_stop_pc()

RA8_INTERNAL void internal_guard_apply_stop_pc ( void )

static

Hand RA8_EMU_STOP_PC (if set) to the profiler stop hook.

Ends the run the first time PC reaches this address (effective in profile insn mode, via prof_insn_hook), letting the profiler cover exactly the boot path. The supplied address has its Thumb bit cleared.

Returns: void

Precondition: The environment is stable for the call.; The profiler module is initialised.

Postcondition: With RA8_EMU_STOP_PC set, the profiler stop PC is armed.; Without it set, no profiler state changes.

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

Since: 0.1.0

Definition at line 200 of file emu_run_guards.c.

References emu_prof_set_stop_pc(), k_env_strtol_base, and RA8_INTERNAL.

Referenced by run_read_guards().

◆ internal_guard_env_u32()

RA8_INTERNAL uint32_t internal_guard_env_u32	(	const char *	name,
		uint32_t	dflt )

static

Read a RA8_EMU_* env var as a positive decimal uint32.

Parses name with strtol (base k_env_strtol_base). A missing variable or a non-positive value leaves dflt in force, matching the "unset keeps the default" contract every budget knob documents.

Parameters

[in]	name	The environment variable name.
[in]	dflt	Value returned when unset or parsed as <= 0.

Returns: The parsed positive value, else dflt.

Return values

dflt	The variable is unset or did not parse to a positive integer.

Precondition: name is a valid NUL-terminated string.; The environment is stable for the duration of the call.

Postcondition: No global state is modified (pure query).; The returned value is dflt or a strictly-positive parse result.

Note: Not thread-safe; getenv is called on the single setup thread.

Since: 0.1.0

Definition at line 51 of file emu_run_guards.c.

References k_env_strtol_base, and RA8_INTERNAL.

Referenced by internal_guard_env_u32_headless(), and run_read_guards().

◆ internal_guard_env_u32_headless()

RA8_INTERNAL uint32_t internal_guard_env_u32_headless	(	const char *	name,
		uint32_t	dflt,
		const board_view_t *	view )

static

Read a headless-only RA8_EMU_* positive uint32 knob.

The idle / USB / MAX_CHUNKS stop knobs have no effect in –view (window-driven) mode; when view is live the override is ignored and dflt is returned, exactly as the inline env parsing did.

Parameters

[in]	name	The environment variable name.
[in]	dflt	Value returned when live-view or unset / non-positive.
[in]	view	The live window handle (NULL when headless).

Returns: dflt when a window is open, otherwise internal_guard_env_u32.

Return values

dflt	A live –view window suppresses the override.

Precondition: name is a valid NUL-terminated string.; view is NULL or a valid window handle.

Postcondition: No global state is modified (pure query).; The override is honoured only in headless mode.

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

Since: 0.1.0

Definition at line 81 of file emu_run_guards.c.

References internal_guard_env_u32().

Referenced by run_read_guards().

◆ internal_guard_read_prof_idle()

RA8_INTERNAL void internal_guard_read_prof_idle	(	uint32_t *	insns,
		uint32_t *	need,
		uint32_t *	arm )

static

Read the profiler compute-idle early-stop tunables.

Once boot has fallen into the steady frame loop the firmware retires almost no instructions per chunk, whereas boot chunks are compute-heavy. Stop after need consecutive chunks that each retire fewer than insns instructions, armed only after arm chunks. All three are RA8_EMU_PROFILE_IDLE_* overridable (strtoul, base k_strtol_base10) so the boot window can be tuned per app.

Parameters

[out]	insns	Per-chunk insn count below which a chunk is idle.
[out]	need	Consecutive idle chunks that end the run.
[out]	arm	Chunks to run before the stop is armed.

Returns: void

Precondition: insns, need and arm are non-NULL.; The environment is stable for the call.

Postcondition: Each output holds its default or its env override.; No other global state is modified.

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

Since: 0.1.0

< Per-chunk insns below which a chunk is idle.

< Consecutive idle chunks that end the run.

< Chunks to run before the stop is armed.

Definition at line 231 of file emu_run_guards.c.

References k_strtol_base10.

Referenced by run_read_guards().

◆ internal_guard_read_stop_on()

RA8_INTERNAL const char * internal_guard_read_stop_on ( const board_view_t * view )

static

Resolve the RA8_EMU_STOP_ON console-banner stop substring.

Stops the headless run as soon as the console UART's last line contains the substring – a generic "stop on a banner" guard for apps that loop forever after a success line. Empty, unset, or –view all disable it.

Parameters

[in] view The live window handle (NULL when headless).

Returns: The stop substring, or NULL when disabled.

Return values

NULL	RA8_EMU_STOP_ON is unset, empty, or a window is open.

Precondition: view is NULL or a valid window handle.; The environment is stable for the call.

Postcondition: No global state is modified (pure query).; A non-NULL result points at a non-empty env string.

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

Since: 0.1.0

Definition at line 176 of file emu_run_guards.c.

References RA8_INTERNAL.

Referenced by run_read_guards().

◆ internal_guard_read_wall()

RA8_INTERNAL void internal_guard_read_wall	(	double *	wall_s,
		bool *	wall_guard_on )

static

Apply the RA8_EMU_WALL_S CPU-time guard override.

A positive value sets the bound in seconds; an explicit 0 DISABLES the guard (the #168 footgun fix – WALL_S=0 no longer silently falls back to the default), leaving the run bounded by chunks alone. Unset keeps both defaults untouched.

Parameters

[in,out]	wall_s	In: default bound; out: override when > 0.
[in,out]	wall_guard_on	In: true; out: false on an explicit WALL_S=0.

Returns: void

Precondition: wall_s and wall_guard_on are non-NULL and pre-seeded to defaults.; The environment is stable for the call.

Postcondition: wall_s holds the effective CPU-time bound in seconds.; wall_guard_on is false iff RA8_EMU_WALL_S was exactly 0.

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

Since: 0.1.0

Definition at line 107 of file emu_run_guards.c.

References k_env_strtol_base, and RA8_INTERNAL.

Referenced by run_read_guards().

◆ internal_guard_setup_record()

RA8_INTERNAL void internal_guard_setup_record	(	const emu_run_cfg_t *	cfg,
		const board_view_t *	view,
		uint32_t *	max_chunks )

static

Apply the –record chunk bound and create the frame directory.

Headless –record-secs bounds the run to exactly the recording window (so the dumped frame sequence spans the requested emulated duration); then, whenever a record directory is set, the directory is created and the recording banner is printed. Both steps are inert when –record is off.

Parameters

[in]	cfg	The run configuration (record dir / seconds).
[in]	view	The live window handle (NULL when headless).
[in,out]	max_chunks	In: current budget; out: record-secs bound when set.

Returns: void

Precondition: cfg and max_chunks are non-NULL.; view is NULL or a valid window handle.

Postcondition: With headless –record-secs, max_chunks equals the recording window.; With –record active, the frame directory exists and the banner printed.

Note: Not thread-safe; performs mkdir + injected error sink output during setup.

Since: 0.1.0

Definition at line 140 of file emu_run_guards.c.

References k_record_dir_mode, k_record_every, k_record_fps, k_record_ms_per_sec, priv_emu_io_errf(), RA8_INTERNAL, emu_run_cfg_t::record_dir, and emu_run_cfg_t::record_secs.

Referenced by run_read_guards().

◆ run_read_guards()

run_guards_t run_read_guards	(	const emu_run_cfg_t *	cfg,
		const board_view_t *	view )

Read the run-guard environment knobs (see run_guards_t).

Moved verbatim from the run preamble: every default, override precedence and –view/–record interaction is unchanged, including the –record-secs chunk bound and the RA8_EMU_STOP_PC hand-off to the profiler.

Parameters

[in]	cfg	The run configuration (record/click fields).
[in]	view	The live window handle (NULL when headless).

Returns: The populated guard set.

Return values

(by	value) Every field holds its default or env override.

Precondition: The environment is stable for the run.; cfg outlives the call.

Postcondition: RA8_EMU_STOP_PC (if set) has been handed to the profiler.; With –record active, the frame directory exists (mkdir) and the recording banner has been printed to injected error sink.

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

Since: 0.1.0

Definition at line 255 of file emu_run_guards.c.

References internal_guard_apply_stop_pc(), internal_guard_env_u32(), internal_guard_env_u32_headless(), internal_guard_read_prof_idle(), internal_guard_read_stop_on(), internal_guard_read_wall(), internal_guard_setup_record(), k_click_settle_chunks, k_run_max_chunks, k_run_wall_s, and k_view_max_chunks.

Referenced by internal_run_loop_setup().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

Function Documentation

◆ internal_guard_apply_stop_pc()

◆ internal_guard_env_u32()

◆ internal_guard_env_u32_headless()

◆ internal_guard_read_prof_idle()

◆ internal_guard_read_stop_on()

◆ internal_guard_read_wall()

◆ internal_guard_setup_record()

◆ run_read_guards()