1This document describes the generic device tree binding for describing the
2relationship between PCI devices and MSI controllers.
3
4Each 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
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
16MSIs may be distinguished in part through the use of sideband data accompanying
17writes. In the case of PCI devices, this sideband data may be derived from the
18Requester ID. A mechanism is required to associate a device with both the MSI
19controllers it can address, and the sideband data that will be associated with
20its writes to those controllers.
21
22For generic MSI bindings, see
23Documentation/devicetree/bindings/interrupt-controller/msi.txt.
24
25
26PCI root complex
27================
28
29Optional 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
59Example (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
87Example (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
116Example (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
146Example (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
176Example (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};
221