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: 9434abdeb797
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: 7df623f35bb7
Choose a head ref
  • 1 commit
  • 9 files changed
  • 1 contributor

Commits on May 25, 2020

  1. Copy the full SHA
    7df623f View commit details
Binary file added images/channel-properties.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/proto-analyzer.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/timebase-properties.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/timeline.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
2 changes: 1 addition & 1 deletion section-decodes.tex
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
\section{Protocol Decodes, Math Functions, and Measurements}
\section{Filters}

\subsection{Introduction}

24 changes: 12 additions & 12 deletions section-history.tex
Original file line number Diff line number Diff line change
@@ -2,11 +2,11 @@ \section{History View}
\label{sec:history}

glscopeclient has the ability to save every waveform during a session in memory, allowing you to go back in time and
see previous state of the system being debugged.
see previous state of the system being debugged. Clicking on a timestamp in the history view pauses acquisition and
loads the historical waveform data for analysis.

By default, the history view (Fig. \ref{historyview}) is not displayed and no history is captured. If the history view
is closed, past history is removed. (TODO: we should probably display a warning prompt or keep existing history when
doing this?)
is closed, history continues to be captured up to the configured maximum history depth.

\begin{figure}[H]
\centering
@@ -15,7 +15,7 @@ \section{History View}
\label{historyview}
\end{figure}

The ``max waveforms" box allows the depth of the history to be configured. It defaults to 100 but can be set to any
The ``max waveforms" box allows the depth of the history to be configured. It defaults to 10 but can be set to any
positive integer value. Older waveforms beyond the history limit are deleted as new waveforms are acquired.

The status bar at the bottom of the history view displays the total number of waveforms in the history, as well as an
@@ -25,21 +25,21 @@ \subsection{Estimating Waveform Memory Usage}

When selecting a maximum depth for the history, it is important to pick a reasonable limit to avoid running out of RAM!
glscopeclient will happily fill tens or hundreds of gigabytes of memory with deep waveforms if given a chance. Memory
usage of waveform data can be roughly estimated as 16+sizeof(sample type) bytes per point, since each sample contains a
usage of waveform data can be roughly estimated as 16 + sizeof(sample type) bytes per point, since each sample contains a
64-bit timestamp and duration plus the sample data.

For example, an analog sample takes 20 bytes of RAM (16 of time plus a 32-bit floating point voltage measurement) per
sample. Thus, a 1M point analog waveform takes approximately 20 MB of RAM per channel, or 80 MB per capture on a
four-channel oscilloscope with all channels enabled.

On the larger side, a 10M point four channel capture would use 800 MB and a 64M point deep-memory capture would use 5
GB. The default 100-waveform history setting is thus wildly inappropriate for such deep captures! A future software
release may support spilling waveform data to a temporary directory on disk, permitting effectively unlimited history
depth given sufficient disk space.
GB. A deep history setting, such as 100 waveforms, is thus wildly inappropriate for such deep captures! A future
software release may support spilling waveform data to a temporary directory on disk, permitting effectively unlimited
history depth given sufficient disk space.

Digital waveforms use one byte per sample for the actual measurement, so 17 MB per channel for a 1M point waveform.

Protocol decode memory usage varies depending on the specific decode, however it is typically not a large contributor
to the overall glscopeclient RAM footprint when using history mode because decodes are evaluated dynamically each time
a waveform is pulled from history rather than having output cached for every historical waveform. Thus, at most one
copy of each decoder's output is present in memory regardless of history depth.
Filter memory usage varies depending on the specific fitler in question, however it is typically not a large
contributor to the overall glscopeclient RAM footprint when using history mode because filters are evaluated
dynamically each time a waveform is pulled from history rather than having output cached for every historical waveform.
Thus, at most one copy of each filter's output is present in memory regardless of history depth.
20 changes: 20 additions & 0 deletions section-protoanalyzer.tex
Original file line number Diff line number Diff line change
@@ -1 +1,21 @@
\section{Protocol Analyzer View}

Some filters for decoding packet-oriented data provide an alternate means of visualizing the decoded traffic.

The protocol analyzer view (Fig. \ref{proto-analyzer}) displays each packet in the history as a row in a list view. The
first column is always the timestamp of the packet; remaining columns vary depending on the particular filter in
question.

Clicking on a packet pauses acquisition, loads the relevant waveform from history if the packet is not in the current
waveform, and scrolls the waveform view containing the protocol decode to the start of the packet. This allows
packet-level data to be easily correlated to physical layer waveforms.

\begin{figure}[H]
\centering
\includegraphics[width=14cm]{images/proto-analyzer.png}
\caption{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).
24 changes: 22 additions & 2 deletions section-timeline.tex
Original file line number Diff line number Diff line change
@@ -9,6 +9,26 @@ \section{Timeline}
the duration of the acquisition. It is possible to zoom or scroll beyond the end of the acquisition (displaying empty
background with no signal) or have a deep capture in which nearly all acquired data is offscreen.

TODO: talk about how to set trigger offset in capture and change timebase once that's implemented
\begin{figure}[h]
\centering
\includegraphics[width=13cm]{images/timeline.png}
\caption{The timeline}
\label{timeline}
\end{figure}

TODO: insert screenshot after we have some pending UI changes done
TODO: talk about how to set trigger offset within acquisition, once implemented (scopehal:21, scopehal-apps:12)

Double-clicking on the timeline brings up the timebase properties dialog (Fig. \ref{timebase-properties}), which allows
the sample rate and memory depth to be configured. If multiple instruments are connected, a separate tab appears in the
dialog for each instrument.

\begin{figure}[h]
\centering
\includegraphics[width=5cm]{images/timebase-properties.png}
\caption{Timebase properties dialog}
\label{timebase-properties}
\end{figure}


Note that the timeline may occasionally show units other than time. For example, an ``eye width" measurement has X axis
units of voltage and Y axis units of time.
27 changes: 19 additions & 8 deletions section-waveformviews.tex
Original file line number Diff line number Diff line change
@@ -31,10 +31,9 @@ \subsection{Y Axis Scale}

Each waveform view has its own Y axis scale, which is locked to the ADC range of the instrument.

Dragging the Y axis scale with the left mouse button currently does nothing (scopehal-apps:54) but in a future software
release will change the voltage offset of the channel.

Scrolling the Y axis scale with the mouse wheel changes the gain of the channel.
If the waveform view is connected to a physical channel of an instrument, the gain may be configured by scrolling with
the mouse wheel, and the offset may be adjusted by dragging with the left mouse button. If the view is displaying the
output of a filter block, gain and offset are set by the filter and not adjustable.

If a left-pointing arrow (as seen in Fig. \ref{y-axis}) is visible, the current channel is selected as a trigger
source. Click on the arrow and drag up or down to select the trigger level.
@@ -52,15 +51,27 @@ \subsection{Channel Information Box}
information about the channel. Currently this is the display name of the channel, the sample rate, and the record
length of the acquisition. Other information, such as probe coupling, may be displayed there in the future.

Double-clicking the information box opens the channel properties dialog.

\begin{figure}[H]
\centering
\includegraphics[width=2cm]{images/channel-infobox.png}
\caption{Channel information box}
\label{channel-infobox}
\end{figure}

The information box may be dragged with the left mouse button to move the entire waveform view to a new location.

Double-clicking the information box opens the channel properties dialog (Fig. \ref{channel-properties}). This dialog
allows changing of the channel's nickname or color. The ``hardware name" of the channel is also displayed, so that a
renamed channel can be easily traced back to a physical instrument input.

\begin{figure}[H]
\centering
\includegraphics[width=8cm]{images/channel-properties.png}
\caption{Channel properties dialog}
\label{channel-properties}
\end{figure}


\subsection{Overlays}

Waveforms may have additional information overlaid on top of them, such as protocol decodes. Each overlay has its own
@@ -78,5 +89,5 @@ \subsection{Overlays}
\label{overlays}
\end{figure}

Overlays can be deleted but cannot currently be moved between waveform areas or reordered within a single waveform area
(scopehal-apps:7, scopehal-apps:6)
Overlays can be deleted by means of the right-click context menu. Dragging the information box with the left mouse
button allows overlays to be reordered, however they cannot currently be moved to another waveform view.