Skip to content

Quickstart

Five minutes from git clone to the first SPARC instruction running inside Lince.

1. Build

git clone https://github.com/claaj/lince.git
cd lince
cmake -S . -B build -G Ninja
cmake --build build

CMake fetches Catch2 and tl::expected automatically. SoftFloat is vendored. No system packages need to be installed beyond a C++20 compiler and CMake/Ninja.

2. Run the test suite

ctest --test-dir build --output-on-failure

You should see 263 tests pass. The single skip — test_rtems_boot — is conditional on a cross-compiled RTEMS image and does not affect correctness.

3. Run a tiny SPARC program

A minimal "hello UART" assembly program is shipped under tests/asm/hello_uart.S. The test harness builds it with the RCC cross-compiler and the resulting ELF can be passed to the CLI:

./build/src/app/lince-emu --image build/tests/asm/hello_uart.elf

Expected output:

Hello UART!

(The newline is provided by the program; nothing else is buffered or post-processed.)

4. Inspect the lifecycle

Add --verbose to see the emulator narrate each phase:

./build/src/app/lince-emu --verbose --image build/tests/asm/hello_uart.elf

You will see, in order:

  1. EmulatorConfig validation
  2. RAM allocation at the configured base
  3. Default GR712RC peripherals wiring (IRQMP → GPTimer → APBUart → MemCtrl)
  4. ELF segment loading with addresses and sizes
  5. Round-robin step loop entering, with periodic time markers

5. Try multi-core

./build/src/app/lince-emu --cores 2 --image build/tests/asm/hello_uart.elf

CPU 1 boots in power-down mode (per real GR712RC behaviour). It will remain idle until CPU 0 releases it via the IRQMP, exactly as on the hardware. The single-threaded round-robin scheduler still ensures TSO and makes atomics correct by construction.

What next?