From: Thierry Reding <thierry.reding@gmail.com>
To: Rob Herring <robh+dt@kernel.org>, Pawel Moll <pawel.moll@arm.com>,
Mark Rutland <mark.rutland@arm.com>,
Ian Campbell <ijc+devicetree@hellion.org.uk>,
Kumar Gala <galak@codeaurora.org>,
Stephen Warren <swarren@wwwdotorg.org>,
Arnd Bergmann <arnd@arndb.de>, Will Deacon <will.deacon@arm.com>,
Joerg Roedel <joro@8bytes.org>
Cc: Cho KyongHo <pullip.cho@samsung.com>,
Grant Grundler <grundler@chromium.org>,
Dave Martin <Dave.Martin@arm.com>,
Marc Zyngier <marc.zyngier@arm.com>,
Hiroshi Doyu <hdoyu@nvidia.com>,
Olav Haugan <ohaugan@codeaurora.org>,
Varun Sethi <varun.sethi@freescale.com>,
devicetree@vger.kernel.org, iommu@lists.linux-foundation.org,
linux-arm-kernel@lists.infradead.org,
linux-tegra@vger.kernel.org, linux-kernel@vger.kernel.org
Subject: [PATCH v4] devicetree: Add generic IOMMU device tree bindings
Date: Fri, 4 Jul 2014 17:29:17 +0200 [thread overview]
Message-ID: <1404487757-18829-1-git-send-email-thierry.reding@gmail.com> (raw)
From: Thierry Reding <treding@nvidia.com>
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 <treding@nvidia.com>
---
Changes in v4:
- clarify that disabling an IOMMU DT node may not disable translation
- be more explicit that examples are only examples
- add multi-ID master example
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 | 172 ++++++++++++++++++++++
1 file changed, 172 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..464a81eaaf61
--- /dev/null
+++ b/Documentation/devicetree/bindings/iommu/iommu.txt
@@ -0,0 +1,172 @@
+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.
+
+The meaning of the IOMMU specifier is defined by the device tree binding of
+the specific IOMMU. Below are a few examples of typical use-cases:
+
+- #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. Note that an IOMMU can by design
+ be multi-master yet only expose a single master in a given configuration.
+ In such cases the number of cells will usually be 1 as in the next case.
+- #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. In some cases more than
+ one cell can be required to represent a single master 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.
+
+Note that these are merely examples and real-world use-cases may use different
+definitions to represent their individual needs. Always refer to the specific
+IOMMU binding for the exact meaning of the cells that make up the specifier.
+
+
+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. Note that merely disabling a device tree node does
+not guarantee that the IOMMU is really disabled since the hardware may not
+have a means to turn off translation.
+
+
+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@1 {
+ reg = <1>;
+ iommus = <&/iommu>;
+ };
+
+ /* static association with IOMMU */
+ master@2 {
+ reg = <2>;
+ iommus = <&/iommu>;
+ };
+
+Multiple-master IOMMU:
+----------------------
+
+ iommu {
+ /* the specifier represents the ID of the master */
+ #iommu-cells = <1>;
+ };
+
+ master@1 {
+ /* device has master ID 42 in the IOMMU */
+ iommus = <&/iommu 42>;
+ };
+
+ master@2 {
+ /* device has master IDs 23 and 24 in the IOMMU */
+ iommus = <&/iommu 23>, <&/iommu 24>;
+ };
+
+Multiple-master IOMMU with configurable DMA window:
+---------------------------------------------------
+
+ / {
+ #address-cells = <1>;
+ #size-cells = <1>;
+
+ iommu {
+ /* master ID, address and length of DMA window */
+ #iommu-cells = <4>;
+ };
+
+ master {
+ /* master ID 42, 4 GiB DMA window starting at 0 */
+ iommus = <&/iommu 42 0 0x1 0x0>;
+ };
+ };
--
2.0.1
next reply other threads:[~2014-07-04 15:29 UTC|newest]
Thread overview: 42+ messages / expand[flat|nested] mbox.gz Atom feed top
2014-07-04 15:29 Thierry Reding [this message]
2014-07-09 13:40 ` [PATCH v4] devicetree: Add generic IOMMU device tree bindings Will Deacon
2014-07-09 14:21 ` Thierry Reding
2014-07-09 18:10 ` Will Deacon
2014-07-10 9:49 ` Thierry Reding
2014-07-10 10:23 ` Will Deacon
2014-07-10 10:57 ` Thierry Reding
2014-07-10 12:38 ` Will Deacon
2014-07-11 20:55 ` Rob Clark
2014-07-12 9:39 ` Will Deacon
2014-07-12 11:26 ` Rob Clark
2014-07-12 12:22 ` Arnd Bergmann
2014-07-12 12:57 ` Rob Clark
2014-07-13 9:43 ` Will Deacon
2014-07-13 11:43 ` Rob Clark
2014-07-16 1:25 ` Olav Haugan
2014-07-16 10:10 ` Will Deacon
2014-07-16 20:24 ` Rob Clark
2014-07-14 6:44 ` Thierry Reding
2014-07-14 10:08 ` Will Deacon
2014-07-14 6:24 ` Thierry Reding
2014-07-14 10:13 ` Rob Clark
2014-07-14 6:15 ` Thierry Reding
2014-07-30 11:04 ` Will Deacon
2014-07-30 13:23 ` Thierry Reding
2014-07-30 13:33 ` Joerg Roedel
2014-07-30 17:37 ` Olof Johansson
2014-07-30 14:30 ` Will Deacon
2014-07-30 18:08 ` Rob Herring
2014-07-30 20:11 ` Arnd Bergmann
2014-07-30 15:26 ` Mark Rutland
2014-07-30 17:35 ` Olof Johansson
2014-07-30 18:18 ` Mark Rutland
2014-07-31 10:09 ` Thierry Reding
2014-07-31 10:50 ` Mark Rutland
2014-07-31 11:14 ` Thierry Reding
2014-07-31 9:51 ` Thierry Reding
2014-07-31 8:39 ` Thierry Reding
2014-07-31 9:22 ` Mark Rutland
2014-07-31 10:18 ` Thierry Reding
2014-07-31 10:23 ` Joerg Roedel
2014-07-31 10:46 ` Thierry Reding
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1404487757-18829-1-git-send-email-thierry.reding@gmail.com \
--to=thierry.reding@gmail.com \
--cc=Dave.Martin@arm.com \
--cc=arnd@arndb.de \
--cc=devicetree@vger.kernel.org \
--cc=galak@codeaurora.org \
--cc=grundler@chromium.org \
--cc=hdoyu@nvidia.com \
--cc=ijc+devicetree@hellion.org.uk \
--cc=iommu@lists.linux-foundation.org \
--cc=joro@8bytes.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-tegra@vger.kernel.org \
--cc=marc.zyngier@arm.com \
--cc=mark.rutland@arm.com \
--cc=ohaugan@codeaurora.org \
--cc=pawel.moll@arm.com \
--cc=pullip.cho@samsung.com \
--cc=robh+dt@kernel.org \
--cc=swarren@wwwdotorg.org \
--cc=varun.sethi@freescale.com \
--cc=will.deacon@arm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).