summaryrefslogtreecommitdiff
path: root/Documentation/devicetree/bindings/pci/pci-msi.txt
blob: 9b3cc817d181a08f772e3ec4c51829df96f5b8ae (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
This document describes the generic device tree binding for describing the
relationship between PCI devices and MSI controllers.

Each PCI device under a root complex is uniquely identified by its Requester ID
(AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
Function number.

For the purpose of this document, when treated as a numeric value, a RID is
formatted such that:

* Bits [15:8] are the Bus number.
* Bits [7:3] are the Device number.
* Bits [2:0] are the Function number.
* Any other bits required for padding must be zero.

MSIs may be distinguished in part through the use of sideband data accompanying
writes. In the case of PCI devices, this sideband data may be derived from the
Requester ID. A mechanism is required to associate a device with both the MSI
controllers it can address, and the sideband data that will be associated with
its writes to those controllers.

For generic MSI bindings, see
Documentation/devicetree/bindings/interrupt-controller/msi.txt.


PCI root complex
================

Optional properties
-------------------

- msi-map: Maps a Requester ID to an MSI controller and associated
  msi-specifier data. The property is an arbitrary number of tuples of
  (rid-base,msi-controller,msi-base,length), where:

  * rid-base is a single cell describing the first RID matched by the entry.

  * msi-controller is a single phandle to an MSI controller

  * msi-base is an msi-specifier describing the msi-specifier produced for the
    first RID matched by the entry.

  * length is a single cell describing how many consecutive RIDs are matched
    following the rid-base.

  Any RID r in the interval [rid-base, rid-base + length) is associated with
  the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).

- msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
  to an msi-specifier per the msi-map property.

- msi-parent: Describes the MSI parent of the root complex itself. Where
  the root complex and MSI controller do not pass sideband data with MSI
  writes, this property may be used to describe the MSI controller(s)
  used by PCI devices under the root complex, if defined as such in the
  binding for the root complex.


Example (1)
===========

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	msi: msi-controller@a {
		reg = <0xa 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	pci: pci@f {
		reg = <0xf 0x1>;
		compatible = "vendor,pcie-root-complex";
		device_type = "pci";

		/*
		 * The sideband data provided to the MSI controller is
		 * the RID, identity-mapped.
		 */
		msi-map = <0x0 &msi_a 0x0 0x10000>,
	};
};


Example (2)
===========

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	msi: msi-controller@a {
		reg = <0xa 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	pci: pci@f {
		reg = <0xf 0x1>;
		compatible = "vendor,pcie-root-complex";
		device_type = "pci";

		/*
		 * The sideband data provided to the MSI controller is
		 * the RID, masked to only the device and function bits.
		 */
		msi-map = <0x0 &msi_a 0x0 0x100>,
		msi-map-mask = <0xff>
	};
};


Example (3)
===========

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	msi: msi-controller@a {
		reg = <0xa 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	pci: pci@f {
		reg = <0xf 0x1>;
		compatible = "vendor,pcie-root-complex";
		device_type = "pci";

		/*
		 * The sideband data provided to the MSI controller is
		 * the RID, but the high bit of the bus number is
		 * ignored.
		 */
		msi-map = <0x0000 &msi 0x0000 0x8000>,
			  <0x8000 &msi 0x0000 0x8000>;
	};
};


Example (4)
===========

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	msi: msi-controller@a {
		reg = <0xa 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	pci: pci@f {
		reg = <0xf 0x1>;
		compatible = "vendor,pcie-root-complex";
		device_type = "pci";

		/*
		 * The sideband data provided to the MSI controller is
		 * the RID, but the high bit of the bus number is
		 * negated.
		 */
		msi-map = <0x0000 &msi 0x8000 0x8000>,
			  <0x8000 &msi 0x0000 0x8000>;
	};
};


Example (5)
===========

/ {
	#address-cells = <1>;
	#size-cells = <1>;

	msi_a: msi-controller@a {
		reg = <0xa 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	msi_b: msi-controller@b {
		reg = <0xb 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	msi_c: msi-controller@c {
		reg = <0xc 0x1>;
		compatible = "vendor,some-controller";
		msi-controller;
		#msi-cells = <1>;
	};

	pci: pci@c {
		reg = <0xf 0x1>;
		compatible = "vendor,pcie-root-complex";
		device_type = "pci";

		/*
		 * The sideband data provided to MSI controller a is the
		 * RID, but the high bit of the bus number is negated.
		 * The sideband data provided to MSI controller b is the
		 * RID, identity-mapped.
		 * MSI controller c is not addressable.
		 */
		msi-map = <0x0000 &msi_a 0x8000 0x08000>,
			  <0x8000 &msi_a 0x0000 0x08000>,
			  <0x0000 &msi_b 0x0000 0x10000>;
	};
};