XGDBSERVER#

Synopsis#

xgdbserver [options]

Description#

XGDBSERVER is an XMOS implementation of a GDB server (also known as a stub or RSP server). XGDBSERVER hosts a server which handles communication with the debug target. XGDB can then be used to interface with the XGDBSERVER server.

Tip

For most cases, it is more convenient to start XGDBSERVER via the XGDB connect or attach commands, which start and connect to an instance of XGDBSERVER from within the XGDB environment.

For advanced use cases, it is possible to start an instance of XGDBSERVER independently and attach to it with the XGDB target remote command.

XGDBSERVER Options#

XGDBSERVER accepts many different options, which can be passed either directly to the xgdbserver program, or to the XGDB connect or attach commands, which start up a local XGDBSERVER.

General options#

-h, --help#: Print help information for all of the available options.

--version#: Display the version of XGDBSERVER.

-b <backend-type>, --backend <backend-type>#

Backend type to use to connect to the target. Valid values:

hardware (default) Connect to hardware via an xTAG.
simulator Connect to an XSIM instance via simulator backdoors.
debugrom-simulator Connect to an XSIM instance, using a fully simulated (slower) debugrom interface.

The backend-type string may be shortened if non-ambiguous.

-s [ --simulator ]#: Shortcut for --backend=simulator

--xe-file <filepath>#: Path to the XE file to debug. This is required when using a simulator backend, but note that when using connect or attach, XGDB will provide this automatically. Note that this only uses the XE file for its system specification, it doesn’t actually load its components into simulated memory.

Note

When starting XGDBSERVER via the XGDB connect or attach commands, this option will automatically be provided, so the user does not need to repeat it.

--args <args>#

Single string containing all of the arguments to pass to the target program when it starts. This string will be split into individual arguments by POSIX convention.

A program must be built with xcc -fcmdline-buffer-bytes in order to support command line arguments. See the compiler documentation for more info.

This is equivalent to the monitor args set command.

Note

From a shell, if multiple arguments are to be passed, wrap them in single quotes so that they are not treated as arguments to XGDBSERVER itself.

--trace#: Enable maximum log level (shortcut for --log-level=trace).

--log-file <filepath>#: Send all log output to a file instead of to stderr. Target program output will not be redirected.

--log-level <logspec>#

Set the log level for XGDBSERVER for internal diagnostic purposes. Log level can be set either broadly, or on a per-log-channel basis. Log levels are specified as pairs, while the global log level (lowest priority) is by itself. The syntax is like rsp=debug,xdbg=trace,warning, which means:

rsp messages of debug or greater will be printed (including sub-channels, like rsp::packet)
All xdbg messages will be printed
Any other channel will have messages printed if they are warning or greater.

The available log levels (in order of verbosity) are: none, error, warning, info, debug and trace. The available channels are dynamic and can be seen in the output log. Some primary log channels are rsp, xdbg, xdbg::usb, service.

Connection options#

These options allow specifying how the server part of XGDBSERVER should behave. These options cannot be used when starting XGDBSERVER via the XGDB connect or attach commands, since XGDB automatically specifies them itself.

-p <portnum>, --port <portnum>#: Port to listen on for TCP connections from XGDB. 0 for ephemeral (see --portfile). Port defaults to 2331 if not specified.

--portfile <filepath>#: XGDBSERVER will write the port number it is using to host the TCP server to this file - useful if an ephemeral port is being used.

--server-timeout <seconds>#: Give up waiting for a connection to the server after this many seconds and terminate. The default (0) means no timeout.

Backend-specific options#

These options change the behaviour of the particular ‘backend’ (see --backend) which is in use, but are not necessarily available for use with every backend.

--adapter-id <id>#: Specify the xTAG adapter to connect to by its serial number. Use --list-devices to get connected device serial numbers. (Supported by: hardware)

--adapter-index <index>#: Specify the xTAG adapter to connect to by its index in the --list-devices list. (Supported by: hardware)

--list-devices#

List all devices which are available for connection, then exit. (Supported by: hardware)

Example:

% xgdbserver --list-devices
Available XMOS Devices
----------------------
  ID    Name                    Adapter ID      Devices
  --    ----                    ----------      -------
  0     XMOS XTAG-3             .BT0u0X2        XS3A[0]
  1     XMOS XTAG-4             BEJMRJ7V        XS2A[0]

The ID column indicates an index which can be used with the xgdbserver --adapter-index option.
The Name column indicates the name of the debug adapter.
The Adapter ID column indicates a unique string which can be used with the xrun --adapter-id option.
The Devices column indicates the target that is connected to the debug adapter. This includes the architecture string, and the IDs of the nodes in square brackets. A 2-chip XS3A system would have XS3A[0-1] in the devices column, for instance.

--reset#

Reset the target upon connection. Without this flag, the system will be left in its current state for XGDB to observe. With this flag, the system will be reset and in a fresh state for XGDB to initialise and control.

XGDB automatically injects this argument when connect is used, and does not use it when attach is used.

(Supported by: hardware) (Implicit for: simulator, debugrom-simulator)

--xscope#

Connect to the target with xSCOPE for IO and data collection. Supplying any other --xscope option will cause this to be automatically implied.

(Supported by: hardware)

--xscope-limit <limit>#

Limit the number of (non-IO) xSCOPE records which will be processed. If not specified, an unlimited number will be allowed.

Note: Set to 0 to restrict xSCOPE to only be used for IO. (Supported by: hardware)

--xscope-file <filepath>#: Send xSCOPE data entries to a file. Argument is the file to write xSCOPE data entries to. Both a file.vcd file for the VCD trace and a file.gtkw for easy loading into GTKWave will be created. The maximum number of entries can be controlled by --xscope-limit. (Supported by: hardware)

--xscope-port <bind address>#

Start a local xSCOPE server at the specified port, which will serve xSCOPE messages. The argument is of the form <local_ip>:<local_port>. If <local_ip> is omitted, the server will be bound to localhost. If <local_port> is omitted, an ephemeral port will be used.

Note that packets sent using this mechanism may be received out-of-order, so if ordering is important for your application, you should reorder them on the client side. See xSCOPE host library for more information on the capability of the host application.

(Supported by: hardware)

--xscope-port-blocking#: Wait for a connection to the --xscope-port xSCOPE server to be made before completing initialisation of XGDBSERVER.This will prevent XGDB from connecting to XGDBSERVER until the xSCOPE server connection has been made, which is useful for preventing race conditions which would cause initial packets to be lost. Note waiting too long (several minutes) before forming the connection may trigger timeouts within XGDB. (Supported by: hardware)

--gprof#

Capture gprof profiling information from the running target to a file in the current directory. One output file will be created for each tile.

See Sample-based profiling of the target program for an example of how to use this feature. (Supported by: hardware)

--sim-args <arg>#

Single string containing all of the arguments to pass to a simulator backend.

See xsim --help for arguments which can be passed into XSIM by this mechanism.

Note

From a shell, if multiple arguments are to be passed, wrap them in single quotes so that they are not treated as arguments to XGDBSERVER itself.

(Supported by: simulator, debugrom-simulator)

--jtag-speed <divider>#: Set the JTAG TCK divider, where the JTAG TCK frequency is (25/(<divider>+2)) MHz. The default frequency is 12.5MHz. (Supported by: hardware)

--xtag <command>#

Instruct the xTAG to do something before continuing. Some of the commands result in XGDBSERVER terminating instead of waiting for a connection. Available commands:

reboot Reboot the xTAG before forming a connection.
rebootandexit Reboot the xTAG, then exit XGDBSERVER without awaiting a GDB connection.
upgrade Upgrade the xTAG bootloader to the newest one compiled into the xTAG firmware, then exit XGDBSERVER.
downgrade Downgrade the xTAG bootloader to the one which was programmed in the factory, then exit XGDBSERVER.

(Supported by: hardware)

Monitor commands#

The following commands are all provided as part of the XGDBSERVER, and can be accessed via the XGDB monitor command while connected.

They can be listed within XGDB by issuing monitor help at the XGDB interactive prompt. Not every monitor command is available for every backend or target type.

Note

Every command documented in this section can be run from within XGDB using the monitor command once connected to XGDBSERVER (such as with the connect command).

For example, to run the command help, type monitor help into the XGDB command prompt.

help#

Usage: monitor help [<query>]

Print the help information for all monitor commands. If query is specified, then only print commands that contain matching text.

args#

Usage: monitor args

Get the arguments which will be passed to the target program when it starts.

Usage: monitor args set <arg>

Set the arguments which will be passed to the target program when it starts. This is equivalent to the xgdbserver --args option.

It is usually preferable to pass arguments to a GDB command such as run or use the xgdb --args option.

A program must be built with xcc -fcmdline-buffer-bytes in order to support command line arguments. See the compiler documentation for more info.

sswitch read#

Usage: monitor sswitch read <address>

Read the node configuration register at ‘address’.

Node configuration registers exist in the SSwitch (System Switch).

sswitch write#

Usage: monitor sswitch write <address> <value>

Set the node configuration register at ‘address’ to equal ‘value’.

Node configuration registers exist in the SSwitch (System Switch).

Warning

Node configuration registers can cause system instability, such as changing the PLL configuration while it is being used - care should be taken to avoid this.

pswitch read#

Usage: monitor pswitch read <address>

Read the tile configuration register at ‘address’.

Tile configuration registers exist in the PSwitch (Processor Switch)

reset#

Usage: monitor reset [<reset type>]

Reset the target. Some of these reset types are internal and shouldn’t really need to be used directly. To restart a program which has already been loaded by XGDB, it is usually more appropriate to just use the XGDB run command.

Warning

When resetting the target using this command, XGDB will not be aware that the target state has changed, so it may be necessary to run maintenance flush register-cache on the XGDB command line to force it to refresh the state.

Table 11 Reset types#
Reset Type	Description
`full-reboot`	The default. Fully reboot the chip/simulation environment. Note that this is a full reset of the chip, including (for instance) starting to load the program again from flash. The target will be halted after some short period of time (this may be long enough to fully boot from flash and start if the program is small.) This can be useful if you want to restart the program that is currently in flash, so it can be debugged after starting up the same way as it will in production.
`detach`	Fully reboot the chip/simulation environment (same as full-reboot), then immediately detach the debugger without halting the target. This can be useful if you want to restart the program exactly as it will boot in production, without affecting its realtime performance at all, because the debugger will not be attached. In order to debug the target after resetting it in this way, the `attach` command should be used.
`pre-load`	(internal use) Reset the chip to a state where it is ready to have a new program loaded. This reboots the target into a halted state where it is waiting for XGDB to load a program to it - it will not start booting from flash. This reset type is used automatically when the `--reset` option, or `load`, `run` or similar commands are used.
`post-load`	(internal use) Reset the ancillary parts of the system after a program has been loaded. This does not restart the target itself, it is just for synchronising the debug adapter systems.
`post-attach`	(internal use) Reset/Resynchronise the ancillary parts of the system after XGDB has attached. This does not restart the target itself, it is just for synchronising the debug adapter systems, such as xSCOPE.

coordinates#

Usage: monitor coordinates [-m]

Get the coordinates to the current thread in the form node[0] tile[1] thread[2]. Add the -m option to provide it in a machine readable 0,1,2 format instead.

It is usually more appropriate to use the XGDB info threads command.

resource read#

Usage: monitor resource read <type> <number> [<port width>]

Low level command to read a resource register, where <type> is the type of resource and <number> is the resource number. <portwidth> is the port width in bits, and must be specified for port resources, and not for other resource types.

Table 12 Resource types#
`<type>`	Description
`port`	Port resource - must specify portwidth.
`timer`	Timer resource.
`chanend`	Channel end resource. Note that this does not read the value received on a channel end, it reads the channel end configuration.
`synchroniser`	Synchroniser resource.
`thread`	Thread resource.
`lock`	Lock resource.
`clkblk`	Clock Block resource.
`swmem`	Software Memory resource.
`ps`	Processor State Register resource (see processor status configuration in the datasheet).
`config`	Configuration resource.
`raw`	Raw Resource ID, for instance as would be allocated by a `GETR` instruction. The resource ID encodes the type, resource number, register ID and port width into a single integer.

Environment#

XDBG_LOG_LEVEL#

This environment variable can be set to increase the log level of XGDBSERVER, as an alternative to the xgdbserver --log-level option. It can be used in 2 different ways.

Firstly, it can accept a log level specification in the same form as is documented in the xgdbserver --log-level option, which allows for a string-based configuration of precise log levels.

Alternatively, for legacy compatibility, it can be set to an 8 bit unsigned integer value; each bit set will enable a logging feature associated with traffic to and from the xTAG. Bits 0 to 3 control system debug and USB tracing and bits 4 to 8 control xSCOPE trace processing.

For example, the following enables all logging:

$ XDGB_LOG_LEVEL=trace xgdb --ex "connect" --ex "run" a.xe

or this enables all logging except for the USB interface (which will only report errors):

$ XDGB_LOG_LEVEL=trace,xdbg::usb=error xgdb --ex "connect" --ex "run" a.xe