Lightning intro

This introduction aims to give you a very rapid introduction to the major tools and some of the fundamental concepts in the tools.

First, let’s write the simplest single-threaded source file main.c:

main.c
1#include <stdio.h>
2
3int main(void) {
4  printf("Hello world!\n");
5  return 0;
6}

Build an executable

Now, let’s build this into an executable using XCC. The executable will be produced within the XE file a.xe:

$ xcc -target=XCORE-200-EXPLORER -g main.c

The xcc -g tells the XCC tool to add debug information. We’ll need that later.

What is a target?

Fundamentally, xcc -target specifies the core architecture of the target we are building for, in this case the XS2 architecure. But actually it specifies much more that this - for instance, it specifies how many cores are present, how they are connected, what the clock frequencies are, and much more. The target is thus most closely associated with the physical PCB and the xcore packages on that PCB.

What is 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 core described by the target.

Run on real hardware

The XRUN tool provides a convenient way of launching an executable on real hardware.

Connect your XCORE-200-EXPLORER development board to your host PC via the XTAG connector. Make sure you’ve also supplied power to the development board itself.

Run a.xe using xrun --io:

$ xrun --io a.xe
Hello world!

Congratulations! You’ve just built and executed your first xcore application. If you have problems with this step, you may need to configure and check your XTAG setup.

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

Run on the simulator

The tools include a near cycle-accurate hardware simulator called XSIM. XSIM is not just a simulation of an xcore tile itself - instead it simulates the entire package in which the tile sits. So in this example, it simulates both the tiles in an XCORE-200-EXPLORER package:

$ xsim a.xe
Hello world!

This output looks exactly the same as the output from XRUN. What’s the difference?

  • XRUN loads and runs an XE file on a real piece of hardware attached via an XTAG

  • XSIM loads and runs an XE file on a simulated piece of hardware, where that simulation is running on your host computer

How does XSIM know that it is simulating a two-tile package? XSIM is configured by the SYSCONFIG sector contained in the .xe file.

Debugging using XGDB

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

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

Summary

In this lightning tour of the 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: