Skip to content

S
Software for White Rabbit PTP Core
Commit 81f2dc66 authored by Grzegorz Daniluk's avatar Grzegorz Daniluk
Browse files
Options

doc updated for wrpc-2.1 release

parent 215ad93a
Hide whitespace changes
Inline Side-by-side
Showing with 253 additions and 215 deletions
doc/wrpc.in
View file @ 81f2dc66
......@@ -63,7 +63,7 @@
This is the user manual for the White Rabbit @sc{ptp} Core developed on
@code{ohwr.org}. It describes the building and running process. If you don't
want to get your hands dirty and prefer to use the binaries available at
@uref{http://www.ohwr.org/projects/wr-cores/files} you can skip
@uref{http://www.ohwr.org/projects/wr-cores/files} please skip
@ref{Building the Core} and move forward directly to
@ref{Running and Configuring}.
......@@ -75,9 +75,12 @@ want to get your hands dirty and prefer to use the binaries available at
@node Repositories and Releases
@section Repositories and Releases
This manual you are reading is not about an official release,
but a snapshot of the current master branch. The last release
we blessed is called @value{release}.
%This manual is not about an official release,
%but a snapshot of the current master branch. The last release
%we blessed is called @value{release}.
This manual is about the official @value{release} stable
release of White Rabbit PTP Core (@sc{WRPC}).
The code and documentation for the project is distributed in the
following places:
......@@ -96,7 +99,7 @@ following places:
@item git://ohwr.org/hdl-core-lib/wr-cores.git
Read-only repository with the complete HDL design of @sc{wrpc}
Read-only repository with the complete HDL sources of @sc{wrpc}
@item git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git
......@@ -104,19 +107,19 @@ following places:
@end table
Other tools useful in building and running @sc{wrpc} can be fetched from the
Other tools useful for building and running @sc{wrpc} can be downloaded from the
following locations:
@table @code
@item http://www.ohwr.org/projects/hdl-make/files
@i{hdlmake} is used in the HDL synthesis process to build the Makefile based
@i{hdlmake} is used in the HDL synthesis process to create a Makefile based
on the set of Manifest files.
@item http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
@sc{lm32} toolchain used to compile the @sc{wrpc} firmware (software).
@sc{lm32} toolchain is used to compile the @sc{wrpc} firmware (software).
This specific file is linked from the @i{files} tab of the
@code{wrpc-sw} project.
......@@ -125,8 +128,7 @@ on the set of Manifest files.
The repositories containing the @sc{wrpc} gateware and software (@i{wr-cores},
@i{wrpc-sw}) are tagged with @code{@value{tagname}} tag. Other tools
used to build the core and load it into @sc{spec} board should be used in their
newest available versions stored in master branch of an appropriate git
repository (unless specified otherwise in this document).
newest stable release.
Any official hot fixes, if any, for this release will live in the branch called
@code{@value{tagname}-fixes}, in each @sc{wrpc} repository.
......@@ -137,14 +139,15 @@ Any official hot fixes, if any, for this release will live in the branch called
The absolutely minimum hardware you need to build and run the White
Rabbit @sc{ptp} Core is a PC computer with Linux and one Simple PCIe @sc{fmc} Carrier
(@sc{spec}) - @uref{http://www.ohwr.org/projects/spec}. However, it is recommended to
use also the DIO @sc{fmc} card (@uref{http://www.ohwr.org/projects/fmc-dio-5chttla})
for storing calibration values and configuration in @sc{eeprom}(described later).
To test the White Rabbit synchronization, you will also need:
(@sc{spec}) - @uref{http://www.ohwr.org/projects/spec}. However, it is highly
recommended to use also the @sc{dio} @sc{fmc} card (@uref{http://www.ohwr.org/projects/fmc-dio-5chttla})
for storing calibration values and configuration in @sc{eeprom}(described later)
as well as feeding 1-PPS and 10MHz from external clock and outputting 1-PPS
aligned to WR time. To test the White Rabbit synchronization, you will also need:
@itemize
@item second @sc{spec} board with DIO @sc{fmc} or a White Rabbit Switch;
@item pair of @sc{wr}-supported @sc{sfp} transceivers (list of supported @sc{sfp}s can be
found on our wiki page @uref{http://www.ohwr.org/projects/white-rabbit/wiki/SFP})
@item second @sc{spec} board with @sc{dio} @sc{fmc} or a White Rabbit Switch;
@item pair of @sc{wr}-supported @sc{sfp} transceivers (the list of supported
@sc{sfp}s can be found on our wiki page @uref{http://www.ohwr.org/projects/white-rabbit/wiki/SFP})
@item a roll of G652, single mode fiber to connect your @sc{spec}s or @sc{spec} with @sc{wr}
Switch.
@end itemize
......@@ -153,9 +156,15 @@ Switch.
@node Building the Core
@chapter Building the Core
@b{Note:} you can skip this chapter if you want to use the release binaries
available for download from @i{ohwr.org}.
@sp 1
Building the White Rabbit @sc{ptp} Core is a two step process. First you have to
synthesize the @sc{fpga} firmware (gateware) and then compile the software which
will be running on a softcore @sc{lm32} CPU instantiated inside the gateware.
Optionally, you can skip the compilation of @sc{lm32} software, since the
synthesized gateware contains default @sc{lm32} software.
To perform the steps below you will need a computer running Linux.
......@@ -164,99 +173,99 @@ To perform the steps below you will need a computer running Linux.
@section HDL synthesis
Before running the synthesis process you have to make sure that your
environment is set up correctly. You need the Xilinx ISE software with at least free
WebPack license. It contains the scripts: @i{settings32.sh},
@i{settings32.csh}, @i{settings64.sh} and @i{settings64.csh} that set up all the
system variables required by Xilinx software. Depending on the shell you use and
whether your Linux is 32 or 64-bits you should execute one of them. For example
the BASH script for 32-bit system should be called from:
environment is set up correctly. You need the Xilinx ISE software with at least
free of charge WebPack license. @i{ISE} provides a set of scripts:
@i{settings32.sh}, @i{settings32.csh}, @i{settings64.sh} and @i{settings64.csh}
that configure all the system variables required by the Xilinx software.
Depending on the shell you use and whether your Linux is 32 or 64-bits you
should execute one of them before other tools are used. For 32-bit system and
BASH shell you should call:
@example
/opt/Xilinx/<version>/ISE_DS/settings32.sh
/opt/Xilinx/<version>/ISE_DS/settings32.sh
@end example
and has to be executed before other tools are used. The easiest way to ensure
that @i{ISE}-related variables are set in the shell is to check if @i{$XILINX}
The easiest way to ensure that @i{ISE}-related variables are always set in your
shell is adding the execution of the script above to your @i{bash.rc} file. You
can check if the shell is configured correctly by verifying if @i{$XILINX}
variable contains the path to your @i{ISE} installation directory.
@b{Note:} current version of @i{hdlmake} tool developed at CERN requires
modification of @i{$XILINX} variable after @i{settings32} script execution.
modification of @i{$XILINX} variable after @i{settings} script execution.
This (provided that the installation path for @i{ISE} is /opt/Xilinx/<version>)
should look like this:
should be the following:
@example
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
@end example
@b{Note:} the Xilinx project file included in the @sc{wrpc} sources was created with
Xilinx ISE 14.5. It is recommended to use the newest available version of ISE
software.
@b{Note:} the Xilinx project file included in the @sc{wrpc} sources was created
with Xilinx ISE 14.5. It is however recommended to use the newest available
version of ISE software.
@sp 1
HDL sources for @sc{wr ptp} Core can be synthesized using Xilinx ISE without any
additional tools. However, using @i{hdlmake} is much more
convenient. It creates a synthesis Makefile and ISE project file based on the
set of Manifest.py files deployed among directories inside @i{wr-cores}
repository.
HDL sources for @sc{wr ptp} Core could be synthesized using Xilinx ISE without
any additional tools, but using @i{hdlmake} is more convenient. It creates a
synthesis Makefile and ISE project file based on a set of Manifest.py files
deployed among the directories inside the @i{wr-cores} repository.
First, please download the @i{hdlmake} binary from its location given in
@ref{Repositories and Releases}. At the time this document is written, the
most recent stable version of @i{hdlmake} is 1.0:
@ref{Repositories and Releases} and make it executable. At the time this
document is written, the most recent stable version of @i{hdlmake} is 1.0:
@example
$ wget http://www.ohwr.org/attachments/download/2070/hdlmake-v1.0
$ wget http://www.ohwr.org/attachments/download/2070/hdlmake-v1.0
$ chmod a+x hdlmake-v1.0
@end example
It is recommended to add the @i{hdlmake} binary location to your @i{$PATH}
environment variable to be able to call it from any directory:
@example
$ export PATH=<your_hdlmake_location>:$PATH
$ export PATH=<your_hdlmake_location>:$PATH
@end example
@b{Note:} the @i{hdlmake} usage instructions here are based on version 1.0.
When there will be newer releases or you use development version, please be
aware that its execution parameters may change. In that case please refer to
@i{hdlmake} documentation.
If you use more recent release or a development version, please be aware that
its execution parameters may change. In that case please refer to @i{hdlmake}
documentation.
@sp 1
Having Xilinx ISE software and @i{hdlmake} you can clone the main @sc{wr ptp} Core
git repository and start building the @sc{fpga} bitstream. First, please create a
local copy of the @i{wr-cores} in the preferred location in your system.
Having Xilinx ISE software and @i{hdlmake} in place, you can clone the main
@sc{wr ptp core} git repository and start building the @sc{fpga} bitstream.
First, please create a local copy of the @i{wr-cores} in the preferred
location in your system.
@example
$ git clone git://ohwr.org/hdl-core-lib/wr-cores.git <your_wrpc_location>
$ cd <your_wrpc_location>
$ git clone git://ohwr.org/hdl-core-lib/wr-cores.git <your_location>/wr-cores
$ cd <your_location>/wr-cores
@end example
You also need to fetch other git repositories containing modules essential for
@sc{wr ptp} Core. They are configured as git submodules inside the @i{wr-cores}
repository:
To build the gateware using sources of a stable release @value{tagname}, you
have to checkout the proper git tag:
@example
$ git submodule init
$ git submodule update
$ git checkout wrpc-v2.1
@end example
The local copies of those submodule repositories are stored to:
If you use @i{wr-cores} within another project (like @i{wr-nic}), you may need
to check out another release tag for this repository. Please refer to the
project's documentation to find out which version of this package you need to
build.
You also need to fetch other git repositories containing modules essential for
@sc{wr ptp core}. They are configured as git submodules inside the @i{wr-cores}
repository:
@example
<your_wrpc_location>/ip_cores
$ git submodule init
$ git submodule update
@end example
If you use @i{wr-cores} within another project (like @i{wr-nic}),
you may need to check out a stable release tag for this repository. Please refer
to the project's documentation to find which version of this package you need
to build.
@b{Note:} alternatively, for the v2.0 and v2.1 releases
of @sc{wr ptp} Core, you can get
the release sources from the tarball available in the @i{files} tab of
@code{wr-cores}:
The local copies of the submodules are stored to:
@example
http://www.ohwr.org/projects/wr-cores/files
<your_location>/wr-cores/ip_cores
@end example
@sp 1
......@@ -264,27 +273,26 @@ The subdirectory which contains the main synthesis Manifest.py for @sc{spec} boa
and in which you should perform the whole process is:
@example
$ cd <your_wrpc_location>/syn/spec_1_1/wr_core_demo/
$ cd <your_location>/wr-cores/syn/spec_1_1/wr_core_demo/
@end example
First you have to call @i{hdlmake} to create a synthesis Makefile for Xilinx
First, please call @i{hdlmake} to create synthesis Makefile for Xilinx
ISE:
@example
$ hdlmake --make-ise --ise-proj
$ hdlmake-v1.0 --make-ise --ise-proj
@end example
After that, the actual synthesis is just the matter of executing the command:
After that, the actual synthesis is just the matter of executing:
@example
$ make
$ make
@end example
as in a regular software compilation process. This takes (depending on
your computer speed) about 15 minutes and should create two files with @sc{fpga}
firmware: @i{spec_top.bit} and @i{spec_top.bin}. The former can be downloaded
to @sc{fpga} with Xilinx Platform Cable using Xilinx software (@i{Impact} or
@i{Chipscope Pro}). The latter can be used with the kernel driver from
This takes (depending on your computer speed) about 15 minutes and should create
two files with @sc{fpga} firmware: @i{spec_top.bit} and @i{spec_top.bin}. The
former can be downloaded to @sc{fpga} with Xilinx Platform Cable using e.g.
@i{Xilinx Impact}. The latter can be used with the kernel drivers from
@i{spec-sw} repository (check example in @ref{Running and Configuring}).
@sp 1
......@@ -299,59 +307,59 @@ everything from scratch you can use the following commands:
@node LM32 software compilation
@section LM32 software compilation
@b{Note:} By default, the release @sc{lm32} software is embedded inside the FPGA
bitstream you've downloaded from @i{ohwr.org} or synthesized in the previous
chapter. That means you don't have to do manual compilation of @sc{lm32}
software unless you want to use a development version or you've made some
changes required by your application.
@sp 1
To compile the @sc{lm32} software for White Rabbit @sc{ptp} Core you will need to
download and unpack the @sc{lm32} toolchain from the location mentioned already in
download and unpack the @sc{lm32} toolchain from the location mentioned in
@ref{Repositories and Releases}:
@example
$ wget http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
$ tar xJf lm32.tar.xz -C <your_lm32_location>
$ wget http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
$ tar xJf lm32.tar.xz -C <your_lm32_location>
@end example
Then you need to setup the @t{CROSS_COMPILE} variable in order
Then you need to set the @t{CROSS_COMPILE} variable in order
to compile the software for a @sc{lm32} processor:
@example
$ export CROSS_COMPILE="<your_lm32_location>/lm32/bin/lm32-elf-"
$ export CROSS_COMPILE="<your_lm32_location>/lm32/bin/lm32-elf-"
@end example
To get the release sources of @sc{wrpc} software please clone the @i{wrpc-sw} git
repository tagged with @value{tagname} tag. Otherwise, you can use the current master
branch, with the latest improvements and fixes. Finally, if you are using
@i{wrpc-sw} within another project, you may need to checkout a
different tag or specific commit; if this applies,
lease refer to the documentation of the other package to find the exact
version you need to reproduce the released binaries before you make
your changes.
To get the sources of @sc{wrpc} software please clone the @i{wrpc-sw} git
repository tagged with @value{tagname} tag. If you use @i{wrpc}
within another project, you may need to checkout a different tag or a specific
commit; if this applies, please refer to the documentation of the other package
to find the exact version you need to reproduce the released binaries before
you make your changes.
@smallexample
$ git clone git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git <your_wrpcsw_location>
$ cd <your_wrpcsw_location>
$ git checkout master # or "git checkout wrpc-v2.0"
$ git clone git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git <your_location>/wrpc-sw
$ cd <your_location>/wrpc-sw
$ git checkout wrpc-v2.1 # or "git checkout master"
@end smallexample
@b{Note:} alternatively you can get the release sources from the tarball
available in the @i{files} tab of the @code{wr-cores} OHWR project.
Before you can compile @i{wrpc-sw}
you need to make a few configuration choices. The package is using
@i{Kconfig} as a configuration engine, so you may run one of the
Before you can compile @i{wrpc-sw} you need to make a few configuration choices.
The package uses @i{Kconfig} as a configuration engine, so you may run one of the
following commnads (the first is text-mode, the second uses a KDE GUI
and the third uses a Gnome GUI):
@example
$ make menuconfig
$ make xconfig
$ make gconfig
$ make menuconfig
$ make xconfig
$ make gconfig
@end example
Other @i{Kconfig} target applies, like @code{config}, @code{oldconfig}
and so on. A few default known-good configurations are found in
@file{./configs} and you choose them by @i{make}ing them by name
like this:
@file{./configs} and you choose one by @i{make}ing it by name:
@example
$ make spec_defconfig
$ make spec_defconfig
@end example
The most important configuration choice at this point in time is
......@@ -363,7 +371,7 @@ After the package is configured, just run @code{make} without
parameters to build your binary file:
@example
$ make
$ make
@end example
The first time you build, the @i{Makefile} automatically downloads
......@@ -383,60 +391,60 @@ Core (@ref{Running and Configuring}).
@node Downloading firmware to SPEC
@section Downloading firmware to SPEC
There is a software support for the @sc{spec} board project in @i{ohwr.org}. It
contains a set of Linux kernel drivers and user space tools written by
Alessandro Rubini and Tomasz Wlostowski that are used to communicate with the
@sc{spec} board plugged into the PCI-Express port of the PC.
There is a @sc{spec} board software support(@sc{spec-sw}) project in @i{ohwr.org}.
It contains a set of Linux kernel drivers and user space tools, written by
Alessandro Rubini and Tomasz Wlostowski, that interact with a @sc{spec} board
plugged into a PCI-Express slot.
The instructions in this section are based on release 2013-05 of @i{spec-sw}
Instructions in this section are based on the release @i{2013-05} of @sc{spec-sw}
and are limited to absolute minimum required to load @sc{wrpc} @sc{fpga}
and @sc{lm32} firmware. The full manual for @i{spec-sw} can be found at:
and @sc{lm32} firmware. Full manual for @sc{spec-sw} can be found at:
@example
http://www.ohwr.org/attachments/download/2134/spec-sw-2013-05-release.pdf
http://www.ohwr.org/attachments/download/2134/spec-sw-2013-05-release.pdf
@end example
If there is a newer version of @sc{spec} software support you would like to
use, the up-to-date documentation can always be found in @i{doc/} subdirectory
of @i{spec-sw} git repository.
If there is a more recent version of the @sc{spec} software support, the
up-to-date documentation can always be found in @i{doc/} subdirectory of
@sc{spec-sw} git repository.
@sp 1
First, please clone the git repository of @sc{spec} software support package and
build the kernel drivers and tools:
First, please clone the git repository of @sc{spec-sw} package and build it:
@smallexample
$ git clone git://ohwr.org/fmc-projects/spec/spec-sw.git <your_specsw_location>
$ cd <your_specsw_location>
$ git checkout spec-sw-v2013-05
$ make
$ git clone git://ohwr.org/fmc-projects/spec/spec-sw.git <your_specsw_location>
$ cd <your_specsw_location>
$ git checkout spec-sw-v2013-05
$ make
@end smallexample
Then you have to copy the @i{spec_top.bin} to /lib/firmware/fmc/. changing its
Then you have to copy your @i{spec_top.bin} generated in @ref{HDL synthesis} or
downloaded from @i{ohwr.org} to /lib/firmware/fmc/. changing its
name:
@b{Note:} the commands below have to be executed with superuser rights
@example
$ sudo cp <your_wrpc_location>/syn/spec_1_1/wr_core_demo/spec_top.bin \
/lib/firmware/fmc/spec-demo.bin
$ sudo cp <your_location>/wr-cores/syn/spec_1_1/wr_core_demo/spec_top.bin \
/lib/firmware/fmc/spec-demo.bin
@end example
You have to download also the "golden" firmware for @sc{spec} card. It is used by
the drivers to recognize correctly the hardware:
the drivers to recognize the hardware:
@example
$ wget http://www.ohwr.org/attachments/download/1756/spec-init.bin-2012-12-14
$ sudo mv spec-init.bin-2012-12-14 /lib/firmware/fmc/spec-init.bin
$ wget http://www.ohwr.org/attachments/download/1756/spec-init.bin-2012-12-14
$ sudo mv spec-init.bin-2012-12-14 /lib/firmware/fmc/spec-init.bin
@end example
Now, you are ready to load necessary drivers that configure the
Spartan 6 @sc{fpga} on @sc{spec} with a given bitstream (make sure you are in
<your_specsw_location>:
Spartan 6 @sc{fpga} with the given bitstream (make sure you are in
<your_specsw_location>):
@example
$ sudo insmod fmc-bus/kernel/fmc.ko
$ sudo insmod kernel/spec.ko
$ sudo insmod fmc-bus/kernel/fmc-trivial.ko gateware=fmc/spec-demo.bin
$ sudo insmod fmc-bus/kernel/fmc.ko
$ sudo insmod kernel/spec.ko
$ sudo insmod fmc-bus/kernel/fmc-trivial.ko gateware=fmc/spec-demo.bin
@end example
To check if the @sc{fpga} firmware file was found by the driver and correctly loaded
......@@ -445,15 +453,15 @@ you should be able to find something very similar to:
@smallexample
@noindent
[1639675.431979] spec 0000:0b:00.0: probe for device 000b:0000
[1639675.431992] spec 0000:0b:00.0: PCI INT A -> GSI 16 (level, low) -> IRQ 16
[1639675.435246] spec 0000:0b:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes
[1639675.625773] spec 0000:0b:00.0: FPGA programming successful
[1639675.994110] spec 0000:0b:00.0: mezzanine 0
[1639675.994111] EEPROM has no FRU information
[1639705.910703] fmc fmc-0b00: Driver has no ID: matches all
[1639705.910731] spec 0000:0b:00.0: reprogramming with fmc/spec-demo.bin
[1639706.104417] spec 0000:0b:00.0: FPGA programming successful
[1639675.431979] spec 0000:0b:00.0: probe for device 000b:0000
[1639675.431992] spec 0000:0b:00.0: PCI INT A -> GSI 16 (level, low) -> IRQ 16
[1639675.435246] spec 0000:0b:00.0: got file "fmc/spec-init.bin", 1484404 (0x16a674) bytes
[1639675.625773] spec 0000:0b:00.0: FPGA programming successful
[1639675.994110] spec 0000:0b:00.0: mezzanine 0
[1639675.994111] EEPROM has no FRU information
[1639705.910703] fmc fmc-0b00: Driver has no ID: matches all
[1639705.910731] spec 0000:0b:00.0: reprogramming with fmc/spec-demo.bin
[1639706.104417] spec 0000:0b:00.0: FPGA programming successful
@end smallexample
If everything went right up to this moment you have your board running the @sc{fpga}
......@@ -462,16 +470,16 @@ built from @i{wrpc-sw} repository you can use the @i{spec-cl} tool. Programming
is done with the simple command below:
@example
$ sudo tools/spec-cl <your_wrpcsw_location>/wrc.bin
$ sudo tools/spec-cl <your_location>/wrpc-sw/wrc.bin
@end example
@sp 1
Now you should be able to start the Virtual-UART software (also a part of
@i{spec-sw} package) that will be used to interact with the White Rabbit @sc{ptp}
Now you should be able to start the Virtual-UART tool (also part of the
@sc{spec-sw} package) that will be used to interact with the White Rabbit @sc{ptp}
Core Shell:
@example
$ sudo tools/spec-vuart
$ sudo tools/spec-vuart
@end example
If you are able to see the @sc{wrpc} Shell prompt @i{wrc#} that means the Core is up
......@@ -482,53 +490,54 @@ and running on your @sc{spec}. Congratulations !
@node Writing EEPROM and calibration
@section Writing EEPROM and calibration
By default @sc{wrpc} starts in @sc{wr} Slave mode, uses the calibration values for
Axcen AXGE-3454-0531 @sc{sfp} and for release @sc{fpga} bitstream available in
@i{http://www.ohwr.org/projects/wr-cores/files}. This might be fine for running
White Rabbit @sc{ptp} Core for the first time and synchronizing it to @sc{wr} Switch.
There are however, two mechanisms that are useful when playing more with @sc{wrpc}
shell and different settings.
By default @sc{wrpc} starts in @sc{wr} Slave mode and uses the default calibration
values for Axcen AXGE-3454-0531 @sc{sfp}. This might be fine for running @sc{wrpc}
for the first time and synchronizing it to another @sc{spec} running the same
firmware. It is however recommended to perform few additional steps through the
@sc{wrpc} shell.
@b{Note:} the examples below describe only a subset of @sc{wrpc} Shell commands
required to make a basic configuration and calibration. A full description of
all supported commands can be found in @ref{WRPC Shell commands}.
@sp 1
First, before making the configuration changes, it is recommended (but not
obligatory) to stop the @sc{ptp} daemon. Then, the debug messages from daemon would
not show up to the console while you will interact with the shell.
Before making the configuration changes, it is good to stop the @sc{ptp} daemon.
Then, the debug messages from daemon would not show up to the console while you
will interact with the shell.
@example
wrc# ptp stop
wrc# ptp stop
@end example
If your @sc{spec} has any Mezzanine board plugged into the @sc{fmc} connector (e.g. DIO,
Fine Delay, TDC...) then you can create a calibration database inside the @sc{fmc}
@sc{eeprom}. The example below presents the @sc{wrpc} Shell commands which create an
empty @sc{sfp} database and add two Axcen transceivers with deltaTx, deltaRx and
alpha parameters associated with them. Those @sc{sfp}s are most widely used in @sc{wr}
development and demonstrations.
If your @sc{spec} has any Mezzanine board plugged into the @sc{fmc} connector
(e.g. @sc{dio}, Fine Delay, @sc{tdc}...) then you can create a calibration
database inside the @sc{fmc} @sc{eeprom}. The example below presents @sc{wrpc}
Shell commands which create an empty @sc{sfp} database and add two Axcen
transceivers with deltaTx, deltaRx and alpha parameters associated with them.
@example
wrc# sfp erase
wrc# sfp add AXGE-1254-0531 46407 183843 73622176
wrc# sfp add AXGE-3454-0531 46407 183843 -73622176
wrc# sfp erase
wrc# sfp add AXGE-1254-0531 180456 148066 72169888
wrc# sfp add AXGE-3454-0531 180456 148066 -73685416
@end example
To check the content of the @sc{sfp} database you can execute the @i{sfp show} shell
command.
@b{Note:} The deltaTx and deltaRx parameters above are the default ones for
@i{wrpc-2.0} release bitstream and most probably will be the cause of some
constant offset when @sc{spec} is synchronized to the @sc{wr} Switch. To find the new values
you should read the @sc{wr} Calibration procedure (@i{http://www.ohwr.org/documents/213}).
@i{wrpc-2.1} release bitstream available on @i{ohwr.org} and most probably will
be the cause of some constant offset when @sc{wrpc} is re-synthesized or
connected to the @sc{WR} Switch. To find the new values you should read the
@sc{wr} Calibration procedure (@i{http://www.ohwr.org/documents/213}).
@sp 1
The @sc{wr ptp} Core's mode of operation (@sc{wr} Master/@sc{wr} Slave) can be set using the
@i{mode} shell command in one of the following two ways:
The @sc{wr ptp} Core's mode of operation (GrandMaster/Master/Slave) can be set using the
@i{mode} shell command:
@example
wrc# mode slave
wrc# mode master
wrc# mode gm # for GrandMaster mode
wrc# mode master # for Master mode
wrc# mode slave # for Slave mode
@end example
This stops the @sc{ptp} daemon, changes the mode of operation, but does not start it
......@@ -536,30 +545,35 @@ back automatically. Therefore after changing it you need to start the daemon
manually:
@example
wrc# ptp start
wrc# ptp start
@end example
@sp 2
@b{Note:} For running in GrandMaster mode, you need to provide 1-PPS and 10MHz
signal from external source (e.g. GPS receiver or Cesium clock). Please connect
then 1-PPS signal to LEMO No.4 and 10MHz to LEMO No.5 connector of @sc{fmc}
@sc{dio} board.
@sp 1
One option is to type all those commands to initialize the @sc{wrpc} software to the
required state every time the Core starts. However, you can also write your own
init script to @sc{fmc} @sc{eeprom} and @sc{wrpc} software will execute it each time it comes
back from the reset state (this also includes coming back from reset after
programming the @sc{fpga} and @sc{lm32}). Building the simple script that reads
detected @sc{sfp} parameters from @sc{eeprom}, configures the mode of operation to @sc{wr}
Slave and starts the @sc{ptp} daemon is presented below:
init script to the @sc{eeprom} and @sc{wrpc} software will execute it each time
it starts (also when coming back from reset after programming the @sc{lm32}).
A simple script that reads @sc{sfp} parameters from the @sc{eeprom}, configures
the @sc{WR} mode to Slave and starts the @sc{ptp} daemon is presented below:
@example
wrc# init erase
wrc# init add ptp stop
wrc# init add sfp detect
wrc# init add sfp match
wrc# init add mode slave
wrc# init add ptp start
wrc# init erase
wrc# init add ptp stop
wrc# init add sfp detect
wrc# init add sfp match
wrc# init add mode slave
wrc# init add calibration
wrc# init add ptp start
@end example
Almost exactly the same one can be used for running @sc{spec} in @sc{wr} Master mode. The
only difference would be of course @i{init add mode slave} vs. @i{init add mode
master}.
Almost exactly the same one can be used for running @sc{wrpc} in GrandMaster or
Master mode. The only difference would be @i{init add mode slave} vs. @i{init
add mode gm} or @i{init add mode master}.
@c ==========================================================================
@node Running the Core
......@@ -570,39 +584,47 @@ calibration} you can restart the @sc{wr ptp} Core by reprogramming the @sc{lm32}
(with @i{spec-cl} tool) or by typing the shell command:
@example
wrc# init boot
wrc# init boot
@end example
After that you should see the log messages that confirm the init script
You should see the log messages that confirm the init script
execution:
@example
(...)
WR Core: starting up...
Found device: 1c:00:00:03:6c:48:83:28
Local MAC address: 8:0:30:6c:48:83
W1: f80000036c38ee28
get_persistent_mac: Using W1 serial number
ID: cafebabe
t24p read from EEPROM: 850 ps
Loops per jiffy: 20815
softpll: mode slave, 1 ref channels, 2 out channels
t24p read from EEPROM: 6900 ps
Loops per jiffy: 20820
Locking PLL
executing: ptp stop
executing: sfp detect
AXGE-1254-0531
executing: sfp match
SFP matched, dTx=46407, dRx=183843, alpha=73622176
SFP matched, dTx=180585, dRx=145855, alpha=72169888
executing: mode slave
softpll: mode slave, 1 ref channels, 2 out channels
Locking PLL
executing: calibration
Found phase transition in EEPROM: 6900ps
executing: ptp start
@end example
Now you should have the White Rabbit @sc{ptp} Core running in @sc{wr} Slave mode. The
Shell also contains the monitoring function which you can use to check the @sc{wr}
synchronization status:
Now you should have the White Rabbit @sc{ptp} Core running in @sc{wr} Slave
mode. @sc{wrpc} needs to make a calibration of t24p phase transition value. It
has to be done only once for a new bitstream and is performed automatically when
@sc{wrpc} runs in Slave mode. That is why it is very important, even if
@sc{wrpc} is meant to run in Master mode, to configure it to Slave for a moment
and connect it to any @sc{wr} Master. That has to be repeated every time a new
bitstream (gateware) is deployed. Measured value is automatically stored to
EEPROM and used later in Master or GrandMaster mode.
The Shell also contains the monitoring function which you can use to check the
@sc{wr} synchronization status:
@example
wrc# gui
wrc# gui
@end example
The information is presented in a clear, auto-refreshing screen. To exit
......@@ -610,28 +632,45 @@ from this console mode press <Esc>. Full
description about information reported by gui is provided in @ref{WRPC GUI
elements}.
@b{Note:} the @i{Synchronization status} and @i{Timing parameters} in @i{gui}
are available only in @sc{wr} Slave mode. When running as @sc{wr} Master, you
would be able to see only the current date and time, link status, Tx and Rx
packet counters, lock and calibration status.
@sp 1
@center @image{wrpc_mon, 12cm,,wrpc sync monitor}
@sp 1
@b{Note:} the @i{Synchronization status} and @i{Timing parameters} in @i{gui}
are available only in @sc{wr} Slave mode. When running as @sc{wr} Master, you would be
able to see only the current date and time, link status, Tx and Rx packet
counters, lock and calibration status.
If you want to store the statistics from @sc{wrpc} operation, it's probably
better to use the @i{stat cont} shell command. It reports the same information
as GUI but in a form which is easier to parse and analyze:
@example
wrc# stat cont
lnk:1 rx:416 tx:118 lock:1 sv:1 ss:'TRACK_PHASE' aux:0 sec:94197 \
nsec:793068184 mu:836241 dms:400556 dtxm:10 drxm:163610 dtxs:0 drxs:128400 \
asym:35129 crtt:544221 cko:-5 setp:7667 hd:61479 md:37221 ad:65000 ucnt:101 \
temp: 45.6875 C
lnk:1 rx:417 tx:119 lock:1 sv:1 ss:'TRACK_PHASE' aux:0 sec:94198 \
nsec:293076296 mu:836253 dms:400562 dtxm:10 drxm:163610 dtxs:0 drxs:128400 \
asym:35129 crtt:544233 cko:-4 setp:7663 hd:61485 md:37259 ad:65000 ucnt:102 \
temp: 45.6875 C
(...)
@end example
@sp 1
If you have a DIO Mezzanine board placed on your @sc{spec}, you can check the
synchronization quality by observing the difference between 1-PPS signals from
the @sc{wr} Master and @sc{wr} Slave. White Rabbit @sc{ptp} Core generates 1-PPS signal to the
LEMO connector No. 1 on DIO Mezzanine. However, please remember to use
oscilloscope cables having the same length and type (with the same delay), or
take their delay difference into account in your measurements.
If you have a @sc{dio} Mezzanine board plugged to your @sc{spec}, you can check
the synchronization performance by observing the offset between 1-PPS signals
from the @sc{wr} Master and @sc{wr} Slave. White Rabbit @sc{ptp} Core generates
1-PPS signal to the LEMO connector No. 1 on @sc{dio} Mezzanine. However, please
remember to use oscilloscope cables having the same length and type (with the
same delay), or take their delay difference into account in your measurements.
@c ##########################################################################
@node Troubleshooting
@chapter Troubleshooting
@b{My computer hangs on loading spec.ko driver.}
@b{My computer hangs on loading spec.ko or fmc-trivial.ko driver.}
This will occur when you try to load the @i{spec.ko} kernel driver while your
@i{spec-vuart} is running and trying to get messages from Virtual-UART's
......@@ -647,7 +686,7 @@ Please check if you have the Xilinx ISE-related system variables set correctly
overwritten the @i{$XILINX} variable to:
@example
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
@end example
or similar, if your installation folder differs from default.
......@@ -708,8 +747,7 @@ function to initialize SoftPll
@item @code{mode} @tab prints available @sc{wr ptp} modes
@item @code{mode gm|master|slave} @tab sets @sc{wrpc} to operate as Grandmaster clock (requires external 10MHz and 1-PPS reference), @sc{ptp} Master or @sc{ptp} Slave. After setting the mode @t{ptp start} must be re-issued
@item @code{calibration} @tab tries to read t2/4 phase transition from @sc{eeprom}, if not found runs calibration procedure
@item @code{calibration force} @tab starts calibration procedure that measures t2/4 phase transition, and stores the result to @sc{eeprom}
@item @code{calibration} @tab tries to read t2/4 phase transition value from @sc{eeprom} (in @sc{WR} Master or GrandMaster mode), or executes the t24p calibration procedure and stores its result to EEPROM (in @sc{WR} Slave mode)
@item @code{time} @tab prints current time from @sc{wrpc}
@item @code{time raw} @tab prints current time in a raw format (seconds, nanoseconds)
......
doc/wrpc_mon.png
View replaced file @ 215ad93a View file @ 81f2dc66
doc/wrpc_mon.png

38.4 KB | W: | H:

doc/wrpc_mon.png

103 KB | W: | H:

doc/wrpc_mon.png
doc/wrpc_mon.png
doc/wrpc_mon.png
doc/wrpc_mon.png
  • 2-up
  • Swipe
  • Onion skin
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