Skip to content

W
White Rabbit Starting Kit
Commit 35c3778d authored by Manuel Castilla's avatar Manuel Castilla Committed by Benoit Rat
Browse files
Options

Merged in manu-191031_update_doc_wr-starting-kit (pull request #10) 

doc:Fix maciej's comments and add section set previous kernel version
parents 50f368ab 021a6735
Hide whitespace changes
Inline Side-by-side
Showing with 80 additions and 45 deletions
doc/wr-starting-kit.md
View file @ 35c3778d
......@@ -68,7 +68,7 @@ Revision table
2.0 15/05/2014 Benoit Rat\ Updating for v2.0 release
[Seven Solutions]
3.0 10/10/2019 Francesco Colella\ Updating for 3.0 reléase
3.0 10/10/2019 Francesco Colella\ Updating for 3.0 release
[Seven Solutions]
------------------------------------------------------------------------
......@@ -146,13 +146,13 @@ conceived to fulfill the following goals:\
Time Precision
: The [WR] technology provides a common clock for physical layer in the entire network, allowing synchronization at sub-nanosecond accuracy with picoseconds precision.
: The [WR] technology provides a common clock for physical layer in the entire network, allowing synchronization at sub-nanosecond accuracy with picoseconds 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.
: 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] standard Ethernet 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.\
: 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 [WR] network elements(nodes or switches) using fiber cables.
The **Starting Kit** has been designed to test and check if the White
......@@ -167,7 +167,7 @@ You can find more information on other components and use cases on:
* The official wiki page <http://www.ohwr.org/projects/white-rabbit/wiki>
About the Starting Kit
About the WR Starting Kit
----------------------------------
This starting kit uses two nodes, each one composed of a [SPEC] and one
......@@ -179,13 +179,13 @@ 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:
This WR Starting Kit is based on different projects:
* [spec-sw], driver to communicate to the [SPEC] card through PCIe. It
also includes a set of tools to experiments.
* [wr-nic], gateware/software that includes the NIC capabilities.
* [wr-nic], gateware/software that includes the Network Interface Card(NIC) capabilities.
* [fmc-dio-5chttla], gateware/software that includes the support for FMC-DIO 5ch TTL
* [wrpc-sw], white rabbit PTP firmware for the synchronization.
* [wrpc-sw], White Rabbit PTP firmware for the synchronization.
About this document
......@@ -218,8 +218,7 @@ In this section, we resume the main changes that happens at each release of the
### wr-starting-kit-v3.0
This new release has been focused to update all different modules used by the starting kit but does not provide
specific update for the starting kit.
This release has been focused to update all different modules constituting WR Starting Kit to use their newer release versions. This release does not provide specific updates to the features or functionalities of the WR Starting Kit.
* Update spec-sw with new VIC core to support kernels (v4.15-v4.18)
* Use new wr-core v4.2 with their update tools (see changelog of wrc-v4.2)
......@@ -270,16 +269,16 @@ hardware elements and theirs connections are described in this section.
What do you need?
----------------
In order to use the white rabbit starting kit and setup the different
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 two `PCIe x4` ports (`x8` & `x16` are also compatible)
* 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.
* The Operative System **Ubuntu LTS 64bit (Long Term Support)** installed.
* Two mini-USB (B) cables (not provided with the kit).
This tutorial has been tested and verified with Ubuntu LTS 16.04.6 (kernel v.4.15.9) and Ubuntu LTS 18.04.2 (kernel v.4.18.0-17), this mean that standard support will only be given for these releases.
However, the `spec-sw` driver should work with other releases, distributions and architectures.
However, the `spec-sw` driver should work with other releases, distributions and architectures. Ubuntu 18.04 LTS is supported but some versions like 18.04.1 or 18.04.3(with kernel version 5.0) does not work correctly unless you [set a previous kernel version](#Set-Previous-Kernel-Version). Ubuntu LTS 14.04 is not supported.
![Configuration with one two PCs](img/ssk_configs.png)
......@@ -373,13 +372,13 @@ Then you need to install all the tools that you will need:
You can also run this command[^debian] for minimal setup:
~~~~{.sh}
sudo apt-get install git build-essential libreadline-dev linux-headers-$(uname -r) minicom
sudo apt-get install git build-essential python-minimal wget libreadline-dev linux-headers-$(uname -r) minicom
~~~~~~~~~
and this one if you also want to generate documentation (not mandatory):
~~~~{.sh}
sudo apt-get install texinfo emacs texlive pandoc
sudo apt-get install texinfo emacs texlive-xetex pandoc
~~~~~~~~~
......@@ -406,19 +405,7 @@ includes the [spec-sw] project.
>:$ git checkout -b wr-starting-kit-v3.0 wr-starting-kit-v3.0
~~~~~~~~~~~~
Configure your Git username/email
~~~~{.sh}
To set your global username/email configuration:
Open the command line.
Set your username:
git config --global user.name "FIRST_NAME LAST_NAME"
Set your email address:
git config --global user.email "MY_NAME@example.com"
~~~~~~~~~~~~
Or you can try our new Makefile that should perform everything!
Now you should execute the Makefile that should perform everything!
~~~~{.sh}
>:$ make
......@@ -478,9 +465,8 @@ you might obtain the following warning on `dmesg`:
~~~~~{.sh}
>:$ dmesg
...
11.949966] spec 0000:01:00.0: mezzanine 0
[ 11.949967] Manufacturer: CERN
[ 11.949967] Product name: FmcDio5cha
[ 7.824668] spec 0000:01:00.0: mezzanine 0
[ 7.824669] EEPROM has no FRU information
...
~~~~~~~~~~
......@@ -488,44 +474,39 @@ This information, called the FRU, contains the type of FMC board, its serial num
In order to write it in case you have an old FMC board without any EEPROM written,
you should execute the following commands
Don't forget to modify the bus id: `FmcDio5cha-XXXX` and the S/N
`7S-DIO-v2-Sxx-XXX` with your specific devices setup.
~~~~~{.sh}
##First you need to go in the fru-generator folder
>:$ cd spec-sw/fmc-bus/tools/
>:$ cd wr-starting-kit/spec-sw/fmc-bus/tools/
## And compile the library
>:$ make
## Then, find out on which bus id you have the boards
>:$ ls /sys/bus/fmc/devices/
FmcDio5cha-0100
fmc-0100
### Enter root mode in the terminal
>:$ sudo bash
## Write the eeprom for fmc-0100: the first/the top one fmc board.
>:# FRU_VENDOR="CERN" FRU_NAME="FmcDio5cha" FRU_PART="EDA-02408-V2-0" \
./fru-generator -s 7S-DIO-v2-S03-058 > /sys/bus/fmc/devices/FmcDio5cha-0100/eeprom
./fru-generator -s 7S-DIO-v2-S03-058 > /sys/bus/fmc/devices/fmc-0100/eeprom
## Finally, Go back to user and starting-kit root directory
>:# exit
>:$ cd -
~~~~~~~~~~
Don't forget to modify the bus id: `FmcDio5cha-XXXX` and the S/N
`7S-DIO-v2-Sxx-XXX` with your specific devices setup.
### Reload the kernel driver
> ***Notes:*** Removing the kernel is actually proving a kernel panic (core-dump) and
your PC will be freezed. This is a known bug that you be corrected in a release fix.
Once you have correctly written (Auto or Manual) the EEPROM of the [FMC-DIO], you need
to reload the kernel driver by doing this
Once you have correctly written the EEPROM of the [FMC-DIO], you need
to reload the kernel driver by reboot the PC
~~~~{.sh}
>:$ sudo rmmod spec
>:$ sudo modprobe spec
>:$ sudo reboot
~~~~~~~~~~
you should now obtain something like this on `dmesg`:
......@@ -1574,6 +1555,60 @@ make
You should finally obtain the bitstream to import in your [FMC] driver folder.
Set Previous Kernel Version
===========================
This chapter describes how to set a previous kernel version when you have problems during the installation with the latest kernel versions.
Find the **$menuentry_id_option** for the submenu
-------------------------------------------------
~~~~~~{.bash}
>:$ grep submenu /boot/grub/grub.cfg
submenu 'Advanced options for Ubuntu' $menuentry_id_option 'gnulinux-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
~~~~~~~~~~~
Show available kernel entries
-----------------------
~~~~~~{.bash}
>:$ grep -A100 submenu /boot/grub/grub.cfg |grep menuentry
submenu 'Advanced options for Ubuntu' $menuentry_id_option 'gnulinux-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
menuentry 'Ubuntu, with Linux 5.0.0-32-generic' --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-5.0.0-32-generic-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
menuentry 'Ubuntu, with Linux 5.0.0-32-generic (recovery mode)' --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-5.0.0-32-generic-recovery-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
menuentry 'Ubuntu, with Linux 4.18.0-17-generic' --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-4.18.0-17-generic-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
menuentry 'Ubuntu, with Linux 4.18.0-17-generic (recovery mode)' --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-4.18.0-17-generic-recovery-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
menuentry 'Ubuntu, with Linux 4.15.0-46-generic' --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-4.15.0-46-generic-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
menuentry 'Ubuntu, with Linux 4.15.0-46-generic (recovery mode)' --class ubuntu --class gnu-linux --class gnu --class os $menuentry_id_option 'gnulinux-4.15.0-46-generic-recovery-541c21ee-e687-4a1e-9f8c-c1b6285694da' {
~~~~~~~~~~~
Create the default menu entry
-----------------------------
The parent entry id for Advanced options in this case is **gnulinux-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da**
Choose the entry for the kernel you want to use. For example, **gnulinux-4.18.0-17-generic-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da**
Conacate both entries with >. The result should be like:
**"gnulinux-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da > gnulinux-4.18.0-17-generic-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da"**
Edit Grub
----------
Edit the file **/etc/default/grub** and replace **GRUB_DEFAULT** with the previously created entry. The file would look like
~~~~~~{.bash}
GRUB_DEFAULT="gnulinux-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da > gnulinux-4.18.0-17-generic-advanced-541c21ee-e687-4a1e-9f8c-c1b6285694da"
#GRUB_TIMEOUT_STYLE=hidden
GRUB_TIMEOUT=10
GRUB_DISTRIBUTOR=`lsb_release -i -s 2> /dev/null || echo Debian`
GRUB_CMDLINE_LINUX_DEFAULT="quiet splash"
GRUB_CMDLINE_LINUX=""
~~~~~~~~~~~
Update Grub and Reboot
----------------------
~~~~~~{.bash}
>:$ sudo update-grub
>:$ sudo reboot
~~~~~~~~~~~
Frequently Added Questions
===========================
......
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