About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / devicetree / bindings / iommu




Custom Search

Based on kernel version 4.1. Page generated on 2015-06-28 12:09 EST.

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		};
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.