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