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


XGDB is an extended version of the more familiar GDB debugger. The extensions allow XGDB to debug a multi-file Xcore application in the form of an XE file.

XGDB is able to attach to multiple targets including:

  • Real hardware via an XTAG debug adapter

  • Simulated hardware provided by XSIM

Most documentation about use of XGDB can be found from the GDB documentation; this page largely only documents where XGDB extends or differs from GDB.


The options for XGDB are largely the same as for GDB. Only options referenced by this documentation are described here. To find all the available commands, use the --help 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.

-ex <command>

Execute given command. If command contains spaces, it should be contained in quotes.


List all available command line options

XMOS commands

The following commands are all provided as part of the XGDB extension to GDB. They can be listed within XGDB by issuing help xmos at the XGDB interactive prompt.


List and enumerate all XTAG adapters connected to your PC.


Connects to a target. If no options are supplied, it will connect to the single XTAG adapter connected to your PC.

Valid options are:

  • --id <id>

    Connect to a specific XTAG adapter as enumerated by listdevices.

  • --adapter-id <adapter-id>

    Connect to a specific XTAG adapter as identified by listdevices. The advantage of using an adapter-id (rather than an enumerated id) is that it is independent of the number of XTAGs that might be connected.

  • --sim, -s

    Connect to a simulated target.

  • --jtagspeed <n>

    Set JTAG clock speed divider, where the frequency generated is \(25/(n+2)\) (MHz). The default frequency is 12.5 MHz.

  • --xtagreboot

    Reboots the XTAG before connecting. Can be used to recover an XTAG which is marked ‘in use’ (by another process).

    Changed in version 15.0.4: Does not work on Windows hosts 15.0.4 onwards due to move to latest winusb.sys driver.


Send a command to the Xmos Target Debug Interface. Available commands:

  • jtagchain

    Print JTAG chain topology, including ‘idcode’ for each element in the chain. Also prints module ids within each element.


Load the binary (and run any setup ELFs as necessary).


Change the focus of subsequent commands to tile <n>.



Setting this to a value, where 9 is the maximum, will cause XGDB to output debug information. For example:

$ XDGB_LOG_LEVEL=9 xgdb a.xe