1 This document describes the generic device tre
2 master(s).
3
4
5 IOMMU device node:
6 ==================
7
8 An IOMMU can provide the following services:
9
10 * Remap address space to allow devices to acce
11 they otherwise wouldn't be capable of access
12
13 Example: 32-bit DMA to 64-bit physical addre
14
15 * Implement scatter-gather at page level granu
16 not have to.
17
18 * Provide system protection against "rogue" DM
19 through the IOMMU and faulting when encounte
20 address regions.
21
22 * Provide address space isolation between mult
23
24 Example: Virtualization
25
26 Device nodes compatible with this binding repr
27 above capabilities.
28
29 IOMMUs can be single-master or multiple-master
30 typically have a fixed association to the mast
31 master IOMMU devices can translate accesses fr
32
33 The device tree node of the IOMMU device's par
34 "dma-ranges" property that describes how the p
35 IOMMU maps to memory. An empty "dma-ranges" pr
36 1:1 mapping from IOMMU to memory.
37
38 Required properties:
39 --------------------
40 - #iommu-cells: The number of cells in an IOMM
41 address.
42
43 The meaning of the IOMMU specifier is defined
44 the specific IOMMU. Below are a few examples o
45
46 - #iommu-cells = <0>: Single master IOMMU devi
47 therefore no additional information needs to
48 This may also apply to multiple master IOMMU
49 association of masters to be configured. Not
50 be multi-master yet only expose a single mas
51 In such cases the number of cells will usual
52 - #iommu-cells = <1>: Multiple master IOMMU de
53 in order to enable translation for a given m
54 address cell corresponds to the master devic
55 one cell can be required to represent a sing
56 - #iommu-cells = <4>: Some IOMMU devices allow
57 be configured. The first cell of the address
58 device's ID for example, while the second ce
59 the DMA window for the given device. The len
60 by the third and fourth cells.
61
62 Note that these are merely examples and real-w
63 definitions to represent their individual need
64 IOMMU binding for the exact meaning of the cel
65
66
67 IOMMU master node:
68 ==================
69
70 Devices that access memory through an IOMMU ar
71 have multiple master interfaces (to one or mor
72
73 Required properties:
74 --------------------
75 - iommus: A list of phandle and IOMMU specifie
76 master interfaces of the device. One entry i
77 interface of the device.
78
79 When an "iommus" property is specified in a de
80 be used for address translation. If a "dma-ran
81 device's parent node it will be ignored. An ex
82 referenced IOMMU is disabled, in which case th
83 parent shall take effect. Note that merely dis
84 not guarantee that the IOMMU is really disable
85 have a means to turn off translation. But it i
86 disable the IOMMU's device tree node in the fi
87 prevent any driver from properly setting up th
88
89 Optional properties:
90 --------------------
91 - pasid-num-bits: Some masters support multipl
92 tagging DMA transactions with an address spa
93 this is 0, which means that the device only
94
95 - dma-can-stall: When present, the master can
96 complete for an indefinite amount of time. U
97 IOMMUs, instead of aborting the translation
98 notify the driver and keep the transaction i
99 to inspect the fault and, for example, make
100 before updating the mappings and completing
101 accepts a limited number of simultaneous sta
102 having to either put back-pressure on the ma
103 transactions.
104
105 Firmware has to opt-in stalling, because mos
106 support it. In particular it isn't compatibl
107 transactions have to complete before a time
108 won't work in systems and masters that haven
109 stalling. For example the OS, in order to ha
110 may attempt to retrieve pages from secondary
111 domain, leading to a deadlock.
112
113
114 Notes:
115 ======
116
117 One possible extension to the above is to use
118 a "dma-ranges" property in a bus device node (
119 can be useful to describe how children on the
120 are not explicitly listed in the device tree (
121 requirements of that use-case haven't been ful
122 this is therefore not recommended without furt
123 this binding.
124
125
126 Examples:
127 =========
128
129 Single-master IOMMU:
130 --------------------
131
132 iommu {
133 #iommu-cells = <0>;
134 };
135
136 master {
137 iommus = <&{/iommu}>;
138 };
139
140 Multiple-master IOMMU with fixed associations:
141 ----------------------------------------------
142
143 /* multiple-master IOMMU */
144 iommu {
145 /*
146 * Masters are statically asso
147 * the same address translatio
148 * have sufficient information
149 *
150 * Consequently address transl
151 * all masters at any given po
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
168 Multiple-master IOMMU:
169 ----------------------
170
171 iommu {
172 /* the specifier represents th
173 #iommu-cells = <1>;
174 };
175
176 master@1 {
177 /* device has master ID 42 in
178 iommus = <&{/iommu} 42>;
179 };
180
181 master@2 {
182 /* device has master IDs 23 an
183 iommus = <&{/iommu} 23>, <&{/i
184 };
185
186 Multiple-master IOMMU with configurable DMA wi
187 ----------------------------------------------
188
189 / {
190 iommu {
191 /*
192 * One cell for the ma
193 * address of the DMA
194 * window is encoded i
195 *
196 * The DMA window is t
197 * master (i.e. the I/
198 */
199 #iommu-cells = <4>;
200 };
201
202 master {
203 /* master ID 42, 4 GiB
204 iommus = <&{/iommu} 4
205 };
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.