From da8eecc7975020c3da5226c699991033a159d80e Mon Sep 17 00:00:00 2001
From: Michael Zhao <michael.zhao@arm.com>
Date: Fri, 17 Sep 2021 17:04:23 +0800
Subject: [PATCH] docs: Describe about virtio-iommu with FDT

Added a section in "Usage" chapter of "iommu.md" to introduce the
special behavior when virtio-iommu is working with FDT on AArch64.

Signed-off-by: Michael Zhao <michael.zhao@arm.com>
---
 docs/iommu.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/iommu.md b/docs/iommu.md
index 099894fcf..c3bfd6e4f 100644
--- a/docs/iommu.md
+++ b/docs/iommu.md
@@ -121,6 +121,29 @@ lspci
 00:04.0 Unassigned class [ffff]: Red Hat, Inc. Virtio RNG
 ```
 
+### Work with FDT on AArch64
+
+On AArch64 architecture, the virtual IOMMU can still be used even if ACPI is not
+enabled. But the effect is different with what the aforementioned test showed.
+
+When ACPI is disabled, virtual IOMMU is supported through Flattened Device Tree
+(FDT). In this case, the guest kernel can not tell which device should be
+IOMMU-attached and which should not. No matter how many devices you attached to
+the virtual IOMMU by setting `iommu=on` option, all the devices on the PCI bus
+will be attached to the virtual IOMMU (except the IOMMU itself). Each of the
+devices will be added into a IOMMU group.
+
+As a result, the directory content of `/sys/kernel/iommu_groups` would be:
+
+```bash
+ls /sys/kernel/iommu_groups/0/devices/
+0000:00:02.0
+ls /sys/kernel/iommu_groups/1/devices/
+0000:00:03.0
+ls /sys/kernel/iommu_groups/2/devices/
+0000:00:04.0
+```
+
 ## Faster mappings
 
 By default, the guest memory is mapped with 4k pages and no huge pages, which