0001 This document describes the generic device tree binding for MSI controllers and
0002 their master(s).
0003
0004 Message Signaled Interrupts (MSIs) are a class of interrupts generated by a
0005 write to an MMIO address.
0006
0007 MSIs were originally specified by PCI (and are used with PCIe), but may also be
0008 used with other busses, and hence a mechanism is required to relate devices on
0009 those busses to the MSI controllers which they are capable of using,
0010 potentially including additional information.
0011
0012 MSIs are distinguished by some combination of:
0013
0014 - The doorbell (the MMIO address written to).
0015
0016 Devices may be configured by software to write to arbitrary doorbells which
0017 they can address. An MSI controller may feature a number of doorbells.
0018
0019 - The payload (the value written to the doorbell).
0020
0021 Devices may be configured to write an arbitrary payload chosen by software.
0022 MSI controllers may have restrictions on permitted payloads.
0023
0024 - Sideband information accompanying the write.
0025
0026 Typically this is neither configurable nor probeable, and depends on the path
0027 taken through the memory system (i.e. it is a property of the combination of
0028 MSI controller and device rather than a property of either in isolation).
0029
0030
0031 MSI controllers:
0032 ================
0033
0034 An MSI controller signals interrupts to a CPU when a write is made to an MMIO
0035 address by some master. An MSI controller may feature a number of doorbells.
0036
0037 Required properties:
0038 --------------------
0039
0040 - msi-controller: Identifies the node as an MSI controller.
0041
0042 Optional properties:
0043 --------------------
0044
0045 - #msi-cells: The number of cells in an msi-specifier, required if not zero.
0046
0047 Typically this will encode information related to sideband data, and will
0048 not encode doorbells or payloads as these can be configured dynamically.
0049
0050 The meaning of the msi-specifier is defined by the device tree binding of
0051 the specific MSI controller.
0052
0053
0054 MSI clients
0055 ===========
0056
0057 MSI clients are devices which generate MSIs. For each MSI they wish to
0058 generate, the doorbell and payload may be configured, though sideband
0059 information may not be configurable.
0060
0061 Required properties:
0062 --------------------
0063
0064 - msi-parent: A list of phandle + msi-specifier pairs, one for each MSI
0065 controller which the device is capable of using.
0066
0067 This property is unordered, and MSIs may be allocated from any combination of
0068 MSI controllers listed in the msi-parent property.
0069
0070 If a device has restrictions on the allocation of MSIs, these restrictions
0071 must be described with additional properties.
0072
0073 When #msi-cells is non-zero, busses with an msi-parent will require
0074 additional properties to describe the relationship between devices on the bus
0075 and the set of MSIs they can potentially generate.
0076
0077
0078 Example
0079 =======
0080
0081 / {
0082 #address-cells = <1>;
0083 #size-cells = <1>;
0084
0085 msi_a: msi-controller@a {
0086 reg = <0xa 0xf00>;
0087 compatible = "vendor-a,some-controller";
0088 msi-controller;
0089 /* No sideband data, so #msi-cells omitted */
0090 };
0091
0092 msi_b: msi-controller@b {
0093 reg = <0xb 0xf00>;
0094 compatible = "vendor-b,another-controller";
0095 msi-controller;
0096 /* Each device has some unique ID */
0097 #msi-cells = <1>;
0098 };
0099
0100 msi_c: msi-controller@c {
0101 reg = <0xc 0xf00>;
0102 compatible = "vendor-b,another-controller";
0103 msi-controller;
0104 /* Each device has some unique ID */
0105 #msi-cells = <1>;
0106 };
0107
0108 dev@0 {
0109 reg = <0x0 0xf00>;
0110 compatible = "vendor-c,some-device";
0111
0112 /* Can only generate MSIs to msi_a */
0113 msi-parent = <&msi_a>;
0114 };
0115
0116 dev@1 {
0117 reg = <0x1 0xf00>;
0118 compatible = "vendor-c,some-device";
0119
0120 /*
0121 * Can generate MSIs to either A or B.
0122 */
0123 msi-parent = <&msi_a>, <&msi_b 0x17>;
0124 };
0125
0126 dev@2 {
0127 reg = <0x2 0xf00>;
0128 compatible = "vendor-c,some-device";
0129 /*
0130 * Has different IDs at each MSI controller.
0131 * Can generate MSIs to all of the MSI controllers.
0132 */
0133 msi-parent = <&msi_a>, <&msi_b 0x17>, <&msi_c 0x53>;
0134 };
0135 };
