Documentation/devicetree/bindings/interrupt-controller/msi.txt

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