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 October 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 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 and v2.1 releases
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. To exit
from this console mode press <Esc>. 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{help} reports the available commands in this instance of 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 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 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 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|master|slave} @tab sets WRPC to operate as Grandmaster clock (requires external 10MHz and 1-PPS reference), PTP Master or PTP Slave. After setting the mode @t{ptp start} must be re-issued

@item @code{calibration} @tab tries to read t2/4 phase transition from 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 (@t{sfp detect} must be executed before @t{match})

@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}
@item @code{ip set <ip>} @tab reports or sets the IPv4 address of the 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 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