Skip to content

S
Software for White Rabbit PTP Core
Commit 88ad061a authored by Maciej Lipinski's avatar Maciej Lipinski
Browse files
Options

[doc] doc reviewed, small corrections

parent caac1e16
Hide whitespace changes
Inline Side-by-side
Showing with 70 additions and 68 deletions
doc/wrpc.tex
View file @ 88ad061a
......@@ -79,7 +79,7 @@ distributed in the following places:
\item \url{git://ohwr.org/hdl-core-lib/wr-cores.git}
repository with the complete HDL sources of the WRPC
repository with the completed HDL sources of the WRPC
\item \url{git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git}
......@@ -98,14 +98,14 @@ following locations:
\item \url{http://www.ohwr.org/attachments/download/1133/lm32.tar.xz}
LM32 toolchain used to compile the LM32 software running inside the WRPC
This is a 32-bit version of a toolchain. If you encounter problems running
LM32 toolchain used to compile the LM32 software running inside the WRPC.
This is a 32-bit version of the toolchain. If you encounter problems running
this toolchain on modern 64bit machines, try 64 version described below.
\item \url{http://www.ohwr.org/attachments/download/3868/lm32_host_64bit.tar.xz}
LM32 toolchain used to compile the LM32 software running inside the WRPC
(64-bit version of toolchain).
(64-bit version of the toolchain).
\end{itemize*}
Repositories containing the WRPC gateware and software (\textit{wr-cores},
......@@ -141,8 +141,8 @@ To be able to test White Rabbit synchronization you would also need
additional components regardless of the reference platform chosen from the list
above:
\begin{itemize}
\item another WR node (e.g. one of the reference boards listed above or a
White Rabbit Switch)
\item another WR node (e.g. one of the reference boards listed above) or a
White Rabbit Switch
\item a pair of WR-supported SFP transceivers\footnote{The list of supported
SFPs can be found on our wiki page
\url{http://www.ohwr.org/projects/white-rabbit/wiki/SFP}}
......@@ -160,7 +160,7 @@ available from \textit{ohwr.org}.
\vspace{1em}
Depending on your needs, building the WRPC can be a one- or two-step process.
In most of the cases you only need to synthesize the FPGA firmware (section
\ref{HDL synthesis}). This way, you get a working WRPC with the default, release
\ref{HDL synthesis}). This way, you get a working WRPC with the default/release
LM32 software running inside the core. If, for some reasons, you need to modify
the LM32 software, please check also section \ref{LM32 software compilation}
which contains a description of the software compilation process.
......@@ -175,7 +175,7 @@ Depending if you want to run the WRPC on Xilinx (e.g. SPEC, SVEC boards) or
Altera/Intel (e.g. VFC-HD) FPGA, you should install either Xilinx ISE or Quartus
Prime software.
\subsubsection{Setting up Xilinx ISE}
\subsubsection{Setting up Xilinx ISE on Linux}
\label{Setting up Xilinx ISE}
To synthesize the FPGA firmware containing the WRPC, Xilinx ISE with free of
charge WebPack license is enough. ISE provides a set of scripts:
......@@ -192,7 +192,7 @@ $ /opt/Xilinx/<version>/ISE_DS/settings64.sh
You can check if the shell is configured correctly by verifying if the
\texttt{\$XILINX} variable contains path to your ISE installation directory.
\subsubsection{Setting up Quartus Prime}
\subsubsection{Setting up Quartus Prime on Linux}
\label{Setting up Quartus Prime}
To be able to synthesize the WRPC for Arria V FPGA (which is used on the VFC-HD
board) you need at least a license for the Quartus Prime Standard Edition with
......@@ -206,7 +206,7 @@ $ export PATH=/opt/altera/16.0/quartus/bin:$PATH
\subsubsection{Downloading the sources and running the synthesis}
Thanks to the \textit{hdlmake} tool, the synthesis process for the reference
designs does not differ between Xilinx and Intel based boards. The tool creates
designs does not differ between Xilinx and Altera/Intel based boards. The tool creates
synthesis Makefile as well as ISE/Quartus project file based on a set of
Manifest.py files that you will find in the \textit{wr-cores} repository.\\
......@@ -234,9 +234,9 @@ $ chmod a+x /usr/bin/hdlmake
\end{lstlisting}
Having all the tools in place, you can now clone the main WR PTP Core git
repository for the v4.0 release. The set of command below does that, checks out
the release tag, and downloads other HDL repositories (submodules) needed to
synthesize the core:
repository for the v4.0 release. The set of commands below clones the WR PTP Core
repository, checks out the release tag, and downloads other HDL repositories
(submodules) needed to synthesize the core:
\begin{lstlisting}
$ git clone git://ohwr.org/hdl-core-lib/wr-cores.git <your_location>/wr-cores
$ cd <your_location>/wr-cores
......@@ -331,7 +331,7 @@ $ export CROSS_COMPILE="<your_location>/lm32/bin/lm32-elf-"
To get the sources of the WRPC software, please clone the \textit{wrpc-sw} git
repository tagged with \texttt{wrpc-v4.0} tag. The commands in the listing below
do that together with submodules needed for this software.\\
clone the \textit{wrpc-sw} repository together with submodules needed for this software.\\
\begin{lstlisting}
$ git clone git://ohwr.org/hdl-core-lib/wr-cores/wrpc-sw.git \
<your_location>/wrpc-sw
......@@ -375,7 +375,7 @@ from the network.
The resulting binary \textit{wrc.bin} can be then used with the loader from
\textit{spec-sw} or \textit{svec-sw} software package to program the LM32 inside
the White Rabbit PTP Core (see section \ref{Programming FPGA} for details).
the White Rabbit PTP Core (see Appendix \ref{Programming FPGA} for details).
% ##########################################################################
\newpage
......@@ -392,7 +392,7 @@ in \textit{doc/} subdirectory of the \texttt{spec-sw} git repository.\\
First you need to clone the SPEC board software support package
(\textit{spec-sw}) from \textit{ohwr.org}. It is a set of Linux kernel drivers and
userspace tools, that interact with a SPEC board plugged into a PCI-Express
userspace tools, that interacts with a SPEC board plugged into a PCI-Express
slot.\\
\begin{lstlisting}
......@@ -504,7 +504,7 @@ First, you should perform a few configuration steps through the WRPC shell
before using the core.
\noindent\textbf{Note:} the examples below describe only a subset of the WRPC
Shell commands. The full list of supported commands can be found in appendix
Shell commands. The full list of supported commands can be found in Appendix
\ref{WRPC Shell commands}.\\
Before making any configuration changes, it is recommended to stop the
......@@ -520,7 +520,8 @@ assigned:
\begin{lstlisting}
wrc# mac get
\end{lstlisting}
If the result of above command is \texttt{MAC-address: 22:33:ww:xx:yy:zz}, this
If the result of above command is \texttt{MAC-address: 22:33:ww:xx:yy:zz} (where
ww, xx, yy, zz are hex values), this
means 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. This is
globally accepted as ``locally assigned'', but you might want to assign your own
......@@ -576,9 +577,9 @@ manually:
wrc# ptp start
\end{lstlisting}
\noindent\textbf{Note:} For running the GrandMaster mode, you need have
\texttt{g\_with\_external\_clock\_input} generic enabled in your FPGA firmware
and provide 1-PPS and 10MHz signal from an external source (e.g. GPS receiver or
\noindent\textbf{Note:} For running the GrandMaster mode, you need to have the
\texttt{g\_with\_external\_clock\_input} generic enabled in your FPGA firmware.
You also must provide 1-PPS and 10MHz signal from an external source (e.g. GPS receiver or
Cesium clock). Depending on your board you should connect:
\begin{itemize*}
\item \textbf{SPEC}: DIO mezzanine LEMO No.4 for 1-PPS, LEMO No.5 for 10MHz
......@@ -587,11 +588,11 @@ Cesium clock). Depending on your board you should connect:
\end{itemize*}
\vspace{1em}
One option is to type all the commands to initialize the WRPC software to
One option is to type by hand all the commands needed to initialize the 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
own initialization script and save it to the Flash/EEPROM. It will be executed every time
the WRPC software starts. A~simple script, that loads the calibration
parameters, configures the WR mode to Slave and starts the PTP daemon and sets
parameters, configures the WR mode to Slave, starts the PTP daemon and sets
the IP address is presented below:
\begin{lstlisting}
......@@ -655,16 +656,16 @@ WR synchronization status:
wrc# gui
\end{lstlisting}
The information is presented in a clear, auto-refreshing screen. The
information is refreshed at every WR iteration or periodically if
The information is presented in a clear, auto-refreshing screen (see the figure blow).
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 \texttt{refresh} command. To
exit from this console mode press <Esc>. A full description of the information
reporter by \textit{gui} is provied in appendix \ref{WRPC GUI elements}.
reporter by \textit{gui} is provided in Appendix \ref{WRPC GUI elements}.
\noindent\textbf{Note:} the \textit{Synchronization status} and \textit{Timing
parameters} in \texttt{gui} are available only in the WR Slave mode. When
running as WR Master, you would be able to see only the current date and time,
running as WR Master, you can see only the current date and time,
link status, Tx and Rx packet counters, IP, lock and calibration status.
\vspace{1em}
......@@ -693,7 +694,7 @@ issue shell commands while stats are running. You can stop statistics by running
alone, you can use ``\texttt{stat on}'' or ``\texttt{stat off}''.
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
are reported when the node is running in master and GrandMaster mode, nor when your node
is running as slave and the master disappeared.\\
You can verify the synchronization performance by observing the offset between
......@@ -718,7 +719,7 @@ of the \texttt{wrpc-sw} was to use serial console with tools like \textit{gui},
etc. For some set-ups, like standalone node, it is very inconvenient to use
external console for diagnostics.
From the version 4.0 of WRPC it is possible to include the \textit{Mini
Starting with version 4.0 of WRPC, it is possible to include the \textit{Mini
SNMP responder}, which allows to perform remote diagnostics using \textit{SNMP} via
a port connected to the \textit{Write Rabbit} network.
......@@ -838,7 +839,7 @@ When the SET support is compiled into the \textit{Mini SNMP responder}, it is
possible to erase or add/replace SFP entires to the SFPs database via SNMP.
\begin{sloppypar} % to prevent \texttt{} from going to the margine
Addition (or modification) of one SFP to the database can done by a row of
Addition (or modification) of one SFP to the database can be done by a row of
SNMP SETs. Firstly, please set the delta Tx (\texttt{wrpcPtpConfigDeltaTx.0}), the
delta Rx (\texttt{wrpcPtpConfigDeltaRx.0}) and the alpha (\texttt{wrpcPtpConfigAlpha.0})
with new values.
......@@ -858,7 +859,8 @@ then set \texttt{writeToMemoryCurrentSfp} to the \texttt{wrpcPtpConfigApply.0}
Please be aware that these changes will be lost after a power cycle of a board,
soft reset of WRPC or unplug/plug of a fiber/SFP.
Currently, after the update of SFP values in the memory, PTP is restarted.
In the current and previous versions of the WRPC after the update of SFP values in
the memory, PTP should be restarted.
Such restart is necessary because PTP does not support on-the-fly changes of
deltas nor alpha. It is expected that this behavior will change in the future.
......@@ -885,7 +887,7 @@ delta Rx "\texttt{2222}" and alpha "\texttt{3333}".
WR-WRPC-MIB::wrpcPtpConfigApply.0 = INTEGER: applySuccessful(100)
\end{lstlisting}
In case the SFP database does not contain the currently plugged SFP, the last
In case when the SFP database does not contain the currently plugged SFP, the last
\texttt{snmpset} command will return \texttt{applySuccessfulMatchFailed(101)}.
Optionally restart the PTP:
......@@ -955,14 +957,14 @@ To activate it, you must build with \texttt{CONFIG\_SYSLOG} and pass proper
parameters at run time.
To configure \textit{syslog} you can run the \texttt{syslog} shell command, which
receives two parameters (\texttt{ipaddr} and \texttt{macaddr}), or the
receives two parameters (\texttt{ipaddr} and \texttt{macaddr}), or a
single \texttt{off} subcommand.
When deploying a network of nodes, you can choose to put the \texttt{syslog
<ip> <mac>} command in the build-time init command. To this aim you
<ip> <mac>} command in the build-time init command. To do so, you
must activate \texttt{CONFIG\_BUILD\_INIT} and then pass your command string
as \texttt{CONFIG\_INIT\_COMMAND}. In that context, you can use ``\texttt{;}'' as
a command separator, as no newlines are permitted in \texttt{Kconfig}
a command separator as no newlines are permitted in \texttt{Kconfig}
strings.
The strings that a WR node sends to the \textit{syslog} server are always
......@@ -984,7 +986,7 @@ situations:
\textit{ Link up after link down } &
The message is ``\texttt{"Link up after} \textit{2.345} \texttt{s}''. The
time printed is the duration of the link-down interval just
time printed is the duration of the link-down interval that has just
passed -- no lost-by-design message is sent at link-down time. The
message is not sent the first time the link goes up, because
the boot message is already there.\\
......@@ -1005,13 +1007,14 @@ situations:
When the WR servo is in \textit{track phase} state after loosing
synchronization, the node sends ``\textit{45}\texttt{-th re-track after}
\textit{23.456} \texttt{s}''. The time reported is the amount of time
during which the node has not been synchronized. The seconth and
during which the node has not been synchronized since previous synchronization.
The seconth and
thirth re-sync are reported as \texttt{2-th} and \texttt{3-th}, to make you
smile. At the \texttt{4-th} you should stop smiling and be concerned.\\
& \\
\textit{ Temperature over threshold } &
The node monitors the various thermometers every few seconds.
The node monitors various thermometers every few seconds.
If \texttt{CONFIG\_TEMP\_POLL\_INTERVAL} and related parameters are
set, any over-temperature event is reported to \textit{syslog}.
If any temperature in the collected set is over threshold,
......@@ -1046,20 +1049,20 @@ are sent and received in the same \textit{vlans} as other CPU frames.
The \texttt{ltest} sender periodically sends three frames, with a sequence
number. One frames is at priority 7, one is at priority 6, and one is
at priority 0. The last frames reports the departure timestamps of the
at priority 0. The last frame reports the departure timestamps of the
previous frames. The \textit{ltest} receiver uses ingress timestamps to
measure latency and report lost frames.
Every node built with \texttt{CONFIG\_LATENCY\_PROBE} listens for frames
Every node that is built with \texttt{CONFIG\_LATENCY\_PROBE} listens for frames
belonging to \texttt{CONFIG\_LATENCY\_ETHTYPE}. A single node in the
network is expected to send \textit{ltest} frames; use the \texttt{ltest}
shell command to select how often to send an \textit{ltest} tuple of three
shell command to select how often to send the \textit{ltest} tuple of three
frames. To enable sending every second use ``\texttt{ltest 1}'', to enable
sending every 100ms use ``\texttt{ltest 0 100}'', to stop sending use
\texttt{ltest 0}.
In the sender node, a reminder is sent to the console very 10s
reporting the node is currently sending \textit{ltest} frames. All
reporting that the node is currently sending \textit{ltest} frames. All
non-sending nodes report every minute to \textit{syslog}. The
report message includes the number of samples received as well
as the minimum, average and maximum latency, in nanoseconds.
......@@ -1078,11 +1081,12 @@ When trying to diagnose software issues, especially lockup situations,
it may be useful to look at the current values or critical variables
within \textit{wrpc-sw}/\textit{ppsi}.
To this aim, you can pass a memory image of \textit{wrpc} to \texttt{tools/wrpc-dump}.
The tools will print information for softpll, ppsi data structures,
To this aim, you can pass a memory image (dump of RAM content) of \textit{wrpc} to
\texttt{tools/wrpc-dump}.
The tool will print information for softpll, ppsi data structures,
ptp data sets and version information.
For example, for a \textit{spec} device, you can use the resource file in
For example, for the \textit{spec} board, you can use the resource file in
\textit{sysfs} to look at a live system, or copy the file for off-line
analysis. The following command line show both uses:
......@@ -1096,13 +1100,13 @@ analysis. The following command line show both uses:
./tools/wrpc-dump wrpc-memory-image
\end{lstlisting}
The \textit{mapper} tool used above, and part of \textit{wrpc-sw}, reads a file
The \textit{mapper} tool used above, that is part of \textit{wrpc-sw}, reads a file
using \textit{mmap()}. The kernel doesn't allow plain \textit{read()} from a
resource file. If you encounter problem using \texttt{wrpc\_dump} directly,
please use \texttt{mapper} then \texttt{wrpc\_dump}.
\textbf{Note:} Data read by \texttt{mapper} may look like has wrong endianness comparing
to the file used for programming lm32 by \texttt{spec-cl}, but \texttt{spec-cl} is the
\textbf{Note:} Data read by \texttt{mapper} may look as if it has wrong endianness compared
to the file used for programming LM32 by \texttt{spec-cl}, but \texttt{spec-cl} is the
one which change the endianness of the binary data during the programming.
With \textit{etherbone}, you can get a snapshot for \textit{wrpc} memory using
......@@ -1122,9 +1126,7 @@ are readable dumps of the data structures, including the PTP timestamps.
To help understanding the CPU time spent in the \textit{softpll}, you can
set \texttt{CONFIG\_SPLL\_FIFO\_LOG} in the configuration. The option
depends on \texttt{CONFIG\_DEVELOPER} and is disabled by default, because
it costs half a kilobyte in binary size and Adam is scared about any size
increase.
depends on \texttt{CONFIG\_DEVELOPER} and is disabled by default.
When the configuration option is set, \texttt{wrpc-dump} will also show
information about the last 16 \textit{softpll} iterations. Both the \texttt{tstamp}
......@@ -1148,9 +1150,9 @@ and \texttt{duration} fields come from reading the \texttt{PPSG} nanosecond coun
at binary address 0xa0. It can be queried by \textit{etherbone}, or
seen in memory maps.
In addition to know how much as the node been up, it can be used to
In addition to knowing how much the node has been up, it can be used to
know roughly when a node got stuck, and whether software is still
running when a node is not active on the network. Neither of this even
running when a node is not active on the network. Neither of this events
happens in production, but the tool is useful during development.
% --------------------------------------------------------------------------
......@@ -1160,7 +1162,7 @@ happens in production, but the tool is useful during development.
The node now has a \textit{ps} command, that shows the number of iterations
and time spent in each \textit{task}. Each task reports when it did
something (as opposed to just polling the clock or network socket and
see nothing is there to do); the \textit{iterations} count shows how many
seeing that nothing is there to do); the \textit{iterations} count shows how many
times the task did something.
\begin{lstlisting}
......@@ -1232,7 +1234,7 @@ udp-based network services, in addition to \textit{ptp}:
The White Rabbit node can be configured to be vlan-aware, by setting
\texttt{CONFIG\_VLAN} in \textit{Kconfig}. The setting depends on \texttt{CONFIG\_DEVELOPER}.
If configured for \textit{vlan} support, the node select packet-filter rules
If configured for \textit{vlan} support, the node selects packet-filter rules
to receive frames in several \textit{vlan}s, all set at configuration time.
At run time you can use \texttt{vlan off} in the shell to turn off all \textit{vlan}
......@@ -1296,8 +1298,8 @@ Check if the oscilloscope cables you use have the same delays. If not, you
should either change the cables or take the delay difference into account in your
measurements. If that's not the case, please make sure you have the correct
calibration values loaded to both of your devices (see section \ref{Writing
configuration}). You made your own synthesis of the WRPC, and the default
calibration values are no longer valid, please read and perform the White Rabbit
configuration}). If you made your own synthesis of the WRPC, then the default
calibration values are no longer valid and you need to perform the White Rabbit
Calibration procedure\footnote{Use the latest version of the document available
at: \url{http://www.ohwr.org/documents/213}}.
......@@ -1348,7 +1350,7 @@ tools used to build and run it, you can write to our mailing list
\code{diag rw <reg\_no>} & reads register <reg\_no> from read-write bank.\\
\code{diag w <reg\_no>} & writes register <reg\_no> from read-write bank. \\
\code{diag w <reg\_no>} & writes register <reg\_no> to read-write bank. \\
\code{faketemp} & \\
\code{faketemp <T1> <T2> <T3>} & reads or sets the three fake temperatures,
......@@ -1423,8 +1425,8 @@ tools used to build and run it, you can write to our mailing list
\code{ps reset} & zeroes the profiling information reported by the \code{ps}
command \\
\code{ptp <e2e|p2p>} & select end-to-end PTP mechanism. If configured you can
set \texttt{p2p} mode, and \texttt{delay}/\texttt{pdelay} as aliases. \\
\code{ptp <e2e|p2p>} & selects PTP delay mechanism: end-to-end or peer-to-peer.
If configured, you can set \texttt{p2p} mode, and \texttt{delay}/\texttt{pdelay} as aliases. \\
\code{ptp gm|master|slave} & sets WRPC to operate as Grandmaster clock
(requires external 10MHz and 1-PPS reference), Master or Slave. After
......@@ -1581,17 +1583,17 @@ tools used to build and run it, you can write to our mailing list
\label{Writing SDBFS image in standalone configuration}
If you use SPEC board in a host-less environment, or you use custom
hardware and SPEC drivers and tools cannot be used, there is still a
hardware and SPEC drivers/tools cannot be used, there is still a
possibility of writing SDBFS through Xilinx JTAG.
\vspace{1em}
In case of SPEC running a reference bitstream provided with a stable
In the case when you want to run on the the SPEC a reference bitstream provided with a stable
WRPC release, you can simply program your Flash with \textit{spec\_top.mcs}
provided with the release binaries using for example Xilinx ISE Impact tool.
This \textit{mcs} file already includes both SDBFS image and FPGA bitstream.
In case of a custom gateware or hardware, you can download a standalone
SDBFS image:
In the case when you want to run a custom gateware or you have a custom hardware, you can
download a standalone SDBFS image:
\begin{lstlisting}
$ wget http://www.ohwr.org/attachments/download/4558/sdbfs-standalone-160812.bin
\end{lstlisting}
......@@ -1673,7 +1675,7 @@ The \textit{Mini SNMP responder} can be easily expanded to export new objects.
Values of new objects can come from WRPC's variables or other HDL modules
as long as there is a proper interface to the WRPC to read these values.
This section contains the instruction how to export new objects with
This section contains the instruction on how to export new objects with
the given variables' content.
The \textit{Mini SNMP responder} internally divides all OIDs into two parts.
......@@ -1746,7 +1748,7 @@ The macro \texttt{OID\_FIELD\_VAR} takes the following arguments:
\item \texttt{\&example\_i32var, \&example\_string} -- addresses to the data in
memory
\end{itemize*}
In case the address of variable is not known at boot, it is possible to define
In the case when the address of variable is not known at boot, it is possible to define
a pointer to the variable which will be initialized (e.g. in the \texttt{snmp\_init}
the function) at the boot time. In that case function \texttt{get\_pp} (\texttt{set\_pp}) has
to be used instead of \texttt{get\_p} (\texttt{set\_p}). For variables that are a part of
......@@ -1826,7 +1828,7 @@ depending of the test's result (not included in the example above).
Be aware that it might be necessary to clone the \texttt{bats} repo first.
\texttt{make} command will inform whether this is needed.
In case the number of OIDs changes please correct variable \texttt{TOTAL\_NUM\_OIDS}
In the case when the number of OIDs changes please correct variable \texttt{TOTAL\_NUM\_OIDS}
in file \texttt{snmp\_test\_config.bash}.
These tests have to be executed after any changes are made to the \textit{Mini SNMP
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment