User Manual

This manual is for people who run Lince or embed it in their own software — booting RTEMS images, scripting batch runs, or linking lince_runtime into a larger simulation. It does not require knowing the emulator's internals; for those, see the Developer Manual.

What is Lince?

Lince is a C++20 functional emulator for Cobham Gaisler's GR712RC (dual-core LEON3FT) and GR740 (quad-core LEON4FT) SPARC SoCs. Its primary goal is running the RTEMS ⅚ leon3 testsuite at high pass rates, in both uniprocessor and SMP configurations.

Where to start

If you want to…	Read
Install and build Lince	Getting started → Installation
Boot an RTEMS image as fast as possible	Getting started → Quickstart
Walk a full first boot end-to-end	Getting started → First RTEMS boot
Look up every CLI flag of lince-emu	Guide → CLI reference
Embed Lince as a library	Guide → Embedding as a library
Configure the emulator (every EmulatorConfig field)	Guide → Configuration
Wire UART output/input	Guide → UART and console
Attach a debugger	Guide → Debugging with GDB
Understand a SoC's memory map and IRQs	Guide → GR712RC reference
Use or configure peripherals	Peripherals
Run or interpret the test suite	Testing

How Lince fits together (user's view)

flowchart LR
    cfg["EmulatorConfig<br/>(struct: SoC recipe + knobs)"] --> emu["Emulator::create()"]
    elf["RTEMS ELF / mkprom2 ROM"] --> emu
    emu --> run["run_for() / run_until()"]
    run --> uart["UART → ICharacterDevice<br/>(stdout / your sink)"]
    run --> gdb["optional: GDB stub"]

You describe the machine with a plain EmulatorConfig struct (usually from a ready-made gr712rc_config() / gr740_config() recipe), load an image, and advance simulated time. All I/O is injected, so the same build works as a CLI tool (lince-emu) or as a linked library.