wrpc.in

\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 2015
@set release __RELEASE_GIT_ID__
@set version 3.0
@set tagname wrpc-v3.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} (@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 PTP Core, part of the White
Rabbit project. 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 about the official @value{release} stable release of the 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

	hosts the pdf documentation for every official release.

@item http://www.ohwr.org/projects/wr-cores/files

	place where you can find a synthesized bitstream, ready to be downloaded to
  SPEC, for every stable release

@item git://ohwr.org/hdl-core-lib/wr-cores.git

	read-only repository with complete HDL sources of the @sc{wrpc}

@item git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git

  read-only repository with the @sc{wrpc} @sc{lm32} software

@end table

Other tools useful for building and running the @sc{wrpc} can be downloaded from
the following locations:

@table @code

@item git://ohwr.org/misc/hdl-make.git

  @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} software

@end table

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 releases.

@c ==========================================================================
@node Required hardware
@section Required hardware

The absolute minimum to run the @sc{wr ptp core} is a PC computer with
Linux and a 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})
to be able to feed 1-PPS and 10MHz from external clock and output 1-PPS aligned
to the WR time. To test the White Rabbit synchronization, you will also need:
@itemize
@item another @sc{spec} board with a @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 a @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 from @i{ohwr.org}.

@sp 1
Building the core is a two step process. First you have to
synthesize the FPGA firmware (gateware) and then compile the software which
will be executed by the @sc{lm32} soft-core processor. If you don't need to
modify the @sc{lm32} software, you can skip the compilation stage since
synthesized gateware already embeds the default software for the release.

@c ==========================================================================
@node HDL synthesis
@section HDL synthesis

Before running the synthesis process you have to make sure your environment is
set up correctly. You need a Xilinx ISE software with at least a 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 a shell you
use and whether your Linux is 32 or 64-bits you should execute one of them
before the other tools are used. For 64-bit system and BASH shell you should
call:
@example
/opt/Xilinx/<version>/ISE_DS/settings64.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 to your @i{bash.rc} file. You can
check if the shell is configured correctly by verifying if the @i{$XILINX}
variable contains 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 the ISE software.

@sp 1
HDL sources for the @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 clone the @i{hdlmake} repository from its location given in
@ref{Repositories and Releases}:
@example
$ wget http://www.ohwr.org/attachments/download/2070/hdlmake-v1.0
$ git clone git://ohwr.org/misc/hdl-make.git <your_location>/hdl-make
$ cd <your_location>/hdl-make
$ git checkout 9d303ee
@end example

Then, using your favorite editor, you should create an @i{hdlmake} script in
/usr/bin to be able to call it from any directory. The script should have the
following content:
@smallexample
@noindent
#!/usr/bin/env bash
python2.7 /path_to_hdlmake_sources/hdl-make/hdlmake/__main__.py $@@
@end smallexample

After that, you should make your script executable:
@example
chmod a+x /usr/bin/hdlmake
@end example

@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 FPGA bitstream.
First, please create a local copy of the @i{wr-cores}:
@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-v3.0
@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 instantiated
inside the @sc{wr ptp core} HDL. They are configured as git submodules:
@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
@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 FPGA firmware: @i{spec_top.bit} and @i{spec_top.bin}. The
former can be downloaded to FPGA with Xilinx Platform Cable using e.g.
@i{Xilinx Impact}. The latter can be used with kernel drivers from the
@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 @sc{lm32} software for a stable release is embedded
inside the FPGA bitstream you've downloaded from @i{ohwr.org} or synthesized in
the previous step. This means you don't have to do a manual compilation of the
@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 the 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 a @t{CROSS_COMPILE} variable in order
to compile the software for the @sc{lm32} processor:

@example
$ export CROSS_COMPILE="<your_lm32_location>/lm32/bin/lm32-elf-"
@end example

To get the sources of the @sc{wrpc} software please clone the @i{wrpc-sw} git
repository tagged with @value{tagname} tag. If you use @sc{wrpc} within another
project, you may need to checkout a different tag or a specific commit. If this
applies, please refer to a documentation for this project.

@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-v3.0   # 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

For this step you will need a @sc{spec} board software support package
(@sc{spec-sw}) from @i{ohwr.org}. It is a set of Linux kernel drivers and
userspace tools, that interact with a @sc{spec} board plugged into PCI-Express
slot.

Instructions in this section are based on a development version of @sc{spec-sw}
so if a stable release more recent than @i{2014-02} is available, you should
use it instead. 

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 c0e18a7
$ make
@end smallexample

Then you should copy your @i{spec_top.bin} generated in @ref{HDL synthesis} or
downloaded from the @i{ohwr} 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-3.0.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/4057/spec-init.bin-2015-09-18
$ sudo mv spec-init.bin-2015-09-18 /lib/firmware/fmc/spec-init.bin
@end example

Now you can load the drivers necessary to access @sc{spec} board from your
system:
@example
$ sudo insmod fmc-bus/kernel/fmc.ko
$ sudo insmod kernel/spec.ko
@end example

By default, when loading the @i{spec.ko} driver FPGA gets programmed with
the "golden" bitstream. Starting from version 3.0, @sc{wr ptp core} uses a flash
memory chip on the carrier as a default place for storing the calibration
parameters and the init script. Also the storage format of this information is
now better organised in the files of the @sc{sdbfs} filesystem. Therefore,
starting from v3.0 you have to write the @sc{sdbfs} filesystem image to the
flash before running the @sc{wr ptp core}. You can download the image from our
project page:
@example
$ wget http://www.ohwr.org/attachments/download/4060/sdbfs-flash.bin
@end example
It contains all the files required by the @sc{wr ptp core}. They are empty, but
have to exist in the @sc{sdbfs} structure to be written later as described in
@ref{Writing configuration}. To store the filesystem image in flash, please
execute the following command:
@example
$ sudo tools/flash-write -b 0x20 -c 0x0 0 1507712 < \
     <your_location>/sdbfs-flash.bin
@end example

@b{Note:} Please refer to @ref{Writing @sc{sdbfs} image in standalone configuration}
for instructions on how to write the @sc{sdbfs} image to a standalone @sc{spec}
or custom hardware.

@sp 1
Now, you are ready to load the last driver, which downloads the actual
@sc{wr ptp core} bitstream to the Spartan 6 FPGA:
@example
$ sudo insmod fmc-bus/kernel/fmc-trivial.ko gateware=fmc/spec-3.0.bin
@end example

You can use the @i{dmesg} Linux command to verify if the FPGA firmware file was
loaded into the FPGA. Among plenty of messages you should be able to find
something very similar to:

@smallexample
@noindent
[1275526.738895] spec 0000:20:00.0:  probe for device 0020:0000
[1275526.738906] spec 0000:20:00.0: PCI INT A -> GSI 16 (level, low) -> IRQ 16
[1275526.738913] spec 0000:20:00.0: setting latency timer to 64
[1275526.743102] spec 0000:20:00.0: got file "fmc/spec-init.bin", 1485236 (0x16a9b4) bytes
[1275526.934710] spec 0000:20:00.0: FPGA programming successful
[1275527.296754] spec 0000:20:00.0: mezzanine 0
[1275527.296756]       Manufacturer: CERN
[1275527.296757]       Product name: FmcDio5cha

[1275593.973147] fmc FmcDio5cha-2000: Driver has no ID: matches all
[1275593.973177] spec 0000:20:00.0: reprogramming with fmc/spec-3.0.bin
[1275594.168249] spec 0000:20:00.0: FPGA programming successful
@end smallexample

If everything went right up to this moment you have your board running the FPGA 
bitstream with a default @sc{lm32} software. If you want to load your own
@i{wrc.bin} built from the @i{wrpc-sw} repository you can use the @i{spec-cl}
tool:

@example
$ sudo tools/spec-cl <your_location>/wrpc-sw/wrc.bin
@end example

@sp 1
Now you should be able to start a Virtual-UART tool (also part of the
@sc{spec-sw} package) that will be used to interact with the @sc{wr ptp core}
shell:

@example
$ sudo tools/spec-vuart
@end example

If you are able to see the @sc{wrpc} Shell prompt @i{wrc#} this means the Core
is up and running on your @sc{spec}. Congratulations !


@c ==========================================================================
@node Writing configuration
@section Writing configuration

First, you should perform a few configuration steps through the @sc{wrpc} shell
before using the core.

@b{Note:} the examples below describe only a subset of the @sc{wrpc} Shell
commands. The full list of 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, debug messages from the daemon will not show up to the console while you
interact with the shell.

@example
wrc# ptp stop
@end example

@sp 1
First you should make sure your board has a proper @sc{mac} address assigned:
@example
wrc# mac get
@end example
If the result of above command is @t{MAC-address: 22:33:ww:xx:yy:zz}, this means
@sc{mac} was not yet configured and stored in the Flash/EEPROM. The value is
based on thermometer serial number as is unique among SPEC devices,
globally accepted as ``locally assigned'', but you might want to assign your own address. A value @t{22:33:44:55:66:77} is the final fallback if no
thermometer is found (very unlikely). You should get
the @sc{mac} for your board from its manufacturer. To configure the address and
store it into the Flash/EEPROM (so that it's automatically loaded every time the
@sc{wrpc} starts) you should type two commands in the @sc{wrpc} shell:
@example
wrc# mac set xx:xx:xx:xx:xx:xx
wrc# mac setp xx:xx:xx:xx:xx:xx
@end example
where @t{xx:xx:xx:xx:xx:xx} is the @sc{mac} address of your board.

@sp 1
Next you should create a calibration database with fixed delays values and
alpha parameters. The example below presents the @sc{wrpc} Shell commands that
clear all previous entries and add two Axcen transceivers with deltaTx, deltaRx
and alpha parameters associated with them.

@example
wrc# sfp erase
wrc# sfp add AXGE-1254-0531 180625 148451 72169888
wrc# sfp add AXGE-3454-0531 180625 148451 -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 defaults for
@value{tagname} release bitstream available on @i{ohwr.org}, running on
@sc{spec} v4 board and calibrated to port 1 of a @sc{wr} Switch v3.3. These
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 the most accurate estimation of
the fixed delays and alpha for 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} mode of operation (GrandMaster/Master/Slave) can be set
using the @i{mode} 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 automatically. Therefore, after calling it, you need to restart the
daemon manually:

@example
wrc# ptp start
@end example

@b{Note:} For running the GrandMaster mode, you need to provide 1-PPS and 10MHz
signal from an external source (e.g. GPS receiver or Cesium clock). Please
connect 1-PPS signal to the LEMO connector No.4 and 10MHz to the LEMO connector
No.5 on the @sc{fmc} @sc{dio} mezzanine board.

@sp 1
One option is to type all the commands to initialize the @sc{wrpc} software to
the required state every time the Core starts. However, you can also write your
own initialization script to the Flash/EEPROM. It will be executed every time
the @sc{wrpc} software starts. A simple script that loads the calibration
parameters, 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
@end example

Almost exactly the same one can be used for running @sc{wrpc} in the GrandMaster
or Master mode. The only difference would be changing the
@i{init add mode slave} line to @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
configuration} 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 log messages that confirm the execution of the initialization
script:

@example
executing: ptp stop
executing: sfp detect
AXGE-3454-0531  
executing: sfp match
SFP matched, dTx=180707, dRx=148323, alpha=-73685416
executing: mode slave
Locking PLL
executing: ptp start
Slave Only, clock class set to 255
@end example

Now you should have the @sc{wr 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 the Slave mode. That is why it is very important, even if
@sc{wrpc} is meant to run in the Master mode, to configure it to Slave for a
moment and connect to any @sc{wr} Master. This has to be repeated every time
a new bitstream (gateware) is deployed. The measured value is automatically
stored to Flash/EEPROM and used later in the Master or GrandMaster mode.

The Shell also contains a 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. The
information is refreshed at every WR iteration or periodically if
nothing else happens (so you see an up-to-date timestamp). The period
defaults to 1 second and can be changed using the @i{refresh} command. To exit from
this console mode press <Esc>. A full description of the 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 the @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 log statistics from the @sc{wrpc} operation, it's probably
better to use the @i{stat} shell command. It reports the same information as GUI
but in a single long line, a form which is easier to parse and analyze:

@example
wrc# stat
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
Unlike @i{gui}, the @i{stat} command runs asynchronously: you can still
issue shell commands while stats are running (this is different from
earlier @t{wrpc-sw} releases).  You can stop statistics by running @i{stat} again.
As an alternative to the toggling action of @i{stat} alone, you can
use ``@i{stat 1}'' or ``@i{stat 0}''.

Statistics are printed every time the WR servo runs; thus no statistics
are reported when the node is running in master mode, nor when your node
is running as slave and the master disappeared.

@sp 1
If you have a @sc{dio} mezzanine board plugged to your @sc{spec}, you can verify
the synchronization performance by observing the offset between 1-PPS signals
from the @sc{wr} Master and @sc{wr} Slave. The @sc{wr ptp core} generates 1-PPS
signal on the LEMO connector No. 1. Please remember to use oscilloscope cables
of 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 driver while your @i{spec-vuart} is
running and trying to get messages from Virtual-UART's registers inside the
@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{settings64.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 the @sc{wr 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} @tab lists available commands in this instance of the @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 sets PPSi verbosity. See the PPSi manual
about the meaning of the digits (hint: @t{verbose 1111} is a good first bet to
see how the @sc{ptp} system is working)

@item @code{pll init <mode> <ref_channel> <align_pps>} @tab manually runs
spll_init() function to initialize SoftPll
@item @code{pll cl <channel>} @tab checks if SoftPLL is locked for the channel
@item @code{pll sps <channel> <picoseconds>} @tab sets phase shift for the channel
@item @code{pll gps <channel>} @tab gets current and target phase shift for the channel
@item @code{pll start <channel>} @tab starts SoftPLL for the channel
@item @code{pll stop <channel>} @tab stops SoftPLL for the channel
@item @code{pll sdac <index> <val>} @tab sets the dac
@item @code{pll gdac <index>} @tab gets dac's value

@item @code{gui} @tab starts GUI @sc{wrpc} monitor

@item @code{stat} @tab toggles reporting of loggable statistics. You can pass
@t{1} or @t{0} as argument as an alternative to toggling

@item @code{stat bts} @tab prints bitslide value for established @sc{wr} Link,
needed by the calibration procedure

@item @code{refresh} @tab changes the update time period of the gui and stat
commands. Default period is 1 second. If you set the period to 0, the log
message is only generated one time.

@item @code{ptp start} @tab starts @sc{wr ptp} daemon
@item @code{ptp stop} @tab stops @sc{wr ptp} daemon

@item @code{mode} @tab prints the current @sc{wr ptp} mode
@item @code{mode gm|master|slave} @tab sets @sc{wrpc} to operate as Grandmaster
clock (requires external 10MHz and 1-PPS reference), Master or 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 the
Flash/EEPROM (in @sc{WR} Master or GrandMaster mode), or executes the t24p
calibration procedure and stores its result to the Flash/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 of the @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 of the @sc{wrpc} time

@item @code{sfp detect} @tab prints the ID of a currently used @sc{sfp}
transceiver

@item @code{sfp erase} @tab erases the @sc{sfp} database stored in the Flash/EEPROM

@item @code{sfp add <ID> <deltaTx> <deltaRx> <alpha>} @tab stores calibration
parameters for @sc{sfp} to a file in Flash/EEPROM

@item @code{sfp show} @tab prints all @sc{sfp} transceivers stored in database

@item @code{sfp match} @tab tries to load the calibration parameters for
currently used @sc{sfp} transceiver (@t{sfp detect} must be executed before @t{match})

@item @code{init erase} @tab erases the initialization script in Flash/EEPROM
@item @code{init add <cmd>} @tab adds shell command at the end of the
initialization script

@item @code{init show} @tab prints all commands from the script stored in Flash/EEPROM
@item @code{init boot} @tab executes the script stored in Flash/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 reads the @sc{mac} address stored in Flash/EEPROM
@item @code{mac set <mac>} @tab sets the @sc{mac} address of @sc{wrpc}
@item @code{mac setp <mac>} @tab stores the @sc{mac} address in Flash/EEPROM

@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} exists, 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 the @sc{wr 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 ##########################################################################
@page
@node Writing @sc{sdbfs} image in standalone configuration
@appendix Writing @sc{sdbfs} image in standalone configuration

If you use @sc{spec} board in a host-less environment, or you use custom
hardware and @sc{spec} drivers and tools cannot be used, there is still a
possibility of writing @sc{sdbfs} through Xilinx JTAG.

@sp 1
In case of @sc{spec} running a reference bitstream provided with a stable
@sc{wrpc} release, you can simply program your Flash with @i{spec_top.mcs}
provided with the release binaries using for example Xilinx ISE Impact tool.
This @i{mcs} file already includes both @sc{sdbfs} image and FPGA bitstream.

In case of a custom gateware or hardware, you can download a standalone
@sc{sdbfs} image:
@example
$ wget http://www.ohwr.org/attachments/download/4144/sdbfs-standalone.bin
@end example
and generate a custom @i{*.mcs} file with your own FPGA bitstream. You should
use the following layout:

@multitable @columnfractions .1 .7
@item @code{0x000000} @tab your FPGA bitstream
@item @code{0x170000} @tab @sc{sdbfs} image
@end multitable 

@sp 1
For example, to generate the @i{*.mcs} file for M25P32 Flash on @sc{spec}, the
following @i{promgen} parameters should be used:
@example
promgen -w -spi -p mcs -c FF -s 32768 -u 0 <your_bitstream>.bit \
-bd sdb-standalone.bin start 0x170000 -o output.mcs
@end example

After that, you can use the Xilinx JTAG cable and Xilinx ISE Impact tool to
write your @i{output.mcs} file to the Flash memory.

@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