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
96Notes:
97======
98
99One possible extension to the above is to use an "iommus" property along with
100a "dma-ranges" property in a bus device node (such as PCI host bridges). This
101can be useful to describe how children on the bus relate to the IOMMU if they
102are not explicitly listed in the device tree (e.g. PCI devices). However, the
103requirements of that use-case haven't been fully determined yet. Implementing
104this is therefore not recommended without further discussion and extension of
105this binding.
106
107
108Examples:
109=========
110
111Single-master IOMMU:
112--------------------
113
114	iommu {
115		#iommu-cells = <0>;
116	};
117
118	master {
119		iommus = <&{/iommu}>;
120	};
121
122Multiple-master IOMMU with fixed associations:
123----------------------------------------------
124
125	/* multiple-master IOMMU */
126	iommu {
127		/*
128		 * Masters are statically associated with this IOMMU and share
129		 * the same address translations because the IOMMU does not
130		 * have sufficient information to distinguish between masters.
131		 *
132		 * Consequently address translation is always on or off for
133		 * all masters at any given point in time.
134		 */
135		#iommu-cells = <0>;
136	};
137
138	/* static association with IOMMU */
139	master@1 {
140		reg = <1>;
141		iommus = <&{/iommu}>;
142	};
143
144	/* static association with IOMMU */
145	master@2 {
146		reg = <2>;
147		iommus = <&{/iommu}>;
148	};
149
150Multiple-master IOMMU:
151----------------------
152
153	iommu {
154		/* the specifier represents the ID of the master */
155		#iommu-cells = <1>;
156	};
157
158	master@1 {
159		/* device has master ID 42 in the IOMMU */
160		iommus = <&{/iommu} 42>;
161	};
162
163	master@2 {
164		/* device has master IDs 23 and 24 in the IOMMU */
165		iommus = <&{/iommu} 23>, <&{/iommu} 24>;
166	};
167
168Multiple-master IOMMU with configurable DMA window:
169---------------------------------------------------
170
171	/ {
172		iommu {
173			/*
174			 * One cell for the master ID and one cell for the
175			 * address of the DMA window. The length of the DMA
176			 * window is encoded in two cells.
177			 *
178			 * The DMA window is the range addressable by the
179			 * master (i.e. the I/O virtual address space).
180			 */
181			#iommu-cells = <4>;
182		};
183
184		master {
185			/* master ID 42, 4 GiB DMA window starting at 0 */
186			iommus = <&{/iommu}  42  0  0x1 0x0>;
187		};
188	};
189