ngscopeclient · Feb 17, 2020
Showing with 145 additions and 8 deletions.

+145 −8 glscopeclient-manual.tex
diff --git a/glscopeclient-manual.tex b/glscopeclient-manual.tex
@@ -8,6 +8,7 @@
 \usepackage{placeins}
 \usepackage{paralist}
 \usepackage{makecell}
+\usepackage{colortbl}
 \usepackage[osf]{libertine}
 \usepackage{zi4}
 \usepackage[libertine,cmbraces]{newtxmath}
@@ -29,6 +30,17 @@
 \lstset{breakatwhitespace=false}
 \lstset{basicstyle=\small\ttfamily}
 
+% standard colors for protocol decodes
+\usepackage{xcolor}
+\definecolor{control}{HTML}{c000a0}
+\definecolor{data}{HTML}{336699}
+\definecolor{address}{HTML}{ffff00}
+\definecolor{preamble}{HTML}{808080}
+\definecolor{checksumok}{HTML}{00ff00}
+\definecolor{checksumbad}{HTML}{ff0000}
+\definecolor{error}{HTML}{ff0000}
+\definecolor{idle}{HTML}{404040}
+
 % table lines
 \newcommand{\thinhline}{\Xhline{1\arrayrulewidth}}
 \newcommand{\thickhline}{\Xhline{2.5\arrayrulewidth}}
@@ -121,6 +133,7 @@ \subsection{Compilation}
 mkdir build
 cd build
 cmake ../
+make
 sudo make install
 \end{lstlisting}
 
@@ -180,28 +193,52 @@ \subsection{Design Philosophy}
 \section{Oscilloscope Drivers}
 
 \subsection{Agilent}
-TODO
+TODO (scopehal:74, scopehal:14)
 
 \subsection{Antikernel Labs}
 TODO
 
+\subsection{Enjoy Digital}
+TODO (scopehal:79)
+
+\subsection{Hantek}
+TODO (scopehal:26)
+
 \subsection{Keysight}
 TODO
 
+\subsection{Pico Technologies}
+TODO (scopehal:15)
+
 \subsection{Rigol}
-TODO
+TODO (scopehal:12)
 
 \subsection{Rohde \& Schwarz}
-TODO
+TODO (scopehal:59)
+
+\subsection{Saleae}
+TODO (scopehal:16)
 
 \subsection{Siglent}
-TODO
+TODO (scopehal:11)
 
 \subsection{Teledyne LeCroy}
+
+There are currently two drivers for Teledyne LeCroy devices.
+
+\subsubsection{lecroy\_lan}
+
 TODO
 
+\subsubsection{lecroy\_vicp}
+
+This driver uses SCPI over
+
 \subsection{Tektronix}
-TODO
+TODO (scopehal:73, scopehal:13)
+
+\subsection{Xilinx}
+TODO (scopehal:40)
 
 \pagebreak
 \section{Main Window}
@@ -304,9 +341,7 @@ \subsection{Channel Information Box}
 
 \subsection{Overlays}
 
-\section{Measurements}
-
-\section{Protocol Decodes and Math Functions}
+\section{Protocol Decodes, Math Functions, and Measurements}
 
 \subsection{Introduction}
 
@@ -336,30 +371,132 @@ \subsubsection{Key Concepts}
 
 \subsubsection{Conventions}
 
+Each protocol decode takes one or more inputs (vector inputs), zero or more parameters (scalar inputs), and outputs a
+signal (vector output).
+
+If the output signal is a complex-valued type (as opposed to a single scalar, e.g. voltage, at each sample) the
+``Output Signal" section will include a table describing how various types of output data are displayed. Printf-style
+format codes maybe used for clarity. For example, ``\%02x" means data is formatted as hexadecimal bytes with leading
+zeroes.
+
+All protocol decodes with complex output use a standardized set of colors to display various types of data fields in a
+consistent manner. These colors are currently hard coded in a table but will be made editable in the future
+(scopehal-apps:43)
+
+Suggestions on changes to the default colors, or new categories for color coding, are welcome
+
+\begin{tabularx}{16cm}{llX}
+\thickhline
+\textbf{Color name} & \textbf{Use case} & \textbf{Default Color} \\
+\thickhline
+Address & Memory addresses & \cellcolor{address}\textcolor{black}{\#ffff00} \\
+\thickhline
+Checksum Bad & Incorrect CRC/checksum & \cellcolor{checksumbad}\textcolor{white}{\#ff0000} \\
+\thickhline
+Checksum OK & Valid CRC/checksum & \cellcolor{checksumok}\textcolor{black}{\#00ff00} \\
+\thickhline
+Control & Miscellaneous control data & \cellcolor{control}\textcolor{white}{\#c000a0} \\
+\thickhline
+Data & User data & \cellcolor{data}\textcolor{white}{\#336699} \\
+\thickhline
+Error & Malformed/unreadable data & \cellcolor{error}\textcolor{white}{\#ff0000} \\
+\thickhline
+Idle & Inter-frame gaps & \cellcolor{idle}\textcolor{white}{\#404040} \\
+\thickhline
+Preamble & Preamble/sync words & \cellcolor{preamble}\textcolor{white}{\#808080} \\
+\thickhline
+\end{tabularx}
+
 \subsection{8B/10B (IBM)}
+
 \subsection{8B/10B (TMDS)}
+
+Decodes the 8-to-10 Transition Minimized Differential Signalling line code used in DVI and HDMI.
+
+\subsubsection{Inputs}
+
+\begin{tabularx}{16cm}{llX}
+\thickhline
+\textbf{Signal name} & \textbf{Type} & \textbf{Description} \\
+\thickhline
+data & 1-bit digital & Serial TMDS data line \\
+\thickhline
+clk & 1-bit digital & DDR \emph{bit} clock, typically generated by use of the \hyperref[filter:cdrpll]{Clock Recovery
+(PLL)} decode on the input data. Note that this is 5x the rate of the HDMI pixel clock signal. \\
+\thickhline
+\end{tabularx}
+
+\subsubsection{Parameters}
+
+This decode takes no parameters.
+
+\subsubsection{Output Signal}
+
+The TMDS decode outputs a time series of TMDS sample objects. These consist of a type field and a byte of data.
+
+The output of the TMDS decode is commonly fed to the \hyperref[filter:dvi]{DVI} or \hyperref[filter:hdmi]{HDMI}
+protocol decoders.
+
+\begin{tabularx}{16cm}{lllX}
+\thickhline
+\textbf{Type} & \textbf{Description} & \textbf{Color} & \textbf{Format} \\
+\thickhline
+Control & Control codes (H/V sync) & \cellcolor{control}\textcolor{white}{Control} & CTL\%d \\
+\thickhline
+Data & Pixel/island data & \cellcolor{data}\textcolor{white}{Data} & \%02x \\
+\thickhline
+Error & Malformed data & \cellcolor{error}\textcolor{white}{Error} & ERROR \\
+\thickhline
+Guard band & HDMI data/video guard band & \cellcolor{preamble}\textcolor{white}{Preamble} & GB \\
+\thickhline
+\end{tabularx}
+
 \subsection{AC Couple}
+\subsection{Average}
+\subsection{Base}
 \subsection{CAN}
 \subsection{Clock Jitter (TIE)}
 \subsection{Clock Recovery (PLL)}
+\label{filter:cdrpll}
+
 \subsection{Clock Recovery Debug}
 \subsection{Clock Recovery (UART)}
 \subsection{DC Offset}
 \subsection{Difference}
 \subsection{DVI}
+\label{filter:dvi}
+
 \subsection{Ethernet - 10baseT}
 \subsection{Ethernet - 100baseTX}
 \subsection{Ethernet Autonegotiation}
+\subsection{Eye Bitrate}
+\subsection{Eye Height}
 \subsection{Eye Pattern}
+\subsection{Eye Period}
+\subsection{Eye P-P Jitter}
+\subsection{Eye Width}
+\subsection{Fall 80-20}
+\subsection{Fall 90-10}
+\subsection{Frequency}
 \subsection{FFT}
+\subsection{HDMI}
+\label{filter:hdmi}
 \subsection{$I^2C$}
 \subsection{JTAG}
+\subsection{Max}
 \subsection{MDIO}
+\subsection{Min}
 \subsection{Moving Average}
+\subsection{Overshoot}
 \subsection{Period}
+\subsection{Peak-Peak}
+\subsection{Rise 10-90}
+\subsection{Fall 20-80}
 \subsection{Sin(x)/x Interpolation}
 \subsection{Threshold}
+\subsection{Top}
 \subsection{UART}
+\subsection{Undershoot}
 \subsection{USB 1.0 / 2.x Activity}
 \subsection{USB 1.0 / 2.x Packet}
 \subsection{USB 1.0 / 2.x PCS}