Commit | Line | Data |
---|---|---|
b531566e MR |
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@c { | |
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 | }; |