0001 This document describes the generic device tree binding for IOMMUs and their
0002 master(s).
0003
0004
0005 IOMMU device node:
0006 ==================
0007
0008 An IOMMU can provide the following services:
0009
0010 * Remap address space to allow devices to access physical memory ranges that
0011 they otherwise wouldn't be capable of accessing.
0012
0013 Example: 32-bit DMA to 64-bit physical addresses
0014
0015 * Implement scatter-gather at page level granularity so that the device does
0016 not have to.
0017
0018 * Provide system protection against "rogue" DMA by forcing all accesses to go
0019 through the IOMMU and faulting when encountering accesses to unmapped
0020 address regions.
0021
0022 * Provide address space isolation between multiple contexts.
0023
0024 Example: Virtualization
0025
0026 Device nodes compatible with this binding represent hardware with some of the
0027 above capabilities.
0028
0029 IOMMUs can be single-master or multiple-master. Single-master IOMMU devices
0030 typically have a fixed association to the master device, whereas multiple-
0031 master IOMMU devices can translate accesses from more than one master.
0032
0033 The device tree node of the IOMMU device's parent bus must contain a valid
0034 "dma-ranges" property that describes how the physical address space of the
0035 IOMMU maps to memory. An empty "dma-ranges" property means that there is a
0036 1:1 mapping from IOMMU to memory.
0037
0038 Required properties:
0039 --------------------
0040 - #iommu-cells: The number of cells in an IOMMU specifier needed to encode an
0041 address.
0042
0043 The meaning of the IOMMU specifier is defined by the device tree binding of
0044 the specific IOMMU. Below are a few examples of typical use-cases:
0045
0046 - #iommu-cells = <0>: Single master IOMMU devices are not configurable and
0047 therefore no additional information needs to be encoded in the specifier.
0048 This may also apply to multiple master IOMMU devices that do not allow the
0049 association of masters to be configured. Note that an IOMMU can by design
0050 be multi-master yet only expose a single master in a given configuration.
0051 In such cases the number of cells will usually be 1 as in the next case.
0052 - #iommu-cells = <1>: Multiple master IOMMU devices may need to be configured
0053 in order to enable translation for a given master. In such cases the single
0054 address cell corresponds to the master device's ID. In some cases more than
0055 one cell can be required to represent a single master ID.
0056 - #iommu-cells = <4>: Some IOMMU devices allow the DMA window for masters to
0057 be configured. The first cell of the address in this may contain the master
0058 device's ID for example, while the second cell could contain the start of
0059 the DMA window for the given device. The length of the DMA window is given
0060 by the third and fourth cells.
0061
0062 Note that these are merely examples and real-world use-cases may use different
0063 definitions to represent their individual needs. Always refer to the specific
0064 IOMMU binding for the exact meaning of the cells that make up the specifier.
0065
0066
0067 IOMMU master node:
0068 ==================
0069
0070 Devices that access memory through an IOMMU are called masters. A device can
0071 have multiple master interfaces (to one or more IOMMU devices).
0072
0073 Required properties:
0074 --------------------
0075 - iommus: A list of phandle and IOMMU specifier pairs that describe the IOMMU
0076 master interfaces of the device. One entry in the list describes one master
0077 interface of the device.
0078
0079 When an "iommus" property is specified in a device tree node, the IOMMU will
0080 be used for address translation. If a "dma-ranges" property exists in the
0081 device's parent node it will be ignored. An exception to this rule is if the
0082 referenced IOMMU is disabled, in which case the "dma-ranges" property of the
0083 parent shall take effect. Note that merely disabling a device tree node does
0084 not guarantee that the IOMMU is really disabled since the hardware may not
0085 have a means to turn off translation. But it is invalid in such cases to
0086 disable the IOMMU's device tree node in the first place because it would
0087 prevent any driver from properly setting up the translations.
0088
0089 Optional properties:
0090 --------------------
0091 - pasid-num-bits: Some masters support multiple address spaces for DMA, by
0092 tagging DMA transactions with an address space identifier. By default,
0093 this is 0, which means that the device only has one address space.
0094
0095 - dma-can-stall: When present, the master can wait for a transaction to
0096 complete for an indefinite amount of time. Upon translation fault some
0097 IOMMUs, instead of aborting the translation immediately, may first
0098 notify the driver and keep the transaction in flight. This allows the OS
0099 to inspect the fault and, for example, make physical pages resident
0100 before updating the mappings and completing the transaction. Such IOMMU
0101 accepts a limited number of simultaneous stalled transactions before
0102 having to either put back-pressure on the master, or abort new faulting
0103 transactions.
0104
0105 Firmware has to opt-in stalling, because most buses and masters don't
0106 support it. In particular it isn't compatible with PCI, where
0107 transactions have to complete before a time limit. More generally it
0108 won't work in systems and masters that haven't been designed for
0109 stalling. For example the OS, in order to handle a stalled transaction,
0110 may attempt to retrieve pages from secondary storage in a stalled
0111 domain, leading to a deadlock.
0112
0113
0114 Notes:
0115 ======
0116
0117 One possible extension to the above is to use an "iommus" property along with
0118 a "dma-ranges" property in a bus device node (such as PCI host bridges). This
0119 can be useful to describe how children on the bus relate to the IOMMU if they
0120 are not explicitly listed in the device tree (e.g. PCI devices). However, the
0121 requirements of that use-case haven't been fully determined yet. Implementing
0122 this is therefore not recommended without further discussion and extension of
0123 this binding.
0124
0125
0126 Examples:
0127 =========
0128
0129 Single-master IOMMU:
0130 --------------------
0131
0132 iommu {
0133 #iommu-cells = <0>;
0134 };
0135
0136 master {
0137 iommus = <&{/iommu}>;
0138 };
0139
0140 Multiple-master IOMMU with fixed associations:
0141 ----------------------------------------------
0142
0143 /* multiple-master IOMMU */
0144 iommu {
0145 /*
0146 * Masters are statically associated with this IOMMU and share
0147 * the same address translations because the IOMMU does not
0148 * have sufficient information to distinguish between masters.
0149 *
0150 * Consequently address translation is always on or off for
0151 * all masters at any given point in time.
0152 */
0153 #iommu-cells = <0>;
0154 };
0155
0156 /* static association with IOMMU */
0157 master@1 {
0158 reg = <1>;
0159 iommus = <&{/iommu}>;
0160 };
0161
0162 /* static association with IOMMU */
0163 master@2 {
0164 reg = <2>;
0165 iommus = <&{/iommu}>;
0166 };
0167
0168 Multiple-master IOMMU:
0169 ----------------------
0170
0171 iommu {
0172 /* the specifier represents the ID of the master */
0173 #iommu-cells = <1>;
0174 };
0175
0176 master@1 {
0177 /* device has master ID 42 in the IOMMU */
0178 iommus = <&{/iommu} 42>;
0179 };
0180
0181 master@2 {
0182 /* device has master IDs 23 and 24 in the IOMMU */
0183 iommus = <&{/iommu} 23>, <&{/iommu} 24>;
0184 };
0185
0186 Multiple-master IOMMU with configurable DMA window:
0187 ---------------------------------------------------
0188
0189 / {
0190 iommu {
0191 /*
0192 * One cell for the master ID and one cell for the
0193 * address of the DMA window. The length of the DMA
0194 * window is encoded in two cells.
0195 *
0196 * The DMA window is the range addressable by the
0197 * master (i.e. the I/O virtual address space).
0198 */
0199 #iommu-cells = <4>;
0200 };
0201
0202 master {
0203 /* master ID 42, 4 GiB DMA window starting at 0 */
0204 iommus = <&{/iommu} 42 0 0x1 0x0>;
0205 };
0206 };
