Skip to content

W
White Rabbit Trigger Distribution
Commit edc81ca5 authored by Dimitris Lampridis's avatar Dimitris Lampridis
Browse files
Options

[doc] wip

parent 4541f38e
Hide whitespace changes
Inline Side-by-side
Showing with 184 additions and 4 deletions
doc/devel.rst
View file @ edc81ca5
......@@ -4,11 +4,118 @@
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
......@@ -18,7 +125,3 @@ Gateware
Firmware
========
doc/usage_pywrap.rst
View file @ edc81ca5
......@@ -31,6 +31,10 @@ will return :cpp:enumerator:`WRTD_ERROR_RESOURCE_UNKNOWN`.
>>> wrtd
<PyWrtd.PyWrtd object at 0x7fa9aeeaee48>
.. hint::
The provided :ref:`tools <tools>` are built on top of this Python wrapper, so they also serve as
a good example of how to use the wrapper.
Error Handling API
------------------
......@@ -75,6 +79,9 @@ Attribute Handling API
Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is straight-forward.
Boolean Attributes
++++++++++++++++++
.. automethod:: PyWrtd.set_attr_bool
.. automethod:: PyWrtd.get_attr_bool
.. code-block:: python
......@@ -86,6 +93,9 @@ Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is
>>> wrtd.get_attr_bool('alarm1', PyWrtd.WRTD_ATTR_ALARM_ENABLED)
True
Integer Attributes
++++++++++++++++++
.. automethod:: PyWrtd.set_attr_int32
.. automethod:: PyWrtd.get_attr_int32
.. code-block:: python
......@@ -97,6 +107,9 @@ Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is
>>> wrtd.get_attr_int32('alarm1', PyWrtd.WRTD_ATTR_ALARM_REPEAT_COUNT)
5
String Attributes
+++++++++++++++++
.. automethod:: PyWrtd.set_attr_string
.. automethod:: PyWrtd.get_attr_string
.. code-block:: python
......@@ -106,6 +119,9 @@ Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is
>>> wrtd.get_attr_string('rule1', PyWrtd.WRTD_ATTR_RULE_SOURCE)
'event0'
Timestamp Attributes
++++++++++++++++++++
Getting and setting :ref:`timestamp` :ref:`Attributes <attribute>` is slightly different than in the
:ref:`clib`.
......
doc/usage_tools.rst
View file @ edc81ca5
......@@ -2,3 +2,64 @@
Tools
=====
WRTD provides two comand-line, Python based tools for accessing a :ref:`node`. One
(:ref:`wrtd_config`) is used to add/remove/configure :ref:`Rules <rule>` and :ref:`Alarms <alarm>`,
and to display information about the :ref:`node` while the other (:ref:`wrtd_logging`) is used for
reading entries from the :ref:`event_log`.
Both tools have a built-in help system that can be accessed by passing the ``-h`` option to the
tool.
Both tools take an obligatory ``-D`` option to specify the :ref:`node` to access. For more details,
please refer to :ref:`node_id`.
For details on how to install these tools (and their dependencies), please refer to
:numref:`installation`.
.. _wrtd_config:
wrtd_config
-----------
.. code-block:: console
> python wrtd-config.py -h
usage: wrtd-config.py [-h] -D DEV <command> ...
WRTD node configuration tool
optional arguments:
-h, --help show this help message and exit
-D DEV, --dev-id DEV MockTurtle device ID (integer) to open
Available commands:
<command> (Use "<command> -h" to get more details)
sys-info Show system information
sys-time Show current system time
set-log Enable/Disable logging
clear-log Clear pending log entries
list-rules List all defined Rules
add-rule Define a new Rule
set-rule Configure a Rule
remove-rule Delete a Rule
remove-all-rules Delete all Rules
enable-rule Enable a Rule
disable-rule Disable a Rule
disable-all-rules Disable all Rules
rule-info Display information about a Rule
reset-rule-stats Reset all statistics of a Rule
list-alarms List all defined Alarms
add-alarm Define a new Alarm
set-alarm Configure an Alarm
remove-alarm Delete an Alarm
remove-all-alarms Delete all Alarms
enable-alarm Enable an Alarm
disable-alarm Disable an Alarm
disable-all-alarms Disable all Alarms
alarm-info Display information about an Alarm
.. _wrtd_logging:
wrtd_logging
------------
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment