.. program:: xsim

.. _xsim_manual:

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:

.. code-block:: bash

  xsim <binary>

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

.. code-block:: bash

  connect -s

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

Options
-------

Overall Options
^^^^^^^^^^^^^^^

.. option:: --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.

.. option:: <xe-file>

    Specifies an XE file to simulate.

.. option:: --max-cycles <n>
   
   Exits when *n* system cycles is reached.

.. option:: --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.

.. option:: --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.

.. option:: --help

   Prints a description of the supported command line options.

.. option:: --version

   Displays the version number and copyrights.

Warning Options
^^^^^^^^^^^^^^^

.. option:: --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.

.. option:: --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 :ref:`~~#pragma stackfunction~~ <xcc_pragma_directives_stackfunction>`
   or :ref:`~~#pragma stackcalls~~ <xcc_pragma_directives_stackcalls>`.

.. option:: --no-warn-registers

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

Tracing Options
^^^^^^^^^^^^^^^

.. option:: --trace, -t

   Turns on instruction tracing for all tiles (see :ref:`xsim_trace`).

.. option:: --trace-to <file>
   
   Same as :option:`--trace`, but redirects trace output to specified file.

.. option:: --disable-rom-tracing

   Turns off tracing for all instructions executed from ROM.

.. option:: --enable-fnop-tracing

   Turns on tracing of FNOP instructions.

.. option:: --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:

   .. _xsim_manual_vcd-tracing_option_pads:
   
   ``-pads``

      Turns on pad tracing.

   .. _xsim_manual_vcd-tracing_option_o:
   
   ``-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:

   .. _xsim_manual_option_vcd-tracing_option_ports:
   
   ``-ports``

      Turns on port tracing.

   .. _xsim_manual_option_vcd-tracing_option_ports-detailed:
   
   ``-ports-detailed``

      Turns on more detailed port tracing.

   .. _xsim_manual_option_vcd-tracing_option_cycles:
   
   ``-cycles``

      Turns on clock cycle tracing.

   .. _xsim_manual_option_vcd-tracing_option_clock-blocks:
   
   ``-clock-blocks``

      Turns on clock block tracing.

   .. _xsim_manual_option_vcd-tracing_option_threads:
   
   ``-cores``

      Turns on logical core tracing.

   .. _xsim_manual_option_vcd-tracing_option_instructions:
   
   ``-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.

   :command:`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:

.. option:: -pin <package> <pin>

   Specifies the pin by its name on a package datasheet. The value of
   *package* must match the ``Id`` attribute of a :ref:`~~Package~~ node <xn_spec_package>` 
   in the XN file used to compile the program.

.. option:: -port <name> <n> <offset>

   Specifies *n* pins that correspond to a named port.

   The value of *name* must match the ``Name`` attribute of a 
   :ref:`~~Port~~ node <xn_spec_port>`
   in the XN file used to compile the program.

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

.. option:: -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
   :ref:`~~Tile~~ node <xn_spec_core>` 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.

.. code-block:: bash

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

xSCOPE Options
^^^^^^^^^^^^^^

.. option:: --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:

   .. _xsim_manual_option_xscope-option_offline:
   
   ``-offline <filename>``

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

   .. _xsim_manual_option_xscope-option_realtime:
   
   ``-realtime <URL:port>``

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

   The following argument is optional:

   .. _xsim_manual_option_xscope-option_limit:
   
   ``-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:

.. code-block:: bash
  
  xsim app.xe --xscope "-offline xscope.xmt"

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

.. code-block:: bash

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