Mark Rutland | 126b16e | 2015-07-23 17:52:43 +0100 | [diff] [blame] | 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 | }; |