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