1# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
2%YAML 1.2
3---
4$id: http://devicetree.org/schemas/mailbox/ti,omap-mailbox.yaml#
5$schema: http://devicetree.org/meta-schemas/core.yaml#
6
7title: TI OMAP2+ and K3 Mailbox devices
8
9maintainers:
10  - Suman Anna <s-anna@ti.com>
11
12description: |
13  The OMAP Mailbox hardware facilitates communication between different
14  processors using a queued mailbox interrupt mechanism. The IP block is
15  external to the various processor subsystems and is connected on an
16  interconnect bus. The communication is achieved through a set of registers
17  for message storage and interrupt configuration registers.
18
19  Each mailbox IP block/cluster has a certain number of h/w fifo queues and
20  output interrupt lines. An output interrupt line is routed to an interrupt
21  controller within a processor subsystem, and there can be more than one line
22  going to a specific processor's interrupt controller. The interrupt line
23  connections are fixed for an instance and are dictated by the IP integration
24  into the SoC (excluding the SoCs that have an Interrupt Crossbar or an
25  Interrupt Router IP). Each interrupt line is programmable through a set of
26  interrupt configuration registers, and have a rx and tx interrupt source per
27  h/w fifo. Communication between different processors is achieved through the
28  appropriate programming of the rx and tx interrupt sources on the appropriate
29  interrupt lines.
30
31  The number of h/w fifo queues and interrupt lines dictate the usable
32  registers. All the current OMAP SoCs except for the newest DRA7xx SoC has a
33  single IP instance. DRA7xx has multiple instances with different number of
34  h/w fifo queues and interrupt lines between different instances. The interrupt
35  lines can also be routed to different processor sub-systems on DRA7xx as they
36  are routed through the Crossbar, a kind of interrupt router/multiplexer. The
37  K3 AM65x, J721E and J7200 SoCs has each of these instances form a cluster and
38  combine multiple clusters into a single IP block present within the Main
39  NavSS. The interrupt lines from all these clusters are multiplexed and routed
40  to different processor subsystems over a limited number of common interrupt
41  output lines of an Interrupt Router. The AM64x SoCS also uses a single IP
42  block comprising of multiple clusters, but the number of clusters are
43  smaller, and the interrupt output lines are connected directly to various
44  processors.
45
46  Mailbox Controller Nodes
47  =========================
48  A Mailbox device node is used to represent a Mailbox IP instance/cluster
49  within a SoC. The sub-mailboxes (actual communication channels) are
50  represented as child nodes of this parent node.
51
52  Mailbox Users
53  ==============
54  A device needing to communicate with a target processor device should specify
55  them using the common mailbox binding properties, "mboxes" and the optional
56  "mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
57  for details). Each value of the mboxes property should contain a phandle to
58  the mailbox controller device node and an args specifier that will be the
59  phandle to the intended sub-mailbox child node to be used for communication.
60  The equivalent "mbox-names" property value can be used to give a name to the
61  communication channel to be used by the client user.
62
63$defs:
64  omap-mbox-descriptor:
65    $ref: /schemas/types.yaml#/definitions/uint32-array
66    description:
67      The omap-mbox-descriptor is made of up of 3 cells and represents a single
68      uni-directional communication channel. A typical sub-mailbox device uses
69      two such channels - one for transmitting (Tx) and one for receiving (Rx).
70    items:
71      - description:
72          mailbox fifo id used either for transmitting on ti,mbox-tx channel or
73          for receiving on ti,mbox-rx channel (fifo_id). This is the hardware
74          fifo number within a mailbox cluster.
75      - description:
76          irq identifier index number to use from the parent's interrupts data.
77          Should be 0 for most of the cases, a positive index value is seen only
78          on mailboxes that have multiple interrupt lines connected to the MPU
79          processor (irq_id). This is an index number in the listed interrupts
80          property in the DT nodes.
81      - description:
82          mailbox user id for identifying the interrupt line associated with
83          generating a tx/rx fifo interrupt (usr_id). This is the hardware
84          user id number within a mailbox cluster.
85
86  omap-sub-mailbox:
87    type: object
88    description:
89      The omap-sub-mailbox is a child node within a Mailbox controller device
90      node and represents the actual communication channel used to send and
91      receive messages between the host processor and a remote processor. Each
92      child node should have a unique node name across all the different mailbox
93      device nodes.
94
95    properties:
96      ti,mbox-tx:
97        $ref: "#/$defs/omap-mbox-descriptor"
98        description: sub-mailbox descriptor property defining a Tx fifo.
99
100      ti,mbox-rx:
101        $ref: "#/$defs/omap-mbox-descriptor"
102        description: sub-mailbox descriptor property defining a Rx fifo.
103
104      ti,mbox-send-noirq:
105        type: boolean
106        description:
107          Quirk flag to allow the client user of this sub-mailbox to send
108          messages without triggering a Tx ready interrupt, and to control
109          the Tx ticker. Should be used only on sub-mailboxes used to
110          communicate with WkupM3 remote processor on AM33xx/AM43xx SoCs.
111
112    required:
113      - ti,mbox-tx
114      - ti,mbox-rx
115
116properties:
117  compatible:
118    enum:
119      - ti,omap2-mailbox # for OMAP2420, OMAP2430 SoCs
120      - ti,omap3-mailbox # for OMAP3430, OMAP3630 SoCs
121      - ti,omap4-mailbox # for OMAP44xx, OMAP54xx, AM33xx, AM43xx and DRA7xx SoCs
122      - ti,am654-mailbox # for K3 AM65x, J721E and J7200 SoCs
123      - ti,am64-mailbox  # for K3 AM64x SoCs
124
125  reg:
126    maxItems: 1
127
128  interrupts:
129    description:
130      Contains the interrupt information for the mailbox device. The format is
131      dependent on which interrupt controller the Mailbox device uses. The
132      number of interrupts listed will at most be the value specified in
133      ti,mbox-num-users property, but is usually limited by the number of
134      interrupts reaching the main processor. An interrupt-parent property
135      is required on SoCs where the interrupt lines are connected through a
136      Interrupt Router before reaching the main processor's GIC.
137
138  "#mbox-cells":
139    const: 1
140    description:
141      The specifier is a phandle to an omap-sub-mailbox device.
142
143  ti,mbox-num-users:
144    $ref: /schemas/types.yaml#/definitions/uint32
145    description:
146      Number of targets (processor devices) that the mailbox device can
147      interrupt.
148
149  ti,mbox-num-fifos:
150    $ref: /schemas/types.yaml#/definitions/uint32
151    description: Number of h/w fifo queues within the mailbox IP block.
152
153  ti,hwmods:
154    $ref: /schemas/types.yaml#/definitions/string
155    deprecated: true
156    description:
157      Name of the hwmod associated with the mailbox. This should be defined
158      in the mailbox node only if the node is not defined as a child node of
159      a corresponding sysc interconnect node.
160
161      This property is only needed on some legacy OMAP SoCs which have not
162      yet been converted to the ti,sysc interconnect hierarachy, but is
163      otherwise considered obsolete.
164
165patternProperties:
166  "^mbox-[a-z0-9-]+$":
167    $ref: "#/$defs/omap-sub-mailbox"
168
169required:
170  - compatible
171  - reg
172  - interrupts
173  - "#mbox-cells"
174  - ti,mbox-num-users
175  - ti,mbox-num-fifos
176
177allOf:
178  - if:
179      properties:
180        compatible:
181          enum:
182            - ti,am654-mailbox
183    then:
184      required:
185        - interrupt-parent
186
187  - if:
188      properties:
189        compatible:
190          enum:
191            - ti,am654-mailbox
192            - ti,am64-mailbox
193    then:
194      properties:
195        ti,mbox-num-users:
196          const: 4
197        ti,mbox-num-fifos:
198          const: 16
199        interrupts:
200          minItems: 1
201          maxItems: 4
202
203  - if:
204      properties:
205        compatible:
206          enum:
207            - ti,omap4-mailbox
208    then:
209      properties:
210        ti,mbox-num-users:
211          enum: [3, 4]
212        ti,mbox-num-fifos:
213          enum: [8, 12]
214        interrupts:
215          minItems: 1
216          maxItems: 4
217
218  - if:
219      properties:
220        compatible:
221          enum:
222            - ti,omap3-mailbox
223    then:
224      properties:
225        ti,mbox-num-users:
226          const: 2
227        ti,mbox-num-fifos:
228          const: 2
229        interrupts:
230          minItems: 1
231          maxItems: 1
232
233  - if:
234      properties:
235        compatible:
236          enum:
237            - ti,omap2-mailbox
238    then:
239      properties:
240        ti,mbox-num-users:
241          const: 4
242        ti,mbox-num-fifos:
243          const: 6
244        interrupts:
245          minItems: 1
246          maxItems: 2
247
248additionalProperties: false
249
250examples:
251  - |
252    /* OMAP4 */
253    #include <dt-bindings/interrupt-controller/arm-gic.h>
254    mailbox: mailbox@4a0f4000 {
255        compatible = "ti,omap4-mailbox";
256        reg = <0x4a0f4000 0x200>;
257        interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
258        #mbox-cells = <1>;
259        ti,mbox-num-users = <3>;
260        ti,mbox-num-fifos = <8>;
261
262        mbox_ipu: mbox-ipu {
263            ti,mbox-tx = <0 0 0>;
264            ti,mbox-rx = <1 0 0>;
265        };
266        mbox_dsp: mbox-dsp {
267            ti,mbox-tx = <3 0 0>;
268            ti,mbox-rx = <2 0 0>;
269        };
270    };
271
272    dsp {
273        mboxes = <&mailbox &mbox_dsp>;
274    };
275
276  - |
277    /* AM33xx */
278    mailbox1: mailbox@480c8000 {
279        compatible = "ti,omap4-mailbox";
280        reg = <0x480c8000 0x200>;
281        interrupts = <77>;
282        #mbox-cells = <1>;
283        ti,mbox-num-users = <4>;
284        ti,mbox-num-fifos = <8>;
285
286        mbox_wkupm3: mbox-wkup-m3 {
287            ti,mbox-tx = <0 0 0>;
288            ti,mbox-rx = <0 0 3>;
289            ti,mbox-send-noirq;
290        };
291    };
292
293  - |
294    /* AM65x */
295    mailbox0_cluster0: mailbox@31f80000 {
296        compatible = "ti,am654-mailbox";
297        reg = <0x31f80000 0x200>;
298        #mbox-cells = <1>;
299        ti,mbox-num-users = <4>;
300        ti,mbox-num-fifos = <16>;
301        interrupt-parent = <&intr_main_navss>;
302        interrupts = <436>;
303
304        mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
305            ti,mbox-tx = <1 0 0>;
306            ti,mbox-rx = <0 0 0>;
307        };
308    };
309