0001 This document describes the generic device tree binding for describing the
0002 relationship between PCI devices and MSI controllers.
0003
0004 Each PCI device under a root complex is uniquely identified by its Requester ID
0005 (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
0006 Function number.
0007
0008 For the purpose of this document, when treated as a numeric value, a RID is
0009 formatted such that:
0010
0011 * Bits [15:8] are the Bus number.
0012 * Bits [7:3] are the Device number.
0013 * Bits [2:0] are the Function number.
0014 * Any other bits required for padding must be zero.
0015
0016 MSIs may be distinguished in part through the use of sideband data accompanying
0017 writes. In the case of PCI devices, this sideband data may be derived from the
0018 Requester ID. A mechanism is required to associate a device with both the MSI
0019 controllers it can address, and the sideband data that will be associated with
0020 its writes to those controllers.
0021
0022 For generic MSI bindings, see
0023 Documentation/devicetree/bindings/interrupt-controller/msi.txt.
0024
0025
0026 PCI root complex
0027 ================
0028
0029 Optional properties
0030 -------------------
0031
0032 - msi-map: Maps a Requester ID to an MSI controller and associated
0033 msi-specifier data. The property is an arbitrary number of tuples of
0034 (rid-base,msi-controller,msi-base,length), where:
0035
0036 * rid-base is a single cell describing the first RID matched by the entry.
0037
0038 * msi-controller is a single phandle to an MSI controller
0039
0040 * msi-base is an msi-specifier describing the msi-specifier produced for the
0041 first RID matched by the entry.
0042
0043 * length is a single cell describing how many consecutive RIDs are matched
0044 following the rid-base.
0045
0046 Any RID r in the interval [rid-base, rid-base + length) is associated with
0047 the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
0048
0049 - msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
0050 to an msi-specifier per the msi-map property.
0051
0052 - msi-parent: Describes the MSI parent of the root complex itself. Where
0053 the root complex and MSI controller do not pass sideband data with MSI
0054 writes, this property may be used to describe the MSI controller(s)
0055 used by PCI devices under the root complex, if defined as such in the
0056 binding for the root complex.
0057
0058
0059 Example (1)
0060 ===========
0061
0062 / {
0063 #address-cells = <1>;
0064 #size-cells = <1>;
0065
0066 msi: msi-controller@a {
0067 reg = <0xa 0x1>;
0068 compatible = "vendor,some-controller";
0069 msi-controller;
0070 #msi-cells = <1>;
0071 };
0072
0073 pci: pci@f {
0074 reg = <0xf 0x1>;
0075 compatible = "vendor,pcie-root-complex";
0076 device_type = "pci";
0077
0078 /*
0079 * The sideband data provided to the MSI controller is
0080 * the RID, identity-mapped.
0081 */
0082 msi-map = <0x0 &msi_a 0x0 0x10000>,
0083 };
0084 };
0085
0086
0087 Example (2)
0088 ===========
0089
0090 / {
0091 #address-cells = <1>;
0092 #size-cells = <1>;
0093
0094 msi: msi-controller@a {
0095 reg = <0xa 0x1>;
0096 compatible = "vendor,some-controller";
0097 msi-controller;
0098 #msi-cells = <1>;
0099 };
0100
0101 pci: pci@f {
0102 reg = <0xf 0x1>;
0103 compatible = "vendor,pcie-root-complex";
0104 device_type = "pci";
0105
0106 /*
0107 * The sideband data provided to the MSI controller is
0108 * the RID, masked to only the device and function bits.
0109 */
0110 msi-map = <0x0 &msi_a 0x0 0x100>,
0111 msi-map-mask = <0xff>
0112 };
0113 };
0114
0115
0116 Example (3)
0117 ===========
0118
0119 / {
0120 #address-cells = <1>;
0121 #size-cells = <1>;
0122
0123 msi: msi-controller@a {
0124 reg = <0xa 0x1>;
0125 compatible = "vendor,some-controller";
0126 msi-controller;
0127 #msi-cells = <1>;
0128 };
0129
0130 pci: pci@f {
0131 reg = <0xf 0x1>;
0132 compatible = "vendor,pcie-root-complex";
0133 device_type = "pci";
0134
0135 /*
0136 * The sideband data provided to the MSI controller is
0137 * the RID, but the high bit of the bus number is
0138 * ignored.
0139 */
0140 msi-map = <0x0000 &msi 0x0000 0x8000>,
0141 <0x8000 &msi 0x0000 0x8000>;
0142 };
0143 };
0144
0145
0146 Example (4)
0147 ===========
0148
0149 / {
0150 #address-cells = <1>;
0151 #size-cells = <1>;
0152
0153 msi: msi-controller@a {
0154 reg = <0xa 0x1>;
0155 compatible = "vendor,some-controller";
0156 msi-controller;
0157 #msi-cells = <1>;
0158 };
0159
0160 pci: pci@f {
0161 reg = <0xf 0x1>;
0162 compatible = "vendor,pcie-root-complex";
0163 device_type = "pci";
0164
0165 /*
0166 * The sideband data provided to the MSI controller is
0167 * the RID, but the high bit of the bus number is
0168 * negated.
0169 */
0170 msi-map = <0x0000 &msi 0x8000 0x8000>,
0171 <0x8000 &msi 0x0000 0x8000>;
0172 };
0173 };
0174
0175
0176 Example (5)
0177 ===========
0178
0179 / {
0180 #address-cells = <1>;
0181 #size-cells = <1>;
0182
0183 msi_a: msi-controller@a {
0184 reg = <0xa 0x1>;
0185 compatible = "vendor,some-controller";
0186 msi-controller;
0187 #msi-cells = <1>;
0188 };
0189
0190 msi_b: msi-controller@b {
0191 reg = <0xb 0x1>;
0192 compatible = "vendor,some-controller";
0193 msi-controller;
0194 #msi-cells = <1>;
0195 };
0196
0197 msi_c: msi-controller@c {
0198 reg = <0xc 0x1>;
0199 compatible = "vendor,some-controller";
0200 msi-controller;
0201 #msi-cells = <1>;
0202 };
0203
0204 pci: pci@f {
0205 reg = <0xf 0x1>;
0206 compatible = "vendor,pcie-root-complex";
0207 device_type = "pci";
0208
0209 /*
0210 * The sideband data provided to MSI controller a is the
0211 * RID, but the high bit of the bus number is negated.
0212 * The sideband data provided to MSI controller b is the
0213 * RID, identity-mapped.
0214 * MSI controller c is not addressable.
0215 */
0216 msi-map = <0x0000 &msi_a 0x8000 0x08000>,
0217 <0x8000 &msi_a 0x0000 0x08000>,
0218 <0x0000 &msi_b 0x0000 0x10000>;
0219 };
0220 };
