You've already forked gitified_old_clb_svn
804 lines
30 KiB
Plaintext
804 lines
30 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 August 2013
|
|
@set release 2.0
|
|
@set tagname wrpc-v2.0
|
|
@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}
|
|
@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 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
|
|
@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 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}.
|
|
|
|
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 design of WRPC
|
|
|
|
@item git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git
|
|
|
|
Read-only repository with the WRPC LM32 software (incl. WR PTP daemon)
|
|
|
|
@end table
|
|
|
|
Other tools useful in building and running WRPC can be fetched 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
|
|
on the set of Manifest files.
|
|
|
|
@item http://www.ohwr.org/attachments/download/1133/lm32.tar.xz
|
|
|
|
LM32 toolchain used to compile the 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 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 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).
|
|
|
|
Any official hot fixes, if any, for this release will live in the branch called
|
|
@code{@value{tagname}-fixes}, in each WRPC repository.
|
|
|
|
@c ==========================================================================
|
|
@node Hardware needed
|
|
@section Hardware needed
|
|
|
|
The absolutely minimum hardware you need to build and run the White
|
|
Rabbit PTP Core is a PC computer with Linux and one Simple PCIe FMC Carrier
|
|
(SPEC) - @uref{http://www.ohwr.org/projects/spec}. However, it is recommended to
|
|
use also the DIO FMC card (@uref{http://www.ohwr.org/projects/fmc-dio-5chttla})
|
|
for storing calibration values and configuration in EEPROM(described later).
|
|
To test the White Rabbit synchronization, you will also need:
|
|
@itemize
|
|
@item second SPEC board with DIO FMC or a White Rabbit Switch;
|
|
@item pair of WR-supported SFP transceivers (list of supported SFPs 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 SPECs or SPEC with WR
|
|
Switch.
|
|
@end itemize
|
|
|
|
@c ##########################################################################
|
|
@node Building the Core
|
|
@chapter Building the Core
|
|
|
|
Building the White Rabbit PTP Core is a two step process. First you have to
|
|
synthesize the FPGA firmware (gateware) and then compile the software which
|
|
will be running on a softcore LM32 CPU instantiated inside the gateware.
|
|
|
|
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
|
|
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:
|
|
|
|
@example
|
|
/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}
|
|
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.
|
|
This (provided that the installation path for @i{ISE} is /opt/Xilinx/<version>)
|
|
should look like this:
|
|
|
|
@example
|
|
$ export XILINX=/opt/Xilinx/<version>/ISE_DS
|
|
@end example
|
|
|
|
@b{Note:} the Xilinx project file included in the WRPC sources was created with
|
|
Xilinx ISE 14.5. It is recommended to use the newest available version of ISE
|
|
software.
|
|
|
|
@sp 1
|
|
HDL sources for 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.
|
|
|
|
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:
|
|
|
|
@example
|
|
$ wget http://www.ohwr.org/attachments/download/2070/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.
|
|
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.
|
|
|
|
@sp 1
|
|
Having Xilinx ISE software and @i{hdlmake} you can clone the main WR PTP Core
|
|
git repository and start building the 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>
|
|
@end example
|
|
|
|
You also need to fetch other git repositories containing modules essential for
|
|
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 those submodule repositories are stored to:
|
|
|
|
@example
|
|
<your_wrpc_location>/ip_cores
|
|
@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 release of WR PTP Core, you can get
|
|
the release sources from the tarball available in the @i{files} tab of
|
|
@code{wr-cores}:
|
|
|
|
@example
|
|
http://www.ohwr.org/projects/wr-cores/files
|
|
@end example
|
|
|
|
@sp 1
|
|
The subdirectory which contains the main synthesis Manifest.py for SPEC board
|
|
and in which you should perform the whole process is:
|
|
|
|
@example
|
|
$ cd <your_wrpc_location>/syn/spec_1_1/wr_core_demo/
|
|
@end example
|
|
|
|
First you have to call @i{hdlmake} to create a synthesis Makefile for Xilinx
|
|
ISE:
|
|
|
|
@example
|
|
$ hdlmake --make-ise --ise-proj
|
|
@end example
|
|
|
|
After that, the actual synthesis is just the matter of executing the command:
|
|
|
|
@example
|
|
$ 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 FPGA
|
|
firmware: @i{spec_top.bit} and @i{spec_top.bin}. The former can be downloaded
|
|
to FPGA with Xilinx Platform Cable using Xilinx software (@i{Impact} or
|
|
@i{Chipscope Pro}). The latter can be used with the kernel driver 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
|
|
|
|
To compile the LM32 software for White Rabbit PTP Core you will need to
|
|
download and unpack the LM32 toolchain from the location mentioned already 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 setup the @t{CROSS_COMPILE} variable in order
|
|
to compile the software for a LM32 processor:
|
|
|
|
@example
|
|
$ export CROSS_COMPILE="<your_lm32_location>/lm32/bin/lm32-elf-"
|
|
@end example
|
|
|
|
To get the release sources of 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.
|
|
|
|
@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"
|
|
@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
|
|
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 them by @i{make}ing them by name
|
|
like this:
|
|
|
|
@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 LM32 inside the White Rabbit 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 software support for the 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
|
|
SPEC board plugged into the PCI-Express port of the PC.
|
|
|
|
The instructions in this section are based on release 2013-05 of @i{spec-sw}
|
|
and are limited to absolute minimum required to load WRPC FPGA
|
|
and LM32 firmware. The full manual for @i{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 newer version of 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.
|
|
|
|
@sp 1
|
|
First, please clone the git repository of SPEC software support package and
|
|
build the kernel drivers and tools:
|
|
|
|
@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 the @i{spec_top.bin} 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
|
|
@end example
|
|
|
|
You have to download also the "golden" firmware for SPEC card. It is used by
|
|
the drivers to recognize correctly 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 FPGA on SPEC with a 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 FPGA firmware file was found by the driver and correctly loaded
|
|
to 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 FPGA
|
|
bitstream with default 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_wrpcsw_location>/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 PTP
|
|
Core Shell:
|
|
|
|
@example
|
|
$ sudo tools/spec-vuart
|
|
@end example
|
|
|
|
If you are able to see the WRPC Shell prompt @i{wrc#} that means the Core is up
|
|
and running on your SPEC. Congratulations !
|
|
|
|
|
|
@c ==========================================================================
|
|
@node Writing EEPROM and calibration
|
|
@section Writing EEPROM and calibration
|
|
|
|
By default WRPC starts in WR Slave mode, uses the calibration values for
|
|
Axcen AXGE-3454-0531 SFP and for release FPGA bitstream available in
|
|
@i{http://www.ohwr.org/projects/wr-cores/files}. This might be fine for running
|
|
White Rabbit PTP Core for the first time and synchronizing it to WR Switch.
|
|
There are however, two mechanisms that are useful when playing more with WRPC
|
|
shell and different settings.
|
|
|
|
@b{Note:} the examples below describe only a subset of 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 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 SPEC has any Mezzanine board plugged into the FMC connector (e.g. DIO,
|
|
Fine Delay, TDC...) then you can create a calibration database inside the FMC
|
|
EEPROM. The example below presents the WRPC Shell commands which create an
|
|
empty SFP database and add two Axcen transceivers with deltaTx, deltaRx and
|
|
alpha parameters associated with them. Those SFPs are most widely used in WR
|
|
development and demonstrations.
|
|
@example
|
|
wrc# sfp erase
|
|
wrc# sfp add AXGE-1254-0531 46407 183843 73622176
|
|
wrc# sfp add AXGE-3454-0531 46407 183843 -73622176
|
|
@end example
|
|
|
|
To check the content of the 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 SPEC is synchronized to the WR Switch. To find the new values
|
|
you should read the WR Calibration procedure (@i{http://www.ohwr.org/documents/213}).
|
|
|
|
@sp 1
|
|
The WR PTP Core's mode of operation (WR Master/WR Slave) can be set using the
|
|
@i{mode} shell command in one of the following two ways:
|
|
|
|
@example
|
|
wrc# mode slave
|
|
wrc# mode master
|
|
@end example
|
|
|
|
This stops the 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
|
|
|
|
@sp 2
|
|
One option is to type all those commands to initialize the WRPC software to the
|
|
required state every time the Core starts. However, you can also write your own
|
|
init script to FMC EEPROM and WRPC software will execute it each time it comes
|
|
back from the reset state (this also includes coming back from reset after
|
|
programming the FPGA and LM32). Building the simple script that reads
|
|
detected SFP parameters from EEPROM, configures the mode of operation to WR
|
|
Slave and starts the 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
|
|
@end example
|
|
|
|
Almost exactly the same one can be used for running SPEC in WR Master mode. The
|
|
only difference would be of course @i{init add mode slave} vs. @i{init add mode
|
|
master}.
|
|
|
|
@c ==========================================================================
|
|
@node Running the Core
|
|
@section Running the Core
|
|
|
|
Having the SFP database, and the init script created in @ref{Writing EEPROM and
|
|
calibration} you can restart the WR PTP Core by reprogramming the LM32 software
|
|
(with @i{spec-cl} tool) or by typing the shell command:
|
|
|
|
@example
|
|
wrc# init boot
|
|
@end example
|
|
|
|
After that 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
|
|
ID: cafebabe
|
|
t24p read from EEPROM: 850 ps
|
|
Loops per jiffy: 20815
|
|
softpll: mode slave, 1 ref channels, 2 out channels
|
|
Locking PLL
|
|
executing: ptp stop
|
|
executing: sfp detect
|
|
AXGE-1254-0531
|
|
executing: sfp match
|
|
SFP matched, dTx=46407, dRx=183843, alpha=73622176
|
|
executing: mode slave
|
|
softpll: mode slave, 1 ref channels, 2 out channels
|
|
Locking PLL
|
|
executing: ptp start
|
|
@end example
|
|
|
|
Now you should have the White Rabbit PTP Core running in WR Slave mode. The
|
|
Shell also contains the monitoring function which you can use to check the WR
|
|
synchronization status:
|
|
|
|
@example
|
|
wrc# gui
|
|
@end example
|
|
|
|
The information is presented in a clear, auto-refreshing screen (full
|
|
description about information reported by gui is provided in @ref{WRPC GUI
|
|
elements}):
|
|
|
|
@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 WR Slave mode. When running as 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
|
|
If you have a DIO Mezzanine board placed on your SPEC, you can check the
|
|
synchronization quality by observing the difference between 1-PPS signals from
|
|
the WR Master and WR Slave. White Rabbit 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.
|
|
|
|
@c ##########################################################################
|
|
@node Troubleshooting
|
|
@chapter Troubleshooting
|
|
|
|
@b{My computer hangs on loading spec.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 WRPC. Please remember to quit @i{spec-vuart} before reloading
|
|
the driver.
|
|
|
|
@sp 1
|
|
@b{I want to synthesize 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{WR PTP Core seems to work but I observe on my oscilloscope that the offset
|
|
between 1-PPS signals from WR Master and WR Slave is more than 1 ns.}
|
|
|
|
If you're trying to synchronize the SPEC board to WR Switch please remember to
|
|
read the document and perform the 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 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{ver} @tab prints which version of wrpc is running
|
|
|
|
@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 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 WR Link, needed by calibration procedure
|
|
|
|
@item @code{ptp start} @tab start WR PTP daemon
|
|
@item @code{ptp stop} @tab stops WR PTP daemon
|
|
|
|
@item @code{mode} @tab prints available WR PTP modes
|
|
@item @code{mode gm} @tab sets WRPC to operate as Grandmaster clock (requires external 10MHz and 1-PPS reference)(*)
|
|
@item @code{mode master} @tab sets WRPC to operate as Free-running Master(*)
|
|
@item @code{mode slave} @tab sets WRPC to operate as Slave node(*)
|
|
|
|
@item @code{calibration} @tab tries to read t2/4 phase transition from 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 EEPROM
|
|
|
|
@item @code{time} @tab prints current time from WRPC
|
|
@item @code{time raw} @tab prints current time in a raw format (seconds, nanoseconds)
|
|
@item @code{time set <sec> <nsec>} @tab sets WRPC time
|
|
@item @code{time setsec <sec>} @tab sets only seconds part of 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 WRPC time
|
|
|
|
@item @code{sfp detect} @tab prints the ID of currently used SFP transceiver
|
|
@item @code{sfp erase} @tab cleans the SFP database stored in FMC EEPROM
|
|
@item @code{sfp add <ID> <deltaTx> <deltaRx> <alpha>} @tab stores calibration parameters for SFP to the database in FMC EEPROM
|
|
@item @code{sfp show} @tab prints all SFP transceivers stored in database
|
|
@item @code{sfp match} @tab tries to get calibration parameters from database for currently used SFP transceiver(**)
|
|
|
|
@item @code{init erase} @tab cleans initialization script in FMC 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 EEPROM
|
|
@item @code{init boot} @tab executes the script stored in FMC EEPROM (the same action is done automatically when WRPC starts after resetting LM32)
|
|
|
|
@item @code{mac get} @tab prints WRPC's MAC address
|
|
@item @code{mac getp} @tab re-generates MAC address from 1-wire digital thermometer or EEPROM
|
|
@item @code{mac set <mac>} @tab sets the MAC address of WRPC
|
|
@item @code{mac setp <mac>} @tab sets MAC address to the 1-wire EEPROM (if available)
|
|
|
|
@item @code{sdb} @tab prints devices connected to the Wishbone bus inside WRPC
|
|
|
|
@item @code{ip get} @tab prints the IPv4 address of the WRPC(***)
|
|
@item @code{ip set <ip>} @tab sets the IPv4 address of the WRPC(***)
|
|
|
|
@end multitable
|
|
|
|
* after executing @t{mode} command, @t{ptp start} is required to start WR PTP
|
|
daemon in new mode
|
|
|
|
** requires running @t{sfp detect} first
|
|
|
|
*** available only with Etherbone support compiled in
|
|
|
|
|
|
@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 PTP Core - @code{<WR
|
|
Master, WR Slave>}
|
|
@item @code{< Locked, NoLock >} @tab SoftPLL lock state
|
|
|
|
@item @code{Servo state:} @tab current state of WR servo state machine -
|
|
@code{<Uninitialized, SYNC_SEC, SYNC_NSEC, SYNC_PHASE, TRACK_PHASE>}
|
|
|
|
@item @code{Phase tracking:} @tab is phase tracking enabled when WR Slave is
|
|
synchronized to WR Master - @code{<ON, OFF>}
|
|
@item @code{Synchronization source:} @tab network interface name from which 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 WR
|
|
Master's hardware (@math{\Delta_{TXM}, \Delta_{RXM}})
|
|
|
|
@item @code{Slave PHY delays:} @tab transmission/reception delays of WR Slave's
|
|
hardware (@math{\Delta_{TXS}, \Delta_{RXS}})
|
|
|
|
@item @code{Total link asymmetry:} @tab 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 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 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
|