Skip to content

CLI reference

lince-emu is the standalone front-end built from the lince_app target. It is a thin shell over lince::runtime::Emulator: it parses arguments, builds an EmulatorConfig, wires StdoutLogger and StdoutCharDevice as defaults, loads the ELF, and runs.

Synopsis

lince-emu --image <path>
          [--ram <MiB>]
          [--cores <N>]
          [--budget <ns>]
          [--gdb-port <port>]
          [--gdb-wait]
          [--verbose]
          [--version]
          [--help]

Options

Option Default Description
--image <path> required SPARC big-endian ELF executable to load.
--ram <MiB> 16 Simulated RAM size in MiB. Allocated at the configured base.
--cores <N> 1 Number of LEON cores. GR712RC supports 1 or 2; GR740 supports 1–4 (Phase 7).
--budget <ns> 1_000_000_000 Simulated time budget. Execution stops at current_sim_time() + budget.
--gdb-port <p> 0 (off) If non-zero, bind the GDB remote stub to 127.0.0.1:p.
--gdb-wait off Together with --gdb-port, block on initialize() until a GDB client connects.
--verbose off Switch the logger to Debug level. Output goes to stderr.
--version — Print the version and exit.
--help, -h — Print the usage summary and exit.

Exit codes

Code Meaning
0 Time budget consumed cleanly.
2 Invalid / missing CLI arguments.
3 Configuration validation failed (bad core count, RAM size, etc.).
4 ELF load failure (not SPARC, malformed, IO error).
5 A core entered ErrorMode (a fatal trap fired with PSR.ET=0). The post-mortem is dumped to stderr.

ErrorMode post-mortem

When lince-emu exits with code 5, it dumps a complete snapshot of core 0 — equivalent to what you'd get from a SPARC-style debugger attaching to a halted CPU:

[lince-emu] core0 post-mortem: pc=0x400034a0 npc=0x400034a4
            tbr=0x40000020 tt=0x02 psr=0x00000083 wim=0x00000002
[lince-emu]   g0-g7: 0 0x00000000 0x00000000 0x00000000
                     0x00000000 0x00000000 0x00000000 0x00000000
[lince-emu]   o0-o7: 0x400fff40 0x00000008 0x00000000 0x00000000
                     0x00000000 0x00000000 0x400fffd0 0x40003490
[lince-emu]   l0-l7: 0x00000000 ...
[lince-emu]   i0-i7: 0x400fff40 0x00000008 ...

tt = 0x02 is illegal_instruction — typical when an OS jumps to unrelocated memory. The tbr field tells you exactly which trap handler the CPU was about to enter when ErrorMode was raised; psr.PS preserves the supervisor state of the predecessor.

Logging levels

The CLI's StdoutLogger accepts four levels:

Level Default sink Typical contents
Debug stderr (with --verbose) Each peripheral's MMIO trace, ELF segment loading detail, idle-time skip events.
Info stderr Lifecycle markers (initialize, load_elf, run begin/end).
Warn stderr Configuration adjustments (e.g. RAM rounded to a sensible boundary).
Error stderr Bus / load / config failures.

Info and above are always shown; Debug is gated on --verbose.

Notes on argument handling

  • The CLI uses standard getopt_long; flags can appear in any order.
  • --ram is in MiB but rounded internally to the nearest 4 KiB page.
  • --budget accepts decimal nanoseconds; for human-friendly values use --budget 5000000000 to mean "5 simulated seconds".
  • --gdb-wait without --gdb-port is a no-op (and emits a warning).
  • An unknown flag exits with code 2 and prints the usage summary.