xrun [RUN OPTIONS] xe-file
xrun [RUN OPTIONS] --args xe-file arg1 arg2 .. argn


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).


--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        O[0]
  1     XMOS XTAG-3             wfF.G58J        P[0]

The adapters are ordered by their Adapter IDs.

--list-board-info, -lb#

Displays information about the connected target board.


Prints a description of the supported command line options.


Displays the version number and copyrights.

Run options#

If only one xtag device is present, it will is specified 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 <ADAPTER-ID>#

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


Prints information about the program loaded onto the target devices.

--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 +1)MHz.


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.


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.


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.


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.


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

The following options are used to enable xSCOPE capabilities.


Enables an xSCOPE server with the target.


Enables an xSCOPE server with the target using a socket connection.

--xscope-file <filename>#

Specifies the filename for xSCOPE data collection.

--xscope-port <ip:port>#

Specifies the IP address and port for realtime data capture.

--xscope-limit <limit>#

Specifies the record limit for xSCOPE data collection.


Similar to --xscope


$ 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.