[doc] doc reviewed, small corrections

88ad061a · Maciej Lipinski · caac1e16 · 88ad061a
Commit 88ad061a authored Mar 03, 2017 by Maciej Lipinski
Show whitespace changes
Inline Side-by-side

Showing with 70 additions and 68 deletions

wrpc.tex doc/wrpc.tex +70 -68

No files found.
--- a/doc/wrpc.tex
+++ b/doc/wrpc.tex
@@ -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
+  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
+  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
+  \item another WR node (e.g. one of the reference boards listed above) or a
-    White Rabbit Switch)
+    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
+repository for the v4.0 release. The set of commands below clones the WR PTP Core 
-the release tag, and downloads other HDL repositories (submodules) needed to
+repository, checks out the release tag, and downloads other HDL repositories 
-synthesize the core:
+(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
+\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
+\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
+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
+The information is presented in a clear, auto-refreshing screen (see the figure blow). 
-information is refreshed at every WR iteration or periodically if
+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}.
+To this aim, you can pass a memory image (dump of RAM content) of \textit{wrpc} to 
-The tools will print information for softpll, ppsi data structures,
+\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
+\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
+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
+depends on \texttt{CONFIG\_DEVELOPER} and is disabled by default.
-it costs half a kilobyte in binary size and Adam is scared about any size
-increase.
 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
+configuration}). If you made your own synthesis of the WRPC, then the default
-calibration values are no longer valid, please read and perform the White Rabbit
+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
+  \code{ptp <e2e|p2p>} & selects PTP delay mechanism: end-to-end or peer-to-peer.
-    set \texttt{p2p} mode, and \texttt{delay}/\texttt{pdelay} as aliases. \\
+    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
+In the case when you want to run a custom gateware or you have a custom hardware, you can 
-SDBFS image:
+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