Getting started¶
Tero is a C++20 functional emulator for Cobham Gaisler's
GR712RC (dual-core LEON3FT) and GR740 (quad-core LEON4FT)
SPARC V8 System-on-Chips. Its primary purpose is to boot and run the
RTEMS 5 / 6 testsuite for the leon3 BSP, at high pass rates, across
uniprocessor and SMP configurations — so you can run, debug, and integrate
the software you would otherwise run on real LEON silicon.
This section gets you from a fresh checkout to a booting RTEMS guest. If you want to embed Tero in your own program rather than run the CLI, jump straight to the user guide.
What you can do with Tero¶
- Run a SPARC ELF or PROM image on a simulated GR712RC / GR740 from
the command line (
tero-emu). - Boot real RTEMS images cross-compiled with the Gaisler RCC toolchain and read their UART console output (First RTEMS boot).
- Embed the emulator as a C++ library (
tero_runtime) — load images, run simulated time, read/write physical memory, inspect CPU registers, install custom peripherals (Embedding as a library). - Debug a guest with GDB over the Remote Serial Protocol, with RTEMS thread-awareness (task names, states, priorities) — see Debugging with GDB.
- Choose between two execution methods at runtime: a tiered LLVM JIT (binary translation to native code — a fast Baseline tier plus a background-optimised tier, with an IR interpreter as the fallback; the default) or a switch interpreter (the correctness oracle) — selected by a config field, no rebuild. See IR and LLVM JIT.
The two manuals¶
The documentation is split by audience:
| Manual | Audience | Start here |
|---|---|---|
| User Manual (this section + the user guide) | You run or embed Tero. | Installation |
| Developer Manual (architecture) | You modify Tero's internals. | Architecture overview |
When a user-manual page says "for how it works, see…", it links into the developer manual. You never need the developer manual to run or embed Tero, but it explains the why behind the behaviour you observe.
Host requirements at a glance¶
Tero is developed and CI-tested on Linux x86-64. Linux ARM64 and macOS are functional but not CI-validated.
| Requirement | Minimum | Notes |
|---|---|---|
| C++ compiler | GCC ≥ 13 or Clang ≥ 17 | Must support C++20 (std::span, concepts). |
| CMake | 3.25 | Presets (CMakePresets.json) require this. |
| Ninja | 1.10 | The recommended generator. |
| LLVM (dev libraries) | 18 | Mandatory — the binary-translation JIT links LLVM ORCv2 and uses the llvm::CodeGenOptLevel API introduced in LLVM 18. It is the one dependency CMake does not fetch. |
| Git | any | Required by CMake's FetchContent. |
| Internet | first configure only | fmt, tl::expected and Catch2 are downloaded once; later builds reuse build/_deps/. |
What CMake brings vs. what you bring
The three C++ libraries (fmt, tl::expected, Catch2) are
fetched automatically by CMake — you do not install them.
Berkeley SoftFloat 3e is vendored in-tree. LLVM ≥ 18 is the
exception: install it on the host (or use the nix develop shell,
which pins it). See Installation for the exact
per-distribution commands.
The reading path¶
- Installation — host requirements, the full
build from source via CMake presets + Ninja, the reproducible
nix developalternative, and troubleshooting. - Quickstart — the fastest path from
git cloneto the first SPARC instruction executing. - First RTEMS boot — end-to-end: obtain or cross-compile a real RTEMS image, run it, and read the UART console.
To embed Tero as a C++ library, continue to the user guide.