.. _switch_setup:

Communicating between tiles
===========================

Usually applications running on separate tiles will need to communicate between
tiles and synchronise their activity. Such communication is passed via XLINKS
and switches using the
`xCONNECT architecture <https://www.xmos.ai/download/xCONNECT-Architecture(1.0).pdf>`_.
A mapping file can also declare channels between the tiles it places
entry-points on.

Declaring a channel in a mapfile
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

More concretely, the XCORE-200-EXPLORER has two tiles and a switch for
communication between them contained within the package. The tools will
automatically configure a channel via the switch using :file:`mapfile.xc`
as below:

.. literalinclude:: examples/switch-setup/mapfile.xc
  :caption: mapfile.xc

In this example, the tile level entrypoint functions each accept a chanend. In
the forward-declarations these functions take a ``chanend`` argument; this is
compatible with a lib_xcore ``chanend_t`` at link-time. The ``chan`` keyword is
used in ``main`` to declare a channel. When a channel is passed to tile-level
main, an end is automatically assigned to each entrypoint which uses it. In the
task-level entrypoints, these chanends are used just like local ones.

Using the channel
^^^^^^^^^^^^^^^^^

In the tile-level entrypoints, the chanends are used as per
:doc:`/prog-guide/quick-start/c-programming-guide/index`. This time in
:file:`main.c`, we have a more interesting pair of tile functions. Each is
passed a chanend_t :samp:`c`, and they use it to communicate between tiles and
synchronise their activities.

.. literalinclude:: examples/switch-setup/main.c
  :caption: main.c

Building and executing this multi-tile application produces the expected result:

.. code-block:: bash

  $ xcc -target=XCORE-200-EXPLORER mapfile.xc main.c
  $ xrun --io a.xe
  Tile 0: Result 0
  Tile 1: Iteration 0 Accumulation: 0
  Tile 1: Iteration 1 Accumulation: 1
  Tile 1: Iteration 2 Accumulation: 3
  Tile 1: Iteration 3 Accumulation: 6
  Tile 1: Iteration 4 Accumulation: 10
  Tile 1: Iteration 5 Accumulation: 15
  Tile 1: Iteration 6 Accumulation: 21
  Tile 1: Iteration 7 Accumulation: 28
  Tile 1: Iteration 8 Accumulation: 36
  Tile 1: Iteration 9 Accumulation: 45
  Tile 0: Result 45

Summary
^^^^^^^

You have now written a multi-tile application which, through the declarations in
the mapfile, configures a path through the XLINKS and switch and provides
pre-allocated chanends to the C functions.