Configuration¶

The Emulator is configured through a single plain-old struct, tero::runtime::EmulatorConfig, defined in src/runtime/include/tero/runtime/emulator_config.hpp. There are no config files and no global state — the client (the CLI, your program, or a future SMP2 wrapper) builds this struct from whatever source it likes. This is the configuration-by-struct principle.

The recommended pattern is start from a kit, then override:

auto cfg = tero::compose::gr712rc_config();   // full GR712RC board
cfg.num_cores     = 2;
cfg.cpu_clock_hz  = 100'000'000;               // 100 MHz
cfg.pacing        = tero::runtime::PacingMode::Turbo;
auto emu = tero::runtime::Emulator::create(cfg);   // validates the result

The kit pattern¶

A kit is a function returning an EmulatorConfig pre-populated for a specific SoC: tero::compose::gr712rc_config() / gr740_config() (header tero/compose/kits.hpp, target tero_compose). Each kit is a ~30-line loader that parses an embedded copy of the corresponding .tero machine-script file (src/compose/machines/gr712rc.tero / src/compose/machines/gr740.tero). Those files are also installed as share/tero/machines/gr712rc.tero and share/tero/machines/gr740.tero for copy-and-derive use. The old hand-written runtime recipes (tero::runtime::gr712rc_config() etc.) were deleted; the kits are their drop-in replacement. You can inspect, modify, replace, or extend any entry of the returned config.

For the GR712RC peripheral/IRQ map a kit builds, see GR712RC reference; the full per-kit instance tables are in the tero_compose module reference. For how peripherals are declared and wired, see the peripheral reference.

Other ways to build the config¶

The kit is one of four routes to an EmulatorConfig: kit as-is, kit + modification, a .tero board script (tero-emu --machine), or a hand-written struct. The four are compared, with examples, in Assembling a machine.

Fields¶

Every field below is a member of EmulatorConfig. Defaults are the bare struct defaults; the kits override some of them (noted where relevant).

SoC and memory¶

Timing and clock¶

Scheduling and execution¶

JIT tier knobs (ignored unless translation)¶

GDB stub¶

PROM (boot ROM)¶

Raw memory images¶

Each EmulatorConfig::MemoryImage carries path (file read at initialize()), blob (inline alternative — wins when both are set, the prom_image_* convention), and base (the physical address the first byte lands on). The bytes are copied verbatim: no format interpretation (an ELF magic only logs a warning — ELF guests go through load_elf() or prom_image_*), and no effect on PC or any other CPU state. Targets must be writable mapped memory — primary RAM, FTAHBRAM, extra Ram entities modelling flash banks; the read-only PROM window keeps its own prom_image_* pair. RAM content survives reset() (warm-reset semantics), so images are applied exactly once. This is the flight-configuration shape: bootloader in PROM via prom_image_path, FSW images in flash banks via memory_images.

Peripherals and devices¶

Execution method¶

Both methods are compiled into every build and chosen at runtime by translation:

• translation = true (default) — binary translation: each block is lowered to architecture-neutral IR and run through the tiered LLVM JIT (Baseline O0 immediately, hot blocks promoted to O2 on a background thread), with the IR interpreter as the fallback for anything the JIT cannot lower. The fast path.
• translation = false — the core::step Switch interpreter: one instruction at a time. The reference path and correctness oracle; every translated path is validated bit-identical against it.

auto cfg = tero::compose::gr712rc_config();
cfg.translation         = false;       // force the interpreter (debugging)
// JIT tuning (only relevant when translation == true):
cfg.jit_background_opt  = false;       // Baseline-only, deterministic latency
cfg.jit_promotion_threshold = 50;      // promote hot blocks to O2 sooner

LLVM (≥ 18) is a mandatory build dependency, so the JIT is always available — there is no build-time switch. A GDB stub keeps using the translation path (it single-steps only breakpoint-bearing blocks); a per-instruction observer (instruction trace) forces the interpreter. Deep dive: IR and LLVM JIT.

Execution mode (host threading)¶

Orthogonal to the execution method, execution_mode controls host threading:

• ExecutionMode::SingleThread (default) — all cores advance cooperatively in one host thread (round-robin quantum). The only SMP2-compatible mode; synchronisation primitives are inert, so it pays no locking overhead. TSO (SPARC Total Store Order — every core observes writes in program order) and atomic read-modify-write are correct by construction, since the single host thread serialises all memory operations.
• ExecutionMode::MultiThread — each simulated core runs on its own host thread, for standalone 1:1 throughput. Activates the thread-safe foundations (gated locks, atomic SPARC RMW, cross-core IRQ queue). CLI flag: --mt. Either execution method can run under either mode.

cfg.execution_mode = tero::runtime::ExecutionMode::MultiThread;
cfg.quantum_batch  = 4;   // amortise the cross-core barrier (tune per workload)

See Multi-core and timing.

Clock frequency¶

GR712RC and GR740 are modelled with a single system-clock domain (one clock drives the cores, the AMBA buses, and the on-chip peripherals). cpu_clock_hz is that one knob. Both the per-instruction simulated time (ns_per_insn, via cpi) and the GPTIMER prescaler period derive from it via ns_per_cycle(hz) = round(1e9 / hz), so changing the frequency in one place keeps the CPU and the timers consistent.

auto cfg = tero::compose::gr712rc_config();
cfg.cpu_clock_hz = 100'000'000;   // 100 MHz
// ns_per_insn is recomputed by Emulator::create from cpu_clock_hz and cpi.

Validation¶

Emulator::create(cfg) runs validate_emulator_config(cfg) and rejects configurations that would produce an unbootable machine, returning an ErrorCode:

• num_cores == 0 or num_cores > 4 → InvalidConfig
• ram_size == 0 → InvalidConfig
• quantum == 0 → InvalidConfig
• cpi <= 0 → InvalidConfig
• A peripheral spec with an empty instance name, a null factory, a duplicate name, an IRQ outside [1, 31], an out-of-range chardev_index, or a port connection to a non-existent peer → InvalidConfig
• A ram_base + ram_size that wraps the 32-bit address space → InvalidAddress

Port name resolution happens later (at the connect_ports lifecycle phase, which needs the peripheral object). Fields not checked above are accepted at face value: set ns_per_insn = 0 and the clock never advances — that's your problem, not the validator's.

Mutating runtime services¶

Some settings live behind setters, not config fields, because they need a service implementation rather than a value. Call them before initialize() — peripherals cache the pointers at attach time.

Pacing¶

pacing controls how the Emulator advances simulated time relative to host wall-clock time:

• PacingMode::Realtime (default): each run_for/run_until is sliced into pacing_slice_ns chunks (default 10 ms). Between chunks the emulator computes the wall-clock instant matching current_sim_time() and std::this_thread::sleep_untils on std::chrono::steady_clock. The simulated MHz follows cpu_clock_hz/cpi, so a faster simulated clock means the host must execute more instructions per real second to stay on schedule.
• PacingMode::Turbo: free-running. The emulator never reads the host clock and runs the whole budget as fast as the host allows. The right choice for tests, batch runs, benchmarks, and the SMP2 wrapper (where an external scheduler dictates time). Mandatory for the SMP2 wrapper.

If the host can't keep up in Realtime, the simulation falls behind silently — sleeping cannot make it faster. Tighten pacing_slice_ns for finer pacing at higher syscall cost (1 ms is a sensible lower bound).

cfg.pacing          = tero::runtime::PacingMode::Turbo;   // free-running
// or:
cfg.pacing_slice_ns = 1'000'000;                           // tighter Realtime (1 ms)

Configuring through the CLI¶

tero-emu builds an EmulatorConfig from a SoC kit (or a .tero board script via --machine — see Assembling a machine) plus the flags in the CLI reference. It exposes the fields you typically override at run time (--ram, --cores, --mhz, --cpi, --turbo, --mt, --gdb-port, --gdb-wait, --quantum, and the JIT diagnostic flags); the rest stay at their kit/struct defaults. To tweak ram_base, pacing_slice_ns, entry_point_override, the prom_* fields, or the peripheral list, embed Tero as a library or extend src/app/src/main.cpp.