mr8sim Launch Configuration Format

Document version: 1.0 Status: Specification Implementation baseline: Memora8 commit 61039f1

mr8sim reads a JSON launch file passed as its positional command-line argument. The file must contain a JSON object. There is no schema_version property in the current format; this document version identifies this description, not a field that should be added to the JSON file.

A launch file may use decimal JSON numbers. Unsigned 32-bit fields also accept numeric strings such as "0x200", which is useful for address-like values. Boolean fields must be JSON true or false, and string fields must be quoted. Paths are resolved from the process working directory.

For command-line arguments and invocation syntax, see the mr8sim Command-Line Reference.

Top-level fields

Field Type Required Purpose
cluster object Yes Selects the canonical cluster profile and cluster count.
system object No Controls simulation output, limits, tracing, and runtime behavior.
startup object No Selects local, boot-image, or Artix-7 startup. Defaults to simulator.
link object No Links a named set of .sobj modules for a local simulator launch.
modules array No Describes individually placed .sobj modules.
mmu_windows array No Maps virtual pages to physical pages for CPUs.
stacks array No Initializes stack pages for CPUs.
cpu_access array No Sets per-CPU page access policy.
page_movers array No Configures the canonical PageMover device group.
blake3_page_count unsigned integer No Sets the page limit for the BLAKE3 page device. Defaults to 1024; range is 1–1024.
page_windows array No Legacy alias for mmu_windows. Use only one of the two fields.

cluster is required even when using one cluster. Use either link or modules for a workload; avoid combining both launch styles in one file.

Cluster profile

"cluster": {
  "count": 1
}
Field Type Default Accepted values
cluster.count integer 1 1 through 8

The current canonical profile fixes each cluster at 8 CPUs. The number of CPUs is therefore cluster.count × 8. The other profile dimensions are fixed internally; adding fields such as cpus_per_cluster, shared_pages_per_cluster, linkbanks_per_cluster, localbuffers_per_cluster, page_movers_per_cluster, or function_devices_per_cluster under cluster is rejected.

Although older parser paths read system.clusters, system.cpus_per_cluster, and system.shared_pages_per_cluster, their values are superseded by the canonical cluster profile. Configure the system using cluster.count instead.

Startup mode

Field Type Default Accepted values
startup.mode string "simulator" "simulator", "hardware_power_on", "artix7"
startup.boot_image string — Required for hardware_power_on; path to the boot .sobj image
startup.artix7 object — UDP endpoint settings used by artix7 mode
startup.artix7.host string "192.168.100.2" IPv4 address
startup.artix7.port unsigned integer 5000 0–65535
startup.artix7.timeout_ms unsigned integer 500 Receive timeout in milliseconds

simulator runs the local software model. hardware_power_on loads the specified boot image into the simulator’s power-on boot flow. artix7 uses the MR8A UDP transport to communicate with the Artix-7 target or a compatible Verilator UDP emulator. That mode currently runs CPU 0.

System settings

Field Type Default Meaning
system.tui boolean true Enable the terminal interface. Set false for headless runs.
system.quiet boolean false Suppress the normal startup banner and status output.
system.cycles unsigned integer 0 Maximum cycle count; 0 means no configured limit.
system.system_boundary unsigned integer 8388608 (0x00800000) User/system address boundary.
system.trace boolean or object false Enable trace output, optionally with trace settings below.
system.trace.enabled boolean false Enable trace when trace is an object.
system.trace.file string "trace.txt" Trace output file.
system.trace.cpu integer -1 CPU filter; the default includes all CPUs.
system.trace.every unsigned integer 1 Emit trace every N system cycles.
system.trace.max_lines unsigned integer 0 Maximum trace lines; 0 means no line limit.
system.ipc string "pipe" "pipe" or "real".
system.udp_debug_fd boolean false Enable a development-only CPU-local debug FunctionDevice.

When system.trace is a boolean, it directly enables or disables tracing. When it is an object, omitted members use the defaults shown above.

Workload forms

Linked modules

Use link when mr8sim should link a named set of modules and select one entry module. link.modules must be a non-empty array. Each entry requires path and name; cpu defaults to 0.

"link": {
  "entry": "language_lib",
  "modules": [
    {
      "path": "mr8sim/examples/language_lib.sobj",
      "name": "language_lib",
      "cpu": 0
    }
  ]
}

The selected entry name must match one of the module names. Place module virtual pages and physical pages with mmu_windows.

Individually placed modules

Use top-level modules to load each image directly. Every item requires:

Field Type Required Meaning
path string Yes Path to a .sobj image.
cpu integer Yes CPU that receives the module. Must be in the configured CPU range.
pages array of page IDs Yes Physical pages used to load the image.
name string No Module name; defaults to the image filename without its extension.
wakeup_cpu integer No CPU to wake; omitted value is -1 (no wake request).
boot boolean No Mark the module as the selected boot entry; defaults to false.
system boolean No Mark the module as system code; defaults to false.
sleep boolean No Keep the target CPU asleep; defaults to true.
args array No Initial ABI argument register values for r2–r7.

Each args element must be a one-property object, for example { "r2": 7 }. Values are unsigned 32-bit integers or command-line placeholders "$r2" through "$r7". A placeholder requires the matching --rN=VALUE option. A register may be specified only once per module. To start module execution in the local simulator, set an explicit wakeup_cpu and provide a non-empty pages list. This is also required when boot is true or sleep is false.

The nested field modules.windows is not supported. Put mappings in the top-level mmu_windows array.

MMU mappings and stacks

Each mmu_windows item requires cpu, win, vpage_hi, and start_page_id:

Field Type Required Meaning
cpu integer Yes CPU index.
win integer Yes First MMU window, 0–7. A multi-page mapping must fit in the remaining windows.
vpage_hi unsigned integer or numeric string Yes First virtual page number.
start_page_id unsigned integer or numeric string Yes First encoded physical page ID.
count_pages unsigned integer No Number of consecutive pages/windows; defaults to 1, range 1–8.
module string No Module name associated with the mapping.
stack boolean No Marks the mapping as a stack mapping; defaults to false.

Physical page IDs use the canonical local 11-bit encoding. The encoded cluster must match the cluster containing the selected CPU. The mapping advances the virtual page and physical page ID for each page in count_pages.

page_windows is accepted for older files as an alias. Supplying both page_windows and mmu_windows is an error; new files should use mmu_windows.

Every stacks item requires cpu, page_id, win, and vpage_hi. It identifies a physical page and MMU window for stack initialization. CPU and window indices must be in range, and the encoded page must belong to that CPU’s cluster.

CPU page access

Each cpu_access item requires cpu and mode:

  • "mode": "all" allows access to all configured pages for that CPU.
  • "mode": "pages" requires a pages array of canonical encoded page IDs. No more than 128 pages may be listed; each page must belong to the CPU’s cluster.

PageMover devices

page_movers is an array of groups. The current profile accepts one group with group_id: 16. Each group must contain a non-empty devices array. cluster_id is not a valid field here; cluster identity is encoded in page IDs.

Device ID Required kind
0 "sram-sram"
1 "dram-sram"
2 "dram-raw"

Each device requires device_id, positive page_count, and kind. Device IDs must be unique within the group. Optional file sets the backing file path and optional busy_cycles sets the simulated busy duration (default 0). Other device IDs or kind combinations are rejected.

Minimal local example

This uses the maintained linked-module example and runs a bounded headless simulation from the repository root:

{
  "cluster": {
    "count": 1
  },
  "system": {
    "tui": false,
    "cycles": 200000
  },
  "link": {
    "entry": "language_lib",
    "modules": [
      {
        "path": "mr8sim/examples/language_lib.sobj",
        "name": "language_lib",
        "cpu": 0
      }
    ]
  },
  "mmu_windows": [
    {
      "cpu": 0,
      "win": 0,
      "vpage_hi": "0x200",
      "start_page_id": 0,
      "module": "language_lib"
    },
    {
      "cpu": 0,
      "win": 7,
      "vpage_hi": "0x7ffff",
      "start_page_id": 7,
      "stack": true
    }
  ],
  "stacks": [
    {
      "cpu": 0,
      "page_id": 7,
      "win": 7,
      "vpage_hi": "0x7ffff"
    }
  ]
}

Run it with:

build/mr8sim/mr8sim mr8sim/examples/language_lib.json

For the Artix-7 board or Verilator UDP emulator, add a startup block such as:

"startup": {
  "mode": "artix7",
  "artix7": {
    "host": "192.168.100.2",
    "port": 5000,
    "timeout_ms": 2000
  }
}

The maintained Artix-7 example contains this startup block together with the required cluster, module, mapping, and stack configuration.

Validation and compatibility

The current parser validates known fields and required values, but it does not reject every unknown property. A property that is not documented here may be ignored. Some unsupported properties, including modules.windows and fixed-profile cluster dimensions, are explicitly rejected.

The parser’s accepted compatibility alias page_windows may be removed in a future format revision. Use mmu_windows in new launch files. Keep JSON files aligned with the current source parser; older examples are not authoritative specifications.

Versioning

This document describes the launch format implemented at Memora8 baseline 61039f1. Changes to accepted keys, defaults, value ranges, or launch behavior should be reflected here. The document version is independent of the mr8sim executable version.