Skip to content

W
White Rabbit Starting Kit
Commit 568c0b73 authored by Benoit Rat's avatar Benoit Rat
Browse files
Options

doc: remove trailing spaces

parent a9980005
Hide whitespace changes
Inline Side-by-side
Showing with 84 additions and 86 deletions
doc/wr-starting-kit.md
View file @ 568c0b73
......@@ -79,8 +79,8 @@ Introduction
About the White Rabbit technology
----------------------------------
White Rabbit ([WR]) is an extension to Ethernet network with **accurate
synchronization** and Gigabit data transfer capability. It has been
White Rabbit ([WR]) is an extension to Ethernet network with **accurate
synchronization** and Gigabit data transfer capability. It has been
conceived to fulfill the following goals:\
......@@ -89,15 +89,15 @@ Time Precision
Scalability
: The [WR] network is designed to be highly scalable up to thousands of nodes. It also intends to be as modular as possible and compatible with non-[WR] devices. Finally, all products related to this technology available at the Open Hardware Repository ([OHWR]) represent “open developments”, i.e. all the hardware designs, firmware and software and documentation are fully available. This shall facilitate the new incremental developments and customization of the available designs and products.
Distance Range
: Taking into account the size and ranges of the majority of industrial and scientific facilities, the [WR] network specifications have been chosen to support distance ranges of 10 km between nodes using fiber cables.\
The **Starting Kit** has been designed to test and check if the White
Rabbit technology meets your requirements. It shall also facilitate the
understanding on the technology capabilities and possibilities.
WR starting kit can also be used to evaluate what can be done with it
The **Starting Kit** has been designed to test and check if the White
Rabbit technology meets your requirements. It shall also facilitate the
understanding on the technology capabilities and possibilities.
WR starting kit can also be used to evaluate what can be done with it
and how to integrate it on your own project.
You can find more information on other components and use cases on:
......@@ -109,54 +109,53 @@ You can find more information on other components and use cases on:
About the Starting Kit
----------------------------------
This starting kit uses two nodes, each one composed of a [SPEC] and one
This starting kit uses two nodes, each one composed of a [SPEC] and one
[FMC-DIO] card.
A node makes basic operations such as input timestamping or programmable output pulse generation.
Additionally, specific software and gateware layers allow to use it as a standard network
interface card implementing the White Rabbit technology functionalities.
Network packages with accurate time-stamping information are generated/timestamped at
the hardware level to achieve the highest accuracy.
Additionally, specific software and gateware layers allow to use it as a standard network
interface card implementing the White Rabbit technology functionalities.
Network packages with accurate time-stamping information are generated/timestamped at
the hardware level to achieve the highest accuracy.
It is based on different projects:
* [spec-sw]: driver to communicate to the [SPEC] card through PCIe. It
* [spec-sw]: driver to communicate to the [SPEC] card through PCIe. It
also includes a set of tools to experiments.
* [wr-nic]: gateware that includes the NIC & DIO capabilities.
* [wrpc-sw]: white rabbit PTP firmware for the synchronization.
* [wrpc-sw]: white rabbit PTP firmware for the synchronization.
About this document:
---------------
This document is intended to be a step by step user friendly tutorial
to start with the White Rabbit technology. It includes the description
of some simple experiments to illustrate [WR] capabilities. Some
concepts are deliberately avoided to ease the comprehension of this document.
If you want to know more about these concepts, please access to the
related documents in the [Reference section](#references)
--------------------
This document is intended to be a step by step user friendly tutorial
to start with the White Rabbit technology. It includes the description
of some simple experiments to illustrate [WR] capabilities. Some
concepts are deliberately avoided to ease the comprehension of this document.
If you want to know more about these concepts, please access to the
related documents in the [Reference section](#references)
and especially to the following ones:
* [spec-sw.pdf]
* [wrpc.pdf]
The rest of the document provides an explanation about the system setup, software driver, FPGA configuration and
some application examples.
The rest of the document provides an explanation about the system setup, software driver, FPGA configuration and
some application examples.
This will allow easily validating the main capabilities of White Rabbit
technology.
This will allow easily validating the main capabilities of White Rabbit
technology.
We have also included a chapter called [Quick Start Guide for
Developers](#quick-start-guide-for-developers) in order to facilitate
the starting stages of development processes, indicating where to find
We have also included a chapter called [Quick Start Guide for
Developers](#quick-start-guide-for-developers) in order to facilitate
the starting stages of development processes, indicating where to find
the different source projects and how to compile them.
System Setup
===========
This section describes the main elements required to start with the White-Rabbit based
on the *"White Rabbit (SPEC-based) starting kit"*. The different
This section describes the main elements required to start with the White-Rabbit based
on the *"White Rabbit (SPEC-based) starting kit"*. The different
hardware elements and theirs connections are described in this section.
What do you need?
......@@ -180,18 +179,18 @@ but it requires more physical space to implement it.
[wr-starting-kit] wiki for a more detailed list of which distro has been tested.
Starting kit components
----------------
-----------------
The starting kit is composed of various elements that you should find
The starting kit is composed of various elements that you should find
in the package[^standardssk] :
* 2x [SPEC]s boards
* 2x [FMC-DIO]s 5CH TTL A
* 2x SFPs LC
* 2x SFPs LC
* AXGE-1254-0531 (blue)
* AXGE-3454-0531 (violet)
* 1x LC-LC cable (2m)
* 1x LC-LC cable (2m)
* 3x LEMO cable (2m)
* 3x LEMO-BNC Adaptor
......@@ -205,9 +204,9 @@ Physical configurations
* Plug the [SPEC+FMCDIO] into your `PCIe x{4,8,16}` port.
* You should also connect a micro-USB cable to the UART of the board.
(A Virtual UART is also available, but it is safer to use the physical
one).
* You should also connect a micro-USB cable to the UART of the board.
(A Virtual UART is also available, but it is safer to use the physical
one).
* Connect the two [SPEC+FMCDIO] boards using the SFPs and the optical fiber cable (LC-LC)
* Start your Ubuntu LTS distribution.
* Prepare an oscilloscope with at least two input channels to access
......@@ -267,8 +266,8 @@ However similar packages exist for other distributions.
Install the project
-------------------
The first step is to install the driver to communicate with the card using
the PCIe port. To do so you need to get the latest release[^commitgit] of [wr-starting-kit] project which
The first step is to install the driver to communicate with the card using
the PCIe port. To do so you need to get the latest release[^commitgit] of [wr-starting-kit] project which
includes the [spec-sw] project.
~~~~{.sh}
......@@ -297,18 +296,18 @@ includes the [spec-sw] project.
The **master** branch might have the latest source but support is only offered for tagged release. The other branches are normally used for development and are not stable.
Structure of the spec-sw project
---------------------------------
Most of the information on how the project is structured can be found in the [spec-sw.pdf] in the `/doc` folder,
Most of the information on how the project is structured can be found in the [spec-sw.pdf] in the `/doc` folder,
however in the following paragraphs we briefly summarize it:
### Folders layout
Each of the following folders contain:
* **doc**: documentation of the project
* **doc**: documentation of the project
* **gateware**: downloaded HDL binaries also called gateware.\
(This folder is created while downloading gateware)
* **kernel**: Kernel modules (drivers) to connect the [SPEC] to the PC through PCIe.
......@@ -319,20 +318,20 @@ Each of the following folders contain:
The Starting Kit contains 3 different drivers:
* **fmc.ko**: Define a generic FMC-bus[^fmc-bus] used to identify and connect to FMC boards independently
* **fmc.ko**: Define a generic FMC-bus[^fmc-bus] used to identify and connect to FMC boards independently
of the carrier being used (e.g. [SPEC], SVEC, ...)
* **spec.ko**: It is the device driver that connects to the [SPEC] through PCI. It also loads the spec-init.bin “golden” gateware file.
* **wr-nic.ko**: The wr-nic driver is basically an Ethernet driver with
* **wr-nic.ko**: The wr-nic driver is basically an Ethernet driver with
support for hardware time stamping. It also loads the following:
* `fmc/wr_nic_dio.bin` gateware for the NIC and DIO properties.
* `fmc/wr_nic_dio-wrc.bin` software for the LM32[^lm32inc].
* `fmc/wr_nic_dio-wrc.bin` software for the LM32[^lm32inc].
[^fmc-bus]: More information about the [FMC]-bus can be found within [fmc-bus.pdf] in the `doc/` folder.
[^lm32inc]: In future version, the program file for the LM32 will be included into the gateware.
[^lm32inc]: In future version, the program file for the LM32 will be included into the gateware.
Compile & install
------------------------
Compile & install
------------------------
A Makefile in the [spec-sw] project has been written to compile and install easily the drivers and the tools used below.
......@@ -348,7 +347,7 @@ A Makefile in the [spec-sw] project has been written to compile and install easi
~~~~~~~~~~~
If everything works well you should see the driver in
~~~~~~~~~~~
~~~~{.sh}
>:$ ls -l /lib/modules/$(uname -r)/extra
~~~~~~~~~~~
......@@ -1426,8 +1425,7 @@ have a few hints on where to find the project but it shall be seen as
work in progress. It will become more complete as new users step in and
report their problems.
This section has the purpose to give the developers a quick start guide to install
This section has the purpose to give the developers a quick start guide to install
the tools and compile the different projects to obtain the binaries used previously.
The starting kit is based on various project:
......@@ -1439,7 +1437,7 @@ The starting kit is based on various project:
[wr-nic]
: gateware (FPGA HDL) that includes the NIC & DIO capabilities.
[wrpc-sw]
: LM32 software in the white rabbit PTP core for the synchronization.
: LM32 software in the white rabbit PTP core for the synchronization.
Tools
......@@ -1454,7 +1452,7 @@ You must have installed the following tools:
* Kernel source
* Lm32 cross compiler
* Hdl make
* Texinfo
* Texinfo
For all these steps you can follow our guide [ohwr_development.pdf](ohwr_development.pdf)
......@@ -1493,14 +1491,14 @@ WRPC-SW (LM32 firmware)
> *Dep*: lm32 compiler
> ***Notes***: The steps in this section are not needed as we already provide the `wrc.ram` in the [wr-nic] repository.
> ***Notes***: The steps in this section are not needed as we already provide the `wrc.ram` in the [wr-nic] repository.
However we provide here a simple resume of the steps required to compile the firmware specifically for the wr-nic.
You should also look at the [wrpc.pdf] to understand how to use it and
You should also look at the [wrpc.pdf] to understand how to use it and
how to compile new firmware for other configurations.
You can download it from [wr-nic-v1.1.tar.gz](http://www.ohwr.org/projects/wr-nic/files) file or you can try to compile it following the instructions below:
You first need to install the **lm32** compiler as suggested in
You first need to install the **lm32** compiler as suggested in
[wrpc.pdf], and then you need to compile it using the specific configuration as bellow:
~~~~~~{.sh}
......@@ -1508,7 +1506,7 @@ You first need to install the **lm32** compiler as suggested in
export CROSS_COMPILE="<your_path_to_lm32>/lm32/bin/lm32-elf-";
## Clone the repository
git clone git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git
git clone git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git
cd wrpc-sw
## Checkout the stable release
......@@ -1531,17 +1529,17 @@ You should obtain various files named wrc.bin, wrc.elf, wrc.vhd, wrc.ram
You can therefore use them to override the one in [wr-nic](#wr-nic-hdl-gateware) project.
~~~~~{.sh}
## Override the default embeded wrpc-sw
## Override the default embeded wrpc-sw
cp wrc.ram <wr_root_folder>/wr-nic/syn/spec
~~~~~~~~~~~
WR-NIC (HDL-gateware)
----------------------
> *Dep*: hdlmake, Xilinx ISE 14
This step shows us how to prepare the WR-NIC bitstream ([SPEC+FMCDIO]) with
This step shows us how to prepare the WR-NIC bitstream ([SPEC+FMCDIO]) with
the wrpc-sw (`wrc.ram` file) embedded inside.
~~~~~~{.bash}
......@@ -1560,7 +1558,7 @@ cd wr-nic/syn/spec/
## Synthetize using hdlmake
hdlmake --make-ise --ise-proj
make
~~~~~~~~~~~
~~~~~~~~~~~
You should finally obtain the bitstream to import in your [FMC] driver folder.
......@@ -1573,9 +1571,9 @@ In the Appendix we include other information that may be of interest.
WRPC 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
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
connecting them to the appropriate LEMO connectors of [FMC-DIO] board:
![Grandmaster setup](ssk_grandmaster.png)
......@@ -1610,8 +1608,8 @@ SPLL_Init: running as GrandMaster, 1 ref channels, 2 out channels
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
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 SPECs.
### PCIe mode
......@@ -1636,7 +1634,7 @@ the corresponding SPI flash memory: `M25P32`.
Then:
* The setup of the cable is exactly the same as above, and you do not need to setup the mode because it is
* The setup of the cable is exactly the same as above, and you do not need to setup the mode 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
......@@ -1672,12 +1670,12 @@ Until the next release you should stick with the Physical UART: micro USB cable
### No SFP in EEPROM database
When you try to match your SFPs and you obtain an error such as **Could not match to DB** you
need to add your own SFP parameters.
When you try to match your SFPs and you obtain an error such as **Could not match to DB** you
need to add your own SFP parameters.
~~~~~{.sh}
## List your actual sfp database
wrc# sfp show
wrc# sfp show
## Erase the actual database if it was corrupted
wrc# sfp erase
......@@ -1688,7 +1686,7 @@ wrc# sfp add AXGE-3454-0531 46407 167843 -73622176
~~~~~~~~~~~
You can also check the [wrpc.pdf] for extended explanations on how to obtain the parameters for your own SFP
and how to calibrate them.
and how to calibrate them.
### Modprobe is not working
......@@ -1698,9 +1696,9 @@ If you get and error like the following:
>:$ sudo modprobe wr-nic
FATAL: Module wr_nic not found.
~~~~~~~~~
Be sure that you have run the `sudo depmod -a` command.
Otherwise you can still load the kernel modules with insmod using the
Be sure that you have run the `sudo depmod -a` command.
Otherwise you can still load the kernel modules with insmod using the
following commands:
~~~~~~~{.sh}
......@@ -1733,7 +1731,7 @@ We also recommand the lecture of the online FAQ:
* <http://www.ohwr.org/projects/spec/wiki/FAQ>
* <http://www.ohwr.org/projects/wr-starting-kit/wiki/FAQ>
* <http://www.ohwr.org/projects/wr-cores/wiki/Wrpc_faq>
* <http://www.ohwr.org/projects/wr-cores/wiki/Wrpc_faq>
......@@ -1772,13 +1770,13 @@ After this you should reboot your PC with the new kernel source and start from [
You have run
~~~~~{.sh}
wrc# calibration force
wrc# calibration force
Enabling ptracker channel: 0
LNK:
LNK:
PLL: SPLL_Init: running as Slave, 1 ref channels, 2 out channels
~~~~~~~~~~~~~~~
And the calibration is doing an infinite loop.
And the calibration is doing an infinite loop.
Calibration is only available for slave and you need to be connected to a **working PTP master** master ([SPEC] in master mode or the switch) to be completed.
To configure your [SPEC] as a working PTP master, just execute in the wrpc shell of the other board:
......@@ -1824,12 +1822,12 @@ need to recalibrate "correctly" your boards.
and you can not see any green LED on the [SPEC].*
Please check that the SFP connector is totally plugged into the [SPEC]. The SFP cage of the [SPEC]
can be blocked sometimes by the PC back-panel. You must push the SFP
can be blocked sometimes by the PC back-panel. You must push the SFP
until hearing a "clicking noise".
### What is the latency in the WR-NIC
Many people ask us about the latency in the WR-NIC.
Many people ask us about the latency in the WR-NIC.
The answer depends really on what you want to measure: The only "relevant" delay might be the time between the SFP and the PCIe which is less than 20 cycles.
However the delay introduced by your nondeterministic OS is much more important.
......@@ -1845,7 +1843,7 @@ Glossary
NIC
: Network Interface Card
DIO
DIO
: Digital Input/Output
PTP
: Precise Time Protocol, a time synchronization protocol
......@@ -1893,7 +1891,7 @@ References
============
* [spec-sw.pdf] main documentation of the spec-sw
* [wrpc.pdf] White Rabbit Core documentation
* [wrpc.pdf] White Rabbit Core documentation
* [fmc-bus.pdf] How the FMC bus driver works and how to write one for your own FMC board.
* SFPs information <http://www.ohwr.org/projects/white-rabbit/wiki/SFP>
* White Rabbit Calibration: <http://www.ohwr.org/documents/213>
......
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