tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
1This document describes the generic device tree binding for describing the
2relationship between PCI(e) devices and IOMMU(s).
3
4Each PCI(e) device under a root complex is uniquely identified by its Requester
5ID (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
6Function number.
7
8For the purpose of this document, when treated as a numeric value, a RID is
9formatted 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
16IOMMUs may distinguish PCI devices through sideband data derived from the
17Requester ID. While a given PCI device can only master through one IOMMU, a
18root complex may split masters across a set of IOMMUs (e.g. with one IOMMU per
19bus).
20
21The generic 'iommus' property is insufficient to describe this relationship,
22and a mechanism is required to map from a PCI device to its IOMMU and sideband
23data.
24
25For generic IOMMU bindings, see
26Documentation/devicetree/bindings/iommu/iommu.txt.
27
28
29PCI root complex
30================
31
32Optional 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
48Example (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
75Example (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
103Example (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
131Example (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};