Commit 65e7e245 authored by manuel's avatar manuel

doc:fix Maciej's comments on the document

parent dfee04e2
......@@ -129,6 +129,9 @@ WR
WRS
: White Rabbit Switch
FRU
: Field Replaceable Unit
\clearpage
......@@ -275,7 +278,7 @@ In order to use the WR Starting Kit and setup the different
experiments you will need:
* An oscilloscope with at least 150Mhz bandwidth (500Mhz is recommended).
* Two PCs with at least one `PCIe x4` port (`x8` & `x16` are also compatible). The use of two PCs is recommended because in some cases there are problems using a PC with 2xPCIe in several kernels.
* Two PCs with at least one `PCIe x4` port (`x8` & `x16` are also compatible). The use of two PCs is recommended because in some cases there are problems using a PC with 2xPCIe depending on the kernel.
* The Operative System **Ubuntu LTS 64bit (Long Term Support)** installed.
* Two mini-USB (B) cables (not provided with the kit).
......@@ -360,7 +363,7 @@ You should obtain something similar as:
Where `01` represent the ID of the PCIe slot given by your motherboard.
> **Note**: The PCIe slot numbering are normally ordered from top to bottom on the motherboard,
this mean that the board with ID `01` will be above.
this mean that the board with ID `01` will be at the top.
Tools
......@@ -439,11 +442,13 @@ To enable the wr-nic you should execute the modprobe[^errmodprobe] command to lo
You should use `insmod` instead and look at the [Frequently Added Questions sections](#frequently-added-questions).
You should expect to obtain two (or one) new interface(s):
You should expect to obtain a new interface:
~~~~{.sh}
>:$ ifconfig -a | grep wr
wri1 Link encap:Ethernet HWaddr XX:XX:XX:XX:XX:XX
>:$ ifconfig -a | grep -A 2 wr
wri1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
inet6 fe80::xxxx:xxxx:xxxx:xxxx prefixlen 64 scopeid 0x20<link>
ether XX:XX:XX:XX:XX:XX txqueuelen 1000 (Ethernet)
~~~~~~~~~~~~
If it is not the case you might have an empty EEPROM that need to be
......@@ -477,7 +482,7 @@ you might obtain the following warning on `dmesg`:
...
~~~~~~~~~~
This information, called the FRU, contains the type of FMC board, its serial number, etc.
This information, called the Field Replaceable Unit (FRU), contains the type of FMC board, its serial number, etc.
In order to write it in case you have an old FMC board without any EEPROM written,
you should execute the following commands
......@@ -531,11 +536,9 @@ you should now obtain something like this on `dmesg`:
Setting Master & Slave using White Rabbit Core
=============================================
A "[SPEC+FMCDIO]" board is considered as a slave node, however in a standard
White Rabbit network the synchronization is done using a master such
as a White Rabbit Switch [WRS].
The "SPEC+FMCDIO" board is configured by default to be a slave node. In a White Rabbit network, slave nodes are synchronized to a master such as a Whtie Rabbit Switch ([WRS]).
In order to enable the synchronization capabilities we need to set up one board in master mode
In order to enable the synchronization capabilities we need to set up one board to be in master mode
(faking to be a [WRS]) and the other one in slave mode (default mode). This is done through the
shell of White Rabbit Core that allows this functionality among others.
......@@ -555,9 +558,13 @@ To access to the physical, you first need to connect the mini-USB of the [SPEC]
>:$ sudo minicom --device=/dev/ttyUSB1 -b 115200
~~~~~~~~~~
> ***Notes:*** ttyUSB0 might not correspond to your first board, and ttyUSB1 to the second one.
> ***Note:*** ttyUSB0 might not correspond to your first board, and ttyUSB1 to the second one.
This depends on how you have plugged the USB cable to your USB of your machine.
> ***Note:*** When the terminal emulator starts, you might need to press enter before seeing the wrc# prompt.
> ***Note:*** In order to leave the minicom emulator, you need press the following combination of keys: CTRL+a, then z, then x and Enter.
### Virtual UART
An easier way to perform this operation is to access to the virtual
......@@ -594,7 +601,7 @@ The White Rabbit Core Shell
Once you are in the UART you should obtain the WR PTP Core console (`wrc#`).
A complete reference of the shell commands is included in the [wrpc.pdf] manual or
you can read them in the [Wiki](https://www.ohwr.org/project/wr-cores/wikis/home)
you can read them in the [Wiki](https://www.ohwr.org/project/wr-cores/wikis/wrpc-core)
The most useful commands are repeated here for your convenience
......@@ -613,7 +620,7 @@ For the tutorial we will use the following names:
Initial Configuration using SDBFS partition
------------------------------------
Since version 3.0 of WR PTP Core ([wrpc-sw]), the on-board flash memory chip on the carrier
Since version 3.0 of WR PTP Core ([wrpc-core]), the on-board flash memory chip on the carrier
is used as a default place for storing calibration parameters and an init script.
The storage format of this information is organized in an SDBFS filesystem that **MUST BE** pre-formatted and
......@@ -622,7 +629,7 @@ should be properly configured at least once (in case it has not been done during
### Checking if SDBFS is properly formatted
The first thing to do is to verify that the SDBFS has been properly formatted and configured.
To do so you should check the trace messages while [connecting to the UART](#connect-to-the-uarts).
To do so you should check the trace messages when opening the [UART connection](#connect-to-the-uarts).
In case you see an error while WR Core is initializing such as:
......@@ -642,7 +649,7 @@ get_persistent_mac: SDB file is empty
get_persistent_mac: Using W1 serial number
~~~~~~~~~~
This means that SDBFS as not been founded or that SDBFS is not properly formatted (corrupted).
This means that SDBFS has not been founded or that SDBFS is not properly formatted (corrupted).
In this case you should format SDBFS as detailed in the [next section](#formatting-sdbfs).
In case SDBFS is found but an error message about an "empty SDB file" appears when retrieving
......@@ -666,7 +673,7 @@ steps and go directly to [configuring slave & master mode](#configure-in-slave-m
> **Warning**: You should skip the following step if you have verified that
> the SDBFS is [properly formatted](#checking-if-sdbfs-is-properly-formatted).
Therefore, starting from v3.0 you have to write the empty
Starting from v3.0 you have to write the empty
SDBFS filesystem image to the flash before running the WRPC. The simplest way of
doing this is by calling a WR PTP Core shell command:
......@@ -707,10 +714,7 @@ get_persistent_mac: SDB file is empty
get_persistent_mac: Using W1 serial number
~~~~~
Your [SPEC] board will use a "auto-generated" MAC address using the
thermometer serial number (W1) as is unique among SPEC devices.
And if even if this MAC should be uniq on this network it has not been
officially assigned following the [IEEE OUI].
Your [SPEC] board will use an "auto-genereted" MAC address derived from the thermometer serial number (W1) that is a unique identifier. However, even if this MAC address should be indeed unique within WR network, it is not created according to IEEE rules and using [IEEE's OUI].
You should get the MAC for your board from its manufacturer. To configure the
address and store it into the Flash/EEPROM (so that it's automatically loaded
......@@ -782,6 +786,8 @@ wrc1# ptp start
wrc2# ptp start
~~~~~~~
> ***Note:*** The PTP daemon needs to be started only after changing the mode (or stopping it with a command), otherwise it is up and running by default.
Finally you can run the WRC shell in `gui` mode to obtain more information
~~~~~{.sh}
......@@ -789,7 +795,7 @@ wrc2# gui
~~~~~~~~~~
~~~~~{.sh}
WR PTP Core Sync Monitor wr-btrain-v1.1-17-g5a72198
WR PTP Core Sync Monitor wr-starting-kit-v3.0
Esc = exit
TAI Time: Thu, Jan 1, 1970, 02:01:57
......@@ -822,7 +828,7 @@ Update counter: 7
You can see that the slave node is locked, calibrated and that the phase tracking is enabled.
> ***Notes:*** We also recommend you to set up an init script if you do not want to repeat these operations at each reboot. You can look at the [wrpc.pdf] for more information or use the `init show` command to check the one you have running.
> ***Notes:*** We also recommend you to set up an init script if you do not want to repeat these operations at each reboot. You can look at the [wrpc.pdf] for more information and use the `init show` command to check the one you have running.
......@@ -834,8 +840,10 @@ Once the drivers are loaded and the PTP has started you might check if the new n
In order to do this you should just execute:
~~~~{.sh}
>:$ sudo ifconfig | grep wr
wri1 Link encap:Ethernet HWaddr 22:33:07:00:f1:a7
>:$ sudo ifconfig | grep -A 2 wr
wri1: flags=4163<UP,BROADCAST,RUNNING,MULTICAST> mtu 1500
ether XX:XX:XX:XX:XX:XX txqueuelen 1000 (Ethernet)
RX packets 0 bytes 0 (0.0 B)
~~~~~~~~~~~~
......@@ -859,7 +867,9 @@ Playing with the DIO channels
The first step to perform is to check if the [FMCDIO] channels are accessible using the installed driver.
The `wr-dio-cmd` program, let you quickly test the I/O features of the [FMCDIO] boards.
This is the general syntax of the command[^sudo]: `wr-dio-cmd: use "wr-dio-cmd [-V] <dev> <cmd> [...]"`
This is the general syntax of the command[^sudo]:
`wr-dio-cmd: use "wr-dio-cmd [-V] <dev> <cmd> [...]"`
[^sudo]: As the application use `ioctl` you should call with root privilege by using sudo.
......@@ -879,14 +889,14 @@ The available modes are:
* `D/d`: DIO core output
* `P/p` (Channel 0): Output PPS (Pulse Per Second) Generator from PTP core.
* `C/c` (Channel 4): Clock Input to PTP core: allow to input a high frequency signal without interruption throwing
* `-` : This operator is used to Keep the current configuration on the channel
>> ***Note:*** If the Letter is capitalized the I/O channel is connected to 50-ohm termination resistor, otherwise it is not. i.e, The `I` is input with 50-ohm termination resistor and `i` is without it.
>> ***Note:*** If the Letter is capitalized the I/O channel is connected to 50-ohm termination resistor, otherwise it is not. e.g. The `I` is input with 50-ohm termination resistor and `i` is without it.
> ***Note:*** The first channel (channel 0) has been modified and now support only the P/p as output
mode. You will not be able to use D,d,1,0 modes.
> ***Note:*** The first channel (channel 0) supports only the P/p as output mode, it also supports input mode, i.e. I/i. You will not be able to use D,d,1,0 modes.
For example you can set it up like this
For example, you can use the following command:
~~~~~{.sh}
## Configure channel 0 as input with termination, 1 as input, 4 as fixed low
......@@ -975,9 +985,13 @@ The configuration is done as indicated in the figure below:
![Time-stamping configuration](img/ssk_playdio.png)
> ***Note:*** We can consider PC1 as "spusa" and PC2 as "tornado"
> ***Note:*** The LEMO cables should be of identical lenght/delay. Ideally, the delay should be bellow 8ns.
~~~~~{.sh}
## Configure #2 & #5 (ch1 & ch4) as ouput and #3 (ch2) as input with termination on wri1 (spusa).
>spusa:$ sudo wr-dio-cmd /dev/fmc-dio-1:0 mode -DI-D
>spusa:$ sudo wr-dio-cmd /dev/fmc-dio-1:0 mode iDI-D
## Configure #4 (ch3) as input on wri1 (tornado)
>tornado:$ sudo wr-dio-cmd /dev/fmc-dio-1:0 mode 3 I
......@@ -1001,11 +1015,7 @@ ch 4, 186792.999999992
ch 3, 186792.999999992
~~~~~~~~~~~~~~~~~
We observe that locally (ouput=>ch1, input=>ch2) and remotely (output=>ch4, input=>ch2),
the timestamp between sending a pulse and receiving is of 8 nanoseconds[^8ns] for both.
This is a very simple example to show how the two [SPEC]s are synchronized.
We can observe that the difference between the output and input timestamps is the same for the "local" and "remote" connection (i.e. "local": output=>ch1@spusa, input=>ch2@spusa, "remote": output=>ch4@spusa, input=>ch2@tornado). The resolution of the timestamps is 8 nanoseconds, so if the lenghts (delays) of the cables are below 8ns, we can observe the minimum difference between the timestamps due it its resolution, i.e. 8ns. This is a very simple example to show how the two [SPEC]s are synchronized.
[^dionum]: The connector on the [FMC-DIO] panel are enumerated from #1 to #5 and correspond to the channel 0 to 4 on the `wr-dio-cmd`.
[^8ns]: The DIO core work at a frequency of 125Mhz, therefore the minimum difference between two timestamped events is of 8ns.
......@@ -1014,16 +1024,17 @@ However with the next experiment you will find out that the synchronization is b
Synchronization of PPS
----------------------------------------------------------------------------------------
This corresponds to the experiment from [spec-sw.pdf:6.8][spec-sw.pdf] document.
Here we want to synchronize the PPS of the master and slave boards using WR protocol on a fiber.
This experiment shows synchronization of PPS outputs between master and slave SPEC boards using WR protocol.
### Setup
In order to perform a more illustrative experiment, this example should
be done with two [SPEC+FMCDIO] boards separated by a 5km fiber
on two different PCs.
However to simplify the experiments we are using 2m fiber cable and the two boards connected to the same PC.
The first connector (ch 0) of each board output the PPS and is connected to the oscilloscope using LEMO cable & BNC adapter.
However to simplify the experiments we are using 2m fiber cable and the two boards connected on two different PCs.
The first connector (ch 0) of each board outputs the PPS and is connected to the oscilloscope using LEMO cables of the same lenght & BNC adapter.
> ***Note:*** For this experiment, the calibration parameters should have been previously configured.
![Setup for the PPS synchronization](img/ssk_pps-setup.png)
......@@ -1066,23 +1077,20 @@ The *wr-nic* driver registers a Linux network interface card for
each [SPEC] device that it drives. The cards are called `wri%d` (i.e.,
*wri1*, *wri2*, ...).
The [SPEC] can carry normal data traffic in
addition to the PTP frames of *White Rabbit*, that remain
invisible to the host computer.
The [SPEC] can transmit to/receive from the host computer normal Ethernet traffic in addition to the WR-PTP frames (the WR-PTP frames remain invisible to the host computer).
> ***Notes:*** If a user wants to use the WR-NIC on a real network to transfer
data he should assign an Interface address. However the *White Rabbit* synchronization happens at Ethernet
layer therefore no IP address is needed. Moreover if you want to communicate two WR-NIC boards that are on the same
data he should assign to the wri%d Interface an IP address. However the *White Rabbit* synchronization happens at Ethernet
layer therefore no IP address is needed. Moreover if you want to communicate between two WR-NIC SPEC boards that are on the same
computer you should not use an IP protocol because the data will never
be put on the fiber since the computer knows
that the two IPs are on the same machine.
### Timestamp Mechanism
The [SPEC] Ethernet interface
supports hardware timestamping for user frames through the
standard Linux mechanisms. Time stamps are currently reported with
a resolution of 8ns only (*White Rabbit* does much better, but the code
The WR-NIC supports hardware timestamping for user frames through the
standard Linux mechanisms. Timestamps are currently reported with
a resolution of 8ns (*White Rabbit* does much better, but the code
to illustrate this is not developed for this simple demo, yet).
Unfortunately the Linux mechanisms are not trivial: the application must
......@@ -1106,7 +1114,7 @@ the user.
The `stamp-frame` example supports two modes of operations. In
*listen* mode, it binds to an Ethernet interface and listens forever:
it waits for the forward frames and replies to them; in normal mode it
it waits for the forward frames and replies to them; in *normal* mode it
sends the forward frame and reports data as soon as it gets a reply.
~~~~~{.sh}
......@@ -1167,7 +1175,7 @@ and `stamp-frame` respects this tradition.
Transmitting external frequency
Forwarding train of pulses
-----------------------------------
This experiment merges the concepts seen before with the [FMCDIO] channels and the NIC synchronization.
......@@ -1180,10 +1188,9 @@ same time in different output boards; (in the framework of a
distributed instrumentation facility); another typical application is
time stamping input events.
Thus in these experiments we are going to transmit an external frequency in
the 100Hz range using the WR Starting Kit:
Thus in these experiments we are going to transmit an external pulse at frequency in the 100Hz range using the WR Starting Kit:
* The user supplies a ~100Hz square wave on the channel 0 of the master card.
* The user supplies a pulse every 100Hz on the channel 0 of the master card.
* The **dio-ruler** on master host reads the UTC time of the rising edge of the external pulse upon IRQ.
* Then the **dio-ruler** forwards it (as an **ioctl** structure) to its local and remote selected outputs.
* At the slave workstation the **dio-agent** waits to receive
......@@ -1195,30 +1202,35 @@ The figure below illustrates how the connection must be done between the differe
![Setup to transmit a 100Hz signal](img/ssk_100Hz.png)
> ***Note:*** The cables between DIO outputs and the scope shoud be of the same lenght.
> ***Note:*** This forwarding is fully software (~100Hz) and that it is used as a proof of concept and not something reliable to be used in production.
### How does it work?
The example is made up of two programs: `wr-dio-agent` and `wr-dio-ruler`: the ruler rules and the agent acts only.
These programs transmit using raw Ethernet frames to force the optical fiber transmission when two boards are on the same machine.
These programs transmit using raw Ethernet frames to force the optical fiber transmission in the case when the two boards are on the same machine.
It also transmits using broadcast addresses to avoid complication on
selecting to who it should be transmitted.
The simplification adopted above, however, most likely prevents the programs from working within a more complex
network topology.
> ***Notes:*** By using an IP protocol (i.e, UDP) the data will never enter the optical fiber between the two boards
> ***Notes:*** If you are using two SPEC boards on a single PC, by using an IP protocol (i.e, UDP) the data will never enter the optical fiber between the two boards
because the OS see that the destination is local and therefore routes them directly to the receiver without using the sender.
The *agent* is a "dumb" agent in charge of forwarding *WR* packet to the *DIO* core.
The *ruler* waits for timestamps to appear on a specific input channel;
when a positive-going edge occurs the *ruler* notifies it or replicates the edge on one or more outputs.
when a positive-going edge occurs the *ruler* is notified and replicates the edge on one or more outputs.
Each output can be local or remote, and can use a different delay from the input pulse.
For further details (deeper studies) the user is recommended to read the [spec-sw.pdf:6.8][spec-sw.pdf] document
and to also take a look at the source code of `wr-dio-agent` and `wr-dio-ruler`
This is the general syntax of the commands:
`wr-dio-ruler: Use "wr-dio-ruler [-V] <wr-if> <dio-dev> IN<ch> {L,R}<ch>+<delay-as-decimal> [...]`
`wr-dio-agent: Use "wr-dio-agent [-V] <wr-if> <dio-dev>"`
> ***Notes:*** All pulses generation are driven by
host software, after a hardware interrupt reports the input event.
......@@ -1234,7 +1246,7 @@ delay of 50 microseconds).
### The setup
Then we should run the "dumb" agent on the slave board in charge of forwarding *ioctl* packet to the *DIO* core:
Let's start by running the "dump" agent on the slave board in charge of forwarding *ioctl* packet to the *DIO* core:
~~~~~~{.sh}
>tornado:$ sudo wr-dio-agent wri1 /dev/fmc-dio-1:0 &
......@@ -1285,7 +1297,7 @@ on both the local (channel 3) and the remote card (channel 1)
>tornado:$ sudo wr-dio-cmd /dev/fmc-dio-1:0 mode -D0--
## Creating the ruler to forward from input 0 to local3 and remote1
>spusa:$ sudo wr-dio-ruler wri1 /dev/fmc-dio-1:0 IN0 L3+0.001 R1+0.001
>spusa:$ sudo wr-dio-ruler wri1 /dev/fmc-dio-1:0 IN0 L3+0.001 R1+0.001 &
wr-dio-ruler: configured for local channel 3, delay 0.001000000
wr-dio-ruler: configured for remote channel 1, delay 0.001000000
~~~~~~~~~~~~~
......@@ -1316,6 +1328,13 @@ Or compare the signals[^3cables] on the oscilloscope as in the next figure:
![Result with a 100Hz train](img/ssk_100Hz-train.jpg)
To stop the experiment, you can use the following commands:
~~~~~{.sh}
>spusa:$ sudo kill wr-dio-ruler
>tornado:$ sudo killall wr-dio-agent
~~~~~~~~~~~~~~~~
[^3cables]: To do this you need to connect from the waveform generator to the input with a LEMO cable that is not provided.
> ***Notes:*** This code was developed as a demo sample therefore: the delays should be no
......@@ -1323,14 +1342,9 @@ more than the interval between input pulses, because the tools
reprograms all output triggers at each input event. The output pulse is fixed at 1ms
### Two PCs example
This experiment is taken from the spec-sw document;
we verified the tools and we think this is a good explanation of how to use them.
### Additional example without need for generator
It shows how to use the *ruler* and *agent* on
two hosts, called `spusa` and `tornado`. It is pretty the same thing as the previous
experiment only that the board are now both named `wri1`.
This experiment shows how to use the *ruler* and *agent* without a generator.
![Transmit PPS between two PCs](img/ssk_txpps.png)
......@@ -1340,11 +1354,12 @@ channel 0.
~~~~~{.sh}
>spusa:# sudo wr-dio-cmd /dev/fmc-dio-1:0 mode 0 P
>spusa:# sudo wr-dio-cmd /dev/fmc-dio-1:0 mode P--DI
>tornado:# sudo wr-dio-cmd /dev/fmc-dio-1:0 mode I-D-D
>tornado:# sudo wr-dio-agent wri1 /dev/fmc-dio-1:0 &
>spusa:# sudo wr-dio-ruler wri1 /dev/fmc-dio-1:0 IN4 L3+.001 R4+.001 R2+.001
>spusa:# sudo wr-dio-ruler wri1 /dev/fmc-dio-1:0 IN4 L3+.001 R4+.001 R2+.001 &
wr-dio-ruler: configured for local channel 3, delay 0.001000000
wr-dio-ruler: configured for remote channel 4, delay 0.001000000
wr-dio-ruler: configured for remote channel 2, delay 0.001000000
......@@ -1366,6 +1381,10 @@ channel 0.
ch 4, 386.001000000
ch 4, 387.001000000
ch 4, 388.001000000
## To stop the agent and ruler
>spusa:$ sudo kill wr-dio-ruler
>tornado:$ sudo killall wr-dio-agent
~~~~~~~~~~~~
Advanced used
......@@ -1402,7 +1421,7 @@ you can see the 3 PPS signals: yellow for [WRS], blue and violet for
![WRS PPS (yellow) vs WR Starting Kit PPS (blue & violet)](img/ssk_wrspps.jpg)
The distance between each PPS might be reduced by the improving the
The skew between each PPS might be reduced by the improving the
calibration which is the subject of the next section.
......@@ -1416,20 +1435,18 @@ and you do not obtain a delay similar as the one in the WRS figure above
you might need to calibrate the [WRS] and the [SPEC+FMCDIO].
The value that you need to use can be found at the wiki page:
<http://www.ohwr.org/projects/white-rabbit/wiki/Calibration>
<https://www.ohwr.org/project/white-rabbit/wikis/calibration#sfp-database-for-spec-with-nic-design>
If you use a custom gateware or SFPs that are not listed in the wiki page
you should run yourself the calibration in order to obtain the correct values
for your setup.
> ***Warning:*** Cable length/type can modify around ~5ns/meter the delay
> ***Warning:*** Cable length/type will add around ~5ns/meter to the delay
between the moment when the PPS was out of the board and when it was
captured by the oscilloscope.
> ***Notes:***: Please check that you are using the values that correspond
to your gateware release. When this document was generated we refer as
wr-starting-kit-v3.0 (WR Starting Kit). You can also check using the `ver` command
if the corresponding embedded LM32 corresponds to your gateware version.
> ***Note:*** Please check that you are using the values that correspond
to your gateware release. We reference the gateware corresponding to this version of the document as wr-starting-kit-v3.0. You can check the version of the gateware you are running with the command ver".
~~~~~{.sh}
wrc# ver
......@@ -1458,7 +1475,7 @@ SPEC+DIO as grandmaster
In basic configuration your Master [SPEC] can use its internal
free-running oscillator as a time reference. However, you can also
discipline your Master [SPEC] with external 10 MHz and 1-PPS signal by
discipline your Master [SPEC] with external 10 MHz(to the channel 4) and 1-PPS(to the channel 3) signal by
connecting them to the appropriate LEMO connectors of [FMC-DIO] board:
![Grandmaster setup](img/ssk_grandmaster.png)
......@@ -1469,6 +1486,10 @@ The requirement for the applied signals are:
* ~[2.5V to 4V] with 50Ohm termination.
* PPS pulse width must be at least one 10MHz period (>100ns).
For more information about grandmaster mode you can take a look at: [wr_external_reference.pdf].
This document has been written for the WR switch, but timing/accuracy/stability requirements are
similar for the [SPEC+FMCDIO].
[^aroundval]: These values are given on an indicative basis because they depend on the source and
connection you are using.
......@@ -1479,28 +1500,15 @@ input 10MHz signal can be square or sinusoidal.
When the GrandMaster is a [SPEC+FMCDIO] `PPS_in` pulse serves to *mark* which rising edge of the 10MHz signal is considered the first one valid for a new second: the `PPS_out` will be fixed on the `10MHz_in` and not the `PPS_in`. `PPS_in` should therefore arrives at least 8ns before the `10MHz_in` clock.
As *1m is around ~5ns of delay*, you could use a cable with 4m to connect to `PPS_in` and a cable with 1m to connect to `10MHz`.
> ***Note:*** In the case when PPS_in and 10MHz_in are perfectly aligned at your source, you can use different lenghts of cables to provide proper skew between the two signals. As 1m is around 5ns of delay, you can use a cable of 1m legnth (5ns) to connect PPS_in and a cable of 3m lenght (15ns) to connect 10MHz.
The following figure shows what kind of signals need to be provided to plug to the GM [SPEC+FMCDIO], and with which fixed delay the `PPS_out` is produced (~8ns).
![Grandmaster signals from GPS with different cables length (PPS in=>Yellow, 10MHz CMOS=> Blue, 10MHz Sin => Green, PPS out=>)](img/ssk_gm-4m1m.jpg)
### Using the fine-delay.
If you have a [FMC fine-delay] board you can generate a precise PPS/10MHz by
executing the following commands (using release v2014.04):
~~~~~~{.sh}
>:$ sudo tools/fmc-fdelay-pulse -o 1 -r 1s-10n -T 1s ## PPS on #1 (10ns before 10MHz).
>:$ sudo tools/fmc-fdelay-pulse -o 2 -1 ## 10MhZ on #2
~~~~~~~~~~~~~
![Grandmaster signals from a FMC fine-delay (PPS=>Yellow, 10MHz=> Blue)](img/ssk_gm_fdelay.jpg)
### Locking GM PLL to external 10MHz/PPS
Then in the wrc console of the [SPEC+FMCDIO] just execute the following commands:
To enable Grandmaster mode, in the wrc console of the [SPEC+FMCDIO] just execute the following commands:
~~~~~~{.sh}
wrc# ptp stop
......@@ -1514,12 +1522,7 @@ And you should obtain:
PLL locking .................. LOCKED
~~~~~~~~~~~~~
For more information about grandmaster mode you can take a look at: [wr_external_reference.pdf].
This document has been written for the WR switch, but timing/accuracy/stability requirements are
similar for the [SPEC+FMCDIO].
By default the [SPEC+FMCDIO] should be configured to be run in GM setup, but if you are not sure please
reset the default value. See [Default Mode](#default-mode) Section. If you
By default, the channels of the FMCDIO are configured such that the SPEC+FMCDIO can act ask a GM. If you are not sure whether your current configuration is correct, please reset to default, see [Default Mode](#default-mode) Section. If you
want to run the [SPEC+FMCDIO] in standalone mode as grandmaster we also
recommand you to modify the startup script as explained in the [section below](#run-in-standalone)
......@@ -1530,18 +1533,13 @@ Run in standalone
> **Note**: You need to have the Xilinx JTAG USB platform cable or similar
to perform the next step.
You can also run GM in a full standalone mode in order to transmit WR clock without the need of a PC.
You can run GM in a full standalone mode in order to transmit WR clock without the need of a PC.
First you need to flash the SPEC with the latest `wr_nic_dio.bit` bitstream you can find in the package:
[wr-starting-kit-v3.0_bin.tar.gz]
And you also need to download a pre-formatted sdbfs partition: [sdbfs-standalone-160812.bin]
In the case when you want to run on the the SPEC a reference bitstream provided with a stable
WRPC release, you can simply program your Flash with \textit{spec\_top.mcs}
provided with the release binaries using for example Xilinx ISE Impact tool.
Then you need to create a `mcs` image that contains both the SDBFS partition and FPGA bitstream.
This can be done by following the layout below:
......@@ -1564,12 +1562,15 @@ To do so you need to generate a MSC file as follows:
Finally:
* The setup of the cable is exactly the same as above, and you do not need to set up the mode because it is
correctly configured for GM by default at power up.
* The setup of the cable is exactly the same as above, and you do not need to update the configuration of DIOFMC inputs because it is correctly configured for GM by default at power up.
* Then you need to run grandmaster mode from wrc console, as above.
* (Optional) Finally, if you need to keep this configuration at power up, you can write a small script
on the EEPROM to boot in grandmaster mode.
> **Note**: In the case when you want to run on the the SPEC a reference bitstream provided with a stable
WRPC release, you can simply program your Flash with \textit{spec\_top.mcs}
provided with the release binaries using for example Xilinx ISE Impact tool.
### EEPROM boot script
~~~~~~{.sh}
......@@ -1611,7 +1612,7 @@ The WR Starting Kit is based on various project:
* [coht-vic], Kernel driver to handles interruption from FPGA such as the one from SPEC
In the following figure you can understand better how the different subproject are connected and contains
In the following figure you can understand better how the different subproject are connected and included in the WR-starting-kit project.
![Structure of repositoryie](img/repos_structure.png)
......@@ -1670,7 +1671,7 @@ WR-SPEC-DIO-NIC (HDL-gateware)
> *Dep*: hdlmake, Xilinx ISE 14
This step shows us how to prepare the WR-SPEC-DIO-NIC bitstream ([SPEC+FMCDIO]) with
This step shows how to prepare the WR-SPEC-DIO-NIC bitstream ([SPEC+FMCDIO]) with
the wrpc-sw (`wrc.ram` file) embedded inside.
~~~~~~{.bash}
......@@ -1687,7 +1688,7 @@ You should finally obtain the bitstream to import in your [FMC] driver folder.
Set Specific Kernel Version
===========================
This chapter describes how to set a force loading a specific (previous) kernel version if you have problems while compiling/loading the wr-starting-kit
This chapter describes how to set a specific (previous) kernel version if you have problems while compiling/loading the wr-starting-kit
drivers with newest/latest kernel[^ubuntultskernel].
> ***Note:*** We recommand to fix your kernel to `4.18.xxx`, as it has been the one that have reported less error during development.
......@@ -1819,7 +1820,7 @@ However the delay introduced by your nondeterministic OS is much more important.
### Why am I getting "Warning: tx timestamp never became available" message form the UART?
This warning seems to appear after unnistalling wr-nic driver if PTP has already been started. It can be easily solved by reinstalling the driver.
This warning seems to appear after uninstalling wr-nic driver if PTP has already been started. It can be easily solved by reinstalling the driver.
After that the device keeps working as was previously specified.
......@@ -1896,13 +1897,14 @@ References
[FMC fine-delay]: https://sevensols.com/index.php/fmc-del/
[OHWR]: http://www.ohwr.org/projects/white-rabbit
[Seven Solutions]: http://www.sevensols.com
[IEEE OUI]: https://standards.ieee.org/products-services/regauth/index.html
[IEEE's OUI]: https://standards.ieee.org/products-services/regauth/index.html
[wr-switch-guide.pdf]: https://sevensols.com/index.php/products/white-rabbit-switch/
[wr-nic]: http://www.ohwr.org/projects/wr-nic/
[wr-starting-kit]: http://www.ohwr.org/projects/wr-starting-kit/
[spec-sw]: http://www.ohwr.org/projects/spec-sw/
[wrpc-sw]: http://www.ohwr.org/projects/wrpc-sw/
[wrpc-core]: https://www.ohwr.org/project/wr-cores/wikis/wrpc-core
[fmc-dio-5chttla]: https://ohwr.org/project/fmc-dio-5chttla/
[coht-vic]: https://ohwr.org/project/coht-vic/
......@@ -1912,7 +1914,7 @@ References
[fmc-bus.pdf]: http://www.ohwr.org/attachments/download/2685/fmc-bus-2014-02-release.pdf
[spec-sw.pdf]:https://www.ohwr.org/project/spec-sw/uploads/1893da4fbb480352be53888d535fd140/spec-sw-2014-02-release.pdf
[wr_external_reference.pdf]: http://www.ohwr.org/attachments/1647/wr_external_reference.pdf
[wrpc.pdf]: http://www.ohwr.org/attachments/2559/wrpc-v2.1.pdf
[wrpc.pdf]: https://www.ohwr.org/project/wr-cores/uploads/ca546161d83fb3e48cd9f0266376377b/wrpc-user-manual-v4.2.pdf
[wrpc-v2.1.pdf]: http://www.ohwr.org/attachments/2559/wrpc-v2.1.pdf
[wr-starting-kit-v3.0_bin.tar.gz]: <https://ohwr.org/project/wr-starting-kit/wikis/uploads/b63d12f90cd0dbb89b78587603fdcfe6/wr-starting-kit-v3.0_bin.tar.gz>
......
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