fm-doc: Some corrections and rewording in the HDL guide

9bc70502 · Theodor-Adrian Stana · 62b0b0d2 · 9bc70502 · 9bc70502 · 9bc70502
Commit 9bc70502 authored Dec 12, 2014 by Theodor-Adrian Stana
5 changed files
--- a/fm/doc/hdlg/clk_info.tex
+++ b/fm/doc/hdlg/clk_info.tex
@@ -27,7 +27,7 @@ Base address (20-MHz counter): 0x120
 \end{longtable}
 }
-\subsubsection{CNTFULLR}
+\subsubsection{CNTFULLR -- Counter full register}
 \label{app:clk-info-cntfullr}
 \vspace{11pt}
@@ -141,7 +141,7 @@ CNTVAL
 \end{small}
 \end{itemize}
-\subsubsection{CNTRSTR}
+\subsubsection{CNTRSTR -- Counter reset register}
 \label{app:clk-info-cntrstr}
 \vspace{11pt}
@@ -180,7 +180,7 @@ CNTRST
 \end{small}
 \end{itemize}
-\subsubsection{CNTENR}
+\subsubsection{CNTENR -- Counter enable register}
 \label{app:clk-info-cntenr}
 \vspace{11pt}

--- a/fm/doc/hdlg/fig/dac-test.svg
+++ b/fm/doc/hdlg/fig/dac-test.svg
@@ -13,7 +13,7 @@
   height="333.5"
   id="svg2"
   version="1.1"
-   inkscape:version="0.48.3.1 r9886"
+   inkscape:version="0.48.4 r9939"
   sodipodi:docname="dac-test.svg">
  <defs
     id="defs4">
@@ -54,13 +54,13 @@
     inkscape:pageopacity="0.0"
     inkscape:pageshadow="2"
     inkscape:zoom="1.979899"
-     inkscape:cx="315.90671"
+     inkscape:cx="331.65292"
-     inkscape:cy="78.651532"
+     inkscape:cy="127.40197"
     inkscape:document-units="px"
     inkscape:current-layer="layer1"
     showgrid="true"
-     inkscape:window-width="1855"
+     inkscape:window-width="1535"
-     inkscape:window-height="1176"
+     inkscape:window-height="876"
     inkscape:window-x="65"
     inkscape:window-y="24"
     inkscape:window-maximized="1"
@@ -98,8 +98,8 @@
     id="layer1"
     transform="translate(12.068966,-30.862183)">
    <path
-       style="opacity:0.2;fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
+       style="opacity:0.5;fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;stroke-dashoffset:0"
-       d="m 465,207.36218 -265,0 0,75 175,0"
+       d="m 465,207.36218 -265,0 0,75 210,0"
       id="path4482"
       inkscape:connector-curvature="0"
       sodipodi:nodetypes="cccc" />
@@ -386,13 +386,13 @@
       height="50"
       x="380"
       y="122.36218"
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-opacity:1" />
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-opacity:1" />
    <text
       sodipodi:linespacing="125%"
       id="text4072"
       y="152.36218"
       x="420"
-       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.3;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.45;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
       xml:space="preserve"><tspan
         style="font-size:16px;font-weight:normal;text-align:center;text-anchor:middle"
         y="152.36218"
@@ -400,7 +400,7 @@
         sodipodi:role="line"
         id="tspan4074">DAC</tspan></text>
    <rect
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-opacity:1"
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-opacity:1"
       y="52.362183"
       x="380"
       height="50"
@@ -408,7 +408,7 @@
       id="rect4076" />
    <text
       xml:space="preserve"
-       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.3;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.45;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
       x="420"
       y="72.362183"
       id="text4078"
@@ -468,7 +468,7 @@
         id="tspan4462"
         sodipodi:role="line">SPI</tspan></text>
    <rect
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-opacity:1"
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-opacity:1"
       y="292.36218"
       x="380"
       height="50"
@@ -476,7 +476,7 @@
       id="rect4464" />
    <text
       xml:space="preserve"
-       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.3;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.45;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
       x="420"
       y="322.36218"
       id="text4466"
@@ -492,13 +492,13 @@
       height="50"
       x="380"
       y="222.36218"
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-opacity:1" />
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-opacity:1" />
    <text
       sodipodi:linespacing="125%"
       id="text4472"
       y="242.36218"
       x="420"
-       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.3;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.45;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
       xml:space="preserve"><tspan
         style="font-size:16px;font-weight:normal;text-align:center;text-anchor:middle"
         y="242.36218"
@@ -527,7 +527,7 @@
       d="m 13.60742,57.279011 c 0,0.552285 -0.447715,1 -1,1 -0.552285,0 -1,-0.447715 -1,-1 0,-0.552285 0.447715,-1 1,-1 0.552285,0 1,0.447715 1,1 z"
       transform="matrix(2.9999989,0,0,2.9999989,302.17775,75.525219)" />
    <path
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#TriangleOutM)"
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#TriangleOutM)"
       d="m 420,117.36218 0,-10"
       id="path4484"
       inkscape:connector-curvature="0" />
@@ -535,16 +535,16 @@
       inkscape:connector-curvature="0"
       id="path4670"
       d="m 420,287.36218 0,-10"
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#TriangleOutM)" />
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-width:1px;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;marker-end:url(#TriangleOutM)" />
    <rect
-       style="opacity:0.3;fill:#e5e5e5;fill-opacity:1;fill-rule:evenodd;stroke:none"
+       style="opacity:0.45;fill:#e5e5e5;fill-opacity:1;fill-rule:evenodd;stroke:none"
       id="rect3063"
       width="32.068962"
       height="330"
       x="-12.068966"
       y="32.362183" />
    <path
-       style="opacity:0.3;fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
+       style="opacity:0.45;fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
       d="m 14.523438,1.5 0,330"
       id="path3845"
       inkscape:connector-curvature="0"
@@ -555,7 +555,7 @@
       id="text3851"
       y="10"
       x="-191.60437"
-       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.3;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+       style="font-size:40px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;opacity:0.45;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
       xml:space="preserve"
       transform="matrix(0,-1,1,0,0,0)"><tspan
         style="font-size:16px;font-weight:bold;text-align:center;writing-mode:lr-tb;text-anchor:middle"
@@ -563,5 +563,11 @@
         x="-191.60437"
         sodipodi:role="line"
         id="tspan3853">Wishbone crossbar</tspan></text>
+    <path
+       style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;opacity:0.45;stroke-miterlimit:4;stroke-dasharray:none"
+       d="m 442.06897,251.5 35,0"
+       id="path3837"
+       inkscape:connector-curvature="0"
+       transform="translate(-12.068966,30.862183)" />
  </g>
 </svg>
--- a/fm/doc/hdlg/fig/ttl-test.svg
+++ b/fm/doc/hdlg/fig/ttl-test.svg
@@ -13,7 +13,7 @@
   height="247.5"
   id="svg2"
   version="1.1"
-   inkscape:version="0.48.3.1 r9886"
+   inkscape:version="0.48.4 r9939"
   sodipodi:docname="ttl-test.svg">
  <defs
     id="defs4">
@@ -40,22 +40,24 @@
     inkscape:pageopacity="0.0"
     inkscape:pageshadow="2"
     inkscape:zoom="1.4"
-     inkscape:cx="278.9082"
+     inkscape:cx="361.54081"
-     inkscape:cy="165.30729"
+     inkscape:cy="129.5335"
     inkscape:document-units="px"
     inkscape:current-layer="layer1"
     showgrid="true"
     showguides="true"
     inkscape:guide-bbox="true"
-     inkscape:window-width="1855"
+     inkscape:window-width="1535"
-     inkscape:window-height="1176"
+     inkscape:window-height="876"
     inkscape:window-x="65"
     inkscape:window-y="24"
     inkscape:window-maximized="1"
     fit-margin-top="0"
     fit-margin-left="0"
     fit-margin-right="0"
-     fit-margin-bottom="0">
+     fit-margin-bottom="0"
+     inkscape:snap-bbox="false"
+     inkscape:object-nodes="true">
    <inkscape:grid
       type="xygrid"
       id="grid2985"
@@ -74,7 +76,7 @@
        <dc:format>image/svg+xml</dc:format>
        <dc:type
           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
-        <dc:title></dc:title>
+        <dc:title />
      </cc:Work>
    </rdf:RDF>
  </metadata>
@@ -89,12 +91,6 @@
       id="path6616"
       inkscape:connector-curvature="0"
       sodipodi:nodetypes="cc" />
-    <path
-       style="opacity:0.2;fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:10, 5;stroke-dashoffset:15.25"
-       d="M 180,282.36218 180,52.362186"
-       id="path6570"
-       inkscape:connector-curvature="0"
-       sodipodi:nodetypes="cc" />
    <path
       style="fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none"
       d="m 90,82.362183 530,0"
@@ -991,5 +987,11 @@
       id="path6652"
       inkscape:connector-curvature="0"
       transform="translate(69.457031,36.112183)" />
+    <path
+       style="opacity:0.2;fill:none;stroke:#000000;stroke-width:2.5;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:10, 5;stroke-dashoffset:15.25"
+       d="M 180,282.36218 180,37.362187"
+       id="path3130"
+       inkscape:connector-curvature="0"
+       sodipodi:nodetypes="cc" />
  </g>
 </svg>
--- a/fm/doc/hdlg/hdlg-pts-conv-ttl-blo.tex
+++ b/fm/doc/hdlg/hdlg-pts-conv-ttl-blo.tex
@@ -2,7 +2,13 @@
 % Document header
 %==============================================================================
 \documentclass[a4paper,11pt]{article}
-\usepackage[pdfborder= 0 0 0 1]{hyperref}
+\usepackage[
+  colorlinks = true,
+  linkcolor  = black,
+  citecolor  = black,
+  urlcolor   = blue,
+]{hyperref}
 \usepackage{graphicx}
 \usepackage{multirow}
 \usepackage{longtable}
@@ -77,6 +83,7 @@ work, see \\
 \pdfbookmark[1]{\contentsname}{toc}
 \tableofcontents
+\pagebreak
 \listoffigures
 \listoftables
@@ -101,7 +108,7 @@ work, see \\
 \section{Introduction}
 \label{sec:intro}
 Production Test Suite (PTS) is the environment designed for running functionality tests
-on boards at the manufacturing site right after production. It assures that boards comply
+on boards at the manufacturing site, right after production. It assures that boards comply
 with a minimum set of quality rules in terms of soldering, mounting and PCB fabrication
 process.
@@ -130,7 +137,8 @@ the PTS gateware, which can be obtained by cloning the git repository for the PT
 The PTS system (Figure~\ref{fig:pts-sys}) is contained within a rack containing an ELMA
 crate, the laptop with the PTS software installed on it and all other accessories necessary
-for running tests. More information about the PTS system can be found in \cite{pts-userguide}.
+for running tests. More information about the PTS system can be found in the PTS user
+guide~\cite{pts-userguide}.
 \begin{figure}[h]
  \centerline{\includegraphics[width=.9\textwidth]{fig/pts-sys}}
@@ -139,10 +147,10 @@ for running tests. More information about the PTS system can be found in \cite{p
 \end{figure}
 The ELMA crate within the PTS contains a system monitor (SysMon) board that monitors
-voltage levels, temperatures and controls fan speeds for the crate fans. The crate
+voltage levels, temperatures and controls fan speeds for the crate fans. The SysMon
 can be accessed via Telnet to send commands to the VME boards inside the crate.
-Using these commands, the CONV-TTL-BLO board can be accessed through the serial
+Using such commands, the CONV-TTL-BLO board can be accessed through the serial
 (I$^2$C) interface on the VME P1 connector. The PTS software on the PTS laptop connects
 to the crate through Telnet and sends \textit{readreg} and \textit{writereg}
 commands to the crate; the commands are translated by the SysMon to I$^2$C transfers
@@ -160,7 +168,8 @@ on a computer writes and reads registers implemented in the PTS gateware running
 on-board FPGA. As described in the following sections, writing and reading to specific registers
 in the gateware result in the running of the steps necessary to test a CONV-TTL-BLO device under test.
-For a complete reference of the registers accessible in the PTS gateware, see Appendix~\ref{app:memmap}.
+For a complete reference of the registers accessible in the PTS gateware, see the complete memory map
+for the gateware in Appendix~\ref{app:memmap}.
 \begin{figure}[h]
  \centerline{\includegraphics[width=1.1\textwidth]{fig/hdl-bd}}
@@ -215,21 +224,23 @@ The logic for this test is shown in Figure~\ref{fig:ttl-test} and can be summari
 \begin{itemize}
 \item the PTS software sets the TTLPT bit in the PTS control and status register (CSR -- see Appendix~\ref{app:pts-regs-csr})
-\item this enables the \textit{pulse\_gen\_gp} component on TTL CH1 to generate
+\item this enables a general-purpose pulse generator component on TTL CH1 to generate
 1~$\mu$s pulses with a period of 500~ms
 \item the pulses are replicated through the channel daisy-chain~\cite{pts-userguide} from
-CH1 to CH10
+CH1 to INV-TTL CH D
-\item CH2 through INV-TTL CH D (CH10 in VHDL) have \textit{conv\_pulse\_gen} components~\cite{conv-common-gw-ohwr}
+\item CH2 through INV-TTL CH D (CH10 in VHDL) have pulse generator components~\cite{conv-common-gw-ohwr}
 which generate 1~$\mu$s pulses when there is a pulse on the input
 \item each channel has one input and output pulse counter; each counter gets incremented when
 there is a rising edge on the input or output
 \item the current values of these counters can be read by the PTS software from the pulse counter
 registers (see Appendix~\ref{app:pulse-cnt})
-\item for the switch test
+\end{itemize}
-  \begin{itemize}
+For the switch test:
+\begin{itemize}
  \item the user sets the switches as indicated in the CONV-TTL-BLO PTS User Guide~\cite{pts-userguide}
-    \item the PTS software reads the CSR.SWITCH field (see Appendix~\ref{app:pts-regs-csr})
+  \item the PTS software reads the CSR.SWITCH field (see Appendix~\ref{app:pts-regs-csr}) to
-  \end{itemize}
+  confirm proper switch setting
 \end{itemize}
 \begin{figure}[h]
@@ -262,8 +273,9 @@ each channel generates a pulse 100~ms after the previous, with 600~ms period:
 blocking inputs via the RTM Interface Tester \cite{pts-hwguide}
 \item each channel has one input and output pulse counter; each counter gets incremented when
 there is a rising edge on the input or output
-\item the current values of these counters can be read by the PTS software from the pulse counter
+\item the PTS software reads the pulse counter registers (Section~\ref{app:pulse-cnt}) to check
-(Section~\ref{app:pulse-cnt}) registers
+that the number of pulses that are sent at outputs are received back at inputs, according
+to the connection diagram on the RTM Interface Tester
 \end{itemize}
 \begin{figure}[hbtp]
@@ -277,7 +289,7 @@ For testing the RTM detection lines and rear-panel LED lines (Figure~\ref{fig:rt
  \item this bit sets all rear LED lines
  \item the rear LED lines are looped back to the RTM detection lines through the RTM
  Interface Tester~\cite{pts-hwguide}
-  \item the PTS software reads the RTM field in the PTS CSR to check for correct value
+  \item the PTS software reads the RTM field in the PTS CSR to check for the correct value
 \end{itemize}
 \begin{figure}[h]
@@ -288,7 +300,7 @@ For testing the RTM detection lines and rear-panel LED lines (Figure~\ref{fig:rt
 %--------------------------------------------------------------------------------------
 % SUBSEC: Test 05
 %--------------------------------------------------------------------------------------
-\subsection{Test 05}
+\subsection{Test 05 -- Thermometer chip test}
 The PTS software interacts with the OpenCores one-wire master core~\cite{onewire}
 to access the DS18B20U+ temperature chip for retrieving the unique board ID and the
@@ -297,19 +309,19 @@ temperature at the time the test is run.
 %--------------------------------------------------------------------------------------
 % SUBSEC: Test 06
 %--------------------------------------------------------------------------------------
-\subsection{Test 06}
+\subsection{Test 06 -- SFP EEPROM test}
-An OpenCores I$^2$C master component~\cite{i2c-master} communicates to the SFP and retrieves
+An OpenCores I$^2$C master component~\cite{i2c-master} communicates to the SFP connector and retrieves
 its internal identifier. The PTS software drives this communication by interacting with the
 I$^2$C master and checks the SFP identifier for correct value.
 %--------------------------------------------------------------------------------------
 % SUBSEC: Test 07
 %--------------------------------------------------------------------------------------
-\subsection{Test 07}
+\subsection{Test 07 -- SPF link test}
 The PTS software communicates with MiniNIC and endpoint components~\cite{wr-cores} to
-initialize them and check whether the link goes up through an SFP loopback connector.
+initialize them and check whether the link goes up through the SFP loopback connector.
 %======================================================================================
 % SEC: Folder structure
@@ -320,6 +332,7 @@ initialize them and check whether the link goes up through an SFP loopback conne
 The folder structure is shown in Table~\ref{tbl:fold-struct}.
 \begin{table}[h]
+  \rowcolors{2}{white}{gray!25}
  \caption{\label{tbl:fold-struct} Folder structure for the PTS gateware}
  \centerline{
  \begin{tabular}{l p{.7\textwidth}}

--- a/fm/doc/hdlg/pts_regs.tex
+++ b/fm/doc/hdlg/pts_regs.tex
@@ -154,7 +154,7 @@ SWITCH
 RTM
 } [\emph{read-only}]: RTM detection lines
 \\
-1 - line activate \\                     0 - line inactive
+1 - line active \\                     0 - line inactive
 \end{small}
 \item \begin{small}
 {\bf