.. program:: xgdb

.. _xgdb_manual:

XGDB
====

Synopsis
--------

.. code-block::

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

Description
-----------

XGDB is an extended version of the more familiar
`GDB debugger <https://www.gnu.org/software/gdb/>`_. The extensions allow XGDB
to debug a multi-file Xcore application in the form of an
:ref:`XE file <xe_format>`.

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 <https://www.gnu.org/software/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 :option:`--help` option.

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

.. option:: -ex <command>

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

.. option:: --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 :samp:`help xmos` at the XGDB
interactive prompt.

.. gdb-cmd:: listdevices

  List and enumerate all XTAG adapters connected to your PC.

.. gdb-cmd:: 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:

  * :samp:`--id <id>`

    Connect to a specific XTAG adapter as enumerated by :gdb-cmd:`listdevices`.

  * :samp:`--adapter-id <adapter-id>`

    Connect to a specific XTAG adapter as identified by :gdb-cmd:`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.

  * :samp:`--sim`, :samp:`-s`

    Connect to a simulated target.

  * :samp:`--jtagspeed <n>`

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

  * :samp:`--xtagreboot`

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

    .. versionchanged:: 15.0.4

      Does not work on Windows hosts 15.0.4 onwards due to move to latest
      `winusb.sys` driver.

.. gdb-cmd:: xcommand

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

  * :samp:`jtagchain`

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

.. gdb-cmd:: load

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

.. gdb-cmd:: tile

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

Environment
-----------

.. envvar:: XDBG_LOG_LEVEL

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

  .. code-block:: bash

    $ XDGB_LOG_LEVEL=9 xgdb a.xe