[RFC PATCH 2/3] transport-mmio: Document restricted-dma-pool SWIOTLB bounce buffer

[David Woodhouse]

From: David Woodhouse <dwmw@xxxxxxxxxxxx>

Add explicit reference to the `restricted-dma-pool` DT schema in the
virtio-mmio transport options, and define its relationship to the
newly-added VIRTIO_F_SWIOTLB feature negotiation.

Signed-off-by: David Woodhouse <dwmw@xxxxxxxxxxxx>
---
 transport-mmio.tex | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/transport-mmio.tex b/transport-mmio.tex
index 94a93a1..300783c 100644
--- a/transport-mmio.tex
+++ b/transport-mmio.tex
@@ -26,6 +26,39 @@ \subsection{MMIO Device Discovery}\label{sec:Virtio Transport Options / Virtio O
 }
 \end{lstlisting}
 
+\subsection{Software IOTLB Bounce Buffer}\label{sec:Virtio Transport Options / Virtio Over MMIO / Software IOTLB Bounce Buffer}
+
+The device tree binding schema defines a ``restricted-dma-pool'' region
+which is intended to be used as a pool of restricted DMA buffers for
+specific devices. This allows devices to operate without DMA access to
+arbitrary system memory addresses.
+
+If a ``restricted-dma-pool'' is present, as in the example below, then
+bus addresses within the referenced range are not subject to the
+requirements of the VIRTIO_F_ORDER_PLATFORM capability, if negotiated.
+
+\begin{lstlisting}
+// EXAMPLE: virtio_block device with SWIOTLB bounce buffer at 0x50000000.
+restricted_dma_reserved: restricted-dma-pool@50000000 {
+        compatible = "restricted-dma-pool";
+        reg = <0x50000000 0x4000000>;
+};
+
+virtio_block@1e000 {
+        compatible = "virtio,mmio";
+        memory-region = <&restricted-dma-reserved>;
+        reg = <0x1e000 0x200>;
+        interrupts = <42>;
+};
+\end{lstlisting}
+
+\drivernormative{\subsubsection}{Software IOTLB Bounce Buffer}{Virtio Transport Options / Virtio Over MMIO / Software IOTLB Bounce Buffer}
+
+The driver SHOULD use the offered buffer in preference to passing system
+memory addresses to the device. If the driver accepts the VIRTIO_F_SWIOTLB
+feature, then the driver MUST use the offered buffer and never pass system
+memory addresses to the device.
+
 \subsection{MMIO Device Register Layout}\label{sec:Virtio Transport Options / Virtio Over MMIO / MMIO Device Register Layout}
 
 MMIO virtio devices provide a set of memory mapped control
-- 
2.49.0