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