Skip to content
Permalink

Comparing changes

Choose two branches to see what’s changed or to start a new pull request. If you need to, you can also or learn more about diff comparisons.

Open a pull request

Create a new pull request by comparing changes across two branches. If you need to, you can also . Learn more about diff comparisons here.
base repository: ngscopeclient/scopehal-docs
Failed to load repositories. Confirm that selected base ref is valid, then try again.
Loading
base: d1a3c6254d4b
Choose a base ref
...
head repository: ngscopeclient/scopehal-docs
Failed to load repositories. Confirm that selected head ref is valid, then try again.
Loading
compare: d67e74248fb7
Choose a head ref
  • 1 commit
  • 9 files changed
  • 1 contributor

Commits on Dec 10, 2020

  1. Added new section for filter graph editor. Documented 64/66b decoder,…

    … major improvements to documentation of 8b10b and TMDS decodes.
    azonenberg committed Dec 10, 2020
    Copy the full SHA
    d67e742 View commit details
1 change: 1 addition & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
@@ -6,6 +6,7 @@ set(DOC_LIST
section-decodes.tex
section-drivers.tex
section-gettingstarted.tex
section-grapheditor.tex
section-history.tex
section-legal.tex
section-mainwindow.tex
7 changes: 6 additions & 1 deletion glscopeclient-manual.tex
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
\documentclass[11pt]{book}
\documentclass[11pt,letterpaper]{book}
\usepackage[T1]{fontenc}
\usepackage[margin=1in,top=0.6in,bottom=0.6in]{geometry}
\usepackage[bookmarks,colorlinks=true,linkcolor=blue,urlcolor=blue]{hyperref}
@@ -15,6 +15,8 @@
\usepackage{textcomp}
\usepackage[libertine,cmbraces]{newtxmath}

\setlength{\parskip}{2mm}

% configuration of source code examples
\usepackage{listings}
\lstset{language=c++}
@@ -66,6 +68,8 @@
\mainmatter
\tableofcontents

\raggedbottom

\include{section-revision}
\include{section-legal}
\include{section-gettingstarted}
@@ -79,6 +83,7 @@
\include{section-waveformviews}
\include{section-history}
\include{section-protoanalyzer}
\include{section-grapheditor}
\include{section-decodes}

\end{document}
Binary file added images/filters/64b66b.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/filters/8b10b.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/filters/tmds.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/graph-editor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
126 changes: 112 additions & 14 deletions section-decodes.tex
Original file line number Diff line number Diff line change
@@ -37,10 +37,7 @@ \subsection{Conventions}
zeroes.

All filters 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
consistent manner. These colors are configurable under the \menustyle{Appearance / Decodes} preferences category.

\begin{tabularx}{16cm}{llX}
\thickhline
@@ -67,14 +64,88 @@ \subsection{Conventions}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pagebreak
\section{64b/66b}
\label{filter:64b66b}

Decodes the 64/66b line code used by \hyperref[filter:10gbaser]{10Gbase-R} and other serial protocols, as originally
specified in IEEE 802.3 clause 49.2.

64b/66b is a serial line code which divides transmitted data into 64-bit blocks and scrambles them with a LFSR, then
appends a 2-bit type field (which is not scrambled) to each block for synchronization. Block synchronization depends on
always having an edge in the type field so types 2'b00 and 2'b11 are disallowed.

Note that this filter only performs block alignment and descrambling. No decoding is applied to the 64-bit blocks, as
different upper-layer protocols assign different meaning to them. In 10Gbase-R, type 2'b01 denotes ``64 bits of upper
layer data" and type 2'b10 denotes ``8-bit type field and 56 bits of data whose meaning depends on the type", however
this is not universal.

\begin{figure}[h]
\centering
\includegraphics[width=17cm]{images/filters/64b66b.png}
\caption{Example 64b/66b decode}
\label{filter_64b66b}
\end{figure}

\subsection{Inputs}

\begin{tabularx}{16cm}{llX}
\thickhline
\textbf{Signal name} & \textbf{Type} & \textbf{Description} \\
\thickhline
data & 1-bit digital & Serial 8b/10b data line \\
\thickhline
clk & 1-bit digital & DDR bit clock, typically generated by use of the \hyperref[filter:cdrpll]{Clock Recovery
(PLL)} filter on the input data.\\
\thickhline
\end{tabularx}

\subsection{Parameters}

This filter takes no parameters.

\subsection{Output Signal}

The 64B/66B filter outputs a time series of 64B/66B sample objects. These consist of a control/data flag and
a 64-bit data block.

\begin{tabularx}{16cm}{lllX}
\thickhline
\textbf{Type} & \textbf{Description} & \textbf{Color} & \textbf{Format} \\
\thickhline
Control & Block with type 2'b10 & \cellcolor{control}\textcolor{white}{Control} & \%016x \\
\thickhline
Data & Block with type 2'b01 & \cellcolor{data}\textcolor{white}{Data} & \%016x \\
\thickhline
Error & Block with type 2'b00 or 2'b11 & \cellcolor{error}\textcolor{white}{Error} & \%016x \\
\thickhline
\end{tabularx}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pagebreak
\section{8B/10B (IBM)}
\label{proto:8b10b}
\label{filter:8b10b}

Decodes the standard 8b/10b line code used by SGMII, \hyperref[filter:1000basex]{1000base-X}, DisplayPort, JESD204,
\hyperref[filter:pcie2_logical]{PCIe gen 1/2}, SATA, USB 3.0, and many other common serial protocols.

8b/10b is a dictionary based code which converts each byte of message data to a ten-bit code. In order to maintain DC
balance and limit run length to a maximum of five identical bits in a row, all legal codes have one of:
\begin{itemize}
\item One legal coding, with exactly five zero bits
\item Two legal codings, one with four zero bits and one with six
\end{itemize}

Decodes the standard 8b/10b line code used by SGMII, \hyperref[proto:1000basex]{1000base-X}, DisplayPort, JESD204,
PCIe gen 1/2, SATA, USB 3.0, and many other common serial protocols.
The transmitter maintains a ``running disparity" counter and chooses the appropriate coding for each symbol to ensure
DC balance. There are twelve legal codes which are not needed for encoding data values; these are used to encode
frame boundaries, idle/alignment sequences, and other control information.

\begin{figure}[h]
\centering
\includegraphics[width=17cm]{images/filters/8b10b.png}
\caption{Example 8b/10b decode}
\label{filter_8b10b}
\end{figure}

\subsection{Inputs}

\begin{tabularx}{16cm}{llX}
\thickhline
@@ -83,13 +154,21 @@ \section{8B/10B (IBM)}
data & 1-bit digital & Serial 8b/10b data line \\
\thickhline
clk & 1-bit digital & DDR bit clock, typically generated by use of the \hyperref[filter:cdrpll]{Clock Recovery
(PLL)} decode on the input data.\\
(PLL)} filter on the input data.\\
\thickhline
\end{tabularx}

\subsection{Parameters}

This filter takes no parameters.
\begin{tabularx}{16cm}{llX}
\thickhline
\textbf{Parameter name} & \textbf{Type} & \textbf{Description} \\
\thickhline
Display Format & Enum &
\textbf{Dotted (K28.5 D21.5)}: displays the 3b4b and 5b6b code blocks separately, with K or D prefix. \newline
\textbf{Hex (K.bc b5)}: displays data as hex byte values and control codes with a K prefix. \\
\thickhline
\end{tabularx}

\subsection{Output Signal}

@@ -100,9 +179,9 @@ \subsection{Output Signal}
\thickhline
\textbf{Type} & \textbf{Description} & \textbf{Color} & \textbf{Format} \\
\thickhline
Control & Control codes & \cellcolor{control}\textcolor{white}{Control} & K\%d.\%d \\
Control & Control codes & \cellcolor{control}\textcolor{white}{Control} & K\%d.\%d+ \\
\thickhline
Data & Pixel/island data & \cellcolor{data}\textcolor{white}{Data} & D\%d.\%d \\
Data & Upper layer protocol data & \cellcolor{data}\textcolor{white}{Data} & D\%d.\%d+ \\
\thickhline
Error & Malformed data & \cellcolor{error}\textcolor{white}{Error} & ERROR \\
\thickhline
@@ -111,8 +190,21 @@ \subsection{Output Signal}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\pagebreak
\section{8B/10B (TMDS)}
\label{filter:tmds}

Decodes the 8-to-10 Transition Minimized Differential Signalling line code used in \hyperref[filter:dvi]{DVI} and HDMI.

Like the \hyperref[filter:8b10b]{8B/10B (IBM)} line code, TMDS is an 8-to-10 bit serial line code. TMDS, however, is
designed to \emph{minimize} the number of toggles in the data stream for EMC reasons, rendering it difficult to
synchronize a CDR PLL to. As a result, HDMI and DVI provide a reference clock at the pixel clock rate (1/10 the serial
data bit rate) along with the data stream to provide synchronization.

Decodes the 8-to-10 Transition Minimized Differential Signalling line code used in DVI and HDMI.
\begin{figure}[h]
\centering
\includegraphics[width=17cm]{images/filters/tmds.png}
\caption{Example TMDS decode}
\label{filter_tmds}
\end{figure}

\subsection{Inputs}

@@ -123,13 +215,19 @@ \subsection{Inputs}
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. \\
(PLL)} filter on the input data. Note that this is 5x the rate of the pixel clock signal. \\
\thickhline
\end{tabularx}

\subsection{Parameters}

This filter takes no parameters.
\begin{tabularx}{16cm}{llX}
\thickhline
\textbf{Parameter name} & \textbf{Type} & \textbf{Description} \\
\thickhline
Lane Number & Integer & Lane number within the link (0-3)\\
\thickhline
\end{tabularx}

\subsection{Output Signal}

28 changes: 28 additions & 0 deletions section-grapheditor.tex
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
\chapter{Filter Graph Editor}

The filter graph editor allows complex signal processing pipelines to be developed in a graphical fashion.

It may be accessed from the \menustyle{Window / Filter Graph} menu item.

The leftmost column shows all of the input channels which may be used as data sources for the filter graph. Filter
nodes are automatically placed in columns such that data flows from left to right, with inputs at the left and outputs
at the right of each node.

Nodes may be dragged vertically within their column by using the left mouse button, however the horizontal position of
each node is fixed.

To make a connection, click on the source node's output and then on the destination node's input. To cancel an
in-progress connection, simply click anywhere outside a node.

\begin{figure}[H]
\centering
\includegraphics[width=17cm]{images/graph-editor.png}
\caption{Filter graph editor view}
\label{graph-editor}
\end{figure}

The title bar of each node in the graph is color coded to match the channel's color in the waveform view.

Input and output ports are color coded according to the type of data. The colors are configurable under the
\menustyle{Appearance / Filter Graph} preference category; the default assignment is dark blue for analog, purple for
digital, and olive for protocol decodes and other non-primitive types.
4 changes: 2 additions & 2 deletions section-protoanalyzer.tex
Original file line number Diff line number Diff line change
@@ -17,5 +17,5 @@ \chapter{Protocol Analyzer View}
\label{proto-analyzer}
\end{figure}

Once closed, the protocol analyzer view is gone for good, although it will eventually be possible to bring it back via
some sort of menu (scopehal-apps:44).
Once closed, the protocol analyzer view may be reopened by selecting the protocol of interest from the
\menustyle{Window / Analyzer} menu.