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
7title: ARM MHUv2 Mailbox Controller
8
9maintainers:
10  - Tushar Khandelwal <tushar.khandelwal@arm.com>
11  - Viresh Kumar <viresh.kumar@linaro.org>
12
13description: |
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'
44select:
45  properties:
46    compatible:
47      contains:
48        enum:
49          - arm,mhuv2-tx
50          - arm,mhuv2-rx
51  required:
52    - compatible
53
54properties:
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
150if:
151  # Interrupt is compulsory for receiver
152  properties:
153    compatible:
154      contains:
155        const: arm,mhuv2-rx
156then:
157  required:
158    - interrupts
159
160required:
161  - compatible
162  - reg
163  - '#mbox-cells'
164  - arm,mhuv2-protocols
165
166additionalProperties: false
167
168examples:
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    };
209