Terminology¶

The following terms are defined:

Host computer (or host): A desktop or laptop on which the XTC Tools are installed
Host tool (or tool): A program supplied with the XTC Tools which may be launched from a shell or console
Target system (or target): One or more printed circuit boards populated with XMOS devices
Target program: A program built with the Tools which can run on a target system

Introduction¶

A set of host computer tools is provided for working with an XMOS target system. A target system is typically a single printed circuit board populated with one or more XMOS devices. A target program, (which is a .xe-suffixed file produced by the tool xcc), may be downloaded into the target RAM and executed using the tool xrun. Symbolic debugging of a target program may be carried out using the tool xgdb. A target program may burned to non-volatile flash using the tool xflash. These tools require an XMOS xTAG to connect the target system to the host computer via USB 2.0.

Key features¶

The following features are provided by the XTC Tools:

Reset the target, download and launch a target program, and optionally support host-IO and xscope operations
Write a target program to a flash device in a target system
Dump the current state of the target (does not reset the target)
Provide symbolic debug of a target (where the program is either downloaded into RAM or booted from flash)
1. The target may be debugged starting from a system-reset state or the debugger may be attached to a running program
2. Host-IO and Xscope API calls may be left in programs which are deployed. The tools will optionally enable host-IO when a connection is made via an xTAG
Provide an API for a developer to use on the host computer to transfer application data to and from the target
Provide sample-based profiling of a target
Management of all XTAGs attached to the host
1. List the xTAGs and detect the type of target system attached
2. For all the tools, an xTAG may be specified by its list index or by unique identifier
3. If only one xTAG is connected to the host an identifier does not need to be supplied to the tools

Targets¶

Three generations of XMOS target system are supported by the tools:

xCORE (XS1 Instruction Set Architecture)
xCORE-200 (XS2A Instruction Set Architecture)
xcore.ai (XS3A Instruction Set Architecture)

Evaluation boards may be obtained from various sources, such as Farnell.

xTAG¶

The xTAG is the physical host-to-target interface. Two types are supported by the tools; xTAG v3.0 (https://www.xmos.ai/download/xTAG-3-Hardware-Manual(1.0).pdf) and xTAG v4.0. Both xTAG types have a USB 2.0 High Speed (Micro-B) interface for connection to the host which also supplies the power to the xTAG. The xTAG3 has a proprietary xSYS interface to the target board and the xTAG4 has an xSYS2 interface to the target board.

Both xSYS and xSYS2 provide 4-wire IEEE1149.1 JTAG interface and a duplex serial xCONNECT link interface, plus some additional control signals. Note the optional JTAG signal nTRST is not pinned out.

When an xTAG is attached to a host it listens for a connection by certain host programs (xrun, xgdb, xflash or xburn). The first connection will download firmware to the xTAG which will support target-related operations. The firmware is not downloaded on subsequent connections until the xTAG is power-cycled.

The elapsed time required to connect to an xTAG is highly variable, due to the possibility of a firmware download occurring, and because the host operating system can introduce delays. This period may extend when multiple xTAGs are attached to the host computer. When a connection is initiated a lock is taken which may pause the execution of other independent host tools each using their own xTAG. The lock is released once the connection is established. Automated test systems should ensure any timeout for an xTAG response is sufficient for the worst case which may need to be determined empirically.

If the xTAG has been used previously with an earlier Tools 15 release the first connection will attempt to install the firmware required for use with this release. The xTAG will automatically reboot as part of this process which will be shown by the xTAG LEDs.

Note 1: If an xTAG has been used with a tools release earlier than Tools 15 it must be manually power cycled prior to making a connection with Tools 15.

Note 2: If the host is rebooted it may fail to enumerate the attached xTAGs. The xTAGs must be power-cycled. Some USB hubs provide a mechanism to power-cycle their downstream ports, and these are recommended for remote lab environments. Note Windows 10 Pro does not support this feature.

xTAG v3.0¶

xTAG v3.0 datasheet: https://www.xmos.ai/download/xTAG-3-Hardware-Manual(1.0).pdf

The xTAG v3.0 provides the xSYS target interface (IDC 20-pin 0.1”) and supports XS1 and XS2 target families. It supports only 3v3 target voltage levels.

xTAG v4.0¶

The xTAG v4.0 provides the xSYS2 target interface (Amphenol Minitek127 20-pin 0.05”) and supports XS2 and XS3 (xcore.ai) target families. It supports 1v8 and 3v3 target voltages, automatically and independently for JTAG and xCONNECT Link interfaces.

The xCONNECT Link is optional – if it is not connected a reduced-footprint connector may be employed on the target board. To reduce the connector cost to a minimum, for production programming and testing, a Tag-Connect Plug-Of-Nails may be used. Only the IEEEE1149.1 JTAG signals need to be connected.

Using xTAGs with Windows 10 Pro¶

On Windows 10 Pro host computers the click-through XTC installer sets up an XTAG service. This service starts following the installation procedure and each time the host boots, and requires no further administration.

On Windows 10 Pro it is not possible to switch between an XTC Tools 15 series release and an earlier XTC Tools release and use the host tools which require access to an xTAG.

On Windows 10 Pro the xTAG unique identifiers are shown in upper case but the tools are case-insensitive so scripts which drive the tools may be used interchangeably between all OS types supported by the tools.

Host tools¶

The host tools that interface with the target system are xrun, xgdb, xflash and xburn.

Unless stated otherwise the following examples in this section assume a single xTAG and target system are attached to the host computer.

xrun¶

The program xrun is used to:

List the xTAGs and target systems attached to the host computer
Download a target program to RAM and launch it
Download a target program to RAM and launch it, managing host-IO
Download a target program to RAM and launch it, and capture xscope data to a file
Dump the state of a target either with a .xe target program so it may be represented symbolically or without a .xe to show state as raw data

List the attached xTAGs¶

The command xrun -l lists the xTAGs attached to the host computer. When an xTAG is first plugged into the host the red LEDs should be illuminated in a dim state. These should change state when xrun -l is invoked. Sometimes the host fails to identify the xTAG. In this case it should be unplugged for several seconds and then re-inserted. If the xTAG is not listed check for its presence. On Linux hosts run the command:

lsusb

On Windows hosts open the Device Manager and expand Universal Serial Bus devices.

Launching a target program¶

A target program may be launched on the target system with:

xrun my_program.xe

xrun will exit immediately, leaving the target program running indefinitely. If the target program fails it may be debugged by attaching with xgdb.

A target program may be launched with host-IO enabled with:

xrun –io my_program.xe

or with xCONNECT Link host-IO enabled:

xrun –xscope my_program.xe

xgdb¶

The host tool xgdb is a variant of the open-source tool gdb. It supports the standard gdb command line options and commands, plus extra command options and builtin commands for use with XMOS targets.

It may be used to carry out all the functions supported by xrun, plus

Interactive, symbolic debug of the downloaded program
Scripted actions with the target
Attaching to a target which is running a program which either booted from flash or was downloaded and launched with xrun or xgdb

Symbolic debug is only available for a source compilation unit (that is, a .c., .cpp or .xc file) if it is compiled with the -g option passed to xcc. Reducing the optimisation level used by xcc with the -O option will improve debuggability at the expense of potential changes in program behaviour.

Debugging a target program¶

The following command will start a debug session of the program my_program.xe by connecting to the target, downloading the program and initialising the device based on the target XN used to build the program:

xgdb -ex “connect” -ex “load” my_program.xe

Commands supplied with the option -ex may be entered at the (gdb) prompt if preferred.

The load command must be supplied only once.

To start the program running the user must enter the command:

(gdb) continue

Before starting the program debugging commands may be supplied. For example, breakpoints may be set with the break command.

Once the target program is started the (gdb) prompt will not be available. Host-IO may appear on the console. Once started the target program may be stopped by pressing Ctrl-C which will report the stopped location and provide the (gdb) prompt.

The active logical cores may be listed with:

(gdb) info threads

Each active logical core is assigned a unique “gdb thread” number. Only active logical cores in all tiles in the system are listed. Note the “gdb thread” number assignments are not static and they may vary each time the target stops. A logical core may be selected for further inspection with the thread command. For example:

(gdb) thread 5

The back trace (call stack) for the logical core may be shown with the where command, for example:

(gdb) where

Local and global variables may be inspected with the standard gdb commands. See the gdb documentation for details.

Attaching to a target¶

In some cases it may be desirable to inspect the state of a target system without resetting it. It is possible to “attach” to a running target. For example:

xgdb -ex “attach” my_program.xe

xgdb will stop all the tiles and provide the (gdb) prompt. xgdb commands may be issued as illustrated in the previous section.

Target interaction¶

The JTAG interface is used by the tools to establish a connection to the target, to reset it and to download programs to RAM. It is used to interact with the target, for example, to extract register state and to set breakpoints. It is used to monitor the target to detect program termination, to detect the target taking a fatal exception and to interrupt the target. It may be used to handle host-IO.

Debug mode¶

Each tile will be placed in its debug mode to: download a program, when a breakpoint is reached, to terminate a target program and when interrupted by a Ctrl-C operation in the xgdb console. In some cases it will enter debug mode to forward host-IO data. When a tile enters debug mode all its logical cores will be paused.

Exceptions¶

The tools xrun and xgdb place a breakpoint on the exception handler entry point. When the target takes a fatal exception (for example, due to arithmetic divide-by-zero), the tools will report on the occurrence of the exception. xgdb may be used to debug the cause, symbolically, typically by showing the back-trace.

Note the message SIGTRAP is generated if a tile enters debug mode unexpectedly. This may occur when certain low-level operations are being carried out with the tiles. The target program has not taken an exception.

Launch with xrun¶

If the target program is launched by xrun without any optional arguments, xrun loads and runs the program, then exits immediately leaving the target program running. If the –io option or any of the –xscope options are supplied to xrun it will not exit until the target program terminates – see below.

Termination¶

If a tile’s control flow reaches the end of main() that tile will terminate and wait. When control flow for all tiles has reached the end of main(), and the target program has been launched with xrun supplying the option –io or any of the –xscope options, the xrun session will terminate. If the program was launched using xgdb it will report “Program exited normally “ on termination.

If a tile calls exit() with a non-zero value, this will be returned by xrun as the process exit code. All tiles must terminate before xrun terminates. Only one tile should call exit(). If launched by xgdb, the exit code will be shown on the console.

Host-IO¶

If the target program calls standard library IO functions from stdio.h such as printf(), fprintf(), fopen(), fread() and fwrite(), and the program was launched with xgdb, or with xrun and the –io or –xscope options, these calls will be redirected to act on the host computer’s filesystem (or its console, for the files stdin, stdout and stderr). Data will be sent from and to the target via the JTAG interface. To transfer data, the tile making the call will enter debug mode which pauses execution of all its logical cores.

These calls may be left in the program when it is deployed to boot from flash using xflash. If xrun or xgdb is later used with a such a system, the IO will be redirected to the host computer. However there is a deployment penalty in run-time and memory used; each call will process its arguments before inspecting internal state to determine whether xrun or xgdb is connected.

Note stdio.h and other headers mentioned in the following sections can be found under the tools installation in the sub-directory target/include on Linux hosts and target\include on Windows hosts.

An example xrun command to enable host-IO:

xrun –adapter-id DFW7DTYY –io test.xe

An example xgdb command (note IO is enabled by default when using xgdb):

xgdb -ex “connect –adapter-id DFW7DTYY” -ex load -ex continue test.xe

Reduced-overhead print functions¶

The header print.h provides a set of reduced overhead print functions such as printstr(). These do not perform any memory allocation or any runtime formatting, making them memory and run-time efficient compared with the standard library IO functions. For example, the following prints a set of characters without a new line:

printstr(“Starting test 1”);

Syscall host-IO¶

The header syscall.h provides the functions _open(), _close(), _write() and _read(). These may be used to perform host-IO with a reduced run-time and memory overhead compared with the standard library IO functions. The standard library IO functions call these underlying syscall functions. For example:

int fd = _open(path, O_WRONLY | O_CREAT | O_TRUNC, S_IREAD | S_IWRITE);
if (_write(fd, buf, len) != len) { // Handle error }

Host-IO via the xCONNECT link¶

The IO transfer rate via JTAG is relatively low. Furthermore, each IO call puts the tile in debug mode which is highly intrusive (as it pauses all logical cores). To achieve a significantly higher bandwidth and minimise intrusion into the target program, the xCONNECT link may be used as a transport. This may be configured in a lossy mode where data may be dropped if the host fails to keep pace with the target, or in lossless mode where the logical core emitting the data may be paused while data is being received by the host.

Note the write APIs (printf(), fprintf(), fwrite() and _write()) will use the xCONNECT Link exclusively. Other APIs such as fopen(), fread() or _read() always use the JTAG interface to transport data even if IO has been configured to use the xCONNECT link.

To use the xCONNECT Link as a transport the following should be provided in a source file from which the target program is built:

#include <xscope.h>

void xscope_user_init() {
  xscope_register(0);
  xscope_config_io(XSCOPE_IO_BASIC);
}

The function below may be called at any stage during target program execution to select lossless mode:

xscope_mode_lossless();

The function below may be called at any stage during target program execution to select lossy mode:

xscope_mode_lossy();

When lossy mode is selected and the data rate of the target cannot be met by the host, entire packets may be dropped.

Key points to note:

The program provides the function named xscope_user_init() (which is called automatically on program startup by the C-runtime initialisation code (CRT) as a static constructor)
The target program must be built with the option –fxscope supplied to xcc
One of the --xscope options must be supplied to xrun or the xgdb connect command

Xscope APIs¶

A set of target APIs is provided to send packets of data to the host to be visualised as waveforms with a 3rd party graphical tool. A set of virtual channels are defined in the target program and each appears as separate waveform trace.

The xCONNECT Link is always used to transport the data sent from the target. This may be configured in lossy mode where data may be dropped if the host fails to keep pace with the target, or in lossless mode where logical core emitting the data may be paused while data is transferred.

The APIs are defined in xscope.h. An example to emit float and integer data on two channels is:

void xscope_user_init(void) {
    xscope_register(2,
                    XSCOPE_CONTINUOUS, "Float0",     XSCOPE_FLOAT, "mV",
                    XSCOPE_CONTINUOUS, "Iterations", XSCOPE_UINT,  "Steps");
}

void emit(float f, unsigned int i) {
    xscope_float(0, f);
    xscope_int(1, i);
}

The xcc option -fxscope must be supplied when building the program.

The xrun option –xscope-file <filename> must be supplied to specify a file into which the data will be written in IEEE 1364-2001 Verilog VCD format.

Lossy or lossless data delivery may be selected as described above.

User-supplied host program¶

The user may supply a host program which handles target data while the target program is running. The target can send data to the host program using either the Xscope APIs, the host-IO APIs or both sets. The host program can send data back to the target program.

The host program can be written in either the C or C++ programming language. The header xscope_endpoint.h provides the API for the host program. It must be linked against the shared library libxscope_endpoint.so on Linux and Mac hosts and xscope_endpoint.a on Windows hosts, using C linkage. These libraries are provided by the XTC Tools in the lib sub-directory of the installation root.

In this example two consoles are used to launch the xgdb session and the host program.

<PORTNUM> must be substituted with a free system port number.

Console 1: launch the xgdb session:

% xgdb -ex "connect --xscope-port --xscope-port localhost:<PORTNUM>"

Console 2: launch the host program:

% host_example <PORTNUM>

Structure of the host program¶

The host program starts by registering callback functions to handle selected target activities, such as target calls to printf() or target calls to xscope APIs. It does this with calls to:

xscope_ep_set_print_cb();
xscope_ep_set_register_cb();
xscope_ep_set_record_cb();
xscope_ep_set_exit_cb();

It then connects to the xgdb session using the <PORTNUM> argument passed to main():

result = xscope_ep_connect("localhost", argv[1]);

If result is zero, the connection was successful. If non-zero the xgdb server was not ready. The xscope_ep_connect() API call may be re-tried until a connection is made.

Once connected the program should sleep in an efficient manner. The callback functions will be called when necessary as a direct result of API calls by the target program.

Example host program and target programs¶

In the following example the host program provides a set of call back functions which are called when the target-initiated events occur.

Compile¶

xcc -g -fxscope -target=XCORE-AI-EXPLORER -o target.xe main.xc target.c
gcc -g -I "$(XMOS_TOOL_PATH)/include" ${XMOS_TOOL_PATH}/lib/xscope_endpoint.so -o host host.c

Run¶

Open two consoles.

In console 1:

% xrun --xscope-port : target.xe
XScope Realtime Server Enabled (localhost:37316)

In console 2: Supply the port number printed by xrun following locallost: above:

% ./host 37316

Host program¶

host.c¶

#include "xscope_endpoint.h"

/* Called when the target calls xscope_register() */
static void xscope_register(unsigned int id,
                            unsigned int type,
                            unsigned int r,
                            unsigned int g,
                            unsigned int b,
                            unsigned char *name,
                            unsigned char *unit,
                            unsigned int data_type,
                            unsigned char *data_name)
{
}

/* Called on each target call to xscope_int() and similar APIs */
static void xscope_record(unsigned int id,
                          unsigned long long timestamp,
                          unsigned int length,
                          unsigned long long dataval,
                          unsigned char *databytes)
{
    /* id is the virtual channel number used by the target in the xscope API call */
    switch (id) {
      /* handle each virtual channel id */
      case 1:
      /* do something for virtual channel 1 */
      break;
      case 2:
      /* do something for virtual channel 2 */
      break;
    }
    /* Send a 2-byte reply to the host : max 256 bytes */
    const char* s = "ok";
    xscope_ep_request_upload(2, s);
}

static void xscope_print(unsigned long long timestamp,
                         unsigned int length,
                         unsigned char *data)
{
    for (int i = 0; i<length; i++) {
        printf("%c", data[i]);
    }
}

static int running;

/* Called when the target program terminates */
static void xscope_exit(void) {
    running = 0;
}

int main(int argc, char *argv[])
{
    if(argc != 2){
        fprintf(stderr, "ERROR missing xscope port number: Usage example %s localhost:12340\n", argv[0]);
        exit(-1);
    }
    xscope_ep_set_print_cb(xscope_print);
    xscope_ep_set_register_cb(xscope_register);
    xscope_ep_set_record_cb(xscope_record);
    xscope_ep_set_exit_cb(xscope_exit);

    int error = 1;
    unsigned attempts = 0;
    const unsigned MAX_ATTEMPTS = 240;

    while (attempts<MAX_ATTEMPTS) {
        error = xscope_ep_connect("localhost", argv[1]);
        if (0 == error) {
            break;
        }
        sleep(1);
        attempts++;
    }

    if (error) {
        fprintf(stderr, "xscope_ep_connect: failed %d attempts\n", attempts);
        return 1;
    }
    running = 1;
    while (running) {
        sleep(1);
    }
    xscope_ep_disconnect();
    return 0;
}

Target program¶

main.xc¶

#include <platform.h>
#include <xscope.h>

extern "C" {
    void main_tile0(chanend);
}

int main (void)
{
    chan xscope_chan;
    par
    {
        xscope_host_data(xscope_chan);
        on tile[0]: main_tile0(xscope_chan);
    }
    return 0;
}

test.c¶

void xscope_user_init(void) {
    xscope_register(2,
        XSCOPE_CONTINUOUS, "V", XSCOPE_INT, "mV", /* Virtual channel 1 */
        XSCOPE_CONTINUOUS, "I", XSCOPE_INT, "mA", /* Virtual channel 2 */
    );
}

void main_tile0(chanend_t xscope_end)
{
    xscope_mode_lossless();
    xscope_connect_data_from_host(xscope_end);

    xscope_int(1, 45);              /* Send 45 to virtual channel 1 */

    // Read response from host
    int bytes_read = 0;
    SELECT_RES(CASE_THEN(xscope_end, read_host_data)) {
        read_host_data: {
            xscope_data_from_host(xscope_end, (char *)buffer_ptr, &bytes_read);
        }
    }
    xscope_int(2, 578);             /* Send 578 to virtual channel 2 */

    // Read response from host
    int bytes_read = 0;
    SELECT_RES(CASE_THEN(xscope_end, read_host_data)) {
        read_host_data: {
            xscope_data_from_host(xscope_end, (char *)buffer_ptr, &bytes_read);
        }
    }
}

Specifying a port number for xgdb and the user host program¶

An example of an explicitly chosen port number is:

xgdb -ex "connect --xscope-port-blocking --xscope-port localhost:45678"  led-flash.xe

Allow xgdb to choose a port number and bind – avoiding a race condition¶

It is often difficult to choose a port number and avoid the race condition where another program on the host computer binds to that number. This race can be prevented by allowing xgdb to choose the port number, and bind to it (which is an atomic operation and prevents another program from using that number). xgdb prints the port number it has used, which is then passed to the host program. The following example shows the xgdb this:

xgdb -ex "connect --xscope-port-blocking --xscope-port :"  led-flash.xe

Host/target data throughput¶

The throughput in each direction using both the xscope interface and the JTAG interface is shown below.

xscope throughput¶
Host machine and OS	Host to target (xscope) [Kbytes/s]	Target to host (xscope) [Kbytes/s]	Host to target (JTAG) [Kbytes/s]	Target to host (JTAG) [Kbytes/s]
Intel I3 NUC PC Centos 7 running natively	1105	6926	2.7	2.8
Intel I3 NUC PC Ubuntu 20.04 running natively	1053	6929	2.8	2.9
Intel I3 NUC PC Windows 10 running natively	1031	6926	2.7	2.9
Intel I7 Laptop Centos 7 running in a VM	932	5183	4.2	15.9

It can be seen that in the direction from target to host, when using the xscope interface the maximum throughput of the XTAG device has been reached (for OSes running natively). This data is streamed from the target to the host without handshaking. In the direction from host to target the data is transferred in a series of blocks along with a handshake for each, which is why the throughput is significantly lower.

Sample-based profiling of the target program¶

The tools provide a mechanism to profile a target program and report the time spent executing its lines and functions, as a flat call graph. It does this non-intrusively by sampling at a low frequency, which might vary considerably, the program counter of each logical core. The samples are captured in a set of gprof data files, and a report generated with the tools xgprof.

This approach is useful for gaining insight into the behaviour of certain types of program, for example those which carry out a repetitive task. It may be useful for debugging a program which is failing to run as intended.

Capturing the sample data¶

Run and capture sample data using the -–gprof option to the connect command to xgdb. When xgdb is quit a set of gprof files (with the extension .gprof) will be written in the current working directory. The filename of each gprof file indicates the tile and logical core which it covers. For example, start capture with:

xgdb -ex "connect --gprof" -ex load -ex continue CircularBuffer.xe

Leave xgdb running for a period to capture samples, interrupt it with Ctrl-C and exit xgdb with the quit command. On exit the gprof profile data files will be written to the current working directory.

Analysing the sample data¶

Spit the target program (.xe) file using the xobjdump -s to obtain the Elf files for each tile. For example:

xobjdump -s CircularBuffer.xe

For the next step, the Elf image_n0c0_2.elf is used for tile 0 analysis, the Elf image_n0c1_2.elf is used for tile 1 and so on. Ignore Elf images without the _2 suffix (these are bootstrap images used to provide system initialisation).

Generate a flat profile report for a logical core with the tool xgprof, supplying the Elf for the tile and the gprof file for the logical core of the tile. It is typically necessary use a selection of report levels to understand the behaviour of the target program. For example, a summary report may be shown with:

xgprof -b image_n0c0_2.elf  tile[0]_core0.gprof

A detailed report at the source line level may be shown with:

xgprof -l -b image_n0c0_2.elf tile[0]_core0.gprof

A very detailed report at the address level with hit-counts may be shown with:

xgprof -C -l -b image_n0c0_2.elf tile[0]_core0.gprof

Profiling a target program which boots from flash¶

The following command may be used to capture profile data for a system which booted from flash:

xgdb -ex "attach –gprof --nointerrupt" test.xe

where test.xe was used to build the flash image (or to build the upgrade image within the flash device) and is currently executing.

Leave xgdb running for a period to capture samples, interrupt with Ctrl-C and exit xgdb with the quit command. On exit the gprof profile data files will be written to the current working directory.

Follow the steps described above to analyse the data files.

Target errors and warnings¶

xSCOPE not supported¶

The following message may be shown when xrun or xgdb is launched with the -–xscope option. This occurs because the application does not make the call xscope_config_io(XSCOPE_IO_BASIC) from a function named xscope_user_init()

WARNING: tile[0] - xSCOPE not supported by application, I/O will be via JTAG

This implies any host-IO will be transported over the JTAG interface which is highly intrusive to the target program.

Failure to parse XN file¶

When xrun or xgdb connects and loads a program to the target it configures the target using the target XN file (and associated configuration files) supplied to xcc with the -target option.

If the following message is shown the clocks and clock dividers in the target will not be set correctly and the target program may not function:

Warning: could not parse XN file, error /tmp/.xgdb21287-I8WMQBQG/platform.xn:11 Error: XN11101 Configuration file for node type "XTAG4" not found.
, PLL will not be set to expected value

This may be because a local XN file and configuration file was used to build the target program. In the example above the file XTAG4.cfg could not be found in the tools installation. The location of these local XN and configuration files may be specified by setting the search path environment variables XCC_TARGET_PATH and XCC_DEVICE_PATH respectively. For example, on a Linux host, the following command adds the current working directory to the paths that will be searched:

% XCC_TARGET_PATH=. XCC_DEVICE_PATH=.:${XCC_DEVICE_PATH} xgdb …

Command examples¶

xgdb examples¶

In the following examples xgdb commands are often supplied as a sequence of -ex options on the xgdb command line. But the they may also be supplied in a command file or typed interactively at the gdb prompt. Commands may be abbreviated for convenience, but abbreviated forms must not be ambiguous.

Load and run a program¶

The following example connects to a target, loads the target program test.xe into RAM and starts it running. Once launched the program must be interrupted with a Ctrl-C action if it does not terminate, either to quit xgdb or to enter further xgdb commands. A Ctrl-C action is made by the holding down both the Ctrl key and the C key on the keyboard:

% xgdb -ex connect -ex load -ex continue test.xe

Note the load command runs two phases. The first phase loads a setup image (which is automatically generated by the tools) to the target SRAM which is executed to initialise it. The second phase loads the target program which was built from the user’s source code.

Breakpoints¶

A breakpoint may be set symbolically or with a numerical address to stop execution of all tiles when the control flow of a logical core reaches that address. The gdb prompt is shown along with a diagnostic message indicating the reason the program stopped.

The xgdb command “break” inserts a soft breakpoint in RAM. There is no limit to the number of soft breakpoints that may be set. A soft breakpoint is implemented by writing a dcall instruction to the breakpoint address in the RAM of the tile.

For example:

(gdb) break my_func
(gdb) break *0x80402

In some cases a soft breakpoint cannot be used, for example where a program will be loaded to RAM over an external link after the breakpoint is set. The xgdb command “hbreak” can be used. This will use the hardware emulation debug feature within the tile to set a breakpoint. A maximum of three hardware breakpoints may be set:

(gdb) hbreak my_func

Watchpoints¶

Xgdb may set watchpoints (also known as data breakpoints) to stop all tiles when an access is made to a watched address. Two types of watchpoint command are supported:

watch <location>: stops execution when a store occurs to the specified location
awatch <location>: stops execution when store occurs to or a load occurs from the specified location

xgdb infers the address range to watch based on the type of the argument <location>.

For example, if my_counter is declared as type int in the target program the following will watch for write accesses only to its 4-byte range:

(gdb) watch my_counter

The following will watch for write and read accesses only to my_counter:

(gdb) awatch my_counter

A watch may be set on an address with a defined range. The following sets a watch on address 0x80250 with a range of 8 bytes:

(gdb) watch  *((char (*)[8]) 0x80250)

The debug hardware which provides watch support monitors the address issued by a load or store instruction, checking whether it is greater than or equal to the lower bound and less than or equal to the upper bound. If the lower bound is the address of the third byte of a word, and the upper bound is the address of the fourth byte of the word, and a 2-byte store is made to the address of the third byte the watch will trigger. But if a 4-byte store is made to the address of first byte the watch will not trigger (although this store will write to the third and fourth byte which is being watched).

If a watch it is set on a global or static variable before the program is started it may be triggered when the startup code in the function _start() performs initialisation.

Attaching to a running target¶

A target may have booted from flash or launched with xgdb, or performed a flash firmware update. Symbolic debug may be carried out with:

xgdb -ex "attach --adapter-id pr1V0_15"  led-flash.xe

If the target application was built to perform host-IO over JTAG (for example, by making a call to printstrln()) this will be enabled.

Attaching to a running target and capture data to generate a sample-based profiling report¶

The following command can be used to attach to a system which is running and collect profile data without intrusion:

xgdb -ex "attach --nointerrupt --gprof --adapter-id pr1V0_15"  led-flash.xe

xrun examples¶

Listing available XTAGs¶

The -l option to the tool xrun will list all attached xTAGS, showing:

The integer value that may be supplied to the --id option to xrun or to the xgdb connect command
The xTAG type
The unique adapter-id string which may be supplied to the –adapter-id option to xrun, to the xgdb command connect or to the xflash option --adapter-id <>
The type of target connected to the xTAG. The letter O indicates an xCORE-200 XS2A architecture and the letter P an XCORE-AI XS3A architecture. The digits in ‘[]’ indicate the number of devices (XMOS nodes) (note there may be multiple in a package). A single 0 indicates one device.

% xrun -l
Available XMOS Devices
----------------------
  ID    Name                    Adapter ID      Devices
  --    ----                    ----------      -------
  0     XMOS XTAG-3             .BT0u0X2        P[0]
  1     XMOS XTAG-4             BEJMRJ7V        O[0]
  2     XMOS XTAG-3             KAKqyceA        O[0]
  3     XMOS XTAG-4             pr1v0_20        P[0]

If the device is described as “In Use” a host tool running is using it. In some cases, after interrupting a session, an xgdb process may be left without a parent (orphaned), and it continues to hold its xTAG. On Linux hosts the orphaned process should be killed with the command kill and if this fails, with kill -9.

If the device is described with “Invalid firmware” is was last used by a host tool from a different tools release (and may be used again by the same tool). If a connection is made to the device with xrun or xgdb the firmware will be replaced.

Dump the target state¶

The following will dump the state of the target:

xrun --dump-state test.xe

where test.xe is the target program that was launched on the target by an invocation of xrun or was burned to flash with the xflash tool.

The following will dump the state of the target without a .xe file:

xrun --dump-state-no-xe

Note in both cases all tiles will be put in their debug mode which will stop execution of all logical cores.

Reboot an XTAG which fails to respond¶

The --xtagreboot option to the xgdb command connect will force the xTAG reboot:

xgdb -ex “connect -–xtagreboot“

If the xTAG is flagged in use by xrun -l the above command will release it. Note this reboot feature is not available on Windows 10 Pro due to limitations in the standard Windows USB driver.