1 This document describes the generic device tree binding for describing the
2 relationship between PCI devices and MSI controllers.
3
4 Each PCI device under a root complex is uniquely identified by its Requester ID
5 (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 MSIs may be distinguished in part through the use of sideband data accompanying
17 writes. In the case of PCI devices, this sideband data may be derived from the
18 Requester ID. A mechanism is required to associate a device with both the MSI
19 controllers it can address, and the sideband data that will be associated with
20 its writes to those controllers.
21
22 For generic MSI bindings, see
23 Documentation/devicetree/bindings/interrupt-controller/msi.txt.
24
25
26 PCI root complex
27 ================
28
29 Optional properties
30 -------------------
31
32 - msi-map: Maps a Requester ID to an MSI controller and associated
33 msi-specifier data. The property is an arbitrary number of tuples of
34 (rid-base,msi-controller,msi-base,length), where:
35
36 * rid-base is a single cell describing the first RID matched by the entry.
37
38 * msi-controller is a single phandle to an MSI controller
39
40 * msi-base is an msi-specifier describing the msi-specifier produced for the
41 first RID matched by the entry.
42
43 * length is a single cell describing how many consecutive RIDs are matched
44 following the rid-base.
45
46 Any RID r in the interval [rid-base, rid-base + length) is associated with
47 the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
48
49 - msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
50 to an msi-specifier per the msi-map property.
51
52 - msi-parent: Describes the MSI parent of the root complex itself. Where
53 the root complex and MSI controller do not pass sideband data with MSI
54 writes, this property may be used to describe the MSI controller(s)
55 used by PCI devices under the root complex, if defined as such in the
56 binding for the root complex.
57
58
59 Example (1)
60 ===========
61
62 / {
63 #address-cells = <1>;
64 #size-cells = <1>;
65
66 msi: msi-controller@a {
67 reg = <0xa 0x1>;
68 compatible = "vendor,some-controller";
69 msi-controller;
70 #msi-cells = <1>;
71 };
72
73 pci: pci@f {
74 reg = <0xf 0x1>;
75 compatible = "vendor,pcie-root-complex";
76 device_type = "pci";
77
78 /*
79 * The sideband data provided to the MSI controller is
80 * the RID, identity-mapped.
81 */
82 msi-map = <0x0 &msi_a 0x0 0x10000>,
83 };
84 };
85
86
87 Example (2)
88 ===========
89
90 / {
91 #address-cells = <1>;
92 #size-cells = <1>;
93
94 msi: msi-controller@a {
95 reg = <0xa 0x1>;
96 compatible = "vendor,some-controller";
97 msi-controller;
98 #msi-cells = <1>;
99 };
100
101 pci: pci@f {
102 reg = <0xf 0x1>;
103 compatible = "vendor,pcie-root-complex";
104 device_type = "pci";
105
106 /*
107 * The sideband data provided to the MSI controller is
108 * the RID, masked to only the device and function bits.
109 */
110 msi-map = <0x0 &msi_a 0x0 0x100>,
111 msi-map-mask = <0xff>
112 };
113 };
114
115
116 Example (3)
117 ===========
118
119 / {
120 #address-cells = <1>;
121 #size-cells = <1>;
122
123 msi: msi-controller@a {
124 reg = <0xa 0x1>;
125 compatible = "vendor,some-controller";
126 msi-controller;
127 #msi-cells = <1>;
128 };
129
130 pci: pci@f {
131 reg = <0xf 0x1>;
132 compatible = "vendor,pcie-root-complex";
133 device_type = "pci";
134
135 /*
136 * The sideband data provided to the MSI controller is
137 * the RID, but the high bit of the bus number is
138 * ignored.
139 */
140 msi-map = <0x0000 &msi 0x0000 0x8000>,
141 <0x8000 &msi 0x0000 0x8000>;
142 };
143 };
144
145
146 Example (4)
147 ===========
148
149 / {
150 #address-cells = <1>;
151 #size-cells = <1>;
152
153 msi: msi-controller@a {
154 reg = <0xa 0x1>;
155 compatible = "vendor,some-controller";
156 msi-controller;
157 #msi-cells = <1>;
158 };
159
160 pci: pci@f {
161 reg = <0xf 0x1>;
162 compatible = "vendor,pcie-root-complex";
163 device_type = "pci";
164
165 /*
166 * The sideband data provided to the MSI controller is
167 * the RID, but the high bit of the bus number is
168 * negated.
169 */
170 msi-map = <0x0000 &msi 0x8000 0x8000>,
171 <0x8000 &msi 0x0000 0x8000>;
172 };
173 };
174
175
176 Example (5)
177 ===========
178
179 / {
180 #address-cells = <1>;
181 #size-cells = <1>;
182
183 msi_a: msi-controller@a {
184 reg = <0xa 0x1>;
185 compatible = "vendor,some-controller";
186 msi-controller;
187 #msi-cells = <1>;
188 };
189
190 msi_b: msi-controller@b {
191 reg = <0xb 0x1>;
192 compatible = "vendor,some-controller";
193 msi-controller;
194 #msi-cells = <1>;
195 };
196
197 msi_c: msi-controller@c {
198 reg = <0xc 0x1>;
199 compatible = "vendor,some-controller";
200 msi-controller;
201 #msi-cells = <1>;
202 };
203
204 pci: pci@f {
205 reg = <0xf 0x1>;
206 compatible = "vendor,pcie-root-complex";
207 device_type = "pci";
208
209 /*
210 * The sideband data provided to MSI controller a is the
211 * RID, but the high bit of the bus number is negated.
212 * The sideband data provided to MSI controller b is the
213 * RID, identity-mapped.
214 * MSI controller c is not addressable.
215 */
216 msi-map = <0x0000 &msi_a 0x8000 0x08000>,
217 <0x8000 &msi_a 0x0000 0x08000>,
218 <0x0000 &msi_b 0x0000 0x10000>;
219 };
220 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.