Commit | Line | Data |
---|---|---|
6ec2392c MR |
1 | This document describes the generic device tree binding for describing the |
2 | relationship between PCI(e) devices and IOMMU(s). | |
3 | ||
4 | Each PCI(e) device under a root complex is uniquely identified by its Requester | |
5 | ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and | |
6 | Function number. | |
7 | ||
8 | For the purpose of this document, when treated as a numeric value, a RID is | |
9 | formatted such that: | |
10 | ||
11 | * Bits [15:8] are the Bus number. | |
12 | * Bits [7:3] are the Device number. | |
13 | * Bits [2:0] are the Function number. | |
14 | * Any other bits required for padding must be zero. | |
15 | ||
16 | IOMMUs may distinguish PCI devices through sideband data derived from the | |
17 | Requester ID. While a given PCI device can only master through one IOMMU, a | |
18 | root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per | |
19 | bus). | |
20 | ||
21 | The generic 'iommus' property is insufficient to describe this relationship, | |
22 | and a mechanism is required to map from a PCI device to its IOMMU and sideband | |
23 | data. | |
24 | ||
25 | For generic IOMMU bindings, see | |
26 | Documentation/devicetree/bindings/iommu/iommu.txt. | |
27 | ||
28 | ||
29 | PCI root complex | |
30 | ================ | |
31 | ||
32 | Optional properties | |
33 | ------------------- | |
34 | ||
35 | - iommu-map: Maps a Requester ID to an IOMMU and associated iommu-specifier | |
36 | data. | |
37 | ||
38 | The property is an arbitrary number of tuples of | |
39 | (rid-base,iommu,iommu-base,length). | |
40 | ||
41 | Any RID r in the interval [rid-base, rid-base + length) is associated with | |
42 | the listed IOMMU, with the iommu-specifier (r - rid-base + iommu-base). | |
43 | ||
44 | - iommu-map-mask: A mask to be applied to each Requester ID prior to being | |
45 | mapped to an iommu-specifier per the iommu-map property. | |
46 | ||
47 | ||
48 | Example (1) | |
49 | =========== | |
50 | ||
51 | / { | |
52 | #address-cells = <1>; | |
53 | #size-cells = <1>; | |
54 | ||
55 | iommu: iommu@a { | |
56 | reg = <0xa 0x1>; | |
57 | compatible = "vendor,some-iommu"; | |
58 | #iommu-cells = <1>; | |
59 | }; | |
60 | ||
61 | pci: pci@f { | |
62 | reg = <0xf 0x1>; | |
63 | compatible = "vendor,pcie-root-complex"; | |
64 | device_type = "pci"; | |
65 | ||
66 | /* | |
67 | * The sideband data provided to the IOMMU is the RID, | |
68 | * identity-mapped. | |
69 | */ | |
70 | iommu-map = <0x0 &iommu 0x0 0x10000>; | |
71 | }; | |
72 | }; | |
73 | ||
74 | ||
75 | Example (2) | |
76 | =========== | |
77 | ||
78 | / { | |
79 | #address-cells = <1>; | |
80 | #size-cells = <1>; | |
81 | ||
82 | iommu: iommu@a { | |
83 | reg = <0xa 0x1>; | |
84 | compatible = "vendor,some-iommu"; | |
85 | #iommu-cells = <1>; | |
86 | }; | |
87 | ||
88 | pci: pci@f { | |
89 | reg = <0xf 0x1>; | |
90 | compatible = "vendor,pcie-root-complex"; | |
91 | device_type = "pci"; | |
92 | ||
93 | /* | |
94 | * The sideband data provided to the IOMMU is the RID with the | |
95 | * function bits masked out. | |
96 | */ | |
97 | iommu-map = <0x0 &iommu 0x0 0x10000>; | |
98 | iommu-map-mask = <0xfff8>; | |
99 | }; | |
100 | }; | |
101 | ||
102 | ||
103 | Example (3) | |
104 | =========== | |
105 | ||
106 | / { | |
107 | #address-cells = <1>; | |
108 | #size-cells = <1>; | |
109 | ||
110 | iommu: iommu@a { | |
111 | reg = <0xa 0x1>; | |
112 | compatible = "vendor,some-iommu"; | |
113 | #iommu-cells = <1>; | |
114 | }; | |
115 | ||
116 | pci: pci@f { | |
117 | reg = <0xf 0x1>; | |
118 | compatible = "vendor,pcie-root-complex"; | |
119 | device_type = "pci"; | |
120 | ||
121 | /* | |
122 | * The sideband data provided to the IOMMU is the RID, | |
123 | * but the high bits of the bus number are flipped. | |
124 | */ | |
125 | iommu-map = <0x0000 &iommu 0x8000 0x8000>, | |
126 | <0x8000 &iommu 0x0000 0x8000>; | |
127 | }; | |
128 | }; | |
129 | ||
130 | ||
131 | Example (4) | |
132 | =========== | |
133 | ||
134 | / { | |
135 | #address-cells = <1>; | |
136 | #size-cells = <1>; | |
137 | ||
138 | iommu_a: iommu@a { | |
139 | reg = <0xa 0x1>; | |
140 | compatible = "vendor,some-iommu"; | |
141 | #iommu-cells = <1>; | |
142 | }; | |
143 | ||
144 | iommu_b: iommu@b { | |
145 | reg = <0xb 0x1>; | |
146 | compatible = "vendor,some-iommu"; | |
147 | #iommu-cells = <1>; | |
148 | }; | |
149 | ||
150 | iommu_c: iommu@c { | |
151 | reg = <0xc 0x1>; | |
152 | compatible = "vendor,some-iommu"; | |
153 | #iommu-cells = <1>; | |
154 | }; | |
155 | ||
156 | pci: pci@f { | |
157 | reg = <0xf 0x1>; | |
158 | compatible = "vendor,pcie-root-complex"; | |
159 | device_type = "pci"; | |
160 | ||
161 | /* | |
162 | * Devices with bus number 0-127 are mastered via IOMMU | |
163 | * a, with sideband data being RID[14:0]. | |
164 | * Devices with bus number 128-255 are mastered via | |
165 | * IOMMU b, with sideband data being RID[14:0]. | |
166 | * No devices master via IOMMU c. | |
167 | */ | |
168 | iommu-map = <0x0000 &iommu_a 0x0000 0x8000>, | |
169 | <0x8000 &iommu_b 0x0000 0x8000>; | |
170 | }; | |
171 | }; |