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
71657cc9
Commit
71657cc9
authored
Jul 29, 2019
by
Javier Serrano
Committed by
Dimitris Lampridis
Jul 30, 2019
1
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
[doc] review of documentation
parent
da3f42d9
Hide whitespace changes
Inline
Side-by-side
Showing
10 changed files
with
35 additions
and
32 deletions
+35
-32
basic_concepts.rst
doc/basic_concepts.rst
+4
-4
devel.rst
doc/devel.rst
+2
-1
introduction.rst
doc/introduction.rst
+5
-5
ref_spec_fmc_adc.rst
doc/ref_spec_fmc_adc.rst
+1
-1
ref_svec_tdc_fd.rst
doc/ref_svec_tdc_fd.rst
+2
-2
usage_clib.rst
doc/usage_clib.rst
+12
-10
usage_pywrap.rst
doc/usage_pywrap.rst
+2
-2
wrtd-common.h
software/include/wrtd-common.h
+1
-1
libwrtd.c
software/lib/libwrtd.c
+2
-2
libwrtd.h
software/lib/libwrtd.h
+4
-4
No files found.
doc/basic_concepts.rst
View file @
71657cc9
...
...
@@ -119,7 +119,7 @@ a digital I/O board.
A Local Channel output transmits output Events from the :ref:`node`. Typical examples include a Fine
Delay generator or a TTL output channel on a digital I/O board.
All Local Channels use
reserved
:ref:`Event IDs <event_id>`.
All Local Channels use
specific IDs as described in
:ref:`Event IDs <event_id>`.
.. _message:
...
...
@@ -152,7 +152,7 @@ counter that gets increased by one every time a new Event is generated.
.. hint:: The sequence counter can be used to detect lost or duplicate Messages.
.. hint:: Altough there are currently no "Data Fields" defined (octets 37 and beyond), it should be
.. hint:: Alt
h
ough there are currently no "Data Fields" defined (octets 37 and beyond), it should be
highlighted that the LXI Event message format supports an arbitrary number of data fields, in the
form of Type/Length/Value (TLV) triplets, which could be used to provide additional functionality
to WRTD in the future.
...
...
@@ -217,8 +217,8 @@ Attributes can be attached to a :ref:`rep_cap`, or they can be "global" (apply t
:ref:`node`).
.. note:: Since global Attributes are not attached to any :ref:`rep_cap`, when using one of the
functions to get/set a global Attribute, a special :ref:`rep_cap_id`
must be passed to the
function (:c:macro:`WRTD_GLOBAL_REP_CAP_ID`)
as the Selector.
functions to get/set a global Attribute, a special :ref:`rep_cap_id`
(:c:macro:`WRTD_GLOBAL_REP_CAP_ID`) must be passed to the function
as the Selector.
Please refer to the :ref:`api_attr` for more details.
...
...
doc/devel.rst
View file @
71657cc9
...
...
@@ -116,7 +116,8 @@ Other than that, the only requirement on the hardware is that it supports `White
<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:
page which can `help you <https://www.ohwr.org/project/white-rabbit/wikis/WRReferenceDesign>`_, or,
more specifically, here's a list with a few open-source boards that already support WR:
* `SPEC <https://www.ohwr.org/projects/spec/wikis>`_ (Xilinx Spartan6 FPGA)
* `FASEC <https://www.ohwr.org/projects/fasec/wikis>`_ (Xilinx Zynq SoC FPGA)
...
...
doc/introduction.rst
View file @
71657cc9
.. _introduction:
ssh://git@ohwr.org:7999/project/wrtd.git
.. _introduction:
------------
Introduction
...
...
@@ -9,7 +9,7 @@ over a White Rabbit (WR) network.
As can be seen in :numref:`fig-wrtd-overview`, WRTD Nodes receive "input" Events and distribute them
to other Nodes over WR in the form of network Messages that are used to transfer the Timestamp of
the input Event. The receiving Nodes are programmed to execute some "output Event (action) upon
the input Event. The receiving Nodes are programmed to execute some "output
"
Event (action) upon
reception of a particular Message, potentially with some fixed delay added to the Timestamp.
.. figure:: graphics/wrtd_overview.png
...
...
@@ -30,7 +30,7 @@ There are two main categories of WRTD applications:
synchronisation provided by WR).
#. The receiving Nodes are "recording" devices (e.g. digitisers), capable of storing data in a
recording buffer. Te source Node transmits the Message, with or without a fixed delay. When one
recording buffer. T
h
e source Node transmits the Message, with or without a fixed delay. When one
of the destination Nodes receives the Message, it stops recording and rolls-back its buffer to
the moment specified by the Timestamp in the received Message (provided that it has a large
enough buffer to compensate for the latency). Thus, all Nodes will deliver recorded data from the
...
...
@@ -80,7 +80,7 @@ exchange of real-time event messages between instruments. These include:
The core specification requires (Rule 6.1) that all LXI devices provide an `Interchangeable Virtual
Instruments (IVI) <http://ivifoundation.org/>`_ driver. Furthermore, it requires (Rule 6.1.1) that
all LXI devices supporting the exch
na
ge of event messages, do so by providing an API that conforms
all LXI devices supporting the exch
an
ge of event messages, do so by providing an API that conforms
to the `IVI-3.15 IviLxiSync Specification`_.
Since the LXI event exchanging mechanism is conceptually very close to WRTD, it was decided to
...
...
@@ -95,7 +95,7 @@ design WRTD to be as close to LXI as possible. In particular:
.. hint:: Do not worry if you do not understand some of the terminology yet. It will be explained in
:numref:`basic_concepts`.
In the future, and with `White Rabbit being standardi
z
ed within the next release of IEEE-1588
In the future, and with `White Rabbit being standardi
s
ed within the next release of IEEE-1588
<https://www.ohwr.org/project/wr-std/wikis/home>`_, it is foreseen to try to merge WRTD with
IVI/LXI. A possible way to do this would be to add a new IVI specification, similar to IVI-3.15,
describing the API to control WRTD-enabled devices. This API would be an extension, allowing any
...
...
doc/ref_spec_fmc_adc.rst
View file @
71657cc9
...
...
@@ -75,7 +75,7 @@ The five :ref:`Local Input Channels <local_channel>` are mapped as follows:
.. note:: In order for any of the :ref:`Local Input Channels <local_channel>` to produce an
:ref:`event`, the user must also properly configure the trigger source of the FMC-ADC via
the ADC library. This falls outside the
the
scope of WRTD library.
the ADC library. This falls outside the scope of WRTD library.
The single :ref:`Local Output Channel <local_channel>` (``LC-O1``) is mapped to the "WRTD" trigger
input of the FMC-ADC.
...
...
doc/ref_svec_tdc_fd.rst
View file @
71657cc9
...
...
@@ -39,12 +39,12 @@ This is a WRTD :ref:`node` based on the `Simple VME FMC Carrier (SVEC)
the FMCs attached, the :ref:`Node` will work if only one of the two (TDC or FD) is
present, as long as it is connected to the correct FMC slot.
The basic principle of this :ref:`node` is simple:
I
t takes in external pulses on its FMC-TDC
The basic principle of this :ref:`node` is simple:
i
t takes in external pulses on its FMC-TDC
inputs, timestamps them using WR time and converts them to WRTD :ref:`Messages <message>`, to be
sent over the WR network. Conversely, the :ref:`node` also receives WRTD :ref:`Messages <message>`
which are then used to generate pulses at a predefined moment on one of the FMC-FD outputs. As such,
it can be seen as a "pulse-to-message" and "message-to-pulse" converter with apllications in the
field
of pulse distribution, trigger syncrh
onisation, etc.
field
s of pulse distribution, trigger synchr
onisation, etc.
.. figure:: graphics/wrtd_ref_design_svec_list_simple.png
:name: fig-ref_svec_list
...
...
doc/usage_clib.rst
View file @
71657cc9
...
...
@@ -167,11 +167,13 @@ parameter should be set to :c:macro:`WRTD_GLOBAL_REP_CAP_ID`.
int main(void) {
wrtd_dev *wrtd;
wrtd_status status;
bool log_empty;
status = wrtd_init("MT01", false, NULL, &wrtd);
status = wrtd_get_attr_bool(wrtd, WRTD_GLOBAL_REP_CAP_ID,
WRTD_ATTR_EVENT_LOG_EMPTY);
WRTD_ATTR_EVENT_LOG_EMPTY,
&log_empty);
wrtd_close(wrtd);
}
...
...
@@ -350,12 +352,12 @@ Configuration of an Alarm happens by setting the relevant :ref:`Attributes <attr
status = wrtd_remove_all_alarms(wrtd);
/* Add three alarms */
status = wrtd_add_alarm("alarm1");
status = wrtd_add_alarm("alarm2");
status = wrtd_add_alarm("alarm3");
status = wrtd_add_alarm(
wrtd,
"alarm1");
status = wrtd_add_alarm(
wrtd,
"alarm2");
status = wrtd_add_alarm(
wrtd,
"alarm3");
/* Remove the 2nd alarm */
status = wrtd_remove_alarm("alarm2");
status = wrtd_remove_alarm(
wrtd,
"alarm2");
/* Get number of defined alarms */
status = wrtd_get_attr_int32(wrtd, WRTD_GLOBAL_REP_CAP_ID,
...
...
@@ -409,12 +411,12 @@ Configuration of a Rule happens by setting the relevant :ref:`Attributes <attrib
status = wrtd_remove_all_rules(wrtd);
/* Add three rules */
status = wrtd_add_rule("rule1");
status = wrtd_add_rule("rule2");
status = wrtd_add_rule("rule3");
status = wrtd_add_rule(
wrtd,
"rule1");
status = wrtd_add_rule(
wrtd,
"rule2");
status = wrtd_add_rule(
wrtd,
"rule3");
/* Remove the 2nd rule */
status = wrtd_remove_rule("rule2");
status = wrtd_remove_rule(
wrtd,
"rule2");
/* Get number of defined rules */
status = wrtd_get_attr_int32(wrtd, WRTD_GLOBAL_REP_CAP_ID,
...
...
@@ -446,7 +448,7 @@ Configuration of a Rule happens by setting the relevant :ref:`Attributes <attrib
status = wrtd_init("MT01", false, NULL, &wrtd);
/* Add a rule */
status = wrtd_add_rule("rule1");
status = wrtd_add_rule(
wrtd,
"rule1");
/* Set rule to listen for events coming on local channel
input 1 and generate a message on the network with
...
...
doc/usage_pywrap.rst
View file @
71657cc9
...
...
@@ -180,7 +180,7 @@ Alarms API
>>>
wrtd
.
set_attr_bool
(
'alarm1'
,
PyWrtd
.
WRTD_ATTR_ALARM_ENABLED
,
True
)
>>>
wrtd
.
get_attr_bool
(
'alarm1'
,
PyWrtd
.
WRTD_ATTR_ALARM_ENABLED
)
True
>>>
wrtd
.
disable_all_
rule
s
()
>>>
wrtd
.
disable_all_
alarm
s
()
>>>
wrtd
.
get_attr_bool
(
'alarm1'
,
PyWrtd
.
WRTD_ATTR_ALARM_ENABLED
)
False
...
...
@@ -207,7 +207,7 @@ Alarms API
..
automethod
::
PyWrtd
.
get_alarm_name
..
code
-
block
::
python
>>>
wrtd
.
add_
rule
(
'alarm1'
)
>>>
wrtd
.
add_
alarm
(
'alarm1'
)
>>>
count
=
wrtd
.
get_attr_int32
(
PyWrtd
.
WRTD_GLOBAL_REP_CAP_ID
,
PyWrtd
.
WRTD_ATTR_ALARM_COUNT
)
>>>
print
(
count
)
1
...
...
software/include/wrtd-common.h
View file @
71657cc9
...
...
@@ -28,7 +28,7 @@ typedef struct wrtd_tstamp {
/** TAI seconds since 1/Jan/1970 (Unix Epoch Time).
This will overflow in 7/Feb/2106... */
uint32_t
seconds
;
/** Number of nanoseconds. Wraps at 1
0
e9. */
/** Number of nanoseconds. Wraps at 1e9. */
uint32_t
ns
;
/** Number of fractional nanoseconds. Unit is 2e-32 ns. */
uint32_t
frac
;
...
...
software/lib/libwrtd.c
View file @
71657cc9
...
...
@@ -953,7 +953,7 @@ wrtd_status wrtd_get_attr_tstamp(wrtd_dev *wrtd,
* - `log tstamp` is the timestamp of when the event was logged.
* - `event tstamp` is the timestamp of when the event happened.
* - `log type` is the type of the event.
* - `log
tstamp
` is the specific reason for this type of event.
* - `log
reason
` is the specific reason for this type of event.
*
* All event log entries have a fixed length of #WRTD_LOG_ENTRY_SIZE.
*
...
...
@@ -973,7 +973,7 @@ wrtd_status wrtd_get_attr_tstamp(wrtd_dev *wrtd,
* finished executing. The exact meaning of this log type is application-specific.
* - `DISCARDED|NO SYNC` : An Event was discarded because the device was not syncrhonized
to White Rabbit. See also #WRTD_ATTR_STAT_RULE_MISSED_NOSYNC.
* - `DISCARDED|HOLD OFF`: An Event was discarded because violated the programmed hold-off
* - `DISCARDED|HOLD OFF`: An Event was discarded because
it
violated the programmed hold-off
* value. See also #WRTD_ATTR_STAT_RULE_MISSED_HOLDOFF.
* - `DISCARDED|TIME OUT`: An Event was discarded because it arrived too late. See also
* #WRTD_ATTR_STAT_RULE_MISSED_LATE.
...
...
software/lib/libwrtd.h
View file @
71657cc9
...
...
@@ -98,7 +98,7 @@ typedef enum wrtd_attr {
/** `RO` `bool` `global` True if the Event Log is empty. */
WRTD_ATTR_EVENT_LOG_EMPTY
=
__WRTD_ATTR_BASE
+
0x00
,
/** `RW` `bool` `global` Enable/d
si
able the Event Log. */
/** `RW` `bool` `global` Enable/d
is
able the Event Log. */
WRTD_ATTR_EVENT_LOG_ENABLED
=
__WRTD_ATTR_BASE
+
0x01
,
/** `RO` `bool` `global` True if the device is synchronized to White Rabbit time. */
WRTD_ATTR_IS_TIME_SYNCHRONIZED
=
__WRTD_ATTR_BASE
+
0x02
,
...
...
@@ -128,16 +128,16 @@ typedef enum wrtd_attr {
/** `RW` `bool` `rule` Enable/disable a Rule. */
WRTD_ATTR_RULE_ENABLED
=
__WRTD_ATTR_BASE
+
0x21
,
/** `RW` `int32` `rule` Specifies the number of times a Rule will fire before becoming
automatically disabled. 0 means infinite. 1 means that the
alarm
will fire only once.
automatically disabled. 0 means infinite. 1 means that the
Rule
will fire only once.
When read, it returns the remaining repetitions. */
WRTD_ATTR_RULE_REPEAT_COUNT
=
__WRTD_ATTR_BASE
+
0x22
,
/** `RW` `string` `rule` Get/set Rule source. Rule sources can be:
- Local source Event IDs (in the form of **LC
I-x
**)
- Local source Event IDs (in the form of **LC
-I<x>
**)
- Alarm IDs (any ID with an **alarm** prefix)
- Any other string which will be interpreted as a network message Event ID. */
WRTD_ATTR_RULE_SOURCE
=
__WRTD_ATTR_BASE
+
0x23
,
/** `RW` `string` `rule` Get/set Rule destinations. Rule destinations can be:
- Local destination Event IDs (in the form of **LC
O-x
**)
- Local destination Event IDs (in the form of **LC
-O<x>
**)
- Any other string which will be interpreted as a network message Event ID. */
WRTD_ATTR_RULE_DESTINATION
=
__WRTD_ATTR_BASE
+
0x24
,
/** `RW` `bool` `rule` If true, events that arrive late (with a timestamp in
...
...
Dimitris Lampridis
@dlampridis
mentioned in merge request
!1 (closed)
·
Jul 30, 2019
mentioned in merge request
!1 (closed)
mentioned in merge request !1
Toggle commit list
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