[PATCH V3 0/2] x86 IOMMU Documentation updates

[PATCH V3 0/2] x86 IOMMU Documentation updates

[Alex Deucher]

This was originally just a patch to add an AMD IOMMU
documentation page, but grew into some cleanup of the
Intel IOMMU documentation page.

v2: AMD documentation rework
    Add Intel Updates
v3: Further documentation reworks

Alex Deucher (2):
  Documentation: x86: Add documentation for AMD IOMMU
  Documentation: x86: Clarify Intel IOMMU documentation

 Documentation/x86/amd-iommu.rst   | 69 +++++++++++++++++++++++++++++++
 Documentation/x86/index.rst       |  1 +
 Documentation/x86/intel-iommu.rst | 13 +++---
 3 files changed, 76 insertions(+), 7 deletions(-)
 create mode 100644 Documentation/x86/amd-iommu.rst

-- 
2.35.1

[PATCH V3 1/2] Documentation: x86: Add documentation for AMD IOMMU

[Alex Deucher]

Add preliminary documentation for AMD IOMMU.

Signed-off-by: Alex Deucher <alexander.deucher@amd.com>
---

V2: Incorporate feedback from Robin to clarify IOMMU vs DMA engine (e.g.,
    a device) and document proper DMA API.  Also correct the fact that
    the AMD IOMMU is not limited to managing PCI devices.
v3: Fix spelling and rework text as suggested by Vasant

 Documentation/x86/amd-iommu.rst   | 69 +++++++++++++++++++++++++++++++
 Documentation/x86/index.rst       |  1 +
 Documentation/x86/intel-iommu.rst |  2 +-
 3 files changed, 71 insertions(+), 1 deletion(-)
 create mode 100644 Documentation/x86/amd-iommu.rst

diff --git a/Documentation/x86/amd-iommu.rst b/Documentation/x86/amd-iommu.rst
new file mode 100644
index 000000000000..3b1fb8fec168
--- /dev/null
+++ b/Documentation/x86/amd-iommu.rst
@@ -0,0 +1,69 @@
+=================
+AMD IOMMU Support
+=================
+
+The architecture spec can be obtained from the below location.
+
+https://www.amd.com/system/files/TechDocs/48882_IOMMU.pdf
+
+This guide gives a quick cheat sheet for some basic understanding.
+
+Some Keywords
+
+- IVRS - I/O Virtualization Reporting Structure
+- IVDB - I/O Virtualization Definition Block
+- IVHD - I/O Virtualization Hardware Definition
+- IOVA - I/O Virtual Address.
+
+Basic stuff
+-----------
+
+ACPI enumerates and lists the different IOMMUs on the platform, and
+device scope relationships between devices and which IOMMU controls
+them.
+
+What is IVRS?
+-------------
+
+The architecture defines an ACPI-compatible data structure called an I/O
+Virtualization Reporting Structure (IVRS) that is used to convey information
+related to I/O virtualization to system software.  The IVRS describes the
+configuration and capabilities of the IOMMUs contained in the platform as
+well as information about the devices that each IOMMU virtualizes.
+
+The IVRS provides information about the following:
+- IOMMUs present in the platform including their capabilities and proper configuration
+- System I/O topology relevant to each IOMMU
+- Peripheral devices that cannot be otherwise enumerated
+- Memory regions used by SMI/SMM, platform firmware, and platform hardware. These are
+generally exclusion ranges to be configured by system software.
+
+How is IOVA generated?
+----------------------
+
+Well behaved drivers call dma_map_*() calls before sending command to device
+that needs to perform DMA. Once DMA is completed and mapping is no longer
+required, driver performs dma_unmap_*() calls to unmap the region.
+
+Fault reporting
+---------------
+
+When errors are reported, the IOMMU signals via an interrupt. The fault
+reason and device that caused it is printed on the console.
+
+Boot Message Sample
+-------------------
+
+Something like this gets printed indicating presence of the IOMMU.
+
+	iommu: Default domain type: Translated
+	iommu: DMA domain TLB invalidation policy: lazy mode
+
+Fault reporting
+^^^^^^^^^^^^^^^
+
+::
+
+	AMD-Vi: Event logged [IO_PAGE_FAULT domain=0x0007 address=0xffffc02000 flags=0x0000]
+	AMD-Vi: Event logged [IO_PAGE_FAULT device=07:00.0 domain=0x0007 address=0xffffc02000 flags=0x0000]
+
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index f498f1d36cd3..15711134eb68 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -22,6 +22,7 @@ x86-specific Documentation
    mtrr
    pat
    intel-iommu
+   amd-iommu
    intel_txt
    amd-memory-encryption
    pti
diff --git a/Documentation/x86/intel-iommu.rst b/Documentation/x86/intel-iommu.rst
index 099f13d51d5f..4d3391c7bd3f 100644
--- a/Documentation/x86/intel-iommu.rst
+++ b/Documentation/x86/intel-iommu.rst
@@ -1,5 +1,5 @@
 ===================
-Linux IOMMU Support
+Intel IOMMU Support
 ===================
 
 The architecture spec can be obtained from the below location.
-- 
2.35.1

Re: [PATCH V3 1/2] Documentation: x86: Add documentation for AMD IOMMU

[Dave Hansen]

On 3/28/22 10:28, Alex Deucher wrote:
> +How is IOVA generated?
> +----------------------
> +
> +Well behaved drivers call dma_map_*() calls before sending command to device
> +that needs to perform DMA. Once DMA is completed and mapping is no longer
> +required, driver performs dma_unmap_*() calls to unmap the region.
> +
> +Fault reporting
> +---------------
> +
> +When errors are reported, the IOMMU signals via an interrupt. The fault
> +reason and device that caused it is printed on the console.

Just scanning this, it looks *awfully* generic.  Is anything in here
AMD-specific?  Should this be in an AMD-specific file?

RE: [PATCH V3 1/2] Documentation: x86: Add documentation for AMD IOMMU

[Deucher, Alexander]

[Public]

> -----Original Message-----
> From: Dave Hansen <dave.hansen@intel.com>
> Sent: Tuesday, March 29, 2022 11:25 AM
> To: Deucher, Alexander <Alexander.Deucher@amd.com>; linux-
> doc@vger.kernel.org; linux-kernel@vger.kernel.org; corbet@lwn.net;
> hpa@zytor.com; x86@kernel.org; dave.hansen@linux.intel.com;
> bp@alien8.de; mingo@redhat.com; tglx@linutronix.de; joro@8bytes.org;
> Suthikulpanit, Suravee <Suravee.Suthikulpanit@amd.com>; will@kernel.org;
> iommu@lists.linux-foundation.org; robin.murphy@arm.com; Hegde, Vasant
> <Vasant.Hegde@amd.com>
> Subject: Re: [PATCH V3 1/2] Documentation: x86: Add documentation for
> AMD IOMMU
> 
> On 3/28/22 10:28, Alex Deucher wrote:
> > +How is IOVA generated?
> > +----------------------
> > +
> > +Well behaved drivers call dma_map_*() calls before sending command to
> > +device that needs to perform DMA. Once DMA is completed and mapping
> > +is no longer required, driver performs dma_unmap_*() calls to unmap the
> region.
> > +
> > +Fault reporting
> > +---------------
> > +
> > +When errors are reported, the IOMMU signals via an interrupt. The
> > +fault reason and device that caused it is printed on the console.
> 
> Just scanning this, it looks *awfully* generic.  Is anything in here AMD-
> specific?  Should this be in an AMD-specific file?

There is some information about the ACPI tables used to enumerate the IOMMUs and a link to the AMD IOMMU programming documentation.  Would you prefer I just create a combined x86 IOMMU document?

Alex

Re: [PATCH V3 1/2] Documentation: x86: Add documentation for AMD IOMMU

[Dave Hansen]

On 3/30/22 07:01, Deucher, Alexander wrote:
>> Just scanning this, it looks *awfully* generic.  Is anything in
>> here AMD- specific?  Should this be in an AMD-specific file?
> There is some information about the ACPI tables used to enumerate the
> IOMMUs and a link to the AMD IOMMU programming documentation.  Would
> you prefer I just create a combined x86 IOMMU document?

Yeah, I think that would make a lot of sense.  Let's just have one
document with an AMD section and an Intel section.  Maybe just rename
the existing one to intel-iommu => x86-iommu.rst.

[PATCH V3 2/2] Documentation: x86: Clarify Intel IOMMU documentation

[Alex Deucher]

Based on feedback from Robin on the initial AMD IOMMU
documentation, fix up the Intel documentation to
clarify IOMMU vs device and modern DMA API.

Signed-off-by: Alex Deucher <alexander.deucher@amd.com>
---

V2: Fix spelling error in commit message
    Rework ACPI section as suggested by Dave Hansen

 Documentation/x86/intel-iommu.rst | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/Documentation/x86/intel-iommu.rst b/Documentation/x86/intel-iommu.rst
index 4d3391c7bd3f..17d8497e506b 100644
--- a/Documentation/x86/intel-iommu.rst
+++ b/Documentation/x86/intel-iommu.rst
@@ -19,9 +19,8 @@ Some Keywords
 Basic stuff
 -----------
 
-ACPI enumerates and lists the different DMA engines in the platform, and
-device scope relationships between PCI devices and which DMA engine  controls
-them.
+ACPI enumerates both the IOMMUs in the platform and which IOMMU
+controls a specific PCI device.
 
 What is RMRR?
 -------------
@@ -36,9 +35,9 @@ unity mappings for these regions for these devices to access these regions.
 How is IOVA generated?
 ----------------------
 
-Well behaved drivers call pci_map_*() calls before sending command to device
+Well behaved drivers call dma_map_*() calls before sending command to device
 that needs to perform DMA. Once DMA is completed and mapping is no longer
-required, device performs a pci_unmap_*() calls to unmap the region.
+required, device performs a dma_unmap_*() calls to unmap the region.
 
 The Intel IOMMU driver allocates a virtual address per domain. Each PCIE
 device has its own domain (hence protection). Devices under p2p bridges
@@ -68,7 +67,7 @@ address from PCI MMIO ranges so they are not allocated for IOVA addresses.
 
 Fault reporting
 ---------------
-When errors are reported, the DMA engine signals via an interrupt. The fault
+When errors are reported, the IOMMU signals via an interrupt. The fault
 reason and device that caused it with fault reason is printed on console.
 
 See below for sample.
-- 
2.35.1

Re: [PATCH V3 2/2] Documentation: x86: Clarify Intel IOMMU documentation

[Bagas Sanjaya]

On 29/03/22 00.28, Alex Deucher wrote:
> Based on feedback from Robin on the initial AMD IOMMU
> documentation, fix up the Intel documentation to
> clarify IOMMU vs device and modern DMA API.
> 

Maybe we can squash into [1/2]?

-- 
An old man doll... just what I always wanted! - Clara