1 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
2 %YAML 1.2
3 ---
4 $id: http://devicetree.org/schemas/mailbox/arm,mhuv2.yaml#
5 $schema: http://devicetree.org/meta-schemas/core.yaml#
6
7 title: ARM MHUv2 Mailbox Controller
8
9 maintainers:
10 - Tushar Khandelwal <tushar.khandelwal@arm.com>
11 - Viresh Kumar <viresh.kumar@linaro.org>
12
13 description: |
14 The Arm Message Handling Unit (MHU) Version 2 is a mailbox controller that has
15 between 1 and 124 channel windows (each 32-bit wide) to provide unidirectional
16 communication with remote processor(s), where the number of channel windows
17 are implementation dependent.
18
19 Given the unidirectional nature of the controller, an MHUv2 mailbox may only
20 be written to or read from. If a pair of MHU controllers is implemented
21 between two processing elements to provide bidirectional communication, these
22 must be specified as two separate mailboxes.
23
24 If the interrupts property is present in device tree node, then its treated as
25 a "receiver" mailbox, otherwise a "sender".
26
27 An MHU controller must be specified along with the supported transport
28 protocols. The transport protocols determine the method of data transmission
29 as well as the number of provided mailbox channels.
30
31 Following are the possible transport protocols.
32
33 - Data-transfer: Each transfer is made of one or more words, using one or more
34 channel windows.
35
36 - Doorbell: Each transfer is made up of single bit flag, using any one of the
37 bits in a channel window. A channel window can support up to 32 doorbells
38 and the entire window shall be used in doorbell protocol. Optionally, data
39 may be transmitted through a shared memory region, wherein the MHU is used
40 strictly as an interrupt generation mechanism but that is out of the scope
41 of these bindings.
42
43 # We need a select here so we don't match all nodes with 'arm,primecell'
44 select:
45 properties:
46 compatible:
47 contains:
48 enum:
49 - arm,mhuv2-tx
50 - arm,mhuv2-rx
51 required:
52 - compatible
53
54 properties:
55 compatible:
56 oneOf:
57 - description: Sender mode
58 items:
59 - const: arm,mhuv2-tx
60 - const: arm,primecell
61
62 - description: Receiver-mode
63 items:
64 - const: arm,mhuv2-rx
65 - const: arm,primecell
66
67 reg:
68 maxItems: 1
69
70 interrupts:
71 description: |
72 The MHUv2 controller always implements an interrupt in the "receiver"
73 mode, while the interrupt in the "sender" mode was not available in the
74 version MHUv2.0, but the later versions do have it.
75 maxItems: 1
76
77 clocks:
78 maxItems: 1
79
80 clock-names:
81 maxItems: 1
82
83 arm,mhuv2-protocols:
84 $ref: /schemas/types.yaml#/definitions/uint32-matrix
85 description: |
86 The MHUv2 controller may contain up to 124 channel windows (each 32-bit
87 wide). The hardware and the DT bindings allows any combination of those to
88 be used for various transport protocols.
89
90 This property allows a platform to describe how these channel windows are
91 used in various transport protocols. The entries in this property shall be
92 present as an array of tuples, where each tuple describes details about
93 one of the transport protocol being implemented over some channel
94 window(s).
95
96 The first field of a tuple signifies the transfer protocol, 0 is reserved
97 for doorbell protocol, and 1 is reserved for data-transfer protocol.
98 Using any other value in the first field of a tuple makes it invalid.
99
100 The second field of a tuple signifies the number of channel windows where
101 the protocol would be used and should be set to a non zero value. For
102 doorbell protocol this field signifies the number of 32-bit channel
103 windows that implement the doorbell protocol. For data-transfer protocol,
104 this field signifies the number of 32-bit channel windows that implement
105 the data-transfer protocol.
106
107 The total number of channel windows specified here shouldn't be more than
108 the ones implemented by the platform, though one can specify lesser number
109 of windows here than what the platform implements.
110
111 mhu: mailbox@2b1f0000 {
112 ...
113
114 arm,mhuv2-protocols = <0 2>, <1 1>, <1 5>, <1 7>;
115 }
116
117 The above example defines the protocols of an ARM MHUv2 mailbox
118 controller, where a total of 15 channel windows are used. The first two
119 windows are used in doorbell protocol (64 doorbells), followed by 1, 5 and
120 7 windows (separately) used in data-transfer protocol.
121
122 minItems: 1
123 maxItems: 124
124 items:
125 items:
126 - enum: [ 0, 1 ]
127 - minimum: 0
128 maximum: 124
129
130
131 '#mbox-cells':
132 description: |
133 It is always set to 2. The first argument in the consumers 'mboxes'
134 property represents the channel window group, which may be used in
135 doorbell, or data-transfer protocol, and the second argument (only
136 relevant in doorbell protocol, should be 0 otherwise) represents the
137 doorbell number within the 32 bit wide channel window.
138
139 From the example given above for arm,mhuv2-protocols, here is how a client
140 node can reference them.
141
142 mboxes = <&mhu 0 5>; // Channel Window Group 0, doorbell 5.
143 mboxes = <&mhu 1 7>; // Channel Window Group 1, doorbell 7.
144 mboxes = <&mhu 2 0>; // Channel Window Group 2, data transfer protocol with 1 window.
145 mboxes = <&mhu 3 0>; // Channel Window Group 3, data transfer protocol with 5 windows.
146 mboxes = <&mhu 4 0>; // Channel Window Group 4, data transfer protocol with 7 windows.
147
148 const: 2
149
150 if:
151 # Interrupt is compulsory for receiver
152 properties:
153 compatible:
154 contains:
155 const: arm,mhuv2-rx
156 then:
157 required:
158 - interrupts
159
160 required:
161 - compatible
162 - reg
163 - '#mbox-cells'
164 - arm,mhuv2-protocols
165
166 additionalProperties: false
167
168 examples:
169 # Multiple transport protocols implemented by the mailbox controllers
170 - |
171 soc {
172 #address-cells = <2>;
173 #size-cells = <2>;
174
175 mhu_tx: mailbox@2b1f0000 {
176 #mbox-cells = <2>;
177 compatible = "arm,mhuv2-tx", "arm,primecell";
178 reg = <0 0x2b1f0000 0 0x1000>;
179 clocks = <&clock 0>;
180 clock-names = "apb_pclk";
181 interrupts = <0 45 4>;
182 arm,mhuv2-protocols = <1 5>, <1 2>, <1 5>, <1 7>, <0 2>;
183 };
184
185 mhu_rx: mailbox@2b1f1000 {
186 #mbox-cells = <2>;
187 compatible = "arm,mhuv2-rx", "arm,primecell";
188 reg = <0 0x2b1f1000 0 0x1000>;
189 clocks = <&clock 0>;
190 clock-names = "apb_pclk";
191 interrupts = <0 46 4>;
192 arm,mhuv2-protocols = <1 1>, <1 7>, <0 2>;
193 };
194
195 mhu_client: dsp@596e8000 {
196 compatible = "fsl,imx8qxp-dsp";
197 reg = <0 0x596e8000 0 0x88000>;
198 clocks = <&adma_lpcg 0>, <&adma_lpcg 1>, <&adma_lpcg 2>;
199 clock-names = "ipg", "ocram", "core";
200 power-domains = <&pd 0>, <&pd 1>, <&pd 2>, <&pd 3>;
201 mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1";
202 mboxes = <&mhu_tx 2 0>, //data-transfer protocol with 5 windows, mhu-tx
203 <&mhu_tx 3 0>, //data-transfer protocol with 7 windows, mhu-tx
204 <&mhu_rx 2 27>, //doorbell protocol channel 2, doorbell 27, mhu-rx
205 <&mhu_rx 0 0>; //data-transfer protocol with 1 window, mhu-rx
206 memory-region = <&dsp_reserved>;
207 };
208 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.