XGDB#

Synopsis#

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

Description#

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.

Options#

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.

--help#

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.

listdevices#

List and enumerate all XTAG adapters connected to your PC.

connect#

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.

xcommand#

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#

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

tile#

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

Environment#

XDBG_LOG_LEVEL#

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