lax-simulator-run

Run compiled LAX VSP programs on the local runsim simulator (S32DS/tools/LAX_Simulator/runsim). Executes an .eld file on a chosen VSPA3 device model (2AU / 16AU / 64AU), prints cycle counts, program f

SKILL.md

GitHub

LAX Simulator Run (runsim)

Run a compiled LAX executable (.eld) on the local runsim cycle-accurate simulator shipped with S32 Design Studio under S32DS/tools/LAX_Simulator/runsim. Report exit status, cycle counts, and program-flow traces.

runsim executes only .eld files (linked LAX executables produced by laxcc). Object files (.eln), source (.c, .sl), or any other extension are rejected by this skill before invocation. If the user has only source or .eln files, first build an .eld with lax-compiler-explorer or lax-linker-explorer.

When to use

Use this skill when:

  • User asks "run this .eld on the LAX simulator"
  • User asks "what's the cycle count of this program on VSPA3 16AU / 64AU?"
  • User asks "trace program flow / show register values while executing on LAX"
  • User wants to redirect simulator stdout to a file for later inspection

Do not use this skill for:

  • Compiling C/C++ to LAX assembly -> lax-compiler-explorer
  • Linking .eln objects into .eld -> lax-linker-explorer
  • Static size/symbol analysis of an .eld -> lax-binary-analysis
  • ARM simulation -> unrelated toolchains

Available capabilities

This skill uses the standardized search_actions + execute_action MCP tool surface.

Action name Purpose
compiler.list_lax_simulator_tools Discover simulator binaries; call first
compiler.lax_simulator_execute Run runsim on an .eld

Invoke via:

  1. search_actions(query="lax simulator") to retrieve the action schema.
  2. execute_action(action_name="compiler.list_lax_simulator_tools") to discover.
  3. execute_action(action_name="compiler.lax_simulator_execute", params={...}) to run.

The runsim command line

runsim [simulator-options] <eldfile> [program-options]

Two argument regions with different meaning:

  1. Simulator flags -- everything before the .eld filename. These configure the simulator itself (device model, verbosity, tracing, output redirection, exit label, etc.). They are what you place in the args parameter of compiler.lax_simulator_execute.
  2. Program flags -- everything after the .eld filename. These are passed through to the user program (argv[] seen by the LAX application). They are not interpreted by runsim.

The compiler.lax_simulator_execute action already appends the resolved .eld path after args, so put simulator flags in args. If the program itself needs arguments, append them to args after you have confirmed with the user; keep in mind the action positions the .eld at the end -- if program-level arguments are required, invoke with executable_file omitted and inline both the eld and trailing args in args (see "Passing program arguments" below).

Simulator flags (runsim options)

Reference (from runsim -h):

Flag Meaning
-d <device> Alternate device model. Supported: vspa3_2au, vspa3_16au, vspa3_64au
-l Be loud (verbose simulator log)
-t Output timing / cycle count
-v, -ver Print simulator version
-h Display help and exit
-redir <fname> Redirect simulated stdout to <fname>
-showpc Print program flow (equivalent to Debugger Shell print on)
-showregs Print program flow + core register values (print on + trace on)
-exitlbl <label> Replace default exit label ___crt0_end with <label>
-imodel Option applied during simulator initialization
-smodel Option applied after init, before execution begins

Program flags

Anything after the .eld is forwarded verbatim to the LAX program. runsim does not inspect these; use them only if the compiled program actually parses argv.

Quickstart

1. Discover the simulator

execute_action(action_name="compiler.list_lax_simulator_tools")

Verify runsim (or runsim.exe on Windows) is present. If not, stop and tell the user the LAX simulator is not installed.

2. Validate the input file

Before calling compiler.lax_simulator_execute:

  • The executable_file must end in .eld (case-insensitive). Reject anything else with a clear message telling the user to build/link an .eld first.
  • Confirm the file exists on disk.

3. Run runsim with cycle count on VSPA3 16AU

execute_action(
  action_name="compiler.lax_simulator_execute",
  params={
    "binary": "runsim",
    "args": "-d vspa3_16au -t",
    "executable_file": "output/main.eld"
  }
)

Resulting command line:

runsim -d vspa3_16au -t <abs>/output/main.eld

Report exit_code, cycle count (from stdout), and the saved_to scratch dir.

4. Program-flow / register trace

execute_action(
  action_name="compiler.lax_simulator_execute",
  params={
    "binary": "runsim",
    "args": "-d vspa3_64au -showregs",
    "executable_file": "output/main.eld"
  }
)

Use -showpc for lighter flow-only tracing; -showregs can produce very large logs on long-running programs -- warn the user first.

5. Redirect simulated stdout

execute_action(
  action_name="compiler.lax_simulator_execute",
  params={
    "binary": "runsim",
    "args": "-d vspa3_16au -redir sim_stdout.txt",
    "executable_file": "output/main.eld"
  }
)

sim_stdout.txt is written into the per-call scratch dir (saved_to).

Passing program arguments (post-eld flags)

compiler.lax_simulator_execute always appends the .eld path last when executable_file is provided. If the user needs to pass flags to the program (i.e. real post-eld arguments), do one of:

  • Recompile / relink the LAX program so it does not require argv (preferred), OR

  • Call with executable_file omitted and inline both the eld and the trailing program args in args, for example:

    execute_action(
      action_name="compiler.lax_simulator_execute",
      params={
        "binary": "runsim",
        "args": "-d vspa3_16au -t <abs path to main.eld> --my-prog-flag 42"
      }
    )
    

    Always resolve <abs path to main.eld> first and verify it ends in .eld.

Configuration

Key simulator facts:

  • Binary: runsim (runsim.exe on Windows), under S32DS/tools/LAX_Simulator/
  • Accepted input: linked LAX executable, extension .eld only
  • Default device: whatever runsim picks if -d is omitted -- always pass -d explicitly to make results reproducible
  • Device options: vspa3_2au, vspa3_16au, vspa3_64au
  • Default exit label: ___crt0_end (override with -exitlbl)

Guardrails

Scope

  • Uses only compiler.list_lax_simulator_tools and compiler.lax_simulator_execute via execute_action. No user files modified; all outputs written to the per-call scratch directory (saved_to).

Input validation

  • Reject any executable_file whose extension is not .eld. Do not attempt to run .eln, .c, .sl, or unknown files through runsim.
  • Refuse if the file does not exist.

Refuse-and-escalate

  • If runsim is not found under the configured LAX simulator root, stop and report.
  • If the user does not specify a device (-d), ask which VSPA3 variant to target -- results differ substantially between 2au, 16au, and 64au.
  • Do not silently mix simulator flags and program flags; explicitly place simulator flags in args (before the eld) and only add program flags with user confirmation.

Resource limits

  • -showregs and -l on long programs can generate huge logs. Warn the user before enabling either on programs whose runtime is unknown.

Secrets

  • Do not echo redirected simulator stdout that may contain sensitive user data beyond what the user requested.

Workflow

Step 1 -- Discover

execute_action(action_name="compiler.list_lax_simulator_tools")

Confirm runsim (or runsim.exe) is present in the output.

Step 2 -- Confirm device

Ask the user which VSPA3 variant to target if not specified:

User hint Flag
Minimal / 2AU -d vspa3_2au
S32R45-like / 16AU -d vspa3_16au
Full width / 64AU -d vspa3_64au

Step 3 -- Validate the eld

Ensure executable_file ends in .eld and exists. Otherwise abort with a clear message.

Step 4 -- Compose simulator flags

Place all runsim flags (device, -t, -showpc, -showregs, -redir, -exitlbl, -imodel, -smodel, ...) in args. Do not put program flags there unless the user explicitly asked and understood the ordering constraint.

Step 5 -- Execute

execute_action(
  action_name="compiler.lax_simulator_execute",
  params={
    "binary": "runsim",
    "args": "<simulator flags>",
    "executable_file": "<path to .eld>"
  }
)

Step 6 -- Report

Summarize:

  • Command line actually run (from command field in the result)
  • Exit code (0 = success; other values = simulator/program error)
  • Cycle count / timing (if -t was set)
  • Trace snippets (if -showpc/-showregs were set)
  • Path to saved_to for full logs and any -redir output file

Validation loop

  1. execute_action(action_name="compiler.list_lax_simulator_tools") shows runsim (or runsim.exe).
  2. executable_file ends in .eld and exists on disk.
  3. args contains an explicit -d vspa3_{2,16,64}au.
  4. execute_action(action_name="compiler.lax_simulator_execute", ...) returns success=true (or a clearly reported failure).
  5. Requested metric (cycle count / trace / redirected stdout) is visible in the result or under saved_to.

Out of scope

  • Compilation / linking (use lax-compiler-explorer, lax-linker-explorer)
  • Static binary analysis (use lax-binary-analysis)
  • ARM simulation

See also

  • lax-compiler-explorer -- build .eln/.eld from C/C++
  • lax-linker-explorer -- link .eln objects into an .eld
  • lax-binary-analysis -- inspect symbols/sections in an .eld