A single-tile program#

This section introduces some of the key tools required to build and run a simple program on a single tile.

To run on hardware one of the following XMOS evaluation boards is required:

XK-EVK-XU316 (with an xcore.ai processor)
XCORE-AI-EXPLORER (with an xcore.ai processor)
XCORE-200-EXPLORER (with an XCORE-200 processor)

Replace the target defintion string used in the following examples (-target=XK-EVK-XU316) with that of the board being used, for example: -target=XCORE-AI-EXPLORER.

The following board and XTAG type combinations are supported:

The XK-EVK-XU316 board has an on-board XTAG4 adapter with a dedicated USB micro-B interface which must be plugged into the host computer
The XCORE-AI-EXPLORER board requires an XTAG4 adapter to be plugged into its XSYS2 connector
The XCORE-200-EXPLORER board requires an XTAG3 adapter to be plugged into its XSYS connector

See: Configure the XTAG and Check the XTAG.

Build an executable#

The following is a simple example contained in the single source file main.c:

Listing 9 main.c#

#include <stdio.h>

int main(void) {
  printf("Hello world!\n");
  return 0;
}

This is built into an executable using the tool XCC. The output is an xcore executable in the XE file a.xe:

$ xcc -target=XK-EVK-XU316 -g main.c

The option -g tells the XCC tool to add debug information. This will be used later.

The target definition#

The option -target=XK-EVK-XU316 provides the tools with a description of the target board on which the application will execute. This particular XMOS evaluation board description is provided with the XMOS XTC Tools (in the target subdirectory). A user will normally provide a description of their board, derived from an XMOS evaluation board description.

The board description includes information about the xcore devices present, their architecture, external flash devices and frequencies at which sub-systems are clocked.

The content of an XE file#

An XE file is often referred to as an executable. However, it is actually a package of files which include an ELF file for each tile in the target definition.

Running the program on the simulator#

The tools include a near cycle-accurate hardware simulator XSIM. XSIM simulates of entire XMOS device, and may also simulate certain external devices such as a QSPI flash memory.

$ xsim a.xe
Hello world!

Run on real hardware#

The XRUN tool is used to launching an executable on real hardware.

Connect your XK-EVK-XU316 development board to your host PC via the XTAG3 or XTAG4 adaptor. Make sure you’ve also supplied power to the development board itself.

Run a.xe using xrun --io:

$ xrun --io a.xe
Hello world!

Note

The option –io is required to make XRUN show the application printf output on the host computer’s console, which also makes it wait until the application has terminated.

Note

If you have problems with this step, you may need to configure and check your XTAG setup.

Congratulations! You’ve just built and executed your first xcore application.

Debugging using XGDB on real hardware#

You have already used the XGDB debugger indirectly when you used the simplified XRUN tool. However, if you want greater insight into how the application is running, you need to use the XGDB debugger directly. Start the debugger:

$ xgdb a.xe

This starts a new debug session with a new (gdb) prompt. You must now connect to the attached hardware and load the application code:

(gdb) connect
...
(gdb) load
...

From now on, using XGDB on this single-threaded program is the same as using normal GDB. For instance, create a breakpoint, run up to that breakpoint, step to the next line and quit:

(gdb) break main
Breakpoint 1 at 0x400fc: file main.c, line 4.
(gdb) continue

Breakpoint 1, main () at main.c:4
4         printf("Hello world!\n");
Current language:  auto; currently minimal
(gdb) step
Hello world!
5         return 0;
(gdb) quit

Debugging using XGDB#

It is possible to use XGDB to debug on the XSIM simulator. The steps are identical to Debugging using XGDB on real hardware, except use connect -s to connect to the simulator instead of the hardware:

(gdb) connect -s
...
(gdb) load
...

Summary#

In this brief overview of some command line tools, you have built an application to produce an XE file. You have run and debugged the XE file on real hardware, and done the same on the simulator.

Through the tour you have used the following tools: