doc: Add Waveform/RTIO analyzer

doc/manual/compiler.rst

@@ -159,7 +159,7 @@ Basic NumPy array handling (``np.array()``, ``numpy.transpose()``, ``numpy.full`
 Print and logging functions
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-ARTIQ offers two native built-in logging functions: ``rtio_log()``, as presented in :ref:`rtio-analyzer-example`, and ``core_log()``, which allows for printing directly to the core log regardless of context or network connection status, which is useful for debugging purposes (especially in satellites or idle/startup kernels, which have no access to a regular ``print()`` RPC). 
+ARTIQ offers two native built-in logging functions: ``rtio_log()``, which prints to the :ref:`RTIO log <rtio-analyzer>`, as retrieved by :mod:`~artiq.frontend.artiq_coreanalyzer`, and ``core_log()``, which allows for printing directly to the core log regardless of context or network connection status. Both exist for debugging purposes, especially in contexts where a ``print()`` RPC is not suitable, such as in idle/startup kernels or when debugging delicate RTIO slack issues which may be strongly affected by the overhead of ``print()``.
 
 ``print()`` itself is in practice an RPC to the regular host Python ``print()``, i.e. with output either in the terminal of :mod:`~artiq.frontend.artiq_run` or in the client logs when using :mod:`~artiq.frontend.artiq_dashboard` or :mod:`~artiq.frontend.artiq_compile`. This means on one hand that it should not be used in idle, startup, or subkernels, and on the other hand that it suffers of some of the timing limitations of any other RPC, especially if the RPC queue is full. Accordingly, it is important to be aware that the timing of ``print()`` outputs can't reliably be used to debug timing in kernels, and especially not the timing of other RPCs.
 

doc/manual/getting_started_core.rst

@@ -185,12 +185,12 @@ Within a parallel block, some statements can be scheduled sequentially again usi
 
 Particular care needs to be taken when working with ``parallel`` blocks which generate large numbers of RTIO events, as it is possible to cause sequencing issues in the gateware; see also :ref:`sequence-errors`.
 
-.. _rtio-analyzer-example:
+.. _rtio-analyzer:
 
 RTIO analyzer
 -------------
 
-The core device records the real-time I/O waveforms into a circular buffer. It is possible to dump any Python object so that it appears alongside the waveforms using the ``rtio_log`` function, which accepts a channel name (i.e. a log target) as the first argument: ::
+The core device records all real-time I/O waveforms, as well as the variation of RTIO slack, into a circular buffer, the contents of which can be extracted using :mod:`~artiq.frontend.artiq_coreanalyzer`. Try for example: ::
 
     from artiq.experiment import *
 
@@ -202,12 +202,28 @@ The core device records the real-time I/O waveforms into a circular buffer. It i
         @kernel
         def run(self):
             self.core.reset()
-            for i in range(100):
-                self.ttl0.pulse(...)
-                rtio_log("ttl0", "i", i)
-                delay(...)
+            for i in range(5):
+                self.ttl0.pulse(0.1 * ms)
+                delay(0.1 * ms)
 
-When using :mod:`~artiq.frontend.artiq_run`, the recorded data can be extracted using :mod:`~artiq.frontend.artiq_coreanalyzer`. To export it to VCD, which can be viewed using third-party tools such as GtkWave, use a command in the form of ``artiq_coreanalyzer -w <file_name>.vcd``. Recorded data can also be viewed directly with the ARTIQ dashboard, which will be presented later in :doc:`getting_started_mgmt`.
+When using :mod:`~artiq.frontend.artiq_run`, the recorded buffer data can be extracted directly into the terminal, using a command in the form of: ::
+
+    $ artiq_coreanalyzer -p
+
+.. note::
+    The first time this command is run, it will retrieve the entire contents of the analyzer buffer, which may include every experiment you have run so far. For a more manageable introduction, run the analyzer once to clear the buffer, run the experiment, and then run the analyzer a second time, so that only the data from this single experiment is displayed.
+
+This will produce a list of the exact output events submitted to RTIO, printed in chronological order, along with the state of both ``now_mu`` and ``rtio_counter_mu``. While useful in diagnosing some specific gateware errors (in particular, :ref:`sequencing issues <sequence-errors>`), it isn't the most readable of formats. An alternate is to export to VCD, which can be viewed using third-party tools such as GtkWave. Run the experiment again, and use a command in the form of: ::
+
+    $ artiq_coreanalyzer -w <file_name>.vcd
+
+The ``<file_name>.vcd`` file should be immediately created and written. Check the directory the command was run in to find it.
+
+.. tip::
+
+    To view e.g. RTIO slack in GtkWave, drag the ``rtio_slack`` signal into the 'Signals' dock, under ``Time``. By default, the data will be presented in a raw form which you will probably not find particularly useful. For RTIO slack in particular, left-click, select ``Data Format > BitsToReal``, then ``Data Format > Analog``, to see a stepped waveform like that which the dashboard displays. Note also that the 'Waves' dock timescale is probably zoomed in very far; you may need to zoom out by some distance to see the effects of your experiment.
+
+The easiest way to view recorded analyzer data, however, is directly in the ARTIQ dashboard, a feature which will be presented later in :ref:`interactivity-waveform`.
 
 .. _getting-started-dma:
 

doc/manual/rtio.rst

@@ -103,7 +103,7 @@ Once the timeline cursor has overtaken the wall clock, the exception does not re
 To track down :class:`~artiq.coredevice.exceptions.RTIOUnderflow` exceptions in an experiment there are a few approaches:
 
   * Exception backtraces show where underflow has occurred while executing the code.
-  * The :ref:`integrated logic analyzer <core-device-rtio-analyzer-tool>` shows the timeline context that lead to the exception. The analyzer is always active and supports plotting of RTIO slack. This may be useful to spot where and how an experiment has 'run out' of positive slack.
+  * The :ref:`integrated logic analyzer <rtio-analyzer>` shows the timeline context that lead to the exception. The analyzer is always active and supports plotting of RTIO slack. This may be useful to spot where and how an experiment has 'run out' of positive slack.
 
 .. _sequence-errors:
 

doc/manual/using_data_interfaces.rst

@@ -109,6 +109,8 @@ Broadly speaking, these controllers are edge cases, serving as proxies for inter
 
 Although they are listed in the references for completeness' sake, there is normally no reason to run the built-in controllers independently. A controller manager run alongside the master (or anywhere else, provided the given addresses are edited accordingly; proxy controllers communicate with the core device by network just as the master does) is more than sufficient.
 
+.. _interactivity-moninj:
+
 Using MonInj
 ------------
 
@@ -137,10 +139,51 @@ For those peripherals which support monitoring, the command-line :mod:`~artiq.fr
 
 This tool is very simple, and there is rarely any reason to prefer its use over the dashboard monitor. Nonetheless, it can be helpful for certain kinds of debugging.
 
-.. RTIO analyzer and Waveform
-.. --------------------------
+.. _interactivity-waveform:
 
-.. TBI.
+Waveform
+--------
+
+The RTIO analyzer was briefly presented in :ref:`rtio-analyzer`. Like MonInj, it is directly accessible to the dashboard through its own proxy controller, :mod:`~artiq.frontend.aqctl_coreanalyzer_proxy`. To see it in action with the management system, navigate to the 'Waveform' tab of the dashboard. The dock should display several buttons and a currently empty list of waveforms, distinguishable only by the timeline along the top of the field. Use the 'Add channels' button, similar to that used by MonInj, to add waveforms to the list, for example ``rtio_slack`` and the ``led0`` user LED.
+
+The circular arrow 'Fetch analyzer data' button has the same basic effect as using the command-line :mod:`~artiq.frontend.artiq_coreanalyzer`: it extracts the full contents of the circular analyzer buffer. In order to start from a clean slate, click the fetch button a few times, until the ``analyzer dump is empty aside from stop message`` warning appears. Try running a simple experiment, for example this one, which underflows: ::
+
+    from artiq.experiment import *
+
+    class BlinkToUnderflow(EnvExperiment):
+        def build(self):
+            self.setattr_device("core")
+            self.setattr_device("led0")
+
+        @kernel
+        def run(self):
+            self.core.reset()
+            for i in range(1000):
+                self.led0.pulse(.2*us)
+                delay(.2*us)
+
+Now fetch the analyzer data again (only once)! Visible waveforms should appear in their respective fields. If nothing is visible to you, the timescale is likely zoomed too far out; adjust by zooming with CTRL+scroll and moving along the timeline by dragging it with your mouse. On a clean slate, ``BlinkToUnderflow`` should represent the first RTIO events on the record, and the waveforms accordingly will be displayed at the very beginning of the timeline.
+
+Eventually, you should be able to see the up-and-down 'square wave' pattern of the blinking LED, coupled with a steadily descending line in the RTIO slack, representing the progressive wearing away of the slack gained using ``self.core.reset()``. This kind of analysis can be especially useful in diagnosing underflows; with some practice, the waveform can be used to ascertain which parts of an experiment are consuming the greatest amounts of slack, thereby causing underflows down the line.
+
+.. tip::
+
+    File options in the top left allow for saving and exporting RTIO traces and channel lists, as well as opening them from saved files.
+
+RTIO logging
+^^^^^^^^^^^^
+
+It is possible to dump any Python object so that it appears alongside the waveforms, using the built-in ``rtio_log()`` function, which accepts a log name as its first parameter and an arbitrary number of objects along with it. Try adding it to the ``BlinkToUnderflow`` experiment: ::
+
+    @kernel
+    def run(self):
+        self.core.reset()
+        for i in range(1000):
+            self.led0.pulse(.2*us)
+            rtio_log("test_trace", "i", i)
+            delay(.2*us)
+
+Run this edited experiment. Fetch the analyzer data. Open the 'Add channels' pop-up again; ``test_trace`` should appear as an option now that the experiment has been run. Observe that every ``i`` is printed as a single-point event in a new waveform timeline.
 
 Shortcuts
 ---------

doc/manual/utilities.rst

@@ -113,14 +113,14 @@ This tool encodes the map of RTIO channel numbers to names in a format suitable
    :nodescription:
    :nodefault:
 
-.. _core-device-rtio-analyzer-tool:
-
 Core device RTIO analyzer tool
 ------------------------------
 
 .. automodule:: artiq.frontend.artiq_coreanalyzer
 
-This tool converts core device RTIO logs to VCD waveform files that are readable by third-party tools such as GtkWave. See :ref:`rtio-analyzer-example` for an example, or :mod:`artiq.test.coredevice.test_analyzer` for a relevant unit test. When using the ARTIQ dashboard, recorded data can be viewed or exported directly in the integrated waveform analyzer (the "Waveform" dock).
+This tool retrieves core device RTIO logs either as raw data or as VCD waveform files, which are readable by third-party tools such as GtkWave. See :ref:`rtio-analyzer` for an example, or :mod:`artiq.test.coredevice.test_analyzer` for a relevant unit test.
+
+Using the management system, the respective functionality is provided by :mod:`~artiq.frontend.aqctl_coreanalyzer_proxy` and the dashboard's 'Waveform' tab; see :ref:`interactivity-waveform`.
 
 .. argparse::
    :ref: artiq.frontend.artiq_coreanalyzer.get_argparser
@@ -148,7 +148,7 @@ ARTIQ RTIO monitor
 
 .. automodule:: artiq.frontend.artiq_rtiomon
 
-Command-line interface for monitoring RTIO channels, as in the Monitor capacity of dashboard MonInj.
+Command-line interface for monitoring RTIO channels, as in the Monitor capacity of dashboard MonInj. See :ref:`interactivity-moninj`.
 
 .. argparse::
    :ref: artiq.frontend.artiq_rtiomon.get_argparser