[PATCH v2] context: Document VIRTIO_F_IOMMU_PLATFORM reserved feature bit (33)

[Will Deacon <will.deacon@arm.com>]

On most virtio systems, physical addresses are provided from the driver
to the device and subsequently used to access memory directly. However,
some systems feature an IOMMU that complicates things slightly:

  - The IOMMU might require configuration for DMA to work at all. Once
    configured, the driver must pass bus addresses to the device, which
    are then translated by the IOMMU into physical addresses in memory.

  - The IOMMU might be bypassed by virtio DMA. In this case, physical
    addresses must still be provided to the device by the driver, even
    though an IOMMU appears to be present.

This has been solved by the addition of a new reserved feature bit,
VIRTIO_F_IOMMU_PLATFORM, to describe the two cases above. Legacy systems
will not negotiate the feature, and therefore continue to operate
directly on physical addresses.

Cc: Michael S. Tsirkin <mst@redhat.com>
Cc: Stefan Hajnoczi <stefanha@redhat.com>
Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com>
Signed-off-by: Will Deacon <will.deacon@arm.com>
---
 content.tex | 23 ++++++++++++++++++++---
 1 file changed, 20 insertions(+), 3 deletions(-)

diff --git a/content.tex b/content.tex
index 222b78e7f5d8..e57ebc530ef6 100644
--- a/content.tex
+++ b/content.tex
@@ -95,10 +95,10 @@ Feature bits are allocated as follows:
 \begin{description}
 \item[0 to 23] Feature bits for the specific device type
 
-\item[24 to 32] Feature bits reserved for extensions to the queue and
+\item[24 to 33] Feature bits reserved for extensions to the queue and
   feature negotiation mechanisms
 
-\item[33 and above] Feature bits reserved for future extensions.
+\item[34 and above] Feature bits reserved for future extensions.
 \end{description}
 
 \begin{note}
@@ -5813,7 +5813,7 @@ descriptor for the \field{sense_len}, \field{residual},
 
 \chapter{Reserved Feature Bits}\label{sec:Reserved Feature Bits}
 
-Currently there are three device-independent feature bits defined:
+Currently these device-independent feature bits defined:
 
 \begin{description}
   \item[VIRTIO_F_RING_INDIRECT_DESC (28)] Negotiating this feature indicates
@@ -5825,6 +5825,12 @@ Currently there are three device-independent feature bits defined:
 
   \item[VIRTIO_F_VERSION_1(32)] This indicates compliance with this
     specification, giving a simple way to detect legacy devices or drivers.
+
+  \item[VIRTIO_F_IOMMU_PLATFORM(33)] This feature indicates that the device is
+  behind an IOMMU that translates bus addresses from the device into physical
+  addresses in memory.  If this feature bit is set to 0, then the device emits
+  physical addresses which are not translated further, even though an IOMMU
+  may be present.
 \end{description}
 
 \drivernormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
@@ -5832,11 +5838,22 @@ Currently there are three device-independent feature bits defined:
 A driver MUST accept VIRTIO_F_VERSION_1 if it is offered.  A driver
 MAY fail to operate further if VIRTIO_F_VERSION_1 is not offered.
 
+A driver SHOULD accept VIRTIO_F_IOMMU_PLATFORM if it is offered, and it MUST
+then either disable the IOMMU or configure the IOMMU to translate bus addresses
+passed to the device into physical addresses in memory.  If
+VIRTIO_F_IOMMU_PLATFORM is not offered, then a driver MUST pass only physical
+addresses to the device.
+
 \devicenormative{\section}{Reserved Feature Bits}{Reserved Feature Bits}
 
 A device MUST offer VIRTIO_F_VERSION_1.  A device MAY fail to operate further
 if VIRTIO_F_VERSION_1 is not accepted.
 
+A device SHOULD offer VIRTIO_F_IOMMU_PLATFORM if it is behind an IOMMU that
+translates bus addresses from the device into physical addresses in memory.
+A device MAY fail to operate further if VIRTIO_F_IOMMU_PLATFORM is not
+accepted.
+
 \section{Legacy Interface: Reserved Feature Bits}\label{sec:Reserved Feature Bits / Legacy Interface: Reserved Feature Bits}
 
 Transitional devices MAY offer the following:
-- 
2.1.4