.. _multi_tile:

Targeting multiple tiles
========================

In the :doc:`previous example <single-tile>`, the code targeted only a
single tile. Most real applications will instead target two or more tiles. It is
not possible to target multiple tiles using a single C application as the tiles
are complete, separate processors. Instead each tile runs its own application,
and each tile's application can communicate with other tiles using the channels
documented previously. To aid development of multi-tile applications, the XMOS
tools allow the use of a special 'mapping file' which can be used to specify an
entry-point for each tile in a network. This is instead of specifying a ``main``
function in C - which is not allowed when a mapping file is used.

.. warning::

  For historical reasons, the format of the mapping is C-like. However, this
  format should not be treated as C-source and is likely to be deprecated in
  future versions of the tools and replaced with a purely declarative format.
  Developers are therefore recommended to avoid any procedural code within a
  mapfile.

Using a mapfile
^^^^^^^^^^^^^^^

To map code onto both of the tiles on a XCORE-200-EXPLORER, it is necessary
to describe that mapping in a file which we will call :file:`mapfile.xc`. An
example is shown below:

.. literalinclude:: examples/multi-tile/mapfile.xc
   :caption: mapfile.xc

This mapfile references the two functions in :file:`main.c`:

.. literalinclude:: examples/multi-tile/main.c
   :caption: main.c

Now build and execute this multi-tile application on real hardware to see the
printed output:

.. code-block:: bash

  $ xcc -target=XCORE-200-EXPLORER mapfile.xc main.c
  $ xrun --io a.xe
  Hello from tile 0
  Hello from tile 1

Summary
^^^^^^^

In this example, you have written a mapfile using the declarative components of
XC language to deploy two C functions onto the two tiles of an
XCORE-200-EXPLORER.

.. seealso::

  At this point, you might proceed to the next topic, or you might chose to
  explore this example further:

  * :ref:`using_xsim_which_tile`
  * :ref:`understanding_xe_structure`