1 # SPDX-License-Identifier: (GPL-2.0-only OR BS 1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 %YAML 1.2 2 %YAML 1.2
3 --- 3 ---
4 $id: http://devicetree.org/schemas/mailbox/arm 4 $id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#
5 $schema: http://devicetree.org/meta-schemas/co 5 $schema: http://devicetree.org/meta-schemas/core.yaml#
6 6
7 title: ARM MHUv3 Mailbox Controller 7 title: ARM MHUv3 Mailbox Controller
8 8
9 maintainers: 9 maintainers:
10 - Sudeep Holla <sudeep.holla@arm.com> 10 - Sudeep Holla <sudeep.holla@arm.com>
11 - Cristian Marussi <cristian.marussi@arm.com> 11 - Cristian Marussi <cristian.marussi@arm.com>
12 12
13 description: | 13 description: |
14 The Arm Message Handling Unit (MHU) Version 14 The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that
15 enables unidirectional communications with r 15 enables unidirectional communications with remote processors through various
16 possible transport protocols. 16 possible transport protocols.
17 The controller can optionally support a vary 17 The controller can optionally support a varying number of extensions that, in
18 turn, enable different kinds of transport to 18 turn, enable different kinds of transport to be used for communication.
19 Number, type and characteristics of each sup 19 Number, type and characteristics of each supported extension can be discovered
20 dynamically at runtime. 20 dynamically at runtime.
21 21
22 Given the unidirectional nature of the contr 22 Given the unidirectional nature of the controller, an MHUv3 mailbox controller
23 is composed of a MHU Sender (MHUS) containin 23 is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU
24 Receiver (MHUR) containing a MailBox (MBX) b 24 Receiver (MHUR) containing a MailBox (MBX) block, where
25 25
26 PBX is used to 26 PBX is used to
27 - Configure the MHU 27 - Configure the MHU
28 - Send Transfers to the Receiver 28 - Send Transfers to the Receiver
29 - Optionally receive acknowledgment of a 29 - Optionally receive acknowledgment of a Transfer from the Receiver
30 30
31 MBX is used to 31 MBX is used to
32 - Configure the MHU 32 - Configure the MHU
33 - Receive Transfers from the Sender 33 - Receive Transfers from the Sender
34 - Optionally acknowledge Transfers sent 34 - Optionally acknowledge Transfers sent by the Sender
35 35
36 Both PBX and MBX need to be present and defi 36 Both PBX and MBX need to be present and defined in the DT description if you
37 need to establish a bidirectional communicat 37 need to establish a bidirectional communication, since you will have to
38 acquire two distinct unidirectional channels 38 acquire two distinct unidirectional channels, one for each block.
39 39
40 As a consequence both blocks needs to be rep 40 As a consequence both blocks needs to be represented separately and specified
41 as distinct DT nodes in order to properly de 41 as distinct DT nodes in order to properly describe their resources.
42 42
43 Note that, though, thanks to the runtime dis 43 Note that, though, thanks to the runtime discoverability, there is no need to
44 identify the type of blocks with distinct co 44 identify the type of blocks with distinct compatibles.
45 45
46 Following are the MHUv3 possible extensions. 46 Following are the MHUv3 possible extensions.
47 47
48 - Doorbell Extension (DBE): DBE defines a ty 48 - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell
49 Channel (DBCH). DBCH enables a single bit 49 Channel (DBCH). DBCH enables a single bit Transfer to be sent from the
50 Sender to Receiver. The Transfer indicates 50 Sender to Receiver. The Transfer indicates that an event has occurred.
51 When DBE is implemented, the number of DBC 51 When DBE is implemented, the number of DBCHs that an implementation of the
52 MHU can support is between 1 and 128, numb 52 MHU can support is between 1 and 128, numbered starting from 0 in ascending
53 order and discoverable at run-time. 53 order and discoverable at run-time.
54 Each DBCH contains 32 individual fields, r 54 Each DBCH contains 32 individual fields, referred to as flags, each of which
55 can be used independently. It is possible 55 can be used independently. It is possible for the Sender to send multiple
56 Transfers at once using a single DBCH, so 56 Transfers at once using a single DBCH, so long as each Transfer uses
57 a different flag in the DBCH. 57 a different flag in the DBCH.
58 Optionally, data may be transmitted throug 58 Optionally, data may be transmitted through an out-of-band shared memory
59 region, wherein the MHU Doorbell is used s 59 region, wherein the MHU Doorbell is used strictly as an interrupt generation
60 mechanism, but this is out of the scope of 60 mechanism, but this is out of the scope of these bindings.
61 61
62 - FastChannel Extension (FCE): FCE defines a 62 - FastChannel Extension (FCE): FCE defines a type of channel called a Fast
63 Channel (FCH). FCH is intended for lower o 63 Channel (FCH). FCH is intended for lower overhead communication between
64 Sender and Receiver at the expense of dete 64 Sender and Receiver at the expense of determinism. An FCH allows the Sender
65 to update the channel value at any time, r 65 to update the channel value at any time, regardless of whether the previous
66 value has been seen by the Receiver. When 66 value has been seen by the Receiver. When the Receiver reads the channel's
67 content it gets the last value written to 67 content it gets the last value written to the channel.
68 FCH is considered lossy in nature, and mea 68 FCH is considered lossy in nature, and means that the Sender has no way of
69 knowing if, or when, the Receiver will act 69 knowing if, or when, the Receiver will act on the Transfer.
70 FCHs are expected to behave as RAM which g 70 FCHs are expected to behave as RAM which generates interrupts when writes
71 occur to the locations within the RAM. 71 occur to the locations within the RAM.
72 When FCE is implemented, the number of FCH 72 When FCE is implemented, the number of FCHs that an implementation of the
73 MHU can support is between 1-1024, if the 73 MHU can support is between 1-1024, if the FastChannel word-size is 32-bits,
74 or between 1-512, when the FastChannel wor 74 or between 1-512, when the FastChannel word-size is 64-bits.
75 FCHs are numbered from 0 in ascending orde 75 FCHs are numbered from 0 in ascending order.
76 Note that the number of FCHs and the word- 76 Note that the number of FCHs and the word-size are implementation defined,
77 not configurable but discoverable at run-t 77 not configurable but discoverable at run-time.
78 Optionally, data may be transmitted throug 78 Optionally, data may be transmitted through an out-of-band shared memory
79 region, wherein the MHU FastChannel is use 79 region, wherein the MHU FastChannel is used as an interrupt generation
80 mechanism which carries also a pointer to 80 mechanism which carries also a pointer to such out-of-band data, but this
81 is out of the scope of these bindings. 81 is out of the scope of these bindings.
82 82
83 - FIFO Extension (FE): FE defines a Channel 83 - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH).
84 FFCH allows a Sender to send 84 FFCH allows a Sender to send
85 - Multiple Transfers to the Receiver wi 85 - Multiple Transfers to the Receiver without having to wait for the
86 previous Transfer to be acknowledged 86 previous Transfer to be acknowledged by the Receiver, as long as the
87 FIFO has room for the Transfer. 87 FIFO has room for the Transfer.
88 - Transfers which require the Receiver 88 - Transfers which require the Receiver to provide acknowledgment.
89 - Transfers which have in-band payload. 89 - Transfers which have in-band payload.
90 In all cases, the data is guaranteed to be 90 In all cases, the data is guaranteed to be observed by the Receiver in the
91 same order which the Sender sent it. 91 same order which the Sender sent it.
92 When FE is implemented, the number of FFCH 92 When FE is implemented, the number of FFCHs that an implementation of the
93 MHU can support is between 1 and 64, numbe 93 MHU can support is between 1 and 64, numbered starting from 0 in ascending
94 order. The number of FFCHs, their depth (s 94 order. The number of FFCHs, their depth (same for all implemented FFCHs) and
95 the access-granularity are implementation 95 the access-granularity are implementation defined, not configurable but
96 discoverable at run-time. 96 discoverable at run-time.
97 Optionally, additional data may be transmi 97 Optionally, additional data may be transmitted through an out-of-band shared
98 memory region, wherein the MHU FIFO is use 98 memory region, wherein the MHU FIFO is used to transmit, in order, a small
99 part of the payload (like a header) and a 99 part of the payload (like a header) and a reference to the shared memory
100 area holding the remaining, bigger, chunk 100 area holding the remaining, bigger, chunk of the payload, but this is out of
101 the scope of these bindings. 101 the scope of these bindings.
102 102
103 properties: 103 properties:
104 compatible: 104 compatible:
105 const: arm,mhuv3 105 const: arm,mhuv3
106 106
107 reg: 107 reg:
108 maxItems: 1 108 maxItems: 1
109 109
110 interrupts: 110 interrupts:
111 minItems: 1 111 minItems: 1
112 maxItems: 74 112 maxItems: 74
113 113
114 interrupt-names: 114 interrupt-names:
115 description: | 115 description: |
116 The MHUv3 controller generates a number 116 The MHUv3 controller generates a number of events some of which are used
117 to generate interrupts; as a consequence 117 to generate interrupts; as a consequence it can expose a varying number of
118 optional PBX/MBX interrupts, representin 118 optional PBX/MBX interrupts, representing the events generated during the
119 operation of the various transport proto 119 operation of the various transport protocols associated with different
120 extensions. All interrupts of the MHU ar 120 extensions. All interrupts of the MHU are level-sensitive.
121 Some of these optional interrupts are de 121 Some of these optional interrupts are defined per-channel, where the
122 number of channels effectively available 122 number of channels effectively available is implementation defined and
123 run-time discoverable. 123 run-time discoverable.
124 In the following names are enumerated us 124 In the following names are enumerated using patterns, with per-channel
125 interrupts implicitly capped at the maxi 125 interrupts implicitly capped at the maximum channels allowed by the
126 specification for each extension type. 126 specification for each extension type.
127 For the sake of simplicity maxItems is a 127 For the sake of simplicity maxItems is anyway capped to a most plausible
128 number, assuming way less channels would 128 number, assuming way less channels would be implemented than actually
129 possible. 129 possible.
130 130
131 The only mandatory interrupts on the MHU 131 The only mandatory interrupts on the MHU are:
132 - combined 132 - combined
133 - mbx-fch-xfer-<N> but only if mbx-fcg 133 - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented.
134 134
135 minItems: 1 135 minItems: 1
136 maxItems: 74 136 maxItems: 74
137 items: 137 items:
138 oneOf: 138 oneOf:
139 - const: combined 139 - const: combined
140 description: PBX/MBX Combined interr 140 description: PBX/MBX Combined interrupt
141 - const: combined-ffch 141 - const: combined-ffch
142 description: PBX/MBX FIFO Combined i 142 description: PBX/MBX FIFO Combined interrupt
143 - pattern: '^ffch-low-tide-[0-9]+$' 143 - pattern: '^ffch-low-tide-[0-9]+$'
144 description: PBX/MBX FIFO Channel <N 144 description: PBX/MBX FIFO Channel <N> Low Tide interrupt
145 - pattern: '^ffch-high-tide-[0-9]+$' 145 - pattern: '^ffch-high-tide-[0-9]+$'
146 description: PBX/MBX FIFO Channel <N 146 description: PBX/MBX FIFO Channel <N> High Tide interrupt
147 - pattern: '^ffch-flush-[0-9]+$' 147 - pattern: '^ffch-flush-[0-9]+$'
148 description: PBX/MBX FIFO Channel <N 148 description: PBX/MBX FIFO Channel <N> Flush interrupt
149 - pattern: '^mbx-dbch-xfer-[0-9]+$' 149 - pattern: '^mbx-dbch-xfer-[0-9]+$'
150 description: MBX Doorbell Channel <N 150 description: MBX Doorbell Channel <N> Transfer interrupt
151 - pattern: '^mbx-fch-xfer-[0-9]+$' 151 - pattern: '^mbx-fch-xfer-[0-9]+$'
152 description: MBX FastChannel <N> Tra 152 description: MBX FastChannel <N> Transfer interrupt
153 - pattern: '^mbx-fchgrp-xfer-[0-9]+$' 153 - pattern: '^mbx-fchgrp-xfer-[0-9]+$'
154 description: MBX FastChannel <N> Gro 154 description: MBX FastChannel <N> Group Transfer interrupt
155 - pattern: '^mbx-ffch-xfer-[0-9]+$' 155 - pattern: '^mbx-ffch-xfer-[0-9]+$'
156 description: MBX FIFO Channel <N> Tr 156 description: MBX FIFO Channel <N> Transfer interrupt
157 - pattern: '^pbx-dbch-xfer-ack-[0-9]+$ 157 - pattern: '^pbx-dbch-xfer-ack-[0-9]+$'
158 description: PBX Doorbell Channel <N 158 description: PBX Doorbell Channel <N> Transfer Ack interrupt
159 - pattern: '^pbx-ffch-xfer-ack-[0-9]+$ 159 - pattern: '^pbx-ffch-xfer-ack-[0-9]+$'
160 description: PBX FIFO Channel <N> Tr 160 description: PBX FIFO Channel <N> Transfer Ack interrupt
161 161
162 '#mbox-cells': 162 '#mbox-cells':
163 description: | 163 description: |
164 The first argument in the consumers 'mbo 164 The first argument in the consumers 'mboxes' property represents the
165 extension type, the second is for the ch 165 extension type, the second is for the channel number while the third
166 depends on extension type. 166 depends on extension type.
167 167
168 Extension types constants are defined in 168 Extension types constants are defined in <dt-bindings/arm/mhuv3-dt.h>.
169 169
170 Extension type for DBE is DBE_EXT and th 170 Extension type for DBE is DBE_EXT and the third parameter represents the
171 doorbell flag number to use. 171 doorbell flag number to use.
172 Extension type for FCE is FCE_EXT, third 172 Extension type for FCE is FCE_EXT, third parameter unused.
173 Extension type for FE is FE_EXT, third p 173 Extension type for FE is FE_EXT, third parameter unused.
174 174
175 mboxes = <&mhu DBE_EXT 0 5>; // DBE, Doo 175 mboxes = <&mhu DBE_EXT 0 5>; // DBE, Doorbell Channel Window 0, doorbell 5.
176 mboxes = <&mhu DBE_EXT 7>; // DBE, Doorb 176 mboxes = <&mhu DBE_EXT 7>; // DBE, Doorbell Channel Window 1, doorbell 7.
177 mboxes = <&mhu FCE_EXT 0 0>; // FCE, Fas 177 mboxes = <&mhu FCE_EXT 0 0>; // FCE, FastChannel Window 0.
178 mboxes = <&mhu FCE_EXT 3 0>; // FCE, Fas 178 mboxes = <&mhu FCE_EXT 3 0>; // FCE, FastChannel Window 3.
179 mboxes = <&mhu FE_EXT 1 0>; // FE, FIFO 179 mboxes = <&mhu FE_EXT 1 0>; // FE, FIFO Channel Window 1.
180 mboxes = <&mhu FE_EXT 7 0>; // FE, FIFO 180 mboxes = <&mhu FE_EXT 7 0>; // FE, FIFO Channel Window 7.
181 const: 3 181 const: 3
182 182
183 clocks: 183 clocks:
184 maxItems: 1 184 maxItems: 1
185 185
186 required: 186 required:
187 - compatible 187 - compatible
188 - reg 188 - reg
189 - interrupts 189 - interrupts
190 - interrupt-names 190 - interrupt-names
191 - '#mbox-cells' 191 - '#mbox-cells'
192 192
193 additionalProperties: false 193 additionalProperties: false
194 194
195 examples: 195 examples:
196 - | 196 - |
197 #include <dt-bindings/interrupt-controller 197 #include <dt-bindings/interrupt-controller/arm-gic.h>
198 198
199 soc { 199 soc {
200 #address-cells = <2>; 200 #address-cells = <2>;
201 #size-cells = <2>; 201 #size-cells = <2>;
202 202
203 mailbox@2aaa0000 { 203 mailbox@2aaa0000 {
204 compatible = "arm,mhuv3"; 204 compatible = "arm,mhuv3";
205 #mbox-cells = <3>; 205 #mbox-cells = <3>;
206 reg = <0 0x2aaa0000 0 0x10000>; 206 reg = <0 0x2aaa0000 0 0x10000>;
207 clocks = <&clock 0>; 207 clocks = <&clock 0>;
208 interrupt-names = "combined", "pbx 208 interrupt-names = "combined", "pbx-dbch-xfer-ack-1",
209 "ffch-high-tide 209 "ffch-high-tide-0";
210 interrupts = <GIC_SPI 36 IRQ_TYPE_ 210 interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>,
211 <GIC_SPI 37 IRQ_TYPE_ 211 <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;
212 }; 212 };
213 213
214 mailbox@2ab00000 { 214 mailbox@2ab00000 {
215 compatible = "arm,mhuv3"; 215 compatible = "arm,mhuv3";
216 #mbox-cells = <3>; 216 #mbox-cells = <3>;
217 reg = <0 0x2aab0000 0 0x10000>; 217 reg = <0 0x2aab0000 0 0x10000>;
218 clocks = <&clock 0>; 218 clocks = <&clock 0>;
219 interrupt-names = "combined", "mbx 219 interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0";
220 interrupts = <GIC_SPI 35 IRQ_TYPE_ 220 interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,
221 <GIC_SPI 38 IRQ_TYPE_ 221 <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>,
222 <GIC_SPI 39 IRQ_TYPE_ 222 <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>;
223 }; 223 };
224 }; 224 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.