From bf6a6019b29a295cabd0315d9b49ea7fd999a473 Mon Sep 17 00:00:00 2001
From: "tone.zhang" <tone.zhang@arm.com>
Date: Tue, 4 Sep 2018 13:56:58 +0800
Subject: [PATCH] Doc: Clarify the IOMMU configuration for User Space Drivers

In the case system charges PCI devices with the "uio_pci_generic"
kernel driver, the IOMMU should be disabled or passthrough, because
the virtual / physical address conversion by IOMMU will make the DMA
transmission invalid.

The patch guides users configure IOMMU in SPDK target system on both
x86_64 and arm64 systems.

Change-Id: I66df4df855a6669d4838eb88bd400ded87d08a49
Signed-off-by: tone.zhang <tone.zhang@arm.com>
Reviewed-on: https://review.gerrithub.io/424470
Reviewed-by: Ben Walker <benjamin.walker@intel.com>
Reviewed-by: Jim Harris <james.r.harris@intel.com>
Tested-by: SPDK CI Jenkins <sys_sgci@intel.com>
---
 doc/Doxyfile                |  1 +
 doc/system_configuration.md | 17 +++++++++++++++++
 doc/user_guides.md          |  1 +
 3 files changed, 19 insertions(+)
 create mode 100644 doc/system_configuration.md

diff --git a/doc/Doxyfile b/doc/Doxyfile
index c2b09347e..99a62d9a0 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -827,6 +827,7 @@ INPUT                  += \
                          porting.md \
                          spdkcli.md \
                          ssd_internals.md \
+                         system_configuration.md \
                          userspace.md \
                          vagrant.md \
                          vhost.md \
diff --git a/doc/system_configuration.md b/doc/system_configuration.md
new file mode 100644
index 000000000..a71092595
--- /dev/null
+++ b/doc/system_configuration.md
@@ -0,0 +1,17 @@
+# System Configuration User Guide {#system_configuration}
+
+This system configuration guide describes how to configure a system for use with SPDK.
+
+# IOMMU configuration {#iommu_config}
+
+An IOMMU may be present and enabled on many platforms. When an IOMMU is present and enabled, it is
+recommended that SPDK applications are deployed with the `vfio-pci` kernel driver. SPDK's
+`scripts/setup.sh` script will automatically select `vfio-pci` in this case.
+
+However, some devices do not function correctly when bound to `vfio-pci` and instead must be
+attached to the `uio_pci_generic` kernel driver. In that case, users should take care to disable
+the IOMMU or to set it into passthrough mode prior to running `scripts/setup.sh`.
+
+To disable the IOMMU or place it into passthrough mode, add `intel_iommu=off`
+or `amd_iommu=off` or `intel_iommu=on iommu=pt` to the GRUB command line on
+x86_64 system, or add `iommu.passthrough=1` on arm64 systems.
diff --git a/doc/user_guides.md b/doc/user_guides.md
index 16dc737d3..f0a4994aa 100644
--- a/doc/user_guides.md
+++ b/doc/user_guides.md
@@ -1,5 +1,6 @@
 # User Guides {#user_guides}
 
+- @subpage system_configuration
 - @subpage app_overview
 - @subpage iscsi
 - @subpage nvmf