tero_interfaces¶

A header-only vocabulary library that defines the strong types and the injected I* contracts shared by every other module. It is the root of the dependency graph: everything links it, and it depends on nothing but tl::expected.

# src/interfaces/CMakeLists.txt
add_library(tero_interfaces INTERFACE)
target_include_directories(tero_interfaces INTERFACE include)
target_link_libraries(tero_interfaces INTERFACE tl::expected)
target_compile_features(tero_interfaces INTERFACE cxx_std_20)

INTERFACE means it produces no .a — only #include paths and the transitive tl::expected dependency. Consume it with:

target_link_libraries(my_target PRIVATE tero::interfaces)

Header inventory¶

All under src/interfaces/include/tero/.

Strong types and Result<T>¶

The strong types in types.hpp are enum class aliases over fixed-width unsigned integers — zero-overhead, not implicitly convertible to each other or to raw int:

enum class PhysAddr   : std::uint32_t {};  // types.hpp:23
enum class VirtAddr   : std::uint32_t {};  // types.hpp:26
enum class CoreId     : std::uint8_t  {};  // types.hpp:29
enum class SimTimeNs  : std::uint64_t {};  // types.hpp:32
enum class IrqLine    : std::uint8_t  {};  // types.hpp:35
enum class AccessSize : std::uint8_t { Byte = 1, Half = 2, Word = 4 };  // types.hpp:38

Operators are provided only where they make physical sense (types.hpp):

Use to_underlying(x) to extract the raw integer (one overload per type) rather than static_cast. bytes(AccessSize) returns ½/4.

template <typename T>
using Result = tl::expected<T, ErrorCode>;          // types.hpp:67

enum class ErrorCode : std::uint8_t {               // types.hpp:49
    Ok = 0, BusError, InvalidAddress, AlignmentError,
    TrapGenerated, InvalidConfig, ElfLoadError,
    IoError,    ///< socket / file / OS API failure (outside the sim bus)
    JitError,   ///< LLVM JIT compile / symbol-lookup / ORCv2 error
};

[[nodiscard]] inline tl::unexpected<ErrorCode> make_error(ErrorCode) noexcept; // types.hpp:71

The injected interfaces¶

These are the seams that decouple tero_core (and the peripherals) from their environment. In standalone mode the tero_defaults implementations are used; an external (SMP2) wrapper substitutes adapters that delegate to the host environment.

Services consumed by the core / runtime¶

Bus / interrupt / scheduling¶

IInterruptController (iinterrupt_controller.hpp) is the SoC-agnostic control surface implemented by both peripherals::IrqMP (GR712RC) and peripherals::IrqAMP (GR740). It exposes only what the two GRLIB IP cores share; GR740-specific extended-IRQ delivery is wrapped internally. consume_core_release_wake(cpu) (iinterrupt_controller.hpp:60) is the generic "one core wakes another" SMP-boot seam — the GRLIB variant drives it from an MPSTAT[i]=1 write, kept inside the implementation. raw_pending() (iinterrupt_controller.hpp:52) is the single-load fast path: a result of 0 proves pending_mask(cpu) == 0 for every cpu, so the SingleThread dispatcher skips the per-CPU scan. set_thread_safe(bool) engages internal locking for MultiThread (call once at initialize(), before threads start).

Atomics in ICpuBus¶

atomic_swap_u32 / atomic_cas_u32 / atomic_ldstub (icpu_bus.hpp:53-93) back the SPARC SWAP, CASA, and LDSTUB instructions. They are non-pure virtual with default implementations that do a plain read-then-write — correct for single-threaded callers (test mocks, the oracle-lockstep overlay). The runtime's CpuBusBridge overrides them with a true atomic RMW on the backing store, which is what makes the SPARC atomics safe once cores run on separate host threads (Phase 13). Keeping them non-pure means other ICpuBus implementations need no change.

Peripheral system¶

class IPeripheral : public IEntity, public IMmio {   // iperipheral.hpp:29
  // IEntity identity — final: the instance name injected by the Soc,
  // falling back to device_class() outside an Emulator.
  std::string_view name() const final;
  virtual std::string_view device_class() const = 0;  // the IP-core kind
  // IMmio: mmio_range(), mmio_read(), mmio_write(), memory_region()
  virtual void             attach(const PeripheralContext&) = 0;
  virtual void             reset() = 0;
  virtual void             tick(SimTimeNs now) = 0;
  virtual void             publish(IPublisher&) = 0;
  // Capability hooks (default null / no-op):
  virtual IPort*           find_port(std::string_view) noexcept { return nullptr; }
  virtual void             connect_ports(IPortResolver&) {}
};

Every device — built-in and custom — implements this one interface. A peripheral is an IEntity whose defining capability is IMmio; authors implement device_class() (the IP-core kind, "apbuart"), while name() is final and returns the PeripheralSpec::instance_name the runtime injects at assembly (iperipheral.hpp:36-42). The capability hooks let a device opt into richer behaviour without bloating the base contract:

PeripheralContext (peripheral_context.hpp) is the aggregate injected once via attach(); pointers stay valid for the peripheral's lifetime:

Peripheral details · Custom peripheral walkthrough

Ports (iport.hpp)¶

The port system wires one peripheral's output to another's input without RTTI dependencies on the consumer:

• IPort — tag-only base; type_id() returns a stable namespaced string constant (e.g. "tero::ISignalPort").
• ISignalPort — one-bit, level-sensitive signal: set(bool), get(), on_change(std::function<void(bool)>). A self-edge (set(get())) is not a transition and fires no callbacks.
• IPortResolver — resolve(peer, peer_slot) → IPort*, handed to peripherals during the connect_ports phase.

Tanda 3 ships only ISignalPort (SignalPort is the concrete impl in tero_peripherals); data/FIFO/bus port types arrive with the first peripheral that needs them.

Observation (iemulator_observer.hpp)¶

IEmulatorObserver is the extension seam for reacting to runtime events without touching the core or a peripheral. Every method has an empty default; install one via Emulator::set_observer(). The runtime guards each call with a null check, so the no-observer default costs one branch per site.

Value types in the interface layer¶

AddressRange (address_range.hpp)¶

Half-open [base, base + size). contains(addr) and overlaps(other) are constexpr and treat size == 0 as empty. Used for every MMIO routing decision in SystemBus.

BreakpointSet (breakpoint_set.hpp)¶

An std::unordered_set<uint32_t> of guest PCs: add, remove, contains (O(1) average, hot path), list (O(N), debugger UI only), size, clear. Owned by the Emulator, referenced non-owning by GdbStub, so future consumers (a CLI, scripted breakpoints) can share one registry. Keys are raw uint32_t (not strong-typed) because the RSP parser and the should_break hot path already deal in raw PCs.

GatedMutex (gated_mutex.hpp)¶

A std::mutex whose locking is gated by a runtime flag (ADR-001). In SingleThread mode the gate is inactive and lock/unlock/try_lock are no-ops (one predictable branch → near-zero overhead); in MultiThread mode it behaves exactly like a std::mutex. It satisfies the BasicLockable / Lockable requirements, so it drops into std::scoped_lock and friends.

What this module deliberately omits¶

• No log macros (ILogger is the only logging surface).
• No utility functions on Result<T> beyond tl::expected's own.
• No global allocator, no global registry, no thread-local state.

Anything not strictly required by the type system or the contracts lives in a downstream module.

See also¶

• Modules overview — the dependency rules and graph.
• Core — ICpuBus consumer; trap/interrupt semantics.
• Peripherals — IPeripheral / PeripheralContext implementers.
• Defaults — the standalone implementations of these interfaces.
• Architecture: traps and interrupts — how IInterruptController and the observer hooks fit the trap path.