Layers and modules¶

Tero is structured as a stack of CMake static libraries with strict, unidirectional dependencies. This page enumerates each layer, what lives in it, what it must not depend on, and — crucially — why each boundary exists. The rules here are the prose expansion of CLAUDE.md rule 5:

Respect the module boundaries. tero_core does not depend on tero_peripherals. tero_bus does not depend on tero_core. Dependencies flow: interfaces ← core, bus ← peripherals ← runtime ← app. The translation stack layers as interfaces ← ir ← {arch/sparc, jit} ← runtime; tero_ir does not depend on tero_core (it works on the opaque GuestState blob), while tero_core does depend on tero_ir — CpuState's integer state IS a GuestState blob (state unification); the SPARC frontend just translates SPARC → IR (sparc_frontend).

Dependency graph¶

flowchart TD
    tero_app[tero_app<br/>CLI executable] --> tero_runtime
    tero_app --> tero_compose
    demo_dma[demo_dma_device<br/>examples] --> tero_runtime

    tero_compose[tero_compose<br/>Machine, kits, .tero scripts, dlopen loader] --> tero_runtime
    tero_compose --> tero_peripherals

    tero_runtime[tero_runtime<br/>Emulator facade, Soc, ExecutionEngine, DebugServer] --> tero_defaults
    tero_runtime --> tero_peripherals
    tero_runtime --> tero_arch_sparc
    tero_runtime --> tero_jit
    tero_runtime --> tero_core
    tero_runtime --> tero_bus

    tero_defaults[tero_defaults<br/>Loggers, CharDevices] -.-> tero_interfaces
    tero_defaults --> fmt

    tero_peripherals[tero_peripherals<br/>IrqMP, IrqAMP, GPTimer, ApbUart, MemCtrl, GRGPIO] --> tero_bus
    tero_peripherals -.-> tero_interfaces

    tero_bus[tero_bus<br/>SystemBus, RAM] -.-> tero_interfaces

    tero_arch_sparc[tero_arch_sparc<br/>SPARC → IR frontend] --> tero_ir
    tero_arch_sparc --> tero_core
    tero_jit[tero_jit<br/>IR → native, LLVM ORCv2] --> tero_ir
    tero_jit --> LLVM[(LLVM ≥ 18)]
    tero_ir[tero_ir<br/>arch-neutral IR, interpreter] -.-> tero_interfaces

    tero_core[tero_core<br/>SPARC V8 ISA, CpuState, Decoder] --> tero_ir
    tero_core --> softfloat3e[(SoftFloat 3e)]
    tero_core -.-> tero_interfaces

    tero_interfaces[tero_interfaces<br/>Header-only API] --> tl_expected[(tl::expected)]

Solid arrows are link-time dependencies; dotted arrows are header-only contracts (tero_interfaces is an INTERFACE target — it produces no .a file, only #include paths and the tl::expected dependency). Round nodes are external dependencies fetched/located by CMake.

The graph is acyclic by construction — tero_core does not know that peripherals exist, tero_bus does not know that there is a CPU, and tero_interfaces knows nothing about anybody.

What goes where¶

Why the layers exist¶

Each boundary buys a concrete, testable property. The boundaries are not aesthetic — they each prevent a specific class of coupling bug.

• tero_interfaces exists so any module can depend on a contract without pulling in an implementation. It is header-only, contains no logic, and is the single place strong types (PhysAddr, SimTimeNs, …) and Result<T> are defined (src/interfaces/include/tero/types.hpp). Every other module links it; nothing else may define a vocabulary type. This is what makes "two Emulators in one process" possible — the types carry no global state.
• tero_core is independent of bus and peripherals so the CPU can be unit-tested with hand-crafted instruction streams against a fake bus (tests/support/test_bus). It reaches the world only through the injected ICpuBus interface (step(CpuState&, ICpuBus&), src/core/include/tero/core/step.hpp:41) — it never names SystemBus, an IRQ controller, or a peripheral.
• tero_bus does not know about CPUs — it is a pure physical-address router. This lets us reuse the same bus instance as the DMA target for peripherals (it implements IBusMaster) without a circular dependency: a peripheral DMAs through exactly the memory map the CPU sees. (Decision 1: the bus is non-movable because peripherals cache raw pointers into it — see decisions.)
• tero_ir knows no guest ISA. It operates on an opaque GuestState byte blob (Decision 49), so it depends only on tero_interfaces. The IR interpreter and the JIT backend are shared across architectures: a new guest ISA (ARM is on an experimental branch) is a new frontend, not a new core. This is the multi-arch seam described in Adding a frontend.
• tero_jit is isolated and owns LLVM. It depends only on tero_ir (+ LLVM), so the JIT can be unit-tested under sanitisers without pulling in tero_core, and the heavyweight LLVM dependency stays out of every lower layer. The LLVM headers are marked SYSTEM so the project's strict -Werror warning set applies to Tero code but not to LLVM's templates (src/jit/CMakeLists.txt). LLVM ≥ 18 is a mandatory build requirement (ADR-002, ADR-003): the JIT uses llvm::CodeGenOptLevel, which LLVM 18 introduced.
• tero_arch_sparc is the only module that bridges core and IR. It is the single place that knows both CpuState (SPARC architectural state) and the neutral IR, keeping that knowledge out of both tero_ir and tero_jit. Because tero_core already exposes its integer state as the GuestState blob, the "sync" is mostly a no-op — the frontend resolves window-relative register offsets at translate time from the block's ModeCtx (Decision 50).
• tero_runtime is the only orchestrator. It composes everything; no other module instantiates Emulator, EventScheduler, or ElfLoader. It is allowed to see every lower layer because assembling the SoC is its job — but the dependency graph terminates here before reaching the app, so tero_app is a thin CLI shell over a fully usable library.
  • Two axes, not one. Only tero_core (the SPARC V8 ISA) and tero_arch_sparc (the frontend) are legitimately CPU-ISA-specific. The GRLIB peripherals, the PnP table, and the gr712rc/gr740 recipes carry SPARC-family vocabulary too, but on a separate board/fabric axis (AMBA / IRQMP / GPTIMER), correctly isolated as data — not an ISA leak. The arch-decoupling pass (plans/arch-decoupling.md) made the neutral run loop honour this: the ExecutionEngine no longer names arch::sparc at all — the nPC/PC delay-slot-boundary reads route through the SPARC lens accessor (sparc->npc()) instead of layout::NpcOff blob offsets, and interrupt acknowledgement passes an opaque InterruptDecision::ack_mask formed by the arch (the GRLIB 1u << level identity lives in the SPARC arch, not the engine).
  • tero::core is a PRIVATE link of tero_runtime (src/runtime/CMakeLists.txt:38-44). The cores_ relocation is complete: the ExecutionEngine owns arch-neutral per-core ir::GuestState blobs + CoreControl run latches and drives the architecture by core index (ir::IArchitecture::attach_cores, src/ir/include/tero/ir/architecture.hpp:158); the SPARC CpuState lens lives inside the SPARC architecture. The runtime .cpp files still use core:: for the SPARC oracle and inspection paths, but the public headers only forward-declare it.
  • The ExecutionEngine implementation is split into cohesive translation units — engine_run_loop.cpp (scheduling rounds), engine_translate.cpp (JIT / IR-interpret quanta), engine_irq_time.cpp (interrupt sampling, time base), engine_mt.cpp (MultiThread workers), engine_oracle.cpp (lockstep validation), execution_engine.cpp (lifecycle). See Runtime decomposition.
• tero_compose sits above the runtime and owns assembly only. It turns a board description (C++ Machine calls, a .tero script, or a kit) into a validated EmulatorConfig and stops — execution and the runtime entity graph belong to the Soc inside tero_runtime. The GR712RC/GR740 kits (tero::compose::gr712rc_config() / gr740_config(), src/compose/src/kits.cpp) live here, not in the runtime. See tero_compose.
• tero_defaults is intentionally restricted to swappable services. Everything an external simulation wrapper (e.g. an SMP2 wrapper) would replace — logger, character device, fault injector, publisher — lives here, behind interfaces, so a downstream consumer can drop the whole library and substitute their own implementations via the Emulator::set_* injection points (Decision 23).

How the boundaries are enforced¶

There is no automated layering linter; the boundaries hold by three mechanisms:

1. CMake link edges. A module can only name symbols from libraries it links. tero_core links neither tero_bus nor tero_peripherals, so a #include "tero/bus/..." in core would fail to find the header (the include path is not on core's target_include_directories).
2. -Werror with a strict warning set (tero::warnings, top-level CMakeLists.txt:51-73): -Wall -Wextra -Wpedantic -Werror plus -Wshadow -Wold-style-cast -Wconversion -Wsign-conversion, etc. The whole tree builds with zero warnings under this set (Decision 6).
3. Code review against CLAUDE.md rule 5. New edges that would violate the flow are rejected; the layering invariant is part of the frozen architectural contract.

Module-by-module narrative¶

For deeper module documentation see the dedicated pages under Modules; the translation stack (tero_ir, tero_arch_sparc, tero_jit) is documented in IR and LLVM JIT and Adding a frontend:

• tero_interfaces
• tero_core
• tero_bus
• tero_peripherals
• tero_runtime
• tero_compose
• tero_defaults
• tero_app
• tero_ir, tero_arch_sparc, tero_jit → IR and LLVM JIT

See also¶

• Architecture overview — how the pieces fit together
• Design principles — the invariants the layering serves
• Execution model — what the runtime drives