You've already forked gitified_old_clb_svn
845 lines
33 KiB
Plaintext
845 lines
33 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
%
|
|
% wrpc.in - main file for the documentation
|
|
%
|
|
%%%%
|
|
|
|
%------------------------------------------------------------------------------
|
|
%
|
|
% NOTE FOR THE UNAWARE USER
|
|
% =========================
|
|
%
|
|
% This file is a texinfo source. It isn't the binary file of some strange
|
|
% editor of mine. If you want ASCII, you should "make wrpc.txt".
|
|
%
|
|
%------------------------------------------------------------------------------
|
|
|
|
%
|
|
% This is not a conventional info file...
|
|
% I use three extra features:
|
|
% - The '%' as a comment marker, if at beginning of line ("\%" -> "%")
|
|
% - leading blanks are allowed (this is something I can't live without)
|
|
% - braces are automatically escaped when they appear in example blocks
|
|
%
|
|
|
|
@comment %**start of header
|
|
@documentlanguage en
|
|
@documentencoding ISO-8859-1
|
|
@setfilename wrpc.info
|
|
@settitle White Rabbit PTP Core
|
|
@iftex
|
|
@afourpaper
|
|
@end iftex
|
|
@paragraphindent none
|
|
@comment %**end of header
|
|
|
|
@setchapternewpage off
|
|
|
|
@set update-month December 2013
|
|
@set release __RELEASE_GIT_ID__
|
|
@set tagname wrpc-v2.1
|
|
@c WARNING: in @example I Can't use @value{tagname}, so please look for this
|
|
@c string when updating the document.
|
|
|
|
@finalout
|
|
|
|
@titlepage
|
|
@title White Rabbit PTP Core User's Manual
|
|
@subtitle @value{update-month} (@value{release})
|
|
@subtitle Building and Running
|
|
@author Grzegorz Daniluk (CERN BE-CO-HT)
|
|
@end titlepage
|
|
@headings single
|
|
|
|
@c ##########################################################################
|
|
@iftex
|
|
@contents
|
|
@end iftex
|
|
|
|
@c ##########################################################################
|
|
@node Top
|
|
@top Introduction
|
|
|
|
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} please skip
|
|
@ref{Building the Core} and move forward directly to
|
|
@ref{Running and Configuring}.
|
|
|
|
@c ##########################################################################
|
|
@node Software and hardware requirements
|
|
@chapter Software and hardware requirements
|
|
|
|
@c ==========================================================================
|
|
@node Repositories and Releases
|
|
@section Repositories and Releases
|
|
|
|
%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:
|
|
|
|
@table @code
|
|
|
|
@item http://www.ohwr.org/projects/wr-cores/documents
|
|
|
|
This place hosts the pdf documentation for every official
|
|
release.
|
|
|
|
@item http://www.ohwr.org/projects/wr-cores/files
|
|
|
|
Here we place the @i{.tar.gz} file for every release,
|
|
including the @i{git} tree and synthesized/compiled binaries
|
|
|
|
@item git://ohwr.org/hdl-core-lib/wr-cores.git
|
|
|
|
Read-only repository with the complete HDL sources of @sc{wrpc}
|
|
|
|
@item git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git
|
|
|
|
Read-only repository with the @sc{wrpc} @sc{lm32} software (incl. @sc{wr ptp} daemon)
|
|
|
|
@end table
|
|
|
|
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 create a Makefile based
|
|
on the set of Manifest files.
|
|
|
|
@item http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
|
|
|
|
@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.
|
|
|
|
@end table
|
|
|
|
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 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.
|
|
|
|
@c ==========================================================================
|
|
@node Hardware needed
|
|
@section Hardware needed
|
|
|
|
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 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 @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
|
|
|
|
@c ##########################################################################
|
|
@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.
|
|
|
|
@c ==========================================================================
|
|
@node HDL synthesis
|
|
@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 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
|
|
@end example
|
|
|
|
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{settings} script execution.
|
|
This (provided that the installation path for @i{ISE} is /opt/Xilinx/<version>)
|
|
should be the following:
|
|
|
|
@example
|
|
$ 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 however recommended to use the newest available
|
|
version of ISE software.
|
|
|
|
@sp 1
|
|
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} 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
|
|
$ 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
|
|
@end example
|
|
|
|
@b{Note:} the @i{hdlmake} usage instructions here are based on version 1.0.
|
|
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} 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_location>/wr-cores
|
|
$ cd <your_location>/wr-cores
|
|
@end example
|
|
|
|
To build the gateware using sources of a stable release @value{tagname}, you
|
|
have to checkout the proper git tag:
|
|
|
|
@example
|
|
$ git checkout wrpc-v2.1
|
|
@end example
|
|
|
|
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
|
|
$ git submodule init
|
|
$ git submodule update
|
|
@end example
|
|
|
|
The local copies of the submodules are stored to:
|
|
|
|
@example
|
|
<your_location>/wr-cores/ip_cores
|
|
@end example
|
|
|
|
@sp 1
|
|
The subdirectory which contains the main synthesis Manifest.py for @sc{spec} board
|
|
and in which you should perform the whole process is:
|
|
|
|
@example
|
|
$ cd <your_location>/wr-cores/syn/spec_1_1/wr_core_demo/
|
|
@end example
|
|
|
|
First, please call @i{hdlmake} to create synthesis Makefile for Xilinx
|
|
ISE:
|
|
|
|
@example
|
|
$ hdlmake-v1.0 --make-ise --ise-proj
|
|
@end example
|
|
|
|
After that, the actual synthesis is just the matter of executing:
|
|
|
|
@example
|
|
$ make
|
|
@end example
|
|
|
|
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
|
|
If, on the other hand, you would like to clean-up the repository and rebuild
|
|
everything from scratch you can use the following commands:
|
|
@itemize
|
|
@item @i{$ make clean} - removes all synthesis reports and log files;
|
|
@item @i{$ make mrproper} - removes spec_top.bin and spec_top.bit files;
|
|
@end itemize
|
|
|
|
@c ==========================================================================
|
|
@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 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>
|
|
@end example
|
|
|
|
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-"
|
|
@end example
|
|
|
|
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_location>/wrpc-sw
|
|
$ cd <your_location>/wrpc-sw
|
|
$ git checkout wrpc-v2.1 # or "git checkout master"
|
|
@end smallexample
|
|
|
|
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
|
|
@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 one by @i{make}ing it by name:
|
|
|
|
@example
|
|
$ make spec_defconfig
|
|
@end example
|
|
|
|
The most important configuration choice at this point in time is
|
|
whether to enable Etherbone or not. It is disabled by default in
|
|
@code{spec_defconfig} and enabled by default in
|
|
@code{etherbone_defconfig}.
|
|
|
|
After the package is configured, just run @code{make} without
|
|
parameters to build your binary file:
|
|
|
|
@example
|
|
$ make
|
|
@end example
|
|
|
|
The first time you build, the @i{Makefile} automatically downloads
|
|
the @i{git submodules} of this package, unless you already did that
|
|
by hand. The second and later build won't download anything
|
|
from the network.
|
|
|
|
The resulting binary @i{wrc.bin} can be then used with the loader from
|
|
@i{spec-sw} software package to program the @sc{lm32} inside the White Rabbit @sc{ptp}
|
|
Core (@ref{Running and Configuring}).
|
|
|
|
@c ##########################################################################
|
|
@node Running and Configuring
|
|
@chapter Running and Configuring
|
|
|
|
@c ==========================================================================
|
|
@node Downloading firmware to SPEC
|
|
@section Downloading firmware to SPEC
|
|
|
|
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.
|
|
|
|
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. Full manual for @sc{spec-sw} can be found at:
|
|
|
|
@example
|
|
http://www.ohwr.org/attachments/download/2134/spec-sw-2013-05-release.pdf
|
|
@end example
|
|
|
|
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-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
|
|
@end smallexample
|
|
|
|
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_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 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
|
|
@end example
|
|
|
|
Now, you are ready to load necessary drivers that configure the
|
|
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
|
|
@end example
|
|
|
|
To check if the @sc{fpga} firmware file was found by the driver and correctly loaded
|
|
to @sc{fpga} the @i{dmesg} Linux command can be called. Among plenty of messages
|
|
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
|
|
@end smallexample
|
|
|
|
If everything went right up to this moment you have your board running the @sc{fpga}
|
|
bitstream with default @sc{lm32} software. If you want to load your own @i{wrc.bin}
|
|
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_location>/wrpc-sw/wrc.bin
|
|
@end example
|
|
|
|
@sp 1
|
|
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
|
|
@end example
|
|
|
|
If you are able to see the @sc{wrpc} Shell prompt @i{wrc#} that means the Core is up
|
|
and running on your @sc{spec}. Congratulations !
|
|
|
|
|
|
@c ==========================================================================
|
|
@node Writing EEPROM and calibration
|
|
@section Writing EEPROM and calibration
|
|
|
|
You should perform few configuration steps through the @sc{wrpc} shell before
|
|
you start testing and using the firmware.
|
|
|
|
@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
|
|
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
|
|
@end example
|
|
|
|
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 180707 148323 72169888
|
|
wrc# sfp add AXGE-3454-0531 180707 148323 -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.1} release bitstream available on @i{ohwr.org} running on @sc{spec} v4 board
|
|
and calibrated to the port 1 of @sc{wr} Switch v3.3. Those values as well as the parameters for the
|
|
@sc{wr} Switch are available on the calibration wiki page
|
|
(@i{http://www.ohwr.org/projects/white-rabbit/wiki/Calibration}). However, if
|
|
you re-synthesize the firmware or want to have most accurate estimation of fixed
|
|
delays and alpha of your fiber you should read and perform the @sc{wr}
|
|
Calibration procedure (@i{http://www.ohwr.org/documents/213}).
|
|
|
|
@sp 1
|
|
The @sc{wr ptp} Core's mode of operation (GrandMaster/Master/Slave) can be set using the
|
|
@i{mode} shell command:
|
|
|
|
@example
|
|
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
|
|
back automatically. Therefore after changing it you need to start the daemon
|
|
manually:
|
|
|
|
@example
|
|
wrc# ptp start
|
|
@end example
|
|
|
|
@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 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 calibration
|
|
wrc# init add ptp start
|
|
@end example
|
|
|
|
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
|
|
@section Running the Core
|
|
|
|
Having the @sc{sfp} database, and the init script created in @ref{Writing EEPROM and
|
|
calibration} you can restart the @sc{wr ptp} Core by reprogramming the @sc{lm32} software
|
|
(with @i{spec-cl} tool) or by typing the shell command:
|
|
|
|
@example
|
|
wrc# init boot
|
|
@end example
|
|
|
|
You should see the log messages that confirm the init script
|
|
execution:
|
|
|
|
@example
|
|
(...)
|
|
WR Core: starting up...
|
|
W1: f80000036c38ee28
|
|
get_persistent_mac: Using W1 serial number
|
|
ID: cafebabe
|
|
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=180585, dRx=145855, alpha=72169888
|
|
executing: mode slave
|
|
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. @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
|
|
@end example
|
|
|
|
The information is presented in a clear, auto-refreshing screen. To exit
|
|
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
|
|
|
|
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 @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 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
|
|
registers inside @sc{wrpc}. Please remember to quit @i{spec-vuart} before reloading
|
|
the driver.
|
|
|
|
@sp 1
|
|
@b{I want to synthesize @sc{wrpc} but hdlmake does nothing, just quits without any
|
|
message.}
|
|
|
|
Please check if you have the Xilinx ISE-related system variables set correctly
|
|
(@i{settings32.sh} script provided by Xilinx sets them) and make sure you have
|
|
overwritten the @i{$XILINX} variable to:
|
|
|
|
@example
|
|
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
|
|
@end example
|
|
|
|
or similar, if your installation folder differs from default.
|
|
|
|
@sp 1
|
|
@b{@sc{wr ptp} Core seems to work but I observe on my oscilloscope that the offset
|
|
between 1-PPS signals from @sc{wr} Master and @sc{wr} Slave is more than 1 ns.}
|
|
|
|
If you're trying to synchronize the @sc{spec} board to @sc{wr} Switch please remember to
|
|
read the document and perform the @sc{wr} Calibration to find out the values of
|
|
deltaRx and deltaTx for your firmware. Check if the oscilloscope cables you use
|
|
have the same delays (or take the delay difference into account in your
|
|
measurements).
|
|
|
|
|
|
@c ##########################################################################
|
|
@node Questions, reporting bugs
|
|
@chapter Questions, reporting bugs
|
|
|
|
If you have found a bug, you have problems with White Rabbit @sc{ptp} Core or one
|
|
of the tools used to build and run it, you can write to our mailing list
|
|
@code{white-rabbit-dev@@ohwr.org}
|
|
|
|
|
|
@c ##########################################################################
|
|
@page
|
|
@node WRPC Shell commands
|
|
@appendix WRPC Shell Commands
|
|
|
|
@multitable @columnfractions .5 .5
|
|
@item @code{help} reports the available commands in this instance of @sc{wrpc}
|
|
|
|
@item @code{ver} @tab prints which version of wrpc is running
|
|
|
|
@item @code{config} @tab prints the Kconfig file used to build this instance of @sc{wrpc}. It is an optional command, enabled at build time by @t{CONFIG_CMD_CONFIG}
|
|
|
|
@item @code{verbose <digits>} @tab Set PPSi verbosity. See the PPSi manual about the meaning of the digits (hint: @t{verbose 1111} is a good first bet too see how the @sc{ptp} system is working)
|
|
|
|
@item @code{pll init <mode> <ref_channel> <align_pps>} @tab manually run spll_init()
|
|
function to initialize SoftPll
|
|
@item @code{pll cl <channel>} @tab check if SoftPLL is locked for the channel
|
|
@item @code{pll sps <channel> <picoseconds>} @tab set phase shift for the channel
|
|
@item @code{pll gps <channel>} @tab get current and target phase shift for the channel
|
|
@item @code{pll start <channel>} @tab start SoftPLL for the channel
|
|
@item @code{pll stop <channel>} @tab stop SoftPLL for the channel
|
|
@item @code{pll sdac <index> <val>} @tab set the dac
|
|
@item @code{pll gdac <index>} @tab get dac's value
|
|
|
|
@item @code{gui} @tab starts GUI @sc{wrpc} monitor
|
|
|
|
@item @code{stat} @tab prints one line log message
|
|
@item @code{stat cont} @tab prints log message for each second (Esc to exit back to shell)
|
|
@item @code{stat bts} @tab prints bitslide value for established @sc{wr} Link, needed by calibration procedure
|
|
|
|
@item @code{ptp start} @tab start @sc{wr ptp} daemon
|
|
@item @code{ptp stop} @tab stops @sc{wr ptp} daemon
|
|
|
|
@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 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)
|
|
@item @code{time set <sec> <nsec>} @tab sets @sc{wrpc} time
|
|
@item @code{time setsec <sec>} @tab sets only seconds part of @sc{wrpc} time (useful for setting time in GrandMaster mode, when nanoseconds counter is aligned to external 1-PPS and 10 MHz)
|
|
@item @code{time setnsec <nsec>} @tab sets only nanoseconds part of @sc{wrpc} time
|
|
|
|
@item @code{sfp detect} @tab prints the ID of currently used @sc{sfp} transceiver
|
|
@item @code{sfp erase} @tab cleans the @sc{sfp} database stored in @sc{fmc} @sc{eeprom}
|
|
@item @code{sfp add <ID> <deltaTx> <deltaRx> <alpha>} @tab stores calibration parameters for @sc{sfp} to the database in @sc{fmc} @sc{eeprom}
|
|
@item @code{sfp show} @tab prints all @sc{sfp} transceivers stored in database
|
|
@item @code{sfp match} @tab tries to get calibration parameters from database for currently used @sc{sfp} transceiver (@t{sfp detect} must be executed before @t{match})
|
|
|
|
@item @code{init erase} @tab cleans initialization script in @sc{fmc} @sc{eeprom}
|
|
@item @code{init add <cmd>} @tab adds shell command at the end of initialization script
|
|
@item @code{init show} @tab prints all commands from the script stored in @sc{eeprom}
|
|
@item @code{init boot} @tab executes the script stored in @sc{fmc} @sc{eeprom} (the same action is done automatically when @sc{wrpc} starts after resetting @sc{lm32})
|
|
|
|
@item @code{mac get} @tab prints @sc{wrpc}'s @sc{mac} address
|
|
@item @code{mac getp} @tab re-generates @sc{mac} address from 1-wire digital thermometer or @sc{eeprom}
|
|
@item @code{mac set <mac>} @tab sets the @sc{mac} address of @sc{wrpc}
|
|
@item @code{mac setp <mac>} @tab sets @sc{mac} address to the 1-wire @sc{eeprom} (if available)
|
|
|
|
@item @code{sdb} @tab prints devices connected to the Wishbone bus inside @sc{wrpc}
|
|
|
|
@item @code{ip get}
|
|
@item @code{ip set <ip>} @tab reports or sets the IPv4 address of the @sc{wrpc} (only available if @t{CONFIG_ETHERBONE} is set at build time
|
|
|
|
@item @code{w1w <offset> <byte> [<byte> ...]}
|
|
@item @code{w1r <offset> <len>} @tab If @t{CONFIG_W1} is set and a OneWire @sc{eeprom} esists, write and read data. For writing, @t{byte} values are decimal
|
|
|
|
@end multitable
|
|
|
|
|
|
|
|
@c ##########################################################################
|
|
@page
|
|
@node WRPC GUI elements
|
|
@appendix WRPC GUI elements
|
|
|
|
@multitable @columnfractions .3 .7
|
|
@item @code{TAI Time:} @tab current state of device's local clock
|
|
@item @code{RX:} / @code{TX:} @tab Rx/Tx packets counters
|
|
@item @code{mode:} @tab operation mode of White Rabbit @sc{ptp} Core - @code{<WR
|
|
Master, WR Slave>}
|
|
@item @code{< Locked, NoLock >} @tab SoftPLL lock state
|
|
|
|
@item @code{Servo state:} @tab current state of @sc{wr} servo state machine -
|
|
@code{<Uninitialized, SYNC_SEC, SYNC_NSEC, SYNC_PHASE, TRACK_PHASE>}
|
|
|
|
@item @code{Phase tracking:} @tab is phase tracking enabled when @sc{wr} Slave is
|
|
synchronized to @sc{wr} Master - @code{<ON, OFF>}
|
|
@item @code{Synchronization source:} @tab network interface name from which @sc{wr}
|
|
daemon gets synchronization - @code{<wru1>}
|
|
|
|
@item @code{Round-trip time (mu):} @tab round-trip delay in picoseconds
|
|
(@math{delay_{MM}})
|
|
|
|
@item @code{Master-slave delay:} @tab estimated one-way (master to slave) link
|
|
delay (@math{delay_{MS}})
|
|
|
|
@item @code{Master PHY delays:} @tab transmission/reception delays of @sc{wr}
|
|
Master's hardware (@math{\Delta_{TXM}, \Delta_{RXM}})
|
|
|
|
@item @code{Slave PHY delays:} @tab transmission/reception delays of @sc{wr} Slave's
|
|
hardware (@math{\Delta_{TXS}, \Delta_{RXS}})
|
|
|
|
@item @code{Total link asymmetry:} @tab @sc{wr} link asymmetry calculated as
|
|
@math{delay_{MM} - 2 \cdot delay_{MS}}
|
|
|
|
@item @code{Cable rtt delay:} @tab round-trip fiber latency
|
|
|
|
@item @code{Clock offset:} @tab Slave to Master offset calculated by @sc{ptp} daemon
|
|
(@math{offset_{MS}})
|
|
|
|
@item @code{Phase setpoint:} @tab current Slave's clock phase shift value
|
|
|
|
@item @code{Skew:} @tab the difference between current and previous estimated
|
|
one-way link delay
|
|
|
|
@item @code{Update counter:} @tab the state of counter incremented every time
|
|
the @sc{wr} servo is updated
|
|
|
|
@end multitable
|
|
|
|
@c ##########################################################################
|
|
@bye
|
|
|
|
@c LocalWords: gnudd titlepage iftex texinfo CERN documentlanguage settitle
|
|
@c LocalWords: documentencoding setfilename afourpaper paragraphindent FPGA
|
|
@c LocalWords: setchapternewpage finalout gateware ohwr modprobe insmod cset
|
|
@c LocalWords: smallexample ctrl timestamp fdelay struct spusa hdlmake Xilinx
|
|
@c LocalWords: bitstream wrpc init EEPROM grandmaster wrpcsw noposix http
|
|
@c LocalWords: tarball toolchain specsw sudo Etherbone
|