1This document describes the generic device tree binding for IOMMUs and their 2master(s). 3 4 5IOMMU device node: 6================== 7 8An IOMMU can provide the following services: 9 10* Remap address space to allow devices to access physical memory ranges that 11 they otherwise wouldn't be capable of accessing. 12 13 Example: 32-bit DMA to 64-bit physical addresses 14 15* Implement scatter-gather at page level granularity so that the device does 16 not have to. 17 18* Provide system protection against "rogue" DMA by forcing all accesses to go 19 through the IOMMU and faulting when encountering accesses to unmapped 20 address regions. 21 22* Provide address space isolation between multiple contexts. 23 24 Example: Virtualization 25 26Device nodes compatible with this binding represent hardware with some of the 27above capabilities. 28 29IOMMUs can be single-master or multiple-master. Single-master IOMMU devices 30typically have a fixed association to the master device, whereas multiple- 31master IOMMU devices can translate accesses from more than one master. 32 33The device tree node of the IOMMU device's parent bus must contain a valid 34"dma-ranges" property that describes how the physical address space of the 35IOMMU maps to memory. An empty "dma-ranges" property means that there is a 361:1 mapping from IOMMU to memory. 37 38Required properties: 39-------------------- 40- #iommu-cells: The number of cells in an IOMMU specifier needed to encode an 41 address. 42 43The meaning of the IOMMU specifier is defined by the device tree binding of 44the specific IOMMU. Below are a few examples of typical use-cases: 45 46- #iommu-cells = <0>: Single master IOMMU devices are not configurable and 47 therefore no additional information needs to be encoded in the specifier. 48 This may also apply to multiple master IOMMU devices that do not allow the 49 association of masters to be configured. Note that an IOMMU can by design 50 be multi-master yet only expose a single master in a given configuration. 51 In such cases the number of cells will usually be 1 as in the next case. 52- #iommu-cells = <1>: Multiple master IOMMU devices may need to be configured 53 in order to enable translation for a given master. In such cases the single 54 address cell corresponds to the master device's ID. In some cases more than 55 one cell can be required to represent a single master ID. 56- #iommu-cells = <4>: Some IOMMU devices allow the DMA window for masters to 57 be configured. The first cell of the address in this may contain the master 58 device's ID for example, while the second cell could contain the start of 59 the DMA window for the given device. The length of the DMA window is given 60 by the third and fourth cells. 61 62Note that these are merely examples and real-world use-cases may use different 63definitions to represent their individual needs. Always refer to the specific 64IOMMU binding for the exact meaning of the cells that make up the specifier. 65 66 67IOMMU master node: 68================== 69 70Devices that access memory through an IOMMU are called masters. A device can 71have multiple master interfaces (to one or more IOMMU devices). 72 73Required properties: 74-------------------- 75- iommus: A list of phandle and IOMMU specifier pairs that describe the IOMMU 76 master interfaces of the device. One entry in the list describes one master 77 interface of the device. 78 79When an "iommus" property is specified in a device tree node, the IOMMU will 80be used for address translation. If a "dma-ranges" property exists in the 81device's parent node it will be ignored. An exception to this rule is if the 82referenced IOMMU is disabled, in which case the "dma-ranges" property of the 83parent shall take effect. Note that merely disabling a device tree node does 84not guarantee that the IOMMU is really disabled since the hardware may not 85have a means to turn off translation. But it is invalid in such cases to 86disable the IOMMU's device tree node in the first place because it would 87prevent any driver from properly setting up the translations. 88 89Optional properties: 90-------------------- 91- pasid-num-bits: Some masters support multiple address spaces for DMA, by 92 tagging DMA transactions with an address space identifier. By default, 93 this is 0, which means that the device only has one address space. 94 95- dma-can-stall: When present, the master can wait for a transaction to 96 complete for an indefinite amount of time. Upon translation fault some 97 IOMMUs, instead of aborting the translation immediately, may first 98 notify the driver and keep the transaction in flight. This allows the OS 99 to inspect the fault and, for example, make physical pages resident 100 before updating the mappings and completing the transaction. Such IOMMU 101 accepts a limited number of simultaneous stalled transactions before 102 having to either put back-pressure on the master, or abort new faulting 103 transactions. 104 105 Firmware has to opt-in stalling, because most buses and masters don't 106 support it. In particular it isn't compatible with PCI, where 107 transactions have to complete before a time limit. More generally it 108 won't work in systems and masters that haven't been designed for 109 stalling. For example the OS, in order to handle a stalled transaction, 110 may attempt to retrieve pages from secondary storage in a stalled 111 domain, leading to a deadlock. 112 113 114Notes: 115====== 116 117One possible extension to the above is to use an "iommus" property along with 118a "dma-ranges" property in a bus device node (such as PCI host bridges). This 119can be useful to describe how children on the bus relate to the IOMMU if they 120are not explicitly listed in the device tree (e.g. PCI devices). However, the 121requirements of that use-case haven't been fully determined yet. Implementing 122this is therefore not recommended without further discussion and extension of 123this binding. 124 125 126Examples: 127========= 128 129Single-master IOMMU: 130-------------------- 131 132 iommu { 133 #iommu-cells = <0>; 134 }; 135 136 master { 137 iommus = <&{/iommu}>; 138 }; 139 140Multiple-master IOMMU with fixed associations: 141---------------------------------------------- 142 143 /* multiple-master IOMMU */ 144 iommu { 145 /* 146 * Masters are statically associated with this IOMMU and share 147 * the same address translations because the IOMMU does not 148 * have sufficient information to distinguish between masters. 149 * 150 * Consequently address translation is always on or off for 151 * all masters at any given point in time. 152 */ 153 #iommu-cells = <0>; 154 }; 155 156 /* static association with IOMMU */ 157 master@1 { 158 reg = <1>; 159 iommus = <&{/iommu}>; 160 }; 161 162 /* static association with IOMMU */ 163 master@2 { 164 reg = <2>; 165 iommus = <&{/iommu}>; 166 }; 167 168Multiple-master IOMMU: 169---------------------- 170 171 iommu { 172 /* the specifier represents the ID of the master */ 173 #iommu-cells = <1>; 174 }; 175 176 master@1 { 177 /* device has master ID 42 in the IOMMU */ 178 iommus = <&{/iommu} 42>; 179 }; 180 181 master@2 { 182 /* device has master IDs 23 and 24 in the IOMMU */ 183 iommus = <&{/iommu} 23>, <&{/iommu} 24>; 184 }; 185 186Multiple-master IOMMU with configurable DMA window: 187--------------------------------------------------- 188 189 / { 190 iommu { 191 /* 192 * One cell for the master ID and one cell for the 193 * address of the DMA window. The length of the DMA 194 * window is encoded in two cells. 195 * 196 * The DMA window is the range addressable by the 197 * master (i.e. the I/O virtual address space). 198 */ 199 #iommu-cells = <4>; 200 }; 201 202 master { 203 /* master ID 42, 4 GiB DMA window starting at 0 */ 204 iommus = <&{/iommu} 42 0 0x1 0x0>; 205 }; 206 }; 207