DDMA: documentation

RELEASE_NOTES.rst

@@ -23,6 +23,8 @@ Highlights:
   support legacy installations, but may be removed in a future release.
 * Added channel names to RTIO errors.
 * Full Python 3.10 support.
+* Distributed DMA is now supported, allowing DMA to be run directly on satellites for corresponding
+  RTIO events, increasing bandwidth in scenarios with heavy satellite usage.
 
 ARTIQ-7
 -------

artiq/coredevice/dma.py

@@ -79,10 +79,12 @@ class CoreDMA:
         """Returns a context manager that will record a DMA trace called ``name``.
         Any previously recorded trace with the same name is overwritten.
         The trace will persist across kernel switches.
-        In DRTIO context, you can toggle distributed DMA with ``enable_ddma``.
+
+        In DRTIO context, distributed DMA can be toggled with ``enable_ddma``.
         Enabling it allows running DMA on satellites, rather than sending all
         events from the master.
-        Disabling it may improve performance in some scenarios, 
+
+        Keeping it disabled it may improve performance in some scenarios, 
         e.g. when there are many small satellite buffers."""
         self.epoch += 1
         self.recorder.name = name

doc/manual/getting_started_core.rst

@@ -243,3 +243,27 @@ Try this: ::
                 # execute RTIO operations in the DMA buffer
                 # each playback advances the timeline by 50*(100+100) ns
                 self.core_dma.playback_handle(pulses_handle)
+
+Distributed Direct Memory Access (DDMA)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default on DRTIO systems, all events recorded by the DMA core are kept and played back on the master.
+
+With distributed DMA, RTIO events that should be played back on remote destinations, are distributed to the corresponding satellites. In some cases (typically, large buffers on several satellites with high event throughput), it allows for better performance and higher bandwidth, as the RTIO events do not have to be sent over the DRTIO link(s) during playback.
+
+To enable distributed DMA, simply provide an ``enable_ddma=True`` argument for the :meth:`~artiq.coredevice.dma.CoreDMA.record` method - taking a snippet from the previous example: ::
+
+        @kernel
+        def record(self):
+            with self.core_dma.record("pulses", enable_ddma=True):
+                # all RTIO operations now go to the "pulses"
+                # DMA buffer, instead of being executed immediately.
+                for i in range(50):
+                    self.ttl0.pulse(100*ns)
+                    delay(100*ns)
+
+This argument is ignored on standalone systems, as it does not apply there.
+
+Enabling DDMA on a purely local sequence on a DRTIO system introduces an overhead during trace recording which comes from additional processing done on the record, so careful use is advised.
+
+Due to the extra time that communicating with relevant satellites takes, an additional delay before playback may be necessary to prevent a :exc:`~artiq.coredevice.exceptions.RTIOUnderflow` when playing back a DDMA-enabled sequence.