-----Original Message-----
From: iommu-bounces at lists.linux-foundation.org [mailto:iommu-
bounces at lists.linux-foundation.org] On Behalf Of Thierry Reding
Sent: Friday, June 27, 2014 2:20 AM
To: Rob Herring; Pawel Moll; Mark Rutland; Ian Campbell; Kumar Gala;
Stephen Warren; Arnd Bergmann; Will Deacon; Joerg Roedel
Cc: Olav Haugan; devicetree at vger.kernel.org; Grant Grundler; Rhyland
Klein; iommu at lists.linux-foundation.org; linux-kernel at vger.kernel.org;
Marc Zyngier; Allen Martin; Paul Walmsley; linux-tegra at vger.kernel.org;
Cho KyongHo; Dave Martin; linux-arm-kernel at lists.infradead.org
Subject: [PATCH v3 02/10] devicetree: Add generic IOMMU device tree
bindings

From: Thierry Reding <redacted>

This commit introduces a generic device tree binding for IOMMU devices.
Only a very minimal subset is described here, but it is enough to cover
the requirements of both the Exynos System MMU and Tegra SMMU as
discussed here:

    https://lkml.org/lkml/2014/4/27/346

Signed-off-by: Thierry Reding <redacted>
---
Changes in v3:
- use #iommu-cells instead of #address-cells/#size-cells
- drop optional iommu-names property

Changes in v2:
- add notes about "dma-ranges" property (drop note from commit message)
- document priorities of "iommus" property vs. "dma-ranges" property
- drop #iommu-cells in favour of #address-cells and #size-cells
- remove multiple-master device example

 Documentation/devicetree/bindings/iommu/iommu.txt | 156
++++++++++++++++++++++
 1 file changed, 156 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/iommu/iommu.txt

diff --git a/Documentation/devicetree/bindings/iommu/iommu.txt

b/Documentation/devicetree/bindings/iommu/iommu.txt
new file mode 100644
index 000000000000..f8f03f057156

--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/iommu.txt

@@ -0,0 +1,156 @@
+This document describes the generic device tree binding for IOMMUs and
+their master(s).
+
+
+IOMMU device node:
+==================
+
+An IOMMU can provide the following services:
+
+* Remap address space to allow devices to access physical memory ranges
+that
+  they otherwise wouldn't be capable of accessing.
+
+  Example: 32-bit DMA to 64-bit physical addresses
+
+* Implement scatter-gather at page level granularity so that the device
+does
+  not have to.
+
+* Provide system protection against "rogue" DMA by forcing all accesses
+to go
+  through the IOMMU and faulting when encountering accesses to unmapped
+  address regions.
+
+* Provide address space isolation between multiple contexts.
+
+  Example: Virtualization
+
+Device nodes compatible with this binding represent hardware with some
+of the above capabilities.
+
+IOMMUs can be single-master or multiple-master. Single-master IOMMU
+devices typically have a fixed association to the master device,
+whereas multiple- master IOMMU devices can translate accesses from more

than one master.
+
+The device tree node of the IOMMU device's parent bus must contain a
+valid "dma-ranges" property that describes how the physical address
+space of the IOMMU maps to memory. An empty "dma-ranges" property means
+that there is a
+1:1 mapping from IOMMU to memory.
+
+Required properties:
+--------------------
+- #iommu-cells: The number of cells in an IOMMU specifier needed to
+encode an
+  address.
+
+Typical values for the above include:
+- #iommu-cells = <0>: Single master IOMMU devices are not configurable
+and
+  therefore no additional information needs to be encoded in the
specifier.
+  This may also apply to multiple master IOMMU devices that do not
+allow the
+  association of masters to be configured.
+- #iommu-cells = <1>: Multiple master IOMMU devices may need to be
+configured
+  in order to enable translation for a given master. In such cases the
+single
+  address cell corresponds to the master device's ID.
+- #iommu-cells = <4>: Some IOMMU devices allow the DMA window for
+masters to
+  be configured. The first cell of the address in this may contain the
+master
+  device's ID for example, while the second cell could contain the
+start of
+  the DMA window for the given device. The length of the DMA window is
+given
+  by the third and fourth cells.
+
+
+IOMMU master node:
+==================
+
+Devices that access memory through an IOMMU are called masters. A
+device can have multiple master interfaces (to one or more IOMMU
devices).
+
+Required properties:
+--------------------
+- iommus: A list of phandle and IOMMU specifier pairs that describe the
+IOMMU
+  master interfaces of the device. One entry in the list describes one
+master
+  interface of the device.
+
+When an "iommus" property is specified in a device tree node, the IOMMU
+will be used for address translation. If a "dma-ranges" property exists
+in the device's parent node it will be ignored. An exception to this
+rule is if the referenced IOMMU is disabled, in which case the
+"dma-ranges" property of the parent shall take effect.
+
+
+Notes:
+======
+
+One possible extension to the above is to use an "iommus" property
+along with a "dma-ranges" property in a bus device node (such as PCI
+host bridges). This can be useful to describe how children on the bus
+relate to the IOMMU if they are not explicitly listed in the device
+tree (e.g. PCI devices). However, the requirements of that use-case
+haven't been fully determined yet. Implementing this is therefore not
+recommended without further discussion and extension of this binding.
+
+
+Examples:
+=========
+
+Single-master IOMMU:
+--------------------
+
+	iommu {
+		#iommu-cells = <0>;
+	};
+
+	master {
+		iommus = <&/iommu>;
+	};
+
+Multiple-master IOMMU with fixed associations:
+----------------------------------------------
+
+	/* multiple-master IOMMU */
+	iommu {
+		/*
+		 * Masters are statically associated with this IOMMU and
+		 * address translation is always enabled.
+		 */
+		#iommu-cells = <0>;
+	};
+
+	/* static association with IOMMU */
+	master at 1 {
+		reg = <1>;
+		iommus = <&/iommu>;
+	};
+
+	/* static association with IOMMU */
+	master at 2 {
+		reg = <2>;
+		iommus = <&/iommu>;
+	};
+
+Multiple-master IOMMU:
+----------------------
+
+	iommu {
+		/* the specifier represents the ID of the master */
+		#iommu-cells = <1>;
+	};
+
+	master {
+		/* device has master ID 42 in the IOMMU */
+		iommus = <&/iommu 42>;
+	};
+