XRUN#

Synopsis#

xrun [options]
xrun [options] xe-file
xrun [options] --args xe-file arg1 arg2 .. argn

Description#

The XRUN tool has two key roles:

  • To list the connected USB xtag devices

  • To load and run XMOS Executable (XE) files on target hardware via a selected USB xtag debugger.

xrun is actually a wrapper around the XGDB tool, and is provided to simplify common usage patterns of XGDB. Therefore everything that can be done with XRUN can also be done with XGDB (but not the other way round).

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.

Inquiry options#

The following options may be used without supplying an XE file. The most commonly used is -l.

--list-devices, -l#

Prints an enumerated list of all JTAG adapters connected to the host and the devices on each JTAG chain. This example shows that there are two xtag devices present:

$ xrun -l

Available XMOS Devices
----------------------

  ID    Name                    Adapter ID      Devices
  --    ----                    ----------      -------
  0     XMOS XTAG-3             V0JhnXmh        XS2A[0]
  1     XMOS XTAG-3             wfF.G58J        XS3A[0]

The adapters are ordered by their Adapter IDs.

--help#

Prints a description of the supported command line options.

--version#

Displays the version number and copyrights.

Run options#

If only one xtag device is present, it is selected implicitly. If more than one device is present, the device must be specified using --id or --adapter-id.

--id <id>#

Specifies the adapter connected to the target hardware.

--adapter-id <serial-number>#

Specifies the serial number of the adapter connected to the target hardware.

--verbose#

Prints detailed information about what commands are going to be run using XGDB, and print all XGDB output to the terminal (without this flag, it is heavily filtered). This can be especially useful when diagnosing a problem, or to provide a starting point for moving from using XRUN to XGDB for an advanced use case.

--jtag-speed <n>#

Sets the divider for the JTAG clock to <n>. If unspecified, the default value is 0. The maximum value is 70.

For XMOS-based debug adapters, the JTAG clock speed is set to \(25/(n+2)\) MHz.

--noreset#

Does not reset the XMOS devices on the JTAG scan chain before loading the program. This is not default.

The following options are used to enable debugging capabilities.

--io#

Causes xrun to remain attached to the JTAG adapter after loading the program, enabling system calls with the host. xrun terminates when the program calls exit.

By default, XRUN disconnects from the JTAG adapter once the program is loaded.

Warning

The --xscope option should be used in preference to the --io option.

System calls delivered via JTAG are slow and cause all threads on a tile to be paused. Any real-time guarantees in a developer’s application will likely be broken.

The --io option is only used for quick examples or for platforms where the xSCOPE xLINK interface to the xTAG debugger has not been wired.

--attach#

Attaches to a JTAG adapter (of a running program), enabling system calls with the host. XRUN terminates when the program performs a call to exit.

An XE file must be specified with this option.

--dump-state#

Prints the core, register and stack contents of all xCORE Tiles in JTAG scan chain.

The following options are used to enable xSCOPE capabilities. See xSCOPE for more info on xSCOPE.

--xscope#

Enables an xSCOPE connection to the target for fast io and data collection.

--xscope-file <filename>#

Specifies the filename for xSCOPE data collection.

--xscope-port <ip:port>#

Specifies the IP address and port to host a server for realtime data collection.

--xscope-limit <limit>#

Specifies the record limit for xSCOPE data collection. After the limit is hit, no further records from probes will be processed.

--xscope-io-only#

Alias for --xscope-limit 0. Probes will not be processed: xSCOPE will only be used for io.

Examples#

$ xrun a.xe

Asynchronously launch a.xe on the single connected target, and return control to the prompt immediately without waiting for the target to exit.

$ xrun -l

List the available USB xtag devices.

$ xrun --adapter-id V0JhnXmh --args a.xe giraffe elephant

Asynchronously launch a.xe on xtag with Adapter ID of ‘V0JhnXmh’ with command line arguments.