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
orattach
, 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.
- --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 ofdebug
or greater will be printed (including sub-channels, likersp::packet
)All
xdbg
messages will be printedAny 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
andtrace
. The available channels are dynamic and can be seen in the output log. Some primary log channels arersp
,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 thexgdbserver --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 thexrun --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 haveXS3A[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 whenattach
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 afile.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 tolocalhost
. 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 thexgdb --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, orload
,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 readable0,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