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.
The following options may be used without supplying an XE file. The most commonly used is
- --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 1 XMOS XTAG-3 wfF.G58J P
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.
- --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
By default, XRUN disconnects from the JTAG adapter once the program is loaded.
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.
--iooption 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
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.
$ xrun a.xe
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
a.xe on xtag with Adapter ID of ‘V0JhnXmh’ with command line arguments.