Commit | Line | Data |
---|---|---|
1a5b5376 TR |
1 | This document describes the generic device tree binding for IOMMUs and their |
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 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 | ||
26 | Device nodes compatible with this binding represent hardware with some of the | |
27 | above capabilities. | |
28 | ||
29 | IOMMUs can be single-master or multiple-master. Single-master IOMMU devices | |
30 | typically have a fixed association to the master device, whereas multiple- | |
31 | master IOMMU devices can translate accesses from more than one master. | |
32 | ||
33 | The 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 | |
35 | IOMMU maps to memory. An empty "dma-ranges" property means that there is a | |
36 | 1:1 mapping from IOMMU to memory. | |
37 | ||
38 | Required properties: | |
39 | -------------------- | |
40 | - #iommu-cells: The number of cells in an IOMMU specifier needed to encode an | |
41 | address. | |
42 | ||
43 | The meaning of the IOMMU specifier is defined by the device tree binding of | |
44 | the 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 | ||
62 | Note that these are merely examples and real-world use-cases may use different | |
63 | definitions to represent their individual needs. Always refer to the specific | |
64 | IOMMU binding for the exact meaning of the cells that make up the specifier. | |
65 | ||
66 | ||
67 | IOMMU master node: | |
68 | ================== | |
69 | ||
70 | Devices that access memory through an IOMMU are called masters. A device can | |
71 | have multiple master interfaces (to one or more IOMMU devices). | |
72 | ||
73 | Required 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 | ||
79 | When an "iommus" property is specified in a device tree node, the IOMMU will | |
80 | be used for address translation. If a "dma-ranges" property exists in the | |
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 the "dma-ranges" property of the | |
83 | parent shall take effect. Note that merely disabling a device tree node does | |
84 | not guarantee that the IOMMU is really disabled since the hardware may not | |
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 first place because it would | |
87 | prevent any driver from properly setting up the translations. | |
88 | ||
89 | ||
90 | Notes: | |
91 | ====== | |
92 | ||
93 | One possible extension to the above is to use an "iommus" property along with | |
94 | a "dma-ranges" property in a bus device node (such as PCI host bridges). This | |
95 | can be useful to describe how children on the bus relate to the IOMMU if they | |
96 | are not explicitly listed in the device tree (e.g. PCI devices). However, the | |
97 | requirements of that use-case haven't been fully determined yet. Implementing | |
98 | this is therefore not recommended without further discussion and extension of | |
99 | this binding. | |
100 | ||
101 | ||
102 | Examples: | |
103 | ========= | |
104 | ||
105 | Single-master IOMMU: | |
106 | -------------------- | |
107 | ||
108 | iommu { | |
109 | #iommu-cells = <0>; | |
110 | }; | |
111 | ||
112 | master { | |
113 | iommus = <&{/iommu}>; | |
114 | }; | |
115 | ||
116 | Multiple-master IOMMU with fixed associations: | |
117 | ---------------------------------------------- | |
118 | ||
119 | /* multiple-master IOMMU */ | |
120 | iommu { | |
121 | /* | |
122 | * Masters are statically associated with this IOMMU and share | |
123 | * the same address translations because the IOMMU does not | |
124 | * have sufficient information to distinguish between masters. | |
125 | * | |
126 | * Consequently address translation is always on or off for | |
127 | * all masters at any given point in time. | |
128 | */ | |
129 | #iommu-cells = <0>; | |
130 | }; | |
131 | ||
132 | /* static association with IOMMU */ | |
133 | master@1 { | |
134 | reg = <1>; | |
135 | iommus = <&{/iommu}>; | |
136 | }; | |
137 | ||
138 | /* static association with IOMMU */ | |
139 | master@2 { | |
140 | reg = <2>; | |
141 | iommus = <&{/iommu}>; | |
142 | }; | |
143 | ||
144 | Multiple-master IOMMU: | |
145 | ---------------------- | |
146 | ||
147 | iommu { | |
148 | /* the specifier represents the ID of the master */ | |
149 | #iommu-cells = <1>; | |
150 | }; | |
151 | ||
152 | master@1 { | |
153 | /* device has master ID 42 in the IOMMU */ | |
154 | iommus = <&{/iommu} 42>; | |
155 | }; | |
156 | ||
157 | master@2 { | |
158 | /* device has master IDs 23 and 24 in the IOMMU */ | |
159 | iommus = <&{/iommu} 23>, <&{/iommu} 24>; | |
160 | }; | |
161 | ||
162 | Multiple-master IOMMU with configurable DMA window: | |
163 | --------------------------------------------------- | |
164 | ||
165 | / { | |
166 | iommu { | |
167 | /* | |
168 | * One cell for the master ID and one cell for the | |
169 | * address of the DMA window. The length of the DMA | |
170 | * window is encoded in two cells. | |
171 | * | |
172 | * The DMA window is the range addressable by the | |
173 | * master (i.e. the I/O virtual address space). | |
174 | */ | |
175 | #iommu-cells = <4>; | |
176 | }; | |
177 | ||
178 | master { | |
179 | /* master ID 42, 4 GiB DMA window starting at 0 */ | |
180 | iommus = <&{/iommu} 42 0 0x1 0x0>; | |
181 | }; | |
182 | }; |