[PATCH] intel-iommu: Document iova_tree

[Peter Xu]

It seems not super clear on when iova_tree is used, and why.  Add a rich
comment above iova_tree to track why we needed the iova_tree, and when we
need it.

Suggested-by: Jason Wang <jasowang@redhat.com>
Signed-off-by: Peter Xu <peterx@redhat.com>
---
 include/hw/i386/intel_iommu.h | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/include/hw/i386/intel_iommu.h b/include/hw/i386/intel_iommu.h
index 46d973e629..8d130ab2e3 100644
--- a/include/hw/i386/intel_iommu.h
+++ b/include/hw/i386/intel_iommu.h
@@ -109,7 +109,35 @@ struct VTDAddressSpace {
     QLIST_ENTRY(VTDAddressSpace) next;
     /* Superset of notifier flags that this address space has */
     IOMMUNotifierFlag notifier_flags;
-    IOVATree *iova_tree;          /* Traces mapped IOVA ranges */
+    /*
+     * @iova_tree traces mapped IOVA ranges.
+     *
+     * The tree is not needed if no MAP notifiers is registered with
+     * current VTD address space, because all UNMAP (including iotlb or
+     * dev-iotlb) events can be transparently delivered to !MAP iommu
+     * notifiers.
+     *
+     * The tree OTOH is required for MAP typed iommu notifiers for a few
+     * reasons.
+     *
+     * Firstly, there's no way to identify whether an PSI event is MAP or
+     * UNMAP within the PSI message itself.  Without having prior knowledge
+     * of existing state vIOMMU doesn't know whether it should notify MAP
+     * or UNMAP for a PSI message it received.
+     *
+     * Secondly, PSI received from guest driver (or even a large PSI can
+     * grow into a DSI at least with Linux intel-iommu driver) can be
+     * larger in range than the newly mapped ranges for either MAP or UNMAP
+     * events. If it directly pass-throughs any such event it may confuse
+     * the registered drivers (e.g. vfio-pci) on either: (1) trying to map
+     * the same region more than once (for VFIO_IOMMU_MAP_DMA, -EEXIST will
+     * trigger), or (2) trying to UNMAP a range that is still partially
+     * mapped.  That accuracy is not required for UNMAP-only notifiers, but
+     * it is a must-to-have for MAP-inclusive notifiers, because the vIOMMU
+     * needs to make sure the shadow page table is always in sync with the
+     * guest IOMMU pgtables for a device.
+     */
+    IOVATree *iova_tree;
 };
 
 struct VTDIOTLBEntry {
-- 
2.37.3