^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) This document describes the generic device tree binding for describing the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) relationship between PCI devices and MSI controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Each PCI device under a root complex is uniquely identified by its Requester ID
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) (AKA RID). A Requester ID is a triplet of a Bus number, Device number, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) Function number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) For the purpose of this document, when treated as a numeric value, a RID is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) formatted such that:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) * Bits [15:8] are the Bus number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) * Bits [7:3] are the Device number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) * Bits [2:0] are the Function number.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) * Any other bits required for padding must be zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) MSIs may be distinguished in part through the use of sideband data accompanying
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) writes. In the case of PCI devices, this sideband data may be derived from the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) Requester ID. A mechanism is required to associate a device with both the MSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) controllers it can address, and the sideband data that will be associated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) its writes to those controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) For generic MSI bindings, see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Documentation/devicetree/bindings/interrupt-controller/msi.txt.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) PCI root complex
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) Optional properties
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) -------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) - msi-map: Maps a Requester ID to an MSI controller and associated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) msi-specifier data. The property is an arbitrary number of tuples of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) (rid-base,msi-controller,msi-base,length), where:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36) * rid-base is a single cell describing the first RID matched by the entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) * msi-controller is a single phandle to an MSI controller
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) * msi-base is an msi-specifier describing the msi-specifier produced for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) first RID matched by the entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) * length is a single cell describing how many consecutive RIDs are matched
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) following the rid-base.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) Any RID r in the interval [rid-base, rid-base + length) is associated with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) the listed msi-controller, with the msi-specifier (r - rid-base + msi-base).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) - msi-map-mask: A mask to be applied to each Requester ID prior to being mapped
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) to an msi-specifier per the msi-map property.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) - msi-parent: Describes the MSI parent of the root complex itself. Where
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) the root complex and MSI controller do not pass sideband data with MSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) writes, this property may be used to describe the MSI controller(s)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) used by PCI devices under the root complex, if defined as such in the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) binding for the root complex.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) Example (1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) / {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) msi: msi-controller@a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) reg = <0xa 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) pci: pci@f {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) reg = <0xf 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) compatible = "vendor,pcie-root-complex";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) device_type = "pci";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) * The sideband data provided to the MSI controller is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) * the RID, identity-mapped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) msi-map = <0x0 &msi_a 0x0 0x10000>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) Example (2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) / {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) msi: msi-controller@a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) reg = <0xa 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) pci: pci@f {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) reg = <0xf 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) compatible = "vendor,pcie-root-complex";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) device_type = "pci";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) * The sideband data provided to the MSI controller is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) * the RID, masked to only the device and function bits.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) msi-map = <0x0 &msi_a 0x0 0x100>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) msi-map-mask = <0xff>
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) Example (3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) / {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) msi: msi-controller@a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) reg = <0xa 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) pci: pci@f {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) reg = <0xf 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) compatible = "vendor,pcie-root-complex";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) device_type = "pci";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) * The sideband data provided to the MSI controller is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) * the RID, but the high bit of the bus number is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) * ignored.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) msi-map = <0x0000 &msi 0x0000 0x8000>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) <0x8000 &msi 0x0000 0x8000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) Example (4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) / {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) msi: msi-controller@a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) reg = <0xa 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) pci: pci@f {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) reg = <0xf 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) compatible = "vendor,pcie-root-complex";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) device_type = "pci";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) * The sideband data provided to the MSI controller is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167) * the RID, but the high bit of the bus number is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) * negated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) msi-map = <0x0000 &msi 0x8000 0x8000>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171) <0x8000 &msi 0x0000 0x8000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176) Example (5)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) / {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183) msi_a: msi-controller@a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) reg = <0xa 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) msi_b: msi-controller@b {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) reg = <0xb 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) msi_c: msi-controller@c {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198) reg = <0xc 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) compatible = "vendor,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) pci: pci@f {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) reg = <0xf 0x1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) compatible = "vendor,pcie-root-complex";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) device_type = "pci";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) * The sideband data provided to MSI controller a is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211) * RID, but the high bit of the bus number is negated.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) * The sideband data provided to MSI controller b is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) * RID, identity-mapped.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) * MSI controller c is not addressable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) msi-map = <0x0000 &msi_a 0x8000 0x08000>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) <0x8000 &msi_a 0x0000 0x08000>,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218) <0x0000 &msi_b 0x0000 0x10000>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) };
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags