Skip to content

References

Authoritative hardware and software manuals consulted during Tero development. Source files live in the repository root under references/ and references/hardware/ and are not committed — they are regenerated locally from PDF originals because they are either third-party documentation (licensing) or large binary blobs.

Why this page exists

CLAUDE.md and the coding rules state explicitly: do not guess hardware semantics. The pages listed below are the authoritative source for register bit fields, trap behaviour, memory map addresses, and peripheral semantics. When an implementation question is uncertain — and the answer is not in Design decisions — the next step is to read the relevant manual.

Local references (not committed)

Document Suggested path What it covers
SPARC V8 Architecture Manual references/sparc-v8-manual.pdf ISA definition, instruction encoding, register windows, traps, ASIs, ABI. Primary reference for everything in tero_core.
GRLIB IP Core User's Manual references/grlib-ip-core-manual.pdf Every peripheral: register layouts, bit fields, semantics. Primary reference for tero_peripherals.
GR712RC User's Manual references/gr712rc-usermanual.md Dual-Core LEON3FT SoC: memory map, peripheral instances and addresses, interrupt model, APB/AHB topology. Primary reference for the gr712rc_config() factory and the boot-time peripheral wiring.
GR740 User's Manual references/gr740-usermanual.md Quad-Core LEON4FT SoC: same role as the GR712RC manual but for the GR740 recipe. Drives gr740_config() and the IrqAMP / GR740-specific peripheral layouts.
RTEMS 5 leon3 BSP source /opt/rcc-1.3.2-gcc/src/rcc-1.3.2/cpukit/ What the guest actually does during boot. Critical for the RTEMS-aware GDB stub (see Debugging with GDB) and for diagnosing trap-related bugs in real workloads.
RCC SPARC GCC toolchain /opt/rcc-1.3.2-gcc/ Cross-toolchain for building RTEMS guests and assembly test programs. Contains sparc-gaisler-rtems5-gcc, -nm, -readelf, etc.

Place the converted Markdown files in references/ at the repo root. See .gitignore for the exclusion rules.

When to reach for which

Question Open this first
"What does this SPARC instruction encoding mean?" SPARC V8 Manual
"How does this trap behave (delayed PC, ET, S, CWP)?" SPARC V8 Manual §7
"Which IRQ line does GPTimer subtimer N raise?" GR712RC User's Manual (Interrupt sources)
"What's the MMIO offset of IRQMP.imask[1]?" GRLIB IP Core Manual + GR712RC base address
"Why does RTEMS poke this address during boot?" RTEMS BSP source under cpukit/bsps/sparc/leon3/
"Where is Thread_Control.executing in memory?" RTEMS source cpukit/include/rtems/score/percpu.h, plus readelf -wi of a compiled binary
"Where is _Per_CPU_Information linked?" nm <binary> (matches the symbol in the ELF)

How to refresh after a toolchain bump

Some hardcoded constants in Tero are tied to specific RTEMS / RCC versions (notably the RTEMS layout offsets in rtems_layout::*). When the toolchain changes:

  1. Rebuild a known guest (tests/guest-programs/rtems/hello-world/).
  2. Re-extract the relevant DWARF members: 
    /opt/rcc-VERSION/bin/sparc-gaisler-rtems5-readelf -wi hello-world.elf \
  | grep -A 8 "DW_AT_name.*: Per_CPU_Control$"
  3. Compare against the constants in src/runtime/include/tero/runtime/gdb_stub.hpp (rtems_layout).
  4. Run the [!mayfail] live-guest test: 
    ./build/tests/tero_tests "[gdb_stub][rtems-aware]"
    A [!mayfail] skip is fine (no nm, no binary). A failure means offsets drifted — refresh the constants.

Note

Wrong assumptions about register fields, trap timing or memory layout create bugs that take days to find. Reading the manual is cheaper than guessing. When the manual is ambiguous, file a question rather than picking a side silently.