XSIM¶

Description¶

XSIM provides a near cycle-accurate model of systems built from one or more xCORE devices. Using the simulator, you can output data to VCD files that can be displayed in standard trace viewers such as GTKWave, including a processor’s instruction trace and machine state. Loopbacks can also be configured to model the behavior of components connected to XMOS ports and links.

To run your program on the simulator, enter the following command:

xsim <binary>

To launch the simulator from within the debugger, at the GDB prompt enter the command:

connect -s

You can then load your program onto the simulator in the same way as if using a development board.

Options¶

Overall Options¶

--args <xe-file> <arg1> <arg2> ... <argn>¶: Provides an alternative way of supplying the XE file which also allows command line arguments to be passed to a program.

<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, -t¶: Turns on instruction tracing for all tiles (see XSIM Trace output).

--trace-to <file>¶: Same as --trace, but redirects trace output to specified 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-options] <-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 -start-disabled -tile tile[0] -ports"

Tracing by the VCD plugin can be enabled and disabled using the _traceStart() and _traceStop() syscalls. The -start-disabled argument disables the vcd tracing from the start, allowing the user to enable/disable only those sections of code where tracing is desired. For example:

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

port p1 = XS1_PORT_1A;

int main() {
   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'

xSCOPE Options¶

--xscope <args>¶

Enables xSCOPE. file format.

If <args> contains any spaces, it must be enclosed in quotes. One of the following 2 options is mandatory:

-offline <filename>

Runs with xSCOPE in offline mode, placing the xSCOPE output in the given file.

-realtime <URL:port>

Runs with xSCOPE in realtime mode, sending the xSCOPE output in the given URL:port.

The following argument is optional:

-limit <num records>

Limts the xSCOPE output records to the given number.

For example, the following will run xSIM with xSCOPE enabled in offline mode:

xsim app.xe --xscope "-offline xscope.xmt"

For example, the following will run xSIM with xSCOPE enabled in reatime mode:

xsim app.xe --xscope "-realtime localhost:12345"