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