doc: merge 2 documents

5cf05621 · Grzegorz Daniluk · 646eb7e8 · 5cf05621 · 5cf05621 · 5cf05621
Commit 5cf05621 authored Mar 13, 2017 by Grzegorz Daniluk
26 changed files
--- a/doc/HDLdoc/aux_clocks.tex
+++ b/doc/HDLdoc/aux_clocks.tex
-\subsection{Aux clocks}
+\subsubsection{Aux clocks}
 \begin{figure}[ht]
  \begin{center}

--- a/doc/HDLdoc/aux_diag.tex
+++ b/doc/HDLdoc/aux_diag.tex
-\subsection{Auxiliary diagnostics interface}
+\subsubsection{Auxiliary diagnostics interface}
 \label{sec:aux_diag}
 Auxiliary diagnostics interface can be used if a user would like to benefit from

--- a/doc/HDLdoc/fabric.tex
+++ b/doc/HDLdoc/fabric.tex
-\subsection{Fabric interface}
+\subsubsection{Fabric interface}
 \label{sec:wrpc_fabric}
 %\begin{figure}[ht]
@@ -117,7 +117,7 @@ WRPC and user-defined module doesn't care about it. The Ethernet frame received
 from the WR Fabric interface may contain additional OOB data suffixed. It has to
 be received (acknowledged) by the user-defined module, but can be simply discarded.
-\subsubsection{Examples}
+\newparagraph{Examples}
 Figure \ref{fig:fabric:simple_tx} shows a very simple WR Fabric cycle. The WRF
 Source of user-defined module sends there an Ethernet frame containing even
 number of bytes.
@@ -207,7 +207,7 @@ immediately break the cycle. This situation is presented in figure
    from the WRF Sink.
 \end{enumerate}
-\subsubsection{SystemVerilog model}
+\newparagraph{SystemVerilog model}
 The SystemVerilog simulation model of the WR Fabric interface (both WRF Source and 
 WRF Sink) can be found in the \emph{wr-cores} git repository
 (git://ohwr.org/hdl-core-lib/wr-cores.git) and consists of the files:

--- a/doc/HDLdoc/intro.tex
+++ b/doc/HDLdoc/intro.tex
-\section{Introduction}
+\section{Instantiating WRPC in your own HDL design}
 This section describes the various options available to the users for instantiating and
 parametrising the WRPC in their designs.
-\begin{figure}
+\begin{figure}[ht]
  \begin{center}
    \includegraphics[width=.6\textwidth]{fig/wrpc_board.pdf}
-    \label{fig:wrpc_board}
    \caption{WRPC HDL abstraction hierarchy}
+    \label{fig:wrpc_board}
  \end{center}
 \end{figure}

--- a/doc/HDLdoc/periph.tex
+++ b/doc/HDLdoc/periph.tex
-\subsection{GPIO/UART/I2C/1-Wire/SPI interfaces}
+\subsubsection{GPIO/UART/I2C/1-Wire/SPI interfaces}
 \label{sec:wrpc_periph}
 %\begin{figure}[ht]

--- a/doc/HDLdoc/phyif.tex
+++ b/doc/HDLdoc/phyif.tex
-\subsection{PHY interface}
+\subsubsection{PHY interface}
 %\begin{figure}[ht]
 %  \begin{center}

--- a/doc/HDLdoc/timecode.tex
+++ b/doc/HDLdoc/timecode.tex
-\subsection{Timecode interface}
+\subsubsection{Timecode interface}
 \label{sec:wrpc_timecode}
 %\begin{figure}[ht]

--- a/doc/HDLdoc/txts.tex
+++ b/doc/HDLdoc/txts.tex
-\subsection{Tx Timestamping interface}
+\subsubsection{Tx Timestamping interface}
 \label{sec:txts}
 %\begin{figure}[ht]

--- a/doc/HDLdoc/wb.tex
+++ b/doc/HDLdoc/wb.tex
-\subsection{External Wishbone Slave/Master interface}
+\subsubsection{External Wishbone Slave/Master interface}
 \label{sec:wrpc_wb}
 %\begin{figure}[ht]

--- a/doc/HDLdoc/wrc_board.tex
+++ b/doc/HDLdoc/wrc_board.tex
-\section{Board Support Packages}
+\subsection{Board Support Packages}
 \label{sec:hdl_board}
 The White Rabbit (WR) PTP core project provides board support packages (BSPs) for the following
@@ -28,7 +28,7 @@ Section~\ref{sec:hdl_platform}). For users who need more control and flexibility
 it is suggested to use the BSP as a reference, and to consider instantiating directly the respective
 PSP for their FPGA family.
-\subsection{Common}
+\subsubsection{Common}
 \label{sec:hdl_board_common}
 Most of the generic parameters and ports of the board-common module map directly to those of the
@@ -56,7 +56,7 @@ tables short and to the point. Users interested in studying the board-common mod
 their own BSP, can find the board-common module under:
 \\\hrefwrpc{board/common/xwrc\_board\_common.vhd}
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 \label{sec:hdl_board_common_param}
 \begin{hdlparamtable}
@@ -86,7 +86,7 @@ their own BSP, can find the board-common module under:
  fabric interface of WRPC \tts{[PLAIN/STREAMERS/ETHERBONE]}\\
 \end{hdlparamtable}
-\subsubsection{Ports}
+\newparagraph{Ports}
 \label{sec:hdl_board_common_ports}
 \begin{hdlporttable}
@@ -260,7 +260,7 @@ their own BSP, can find the board-common module under:
  link\_ok\_o & out & 1 & Link status indicator\\
 \end{hdlporttable}
-\subsection{SPEC}
+\subsubsection{SPEC}
 \label{sec:hdl_board_spec}
 The SPEC BSP provides a ready-to-use WRPC wrapper for the
@@ -281,13 +281,13 @@ An example (VHDL) instantiation of this module can be found in the SPEC WRPC ref
 This section describes the generic parameters and ports which are specific to the SPEC BSP.
 Parameters and ports common to all BSPs are described in Section~\ref{sec:hdl_board_common}.
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 No additional generic parameters are declared in the SPEC BSP. See
 Section~\ref{sec:hdl_board_common_param} for a the list of common BSP parameters.
-\subsubsection{Ports}
+\newparagraph{Ports}
 \begin{hdlporttable}
  \hdltablesection{Clocks and resets}\\
@@ -355,7 +355,7 @@ Section~\ref{sec:hdl_board_common_param} for a the list of common BSP parameters
  flash\_miso\_i & in  & 1 & Flash SPI MISO\\
 \end{hdlporttable}
-\subsection{SVEC}
+\subsubsection{SVEC}
 \label{sec:hdl_board_svec}
 The SVEC BSP provides a ready-to-use WRPC wrapper for the
@@ -376,12 +376,12 @@ An example (VHDL) instantiation of this module can be found in the SVEC WRPC ref
 This section describes the generic parameters and ports which are specific to the SVEC BSP.
 Parameters and ports common to all BSPs are described in Section~\ref{sec:hdl_board_common}.
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 No additional generic parameters are declared in the SVEC BSP. See
 Section~\ref{sec:hdl_board_common_param} for a the list of common BSP parameters.
-\subsubsection{Ports}
+\newparagraph{Ports}
 \begin{hdlporttable}
  \hdltablesection{Clocks and resets}\\
@@ -453,7 +453,7 @@ Section~\ref{sec:hdl_board_common_param} for a the list of common BSP parameters
  spi\_miso\_i & in  & 1 & Flash SPI MISO\\
 \end{hdlporttable}
-\subsection{VFC-HD}
+\subsubsection{VFC-HD}
 \label{sec:hdl_board_vfchd}
 The VFC-HD BSP provides a ready-to-use WRPC wrapper for the
@@ -474,7 +474,7 @@ An example (VHDL) instantiation of this module can be found in the VFC-HD WRPC r
 This section describes the generic parameters and ports which are specific to the VFC-HD BSP.
 Parameters and ports common to all BSPs are described in Section~\ref{sec:hdl_board_common}.
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 \begin{hdlparamtable}
  g\_pcs16\_bit & boolean & false & Altera Arria V FPGAs provide the possibility
@@ -482,7 +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}
-\subsubsection{Ports}
+\newparagraph{Ports}
 \begin{hdlporttable}
  \hdltablesection{Clocks and resets}\\

--- a/doc/HDLdoc/wrc_core.tex
+++ b/doc/HDLdoc/wrc_core.tex
-\section{WR Core}
+\subsection{WR PTP Core component}
 \label{sec:hdl_wrpc}
 This section describes the input and output ports of the WRPC IP-core and VHDL generic parameters
 that can be used to personalize the core.
@@ -11,8 +11,8 @@ ports can be found under:\\\hrefwrpc{modules/wrc\_core/xwr\_core.vhd}
 \begin{figure}
  \begin{center}
    \includegraphics[width=.9\textheight, angle=270]{fig/basic_top.pdf}
-    \label{intro:fig:wrpc_top}
    \caption{Simple top design with WRPC}
+    \label{intro:fig:wrpc_top}
  \end{center}
 \end{figure}
@@ -31,12 +31,12 @@ A very similar example can be found in the WRPC reference design for PCI-Express
 Section~\ref{sec:hdl_board_spec}).
-\input{wrc_generics.tex}
+\input{HDLdoc/wrc_generics.tex}
-\input{wrc_ports.tex}
+\input{HDLdoc/wrc_ports.tex}
-\input{phyif.tex}
+\input{HDLdoc/phyif.tex}
-\input{periph.tex}
+\input{HDLdoc/periph.tex}
-\input{wb.tex}
+\input{HDLdoc/wb.tex}
-\input{fabric.tex}
+\input{HDLdoc/fabric.tex}
-\input{txts.tex}
+\input{HDLdoc/txts.tex}
-\input{timecode.tex}
+\input{HDLdoc/timecode.tex}
-\input{aux_diag.tex}
+\input{HDLdoc/aux_diag.tex}
--- a/doc/HDLdoc/wrc_generics.tex
+++ b/doc/HDLdoc/wrc_generics.tex
-\subsection{Generic parameters}
+\subsubsection{Generic parameters}
 \label{sec:wrc_generics}
 \begin{hdlparamtable}

--- a/doc/HDLdoc/wrc_platform.tex
+++ b/doc/HDLdoc/wrc_platform.tex
-\section{Platform Support Packages}
+\subsection{Platform Support Packages}
 \label{sec:hdl_platform}
 The White Rabbit (WR) PTP core project provides platform support packages (PSPs) for Altera and
@@ -9,12 +9,12 @@ components for the WR PTP core (PHY, PLLs, etc.) in one go, without having to de
 implementation details, using a setup that has been tested and is known to work well on the
 supported FPGAs.
-\subsection{Common}
+\subsubsection{Common}
 \label{sec:hdl_platform_common}
 This section describes the generic parameters and ports which are common to all provided PSPs.
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 \begin{hdlparamtable}
  g\_with\_external\_clock\_input & boolean & false & Select whether to
@@ -43,7 +43,7 @@ these parameters.
  and also multiplied to 125MHz.
 \end{description}
-\subsubsection{Ports}
+\newparagraph{Ports}
 \begin{hdlporttable}
  areset\_n\_i & in & 1 & asynchronous reset (active low)\\
@@ -123,7 +123,7 @@ these parameters.
  ext\_ref\_rst\_i & in & 1 & \\
 \end{hdlporttable}
-\subsection{Altera}
+\subsubsection{Altera}
 \label{sec:hdl_platform_altera}
 The Altera PSP currently supports the Arria V family of FPGAs.
@@ -139,7 +139,7 @@ also Section~\ref{sec:hdl_board_vfchd}):\\\hrefwrpc{board/vfchd/xwrc\_board\_vfc
 This section describes the generic parameters and ports which are specific to the Altera
 PSP. Parameters and ports common to all PSPs are described in Section~\ref{sec:hdl_platform_common}.
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 \begin{hdlparamtable}
  g\_fpga\_family & string & arria5 & Defines the family/model of Altera
@@ -150,7 +150,7 @@ PSP. Parameters and ports common to all PSPs are described in Section~\ref{sec:h
  but this generic can be used to override it\\
 \end{hdlparamtable}
-\subsubsection{Ports}
+\newparagraph{Ports}
 \begin{hdlporttable}
  \hdltablesection{Interface with SFP}\\
@@ -162,7 +162,7 @@ PSP. Parameters and ports common to all PSPs are described in Section~\ref{sec:h
  \linebreak sfp\_rx\_i\linebreak & in & 1 &\\
 \end{hdlporttable}
-\subsection{Xilinx}
+\subsubsection{Xilinx}
 \label{sec:hdl_platform_xilinx}
 The Xilinx PSP currently supports the Spartan 6 family of FPGAs.
@@ -182,7 +182,7 @@ This section describes the generic parameters and ports which are
 specific to the Xilinx PSP. Parameters and ports common to all PSPs
 are described in Section~\ref{sec:hdl_platform_common}.
-\subsubsection{Generic parameters}
+\newparagraph{Generic parameters}
 \begin{hdlparamtable}
  g\_fpga\_family & string & spartan6 & Defines the family/model of Xilinx
@@ -192,7 +192,7 @@ are described in Section~\ref{sec:hdl_platform_common}.
  be set to '0' for synthesis\\
 \end{hdlparamtable}
-\subsubsection{Ports}
+\newparagraph{Ports}
 \begin{hdlporttable}
  clk\_125m\_gtp\_p\_i & in & 1 & \multirowpar{2}{125MHz GTP

--- a/doc/HDLdoc/wrc_ports.tex
+++ b/doc/HDLdoc/wrc_ports.tex
-\subsection{Ports}
+\subsubsection{Ports}
 \label{sec:wrc_ports}
 %\begin{figure}[ht]

--- a/doc/HDLdoc/fig/basic_top.pdf
+++ b/doc/HDLdoc/fig/basic_top.pdf
--- a/doc/HDLdoc/fig/basic_wrf_cycle.pdf
+++ b/doc/HDLdoc/fig/basic_wrf_cycle.pdf
--- a/doc/HDLdoc/fig/basic_wrf_cycle_err.pdf
+++ b/doc/HDLdoc/fig/basic_wrf_cycle_err.pdf
--- a/doc/HDLdoc/fig/basic_wrf_cycle_sel.pdf
+++ b/doc/HDLdoc/fig/basic_wrf_cycle_sel.pdf
--- a/doc/HDLdoc/fig/basic_wrf_cycle_simple.pdf
+++ b/doc/HDLdoc/fig/basic_wrf_cycle_simple.pdf
--- a/doc/HDLdoc/fig/basic_wrf_data.pdf
+++ b/doc/HDLdoc/fig/basic_wrf_data.pdf
--- a/doc/HDLdoc/fig/oob_rx.pdf
+++ b/doc/HDLdoc/fig/oob_rx.pdf
--- a/doc/HDLdoc/fig/oob_tx.pdf
+++ b/doc/HDLdoc/fig/oob_tx.pdf
--- a/doc/HDLdoc/fig/status.pdf
+++ b/doc/HDLdoc/fig/status.pdf
--- a/doc/HDLdoc/fig/wrpc_board.pdf
+++ b/doc/HDLdoc/fig/wrpc_board.pdf
--- a/doc/HDLdoc/fig/wrpc_board.svg
+++ b/doc/HDLdoc/fig/wrpc_board.svg
--- a/doc/wrpc.tex
+++ b/doc/wrpc.tex
@@ -19,6 +19,73 @@ basicstyle=\footnotesize\ttfamily, backgroundcolor=\color{light-gray}, label=lst
 \usepackage[T1]{fontenc}
 \usepackage{lmodern}
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+\usepackage{graphicx}
+\usepackage{colortbl}
+\usepackage{array}
+\usepackage{multirow}
+\newcommand{\newparagraph}[1]{\paragraph{#1}\mbox{}\\}
+\definecolor{wrlblue}{RGB}{165,195,210}
+\definecolor{wrlgray}{RGB}{209,211,212}
+\newcommand{\multirowpar}[2]{
+  \multirow{#1}{\hsize}{\parbox{\hsize}{\strut\raggedright#2\strut}}
+}
+\newcommand{\hdltablesection}[1]{
+  \multicolumn{4}{|c|}{\bf\small#1}
+}
+\newcolumntype{L}[1]{>{\raggedright\let\newline\\\arraybackslash\hspace{0pt}}m{#1}}
+\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}}
+\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}|}
+      \firsthline
+      \rowcolor{wrlblue}
+      \bf{name} & \bf{type} & \bf{default} & \bf{description}\\
+      \hline
+      \endhead
+}{
+  \lasthline
+    \end{longtable}
+  \end{center}
+}
+\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}|}
+      \firsthline
+      \rowcolor{wrlblue}
+      \bf{name} & \bf{dir} & \bf{size} & \bf{description}\\
+      \hline
+      \endhead
+}{
+  \lasthline
+    \end{longtable}
+  \end{center}
+}
+\def \wrpcrelease {for-tests}
+%\def \wrpcrelease {wrpc-v4.0}
+\newcommand{\tts}[1]{
+  \texttt{\small{#1}}}
+% same as \tts{}, without argument
+\newcommand{\ttsmall}{\ttfamily\small}
+\newcommand{\hrefwrpc}[1]{
+  \tts{\href{http://www.ohwr.org/projects/wr-cores/repository/entry/#1?rev=\wrpcrelease}{#1}}}
 \begin{document}
 \input{version.tex}
@@ -1286,6 +1353,14 @@ processed by the WRPC, class 6 is used for Streamers traffic, class 7 is used
 for Etherbone traffic (see HDL documentation for boards HDL modules and
 selection between Streamers, Etherbone and Plain modes).
+% ##########################################################################
+\newpage
+\input{HDLdoc/intro}
+\input{HDLdoc/wrc_core}
+\input{HDLdoc/wrc_platform}
+\input{HDLdoc/wrc_board}
 % ##########################################################################
 \newpage
 \section{Troubleshooting}