.. _devel:

-----------
Development
-----------

This section provides guidelines on how to develop a new WRTD Node (or, modify an :ref:`existing one
<ref_nodes>`), including :ref:`hw_dev`, :ref:`gw_dev` and :ref:`fw_dev`, using the resources
provided by the `WRTD project <https://www.ohwr.org/project/wrtd/>`_. If you simply need to control
an existing WRTD Node, please refer to :numref:`usage` instead.

It should be noted that a new Node need not necessarily use the resources provided by the WRTD
project itself. In fact, the only hard requirement is that the Node is able to send and/or receive
:ref:`Event Messages <message>` over an Ethernet-based LAN.

Of course, the above is the absolute minimum requirement, which is already fullfilled by any LXI
device supporting the relevant LXI extended functions (see also :ref:`lxi`).

Moving one step further, the network interface of the Node should be White Rabbit enabled, to allow
for accurate timestamping and sub-ns synchronisation between the Nodes.


.. _dev_setup:

Setting Up the Environment
==========================

The WRTD development environment has been tested and works best under Linux.

.. todo::

   Add instructions on how to get release source tarball

The source code of WRTD is maintained in a `Git <https://git-scm.com/>`_ repository. To create a
local copy of it, please use:

.. code-block:: console

   $ git clone "https://ohwr.org/project/wrtd.git"

And then `checkout <https://git-scm.com/docs/git-checkout>`_ the correct commit, branch or tag that
you wish to work on. Typically, the latest stable commit will be tracked by the `master
<https://www.ohwr.org/project/wrtd/tree/master>`_ branch, while the latest development commit will
be tracked by the `proposed_master <https://www.ohwr.org/project/wrtd/tree/proposed_master>`_
branch.

Once this is done, you need to bring in the various dependencies of WRTD (which are present as `Git
submodules <https://git-scm.com/book/en/v2/Git-Tools-Submodules>`_ within the WRTD repository):

.. code-block:: console

   $ cd wrtd
   $ git submodule update --init

.. important::

   Despite the fact that many of WRTD's dependencies contain their own submodules, you should not
   bring in those dependencies recursively, as they may create conflicts (e.g. both WRTD and one of
   its submodules depending on another submodule but on a different version of it). WRTD's top-level
   dependencies (which are brought in with the above command) contain everything that is needed for
   development.

Furthermore, you will need a RISC-V cross-compilation toolchain for compiling the firmware for the
Nodes.

.. todo::

   * Add instructions on how to install cross compiler from RPM
   * Add instructions on how to install cross compiler from binary tarball

Alternatively, you can try to build your own toolchain like this:

.. code-block:: console

   $ git clone "https://ohwr.org/project/soft-cpu-toolchains.git"
   $ cd soft-cpu-toolchains/riscv
   $ sh ./build-riscv.sh

This will checkout the ``master`` branch of the repository and start the build process, which takes
a long time to complete.

Once the process is complete, the resulting RISC-V toolchain binaries will be placed under
``soft-cpu-toolchains/riscv/riscv-toolchain/bin``. You should either copy them to somewhere within
your system's path (typicallly ``/usr/local/bin``), or set the environment variable
``CROSS_COMPILE_TARGET`` to point to the correct location, with the ``riscv32-elf-`` suffix appended
to the path, like this:

.. code-block:: console

   $ export CROSS_COMPILE_TARGET="<path_to_repository>/riscv/riscv-toolchain/bin/riscv32-elf-"

You either need to configure the above command to be run automatically on a new terminal (typically
by putting the command in ``~/.profile`` or ``~/.bash_profile`` but this depends ultimately on the
shell you are using), or you should run it every time you start a new terminal and need to compile
RISC-V firmware.

.. _hw_dev:

Hardware
========

Hardware-wise, WRTD does not impose any particular requirements. It is assumed that the device is
capable of producing and/or consuming "events" (e.g. trigger in, trigger out), otherwise there is no
point in using WRTD.

Other than that, the only requirement on the hardware is that it supports `White Rabbit (WR)
<https://www.ohwr.org/project/white-rabbit>`_.

If you are designing your own board and you would like to have something as a reference, here's a
few open-source boards that already support WR:

* `SPEC <https://www.ohwr.org/projects/spec>`_ (Xilinx Spartan6 FPGA)
* `FASEC <https://www.ohwr.org/projects/fasec>`_  (Xilinx Zynq SoC FPGA)
* `VFC-HD <https://www.ohwr.org/projects/vfc-hd>`_ (Intel Arria V)

All of the above examples make use of the `WR PTP Core
<https://www.ohwr.org/project/wr-cores/wikis/wrpc-core>`_ inside their FPGA.

.. _gw_dev:

Gateware
========

.. _fw_dev:

Firmware
========
