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 :file:`main.c`: .. literalinclude:: examples/single-tile/main.c :caption: main.c :linenos: Build an executable ------------------- Now, let's build this into an executable using :ref:`XCC`. The executable will be produced within the XE file :file:`a.xe`: .. code-block:: bash $ xcc -target=XCORE-200-EXPLORER -g main.c The :option:`xcc -g` tells the XCC tool to add debug information. We'll need that later. What is a target? ^^^^^^^^^^^^^^^^^ Fundamentally, :option:`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 :ref:`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 :ref:`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 :file:`a.xe` using :option:`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 :ref:`configure` and :ref:`check` your XTAG setup. .. _lightning_intro_debugging_using_xgdb: Debugging using XGDB on real hardware ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ You have already used the :ref:`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: .. code-block:: bash $ xgdb a.xe This starts a new debug session with a new (gdb) prompt. You must now :gdb-cmd:`connect` to the attached hardware and :gdb-cmd:`load` the application code: .. code-block:: text (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: .. code-block:: text (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 :ref:`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: .. code-block:: bash $ 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 :ref:`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 :ref:`lightning_intro_debugging_using_xgdb`, except we use :gdb-cmd:`connect -s ` to connect to the simulator instead of the hardware: .. code-block:: text (gdb) connect -s ... (gdb) load ... Summary ------- In this lightning tour of the command line tools, you have built an application to produce an :ref:`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: * :ref:`XCC` * :ref:`XRUN` * :ref:`XGDB` * :ref:`XSIM`