^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) This document describes the generic device tree binding for MSI controllers and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) their master(s).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Message Signaled Interrupts (MSIs) are a class of interrupts generated by a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) write to an MMIO address.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) MSIs were originally specified by PCI (and are used with PCIe), but may also be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) used with other busses, and hence a mechanism is required to relate devices on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9) those busses to the MSI controllers which they are capable of using,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) potentially including additional information.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12) MSIs are distinguished by some combination of:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) - The doorbell (the MMIO address written to).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) Devices may be configured by software to write to arbitrary doorbells which
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) they can address. An MSI controller may feature a number of doorbells.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) - The payload (the value written to the doorbell).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) Devices may be configured to write an arbitrary payload chosen by software.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) MSI controllers may have restrictions on permitted payloads.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) - Sideband information accompanying the write.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) Typically this is neither configurable nor probeable, and depends on the path
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) taken through the memory system (i.e. it is a property of the combination of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) MSI controller and device rather than a property of either in isolation).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) MSI controllers:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) ================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) An MSI controller signals interrupts to a CPU when a write is made to an MMIO
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) address by some master. An MSI controller may feature a number of doorbells.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Required properties:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) - msi-controller: Identifies the node as an MSI controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42) Optional properties:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) - #msi-cells: The number of cells in an msi-specifier, required if not zero.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47) Typically this will encode information related to sideband data, and will
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) not encode doorbells or payloads as these can be configured dynamically.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) The meaning of the msi-specifier is defined by the device tree binding of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) the specific MSI controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) MSI clients
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) MSI clients are devices which generate MSIs. For each MSI they wish to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) generate, the doorbell and payload may be configured, though sideband
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) information may not be configurable.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) Required properties:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) --------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) - msi-parent: A list of phandle + msi-specifier pairs, one for each MSI
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) controller which the device is capable of using.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) This property is unordered, and MSIs may be allocated from any combination of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) MSI controllers listed in the msi-parent property.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70) If a device has restrictions on the allocation of MSIs, these restrictions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) must be described with additional properties.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73) When #msi-cells is non-zero, busses with an msi-parent will require
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) additional properties to describe the relationship between devices on the bus
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) and the set of MSIs they can potentially generate.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) Example
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) =======
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) / {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) #address-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) #size-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) msi_a: msi-controller@a {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) reg = <0xa 0xf00>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) compatible = "vendor-a,some-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) /* No sideband data, so #msi-cells omitted */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) msi_b: msi-controller@b {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) reg = <0xb 0xf00>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) compatible = "vendor-b,another-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) /* Each device has some unique ID */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) msi_c: msi-controller@c {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) reg = <0xc 0xf00>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) compatible = "vendor-b,another-controller";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) msi-controller;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) /* Each device has some unique ID */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) #msi-cells = <1>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) dev@0 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) reg = <0x0 0xf00>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) compatible = "vendor-c,some-device";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) /* Can only generate MSIs to msi_a */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) msi-parent = <&msi_a>;
^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) dev@1 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) reg = <0x1 0xf00>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) compatible = "vendor-c,some-device";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) * Can generate MSIs to either A or B.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) msi-parent = <&msi_a>, <&msi_b 0x17>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) dev@2 {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) reg = <0x2 0xf00>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) compatible = "vendor-c,some-device";
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) /*
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) * Has different IDs at each MSI controller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) * Can generate MSIs to all of the MSI controllers.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) msi-parent = <&msi_a>, <&msi_b 0x17>, <&msi_c 0x53>;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) };
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags