XSIM Command-Line Manual

XSIM performs a cycle-based simulation of an XMOS Executable (XE) file. The XE file contains a description of the target hardware.

Overall Options

  • xe-file

    Specifies an XE file to simulate.

  • –max-cycles n

    Exits when n system cycles is reached.

  • –plugin name args

    Loads a plugin DLL. The format of args is determined by the plugin; if args contains any spaces, it must be enclosed in quotes.

  • –stats

    On exit, prints the following:

    • A breakdown of the instruction counts for each logical core.
    • The number of data and control tokens sent through the switches.

  • –help

    Prints a description of the supported command line options.

  • –version

    Displays the version number and copyrights.

Warning Options

  • –warn-resources

    Prints (on standard error) warning messages for the following:

    • A timed input or output operation specifies a time in the past.
    • The data in a buffered port’s transfer register is overwritten before it is input by the processor.

  • –warn-stack

    Turns on warnings about possible stack corruption.

    XSIM prints a warning if one XC task attempts to read or write to another task’s workspace. This can happen if the stack space for a task is specified using either #pragma stackfunction or #pragma stackcalls.

  • –no-warn-registers

    Don’t warn when a register is read before being written.

Tracing Options

Trace output for XS1 processors
Core Core State Address Instruction Mem Cycle
Name
from
XN		 I0 I1 I2 S0S1(T0) … S0S1(Tn) . M S K N PC ( sym + offset) : name operands address @val
-
D		 *
P		 -
d		 -
a
A
i
I
p
m
s
w		 -
i
e		 n status pairs   -
m		 -
s		 -
k		 -
n		     val
rm(val)
res[id]		 L[adr]
S[adr]		  
I0: - No debug interrupt S1: - Interrupts and events disabled
I0: D Instruction caused debug interrupt S1: b Interrupts and events enabled
I1: * Instruction excepted S1: i Interrupts enabled and events disabled
I1: P Instruction paused S1: e Interrupts disabled and events enabled
I2: - Not in debug mode M: - MSYNC not set
I2: d Tile in debug mode M: m MSYNC set
S0: - Core not in use S: - SSYNC not set
S0: a Core active S: s SSYNC set
S0: A Core active (traced instruction belongs to this core) K: - INK not set
S0: i Core active with ININT bit set K: k INK set
S0: I Core active with ININT bit set (belongs to this core) N: - INENB not set
S0: p Core paused due to instruction fetch N: n INENB set
S0: m Core paused with MSYNC bit set rn (val) Value of register n
S0: s Core paused withSSYNC bit set res[id] Resource identifier
S0: w Core paused with WAITING bit set L/S[adr] Load from/Store to address

  • –trace-to file

    Turns on instruction tracing for all tiles. The trace is output to file.

  • –disable-rom-tracing

    Turns off tracing for all instructions executed from ROM.

  • –enable-fnop-tracing

    Turns on tracing of FNOP instructions.

  • –vcd-tracing args

    Enables signal tracing. The trace data is output in the standard VCD file format.

    If args contains any spaces, it must be enclosed in quotes. Its format is:

    global-optionsopt < -tile name <trace-options*>*>

    The global options are:

    • -pads

      Turns on pad tracing.

    • -o file

      Places output in file.

    The trace options are specific to the tile associated with the XN core declaration name, for example tile[0].

    The trace options are:

    • -ports

      Turns on port tracing.

    • -ports-detailed

      Turns on more detailed port tracing.

    • -cycles

      Turns on clock cycle tracing.

    • -clock-blocks

      Turns on clock block tracing.

    • -cores

      Turns on logical core tracing.

    • -instructions

      Turns on instruction tracing.

    To output traces from different nodes, tiles or logical cores to different files, this option can be specified multiple times.

    For example, the following command configures the simulator to trace the ports on tile[0] to the file trace.vcd.

    xsim a.xe –vcd-tracing “-o trace.vcd -tile tile[0] -ports”

    Tracing by the VCD plugin can be enabled and disabled using the _traceStart() and _traceStop() syscalls, for example:

    #include <xs1.h>
#include <syscall.h>

port p1 = XS1_PORT_1A;

int main() {
   _traceStop();

   p1 <: 1;
   p1 <: 0;

   _traceStart();
   p1 <: 1;
   p1 <: 0;
   _traceStop();

   p1 <: 1;
   p1 <: 0;

   return 0;
}

Loopback Plugin Options

The XMOS Loopback plugin configures any two ports on the target platform to be connected together. The format of the arguments to the plugin are:

  • -pin package pin

    Specifies the pin by its name on a package datasheet. The value of package must match the Id attribute of a Package node in the XN file used to compile the program.

  • -port name n offset

    Specifies n pins that correspond to a named port.

    The value of name must match the Name attribute of a Port node in the XN file used to compile the program.

    Setting offset to a non-zero value specifies a subset of the available pins.

  • -port tile p n offset

    Specifies n pins that are connected to the port p on a tile.

    The value of tile must match the Reference attribute of a Tile node in the XN file used to compile the program.

    p can be any of the port identifiers defined in <xs1.h>. Setting offset to a non-zero value specifies a subset of the available pins.

The plugin options are specified in pairs, one for each end of the connection. For example, the following command configures the simulator to loopback the pin connected to port XS1_PORT_1A on tile[0] to the pin defined by the port UART_TX in the program.

xsim uart.xe –plugin LoopbackPort.dll ‘-port tile[0] XS1_PORT_1A 1 0 -port UART_TX 1 0’