mr8sim Command-Line Reference

Document version: 1.0 Status: Published specification

mr8sim starts from a JSON launch file. The file selects the startup mode and describes the system and workload. The command line provides help and optional values for module arguments.

Invocation

mr8sim [--r2=VALUE ... --r7=VALUE] <launch.json>

The JSON launch file is required for every run. The path is resolved from the current working directory. Run the maintained examples from the root of the Memora8 repository.

Show command-line help without starting a simulation:

mr8sim --help

-h is an alias for --help.

Command-line options

Option Description
--help, -h Print usage and exit.
--r2=VALUE through --r7=VALUE Supply an unsigned 32-bit value for the corresponding module argument. Values may be decimal or hexadecimal with a 0x prefix.
<launch.json> Required positional launch configuration.

Each register option may appear at most once. Negative values and values larger than 0xFFFFFFFF are rejected. These options do not directly set CPU registers; they fill matching placeholders in a module’s args configuration. The accepted argument registers are r2 through r7.

For example, if a module declares:

"args": [
  { "r2": "$r2" },
  { "r3": 16 }
]

then this invocation supplies the value for $r2:

mr8sim --r2=42 launch.json

A hexadecimal value can be supplied the same way:

mr8sim --r2=0x2A launch.json

The full JSON schema, defaults, and validation rules are described in the mr8sim launch configuration reference.

Startup modes

Select a mode in the JSON startup.mode field:

Mode Behavior
simulator Run the configured system locally in the MR8Sim software model. This is the default when startup.mode is omitted.
hardware_power_on Run the simulator’s power-on boot flow using the required startup.boot_image file.
artix7 Connect to an Artix-7 target over UDP, initialize the configured pages and mappings, then control and monitor CPU 0. The same MR8A transport can be used with the Verilator UDP emulator.

For artix7, the endpoint is configured under startup.artix7. Its defaults are host 192.168.100.2, UDP port 5000, and a 500 ms timeout. Set the host and port to match the board or emulator endpoint. The complete set of connection fields is documented in the launch configuration reference.

Interactive and headless runs

The system object in the launch file controls the user interface and run limit:

  • system.tui enables the terminal interface; it defaults to true.
  • system.cycles sets the maximum number of cycles. It defaults to 0, which means no cycle limit. In headless mode, the local simulator runs until the workload halts when the value is 0.
  • system.quiet suppresses the startup banner and normal status output; it defaults to false.

In the interactive terminal interface:

  • Space pauses or resumes execution.
  • N advances one cycle.
  • Q quits the interface.

For scripted runs, set system.tui to false in the launch JSON. Use system.cycles when the run needs a bounded cycle count.

Examples

Run the maintained local simulator example

From the repository root:

cmake -S mr8sim -B build/mr8sim
cmake --build build/mr8sim --target mr8sim
build/mr8sim/mr8sim mr8sim/examples/language_lib.json

This example disables the TUI and runs the local simulator for a bounded number of cycles.

Run the same workload on an Artix-7 board

The maintained board example configures startup.mode as artix7 and uses the default BX72 board endpoint. Adjust startup.artix7.host when the board has a different address:

build/mr8sim/mr8sim mr8sim/examples/language_lib_artix7.json

The Artix-7 launch uses UDP for MR8A commands, snapshots, and page transfers. Ensure the target is powered, reachable, and running the matching MR8A server before starting this mode.

Run against the Verilator UDP emulator

The repository includes a bounded smoke script that takes the maintained Artix-7 JSON, substitutes the emulator endpoint in a temporary copy, and runs the workload:

MR8SIM_BIN=build/mr8sim/mr8sim \
MR8SIM_LAUNCH_JSON=mr8sim/examples/language_lib_artix7.json \
MR8SIM_WORKDIR="$PWD" \
MR8SIM_EXPECT_OUTPUT='LANGUAGE TESTS OK' \
mr8/verilator/run_mr8sim_udp_smoke.sh

Errors and exit behavior

MR8Sim exits with a nonzero status when the launch file is missing or invalid, an option is unknown or malformed, a required image cannot be loaded, or the configured remote endpoint cannot be reached or returns an error. --help exits successfully without requiring a launch file.

Versioning

This document describes the command-line interface and launch behavior implemented at Memora8 baseline 61039f1. The launch JSON schema has its own versioning and is documented separately.