From b225717ddbd038f40af5d3b875a5cebcda622098 Mon Sep 17 00:00:00 2001
From: Spaqin <mw@m-labs.hk>
Date: Wed, 29 Mar 2023 13:46:33 +0800
Subject: [PATCH] DDMA: documentation

---
 RELEASE_NOTES.rst                   |  2 ++
 artiq/coredevice/dma.py             |  6 ++++--
 doc/manual/getting_started_core.rst | 24 ++++++++++++++++++++++++
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/RELEASE_NOTES.rst b/RELEASE_NOTES.rst
index 8ccbc3347..590ade183 100644
--- a/RELEASE_NOTES.rst
+++ b/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
 -------
diff --git a/artiq/coredevice/dma.py b/artiq/coredevice/dma.py
index 72e0f4a08..ff4aa01cb 100644
--- a/artiq/coredevice/dma.py
+++ b/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
diff --git a/doc/manual/getting_started_core.rst b/doc/manual/getting_started_core.rst
index a17e0633e..5b7cab0e5 100644
--- a/doc/manual/getting_started_core.rst
+++ b/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.
\ No newline at end of file