Skip to content
Projects
Groups
Snippets
Help
Loading...
Sign in
Toggle navigation
W
White Rabbit Trigger Distribution
Project
Project
Details
Activity
Cycle Analytics
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Charts
Issues
0
Issues
0
List
Board
Labels
Milestones
Merge Requests
0
Merge Requests
0
Wiki
Wiki
image/svg+xml
Discourse
Discourse
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Charts
Create a new issue
Commits
Issue Boards
Open sidebar
Projects
White Rabbit Trigger Distribution
Commits
edc81ca5
Commit
edc81ca5
authored
Jul 10, 2019
by
Dimitris Lampridis
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
[doc] wip
parent
4541f38e
Hide whitespace changes
Inline
Side-by-side
Showing
3 changed files
with
184 additions
and
4 deletions
+184
-4
devel.rst
doc/devel.rst
+107
-4
usage_pywrap.rst
doc/usage_pywrap.rst
+16
-0
usage_tools.rst
doc/usage_tools.rst
+61
-0
No files found.
doc/devel.rst
View file @
edc81ca5
...
@@ -4,11 +4,118 @@
...
@@ -4,11 +4,118 @@
Development
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:
.. _hw_dev:
Hardware
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:
.. _gw_dev:
Gateware
Gateware
...
@@ -18,7 +125,3 @@ Gateware
...
@@ -18,7 +125,3 @@ Gateware
Firmware
Firmware
========
========
doc/usage_pywrap.rst
View file @
edc81ca5
...
@@ -31,6 +31,10 @@ will return :cpp:enumerator:`WRTD_ERROR_RESOURCE_UNKNOWN`.
...
@@ -31,6 +31,10 @@ will return :cpp:enumerator:`WRTD_ERROR_RESOURCE_UNKNOWN`.
>>>
wrtd
>>>
wrtd
<
PyWrtd
.
PyWrtd
object
at
0x7fa9aeeaee48
>
<
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
Error
Handling
API
------------------
------------------
...
@@ -75,6 +79,9 @@ Attribute Handling API
...
@@ -75,6 +79,9 @@ Attribute Handling API
Getting
and
setting
boolean
,
integer
and
string
:
ref
:`
Attributes
<
attribute
>`
is
straight
-
forward
.
Getting
and
setting
boolean
,
integer
and
string
:
ref
:`
Attributes
<
attribute
>`
is
straight
-
forward
.
Boolean
Attributes
++++++++++++++++++
..
automethod
::
PyWrtd
.
set_attr_bool
..
automethod
::
PyWrtd
.
set_attr_bool
..
automethod
::
PyWrtd
.
get_attr_bool
..
automethod
::
PyWrtd
.
get_attr_bool
..
code
-
block
::
python
..
code
-
block
::
python
...
@@ -86,6 +93,9 @@ Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is
...
@@ -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
)
>>>
wrtd
.
get_attr_bool
(
'alarm1'
,
PyWrtd
.
WRTD_ATTR_ALARM_ENABLED
)
True
True
Integer
Attributes
++++++++++++++++++
..
automethod
::
PyWrtd
.
set_attr_int32
..
automethod
::
PyWrtd
.
set_attr_int32
..
automethod
::
PyWrtd
.
get_attr_int32
..
automethod
::
PyWrtd
.
get_attr_int32
..
code
-
block
::
python
..
code
-
block
::
python
...
@@ -97,6 +107,9 @@ Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is
...
@@ -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
)
>>>
wrtd
.
get_attr_int32
(
'alarm1'
,
PyWrtd
.
WRTD_ATTR_ALARM_REPEAT_COUNT
)
5
5
String
Attributes
+++++++++++++++++
..
automethod
::
PyWrtd
.
set_attr_string
..
automethod
::
PyWrtd
.
set_attr_string
..
automethod
::
PyWrtd
.
get_attr_string
..
automethod
::
PyWrtd
.
get_attr_string
..
code
-
block
::
python
..
code
-
block
::
python
...
@@ -106,6 +119,9 @@ Getting and setting boolean, integer and string :ref:`Attributes <attribute>` is
...
@@ -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
)
>>>
wrtd
.
get_attr_string
(
'rule1'
,
PyWrtd
.
WRTD_ATTR_RULE_SOURCE
)
'event0'
'event0'
Timestamp
Attributes
++++++++++++++++++++
Getting
and
setting
:
ref
:`
timestamp
`
:
ref
:`
Attributes
<
attribute
>`
is
slightly
different
than
in
the
Getting
and
setting
:
ref
:`
timestamp
`
:
ref
:`
Attributes
<
attribute
>`
is
slightly
different
than
in
the
:
ref
:`
clib
`.
:
ref
:`
clib
`.
...
...
doc/usage_tools.rst
View file @
edc81ca5
...
@@ -2,3 +2,64 @@
...
@@ -2,3 +2,64 @@
Tools
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
------------
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment