Documentation/devicetree/bindings/pci/pci-msi.txt

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