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@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}; 221