doc: final changes to hdldoc part and minor corrections to main part

f1ce2b23 · Dimitris Lampridis · cd185f43 · f1ce2b23 · f1ce2b23 · f1ce2b23
Commit f1ce2b23 authored Mar 13, 2017 by Dimitris Lampridis
9 changed files
--- a/doc/HDLdoc/aux_clocks.tex
+++ b/doc/HDLdoc/aux_clocks.tex
 \subsubsection{Aux clocks}

-The WRPC can syntonize auxiliary clock signals to the White Rabbit timebase. It
-is done with a similar PLL that is used to discipline the local reference clock
-(section \ref{basic:clk_rst}). WRPC provides tuning values for the VCXO producing
-clock signal which is connected to \emph{clk\_aux\_i}.
+The WRPC can syntonize auxiliary clock signals to the White Rabbit timebase. It is done with a
+similar PLL that is used to discipline the local reference clock. WRPC provides tuning values for
+the VCXO producing clock signal which is connected to \emph{clk\_aux\_i}.
--- a/doc/HDLdoc/intro.tex
+++ b/doc/HDLdoc/intro.tex
 \section{Instantiating WRPC in your own HDL design}
+\label{sec:wrpc_hdl}
 This section describes the various options available to the users for instantiating and
 parametrising the WRPC in their designs.


--- a/doc/HDLdoc/wb.tex
+++ b/doc/HDLdoc/wb.tex
 \subsubsection{External Wishbone Slave/Master interface}
 \label{sec:wrpc_wb}

-{\bf Ext WB Slave} is a Wishbone slave interface (see the Wishbone bus specification~\cite{wb_spec}
-for more details). It controls the primary Wishbone Crossbar insisde the WRPC and thus provides
+{\bf Ext WB Slave} is a Wishbone slave interface\footnote{see the Wishbone bus specification (rev.B4)
+for more details}. It controls the primary Wishbone Crossbar insisde the WRPC and thus provides
 access to all the WRPC internals.

 In most designs, this slave interface should be connected to the host (if any), via an aprropriate

--- a/doc/HDLdoc/wrc_board.tex
+++ b/doc/HDLdoc/wrc_board.tex
@@ -185,7 +185,7 @@ their own BSP, can find the board-common module under:
    in order to provide access to all WB peripherals over Etherbone}\\
  \cline{1-3}
  \linebreak wb\_eth\_master\_i\linebreak & in & rec & \\
-  \hline
+  \hline\pagebreak
  \hdltablesection{Generic diagnostics interface}\\
  \hline
  \linebreak aux\_diag\_i\linebreak & in & var & \multirowpar{2}{Arrays of 32~bit vectors, to be
@@ -435,7 +435,7 @@ Section~\ref{sec:hdl_board_common_param} for a the list of common BSP parameters
  sfp\_scl\_o & out & 1 & \\
  \hline
  sfp\_rate\_select\_o & out & 1 & SFP rate select\\
-  \hline
+  \hline\pagebreak
  \hdltablesection{Physical UART interface}\\
  \hline
  uart\_rxd\_i & in  & 1 & UART RXD (serial data to WRPC)\\
@@ -482,6 +482,7 @@ Parameters and ports common to all BSPs are described in Section~\ref{sec:hdl_bo
  the 8bit PCS. Currently, 16bit PCS is not supported for Arria V.\\
 \end{hdlparamtable}

+\pagebreak
 \newparagraph{Ports}

 \begin{hdlporttable}

--- a/doc/HDLdoc/wrc_core.tex
+++ b/doc/HDLdoc/wrc_core.tex
@@ -20,9 +20,9 @@ Figure \ref{intro:fig:wrpc_top} is an example on how to instantiate the WRPC com
 Xilinx Spartan6-based project. It contains few additional modules besides the WRPC:
 \begin{itemize}
  \item \emph{wr\_gtp\_phy\_spartan6}: module wrapping Xilinx GTP SerDes to improve its determinism
-  \item \emph{PLL\_BASE}: Xilinx Spartan6 PLL primitive \cite{pll_base}, used to produce 62.5 MHz
-    system clock from 125 MHz local reference clock and to produce the DMTD offset clock from a
-    local 20 MHz oscillator
+  \item \emph{PLL\_BASE}: Xilinx Spartan6 PLL primitive\footnote{see also Xilinx Spartan-6 FPGA
+    Clocking Resources, User Guide}, used to produce 62.5 MHz system clock from 125 MHz local
+    reference clock and to produce the DMTD offset clock from a local 20 MHz oscillator
  \item \emph{spec\_serial\_dac\_arb}: converts DACs tuning values to serial interface and
    arbitrates access to two DACs used for reference and DMTD clock tuning.
 \end{itemize}

--- a/doc/HDLdoc/wrc_platform.tex
+++ b/doc/HDLdoc/wrc_platform.tex
@@ -14,6 +14,7 @@ supported FPGAs.

 This section describes the generic parameters and ports which are common to all provided PSPs.

+\newpage
 \newparagraph{Generic parameters}

 \begin{hdlparamtable}

--- a/doc/HDLdoc/wrc_ports.tex
+++ b/doc/HDLdoc/wrc_ports.tex
@@ -68,7 +68,7 @@
  \hline
  phy\_loopen\_o & out & 1 & \multirowpar{2}{local loopback enable (TX$\rightarrow$RX), active high}\\
  \cline{1-3}
-  phy\_loopen\_vec\_o & out & 3 \\
+  phy\_loopen\_vec\_o & out & 3 &\\
  \hline
  phy\_tx\_prbs\_sel\_o & out & 3 & PRBS select (see Xilinx UG386 Table 3-15; "000" = Standard operation, pattern generator off)\\
  \hline
@@ -113,7 +113,7 @@
  sfp\_scl\_o & out & 1 & \\
  \hline
  sfp\_det\_i & in & 1 & SFP presence indicator\\
-  \hline  
+  \hline\pagebreak
  btn1\_i & in & 1 & \multirowpar{2}{two microswitch inputs, active low, currently not
    used in official WRPC software}\\
  \cline{1-3}
@@ -199,7 +199,7 @@
    ports for the aux WB master interface (available in \tts{xwr\_core.vhd})}\\
  \cline{1-3}
  aux\_master\_i & in & rec & \\
-  \hline
+  \hline\pagebreak
  \hdltablesection{External fabric interface}\\
  \hline
  ext\_snk\_adr\_i & in & 2 & \multirowpar{9}{External fabric Wishbone
@@ -271,7 +271,7 @@
  \hline
  txtsu\_ack\_i & in & 1 & acknowledge, indicating that user-defined module
  has received the timestamp\\
-  \hline 
+  \hline\pagebreak
  \hdltablesection{Pause frame control}\\
  \hline
  fc\_tx\_pause\_req\_i   & in  &  1 & Ethernet flow control, request sending
@@ -326,5 +326,4 @@
    \tts{g\_diag\_rw\_size} elements}\\
  \cline{1-3}
  \linebreak aux\_diag\_o\linebreak & out & var & \\
-  \hline
 \end{hdlporttable}
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -6,7 +6,7 @@ all : wrpc.pdf

 .PHONY : all clean

-wrpc.pdf : wrpc.tex
+wrpc.pdf : wrpc.tex HDLdoc/*.tex
 	bash -c "echo '\\newcommand{\\gitrevinfo}{'$(RELEASE)'}' > version.tex"
 	pdflatex -dPDFSETTINGS=/prepress -dSubsetFonts=true -dEmbedAllFonts=true -dMaxSubsetPct=100 -dCompatibilityLevel=1.4 $^
 	pdflatex -dPDFSETTINGS=/prepress -dSubsetFonts=true -dEmbedAllFonts=true -dMaxSubsetPct=100 -dCompatibilityLevel=1.4 $^

--- a/doc/wrpc.tex
+++ b/doc/wrpc.tex
@@ -4,15 +4,10 @@
 \usepackage{pgf}
 \usepackage{tikz}
 \usepackage[pdftex]{hyperref}  % makes cross references and URLs clickable
-\newcommand{\code}[1]{\texttt{#1}}
 \usepackage[overload]{textcase}
 \usepackage{listings}
 \usepackage{color}
-\definecolor{light-gray}{gray}{0.95}
 \usepackage{textcomp}
-% set listings as in other WR-doc(s)
-\lstset{columns=flexible, upquote=true, frame=single,
-basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst:init_src}
 \usepackage{longtable} % table over many pages
 \usepackage[document]{ragged2e} %texta djustment
 \usepackage{mdwlist} % to have tight itemization
@@ -23,10 +18,23 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst
 \usepackage{colortbl}
 \usepackage{array}
 \usepackage{multirow}
+
 \newcommand{\newparagraph}[1]{\paragraph{#1}\mbox{}\\}

 \definecolor{wrlblue}{RGB}{165,195,210}
 \definecolor{wrlgray}{RGB}{209,211,212}
+\definecolor{light-gray}{gray}{0.95}
+
+\hypersetup{
+    colorlinks,
+    linkcolor={red!50!black},
+    citecolor={blue!50!black},
+    urlcolor={blue!80!black}
+}
+
+% set listings as in other WR-doc(s)
+\lstset{columns=flexible, upquote=true, frame=single,
+basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst:init_src}

 \newcommand{\multirowpar}[2]{
  \multirow{#1}{\hsize}{\parbox{\hsize}{\strut\raggedright#2\strut}}
@@ -40,10 +48,11 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst
 \newcolumntype{M}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}\ttsmall}m{#1}}
 \newcolumntype{C}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
 \newcolumntype{D}[1]{>{\centering\let\newline\\\arraybackslash\hspace{0pt}\ttsmall}m{#1}}
-  
+
+\let\underscore\_
+\renewcommand{\_}{\underscore\allowbreak}
+
 \newenvironment{hdlparamtable}{
-  \let\underscore\_
-  \renewcommand{\_}{\underscore\allowbreak}
  \setlength{\extrarowheight}{1pt}
  \begin{center}
    \begin{longtable}{|M{.2\textwidth}|C{.09\textwidth}|D{.11\textwidth}|L{.5\textwidth}|}
@@ -59,8 +68,6 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst
 }

 \newenvironment{hdlporttable}{
-  \let\underscore\_
-  \renewcommand{\_}{\underscore\allowbreak}
  \setlength{\extrarowheight}{1pt}
  \begin{center}
    \begin{longtable}{|M{.25\textwidth}|C{.05\textwidth}|D{.05\textwidth}|L{.55\textwidth}|}
@@ -78,6 +85,8 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst
 \def \wrpcrelease {for-tests}
 %\def \wrpcrelease {wrpc-v4.0}

+\newcommand{\code}[1]{\texttt{#1}}
+
 \newcommand{\tts}[1]{
  \texttt{\small{#1}}}

@@ -98,9 +107,9 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst
 \raggedright
 {\LARGE\bf\@title}\\[0.2 cm]
 \hrule height 4pt \vspace{0.1cm}
-\large\gitrevinfo\hfill\today\\
+{\large\gitrevinfo\hfill\today}\\
 \vspace*{\fill}
-\large\@author\\
+{\large\@author}\\
 \hrule height 2pt
 \justify
 \makeatother
@@ -111,23 +120,25 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst

 \newpage

-{\noindent \LARGE {\bf Introduction}}\\
+\section{Introduction}

+This is the user manual for the White Rabbit PTP Core (WRPC), part of the White
+Rabbit project. It describes the building and running process, and it provides a
+guide to instantiating the WRPC in your own HDL design.

-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 start with the demo binaries
+If you don't want to get your hands dirty and prefer to start with the demo binaries
 available at \url{http://www.ohwr.org/projects/wr-cores/files} for officially
-supported boards, please skip section \ref{Building the Core} and move forward
-directly to section \ref{Programming FPGA}.
+supported boards, please skip Section~\ref{Building the Core} and move forward
+directly to Section~\ref{Programming FPGA}. For help with instantiating the WRPC in
+your own HDL design, see Section~\ref{sec:wrpc_hdl}.


 % ##########################################################################
-\section{Software and hardware requirements}
+\subsection{Software and hardware requirements}
 \label{Software and hardware requirements}

 % ==========================================================================
-\subsection{Repositories and Releases}
+\subsubsection{Repositories and Releases}
 \label{Repositories and Releases}

 This manual is about the official \gitrevinfo{} stable release of the White
@@ -182,27 +193,22 @@ build the core and load it into the FPGA should be used in their newest stable
 releases, unless otherwise stated.

 % ==========================================================================
-\subsection{Required hardware}
+\subsubsection{Required hardware}
 \label{Required hardware}

 The minimum hardware set required to run the WR PTP Core reference firmware
 depends on the hardware platform you want to use. One of the following setups
 can be chosen:
 \begin{itemize}
-  \item {\bf SPEC} PCIe board\footnote{SPEC project page
-    \url{http://www.ohwr.org/projects/spec}} + FMC DIO
-    card\footnote{\label{note_dio}FMC DIO project page
-    \url{http://www.ohwr.org/projects/fmc-dio-5chttla}} + PC computer running
-    Linux
-
-  \item  {\bf SVEC} VME board\footnote{SVEC project page
-    \url{http://www.ohwr.org/projects/svec}} + VME crate with a single board
-    computer running Linux\footnote{\label{note_a20}In our test setup we used MEN A20 board}
-
-  \item {\bf VFC-HD} VME board\footnote{VFC-HD project page
-    \url{http://www.ohwr.org/projects/vfc-hd}} + FMC DIO card\footref{note_dio}
-    + VME crate with s single board computer running Linux\footref{note_a20}
-
+\item \href{http://www.ohwr.org/projects/spec}{SPEC PCIe board} +
+  \href{http://www.ohwr.org/projects/fmc-dio-5chttla}{FMC DIO card} + PC
+  computer running Linux
+\item \href{http://www.ohwr.org/projects/svec}{SVEC VME board} + VME crate with
+  a single board computer running Linux\footnote{\label{note_a20}In our test setup
+    we used MEN A20 board}
+\item \href{http://www.ohwr.org/projects/vfc-hd}{VFC-HD VME board} +
+  \href{http://www.ohwr.org/projects/fmc-dio-5chttla}{FMC DIO card} +
+  VME crate with a single board computer running Linux\footref{note_a20}
 \end{itemize}

 To be able to test White Rabbit synchronization you would also need
@@ -239,7 +245,7 @@ which contains a description of the software compilation process.

 Before running the synthesis process you have to make sure your environment is
 set up correctly. You will need a synthesis software from your FPGA vendor.
-Depending if you want to run the WRPC on Xilinx (e.g. SPEC, SVEC boards) or
+Depending on whether 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.

@@ -249,7 +255,7 @@ To synthesize the FPGA firmware containing the WRPC, Xilinx ISE with free of
 charge WebPack license is enough. ISE provides a set of scripts:
 \texttt{settings32.sh}, \texttt{settings32.csh}, \texttt{settings64.sh} and
 \texttt{settings64.csh} that configure all the system variables to let you
-easily run the software. Depending on a shell you use and whether your Linux is
+easily run the software. Depending on the 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 (assuming that ISE is installed
 in the default \textit{/opt} directory):
@@ -313,8 +319,9 @@ $ git submodule init
 $ git submodule update
 \end{lstlisting}

-The local copies of the submodules are stored to
-\texttt{<your\_location>/wr-cores/ip\_cores}.
+The local copies of the submodules are stored to:
+
+\texttt{<your\_location>/wr-cores/ip\_cores}

 \vspace{1em}
 \textbf{Note:} If you use the WRPC within another project (like