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
7 title: TI OMAP2+ and K3 Mailbox devices
8
9 maintainers:
10 - Suman Anna <s-anna@ti.com>
11
12 description: |
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
116 properties:
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 hierarchy, but is
163 otherwise considered obsolete.
164
165 patternProperties:
166 "^mbox-[a-z0-9-]+$":
167 $ref: "#/$defs/omap-sub-mailbox"
168
169 required:
170 - compatible
171 - reg
172 - interrupts
173 - "#mbox-cells"
174 - ti,mbox-num-users
175 - ti,mbox-num-fifos
176
177 allOf:
178 - if:
179 properties:
180 compatible:
181 enum:
182 - ti,am654-mailbox
183 - ti,am64-mailbox
184 then:
185 properties:
186 ti,mbox-num-users:
187 const: 4
188 ti,mbox-num-fifos:
189 const: 16
190 interrupts:
191 minItems: 1
192 maxItems: 4
193
194 - if:
195 properties:
196 compatible:
197 enum:
198 - ti,omap4-mailbox
199 then:
200 properties:
201 ti,mbox-num-users:
202 enum: [3, 4]
203 ti,mbox-num-fifos:
204 enum: [8, 12]
205 interrupts:
206 minItems: 1
207 maxItems: 4
208
209 - if:
210 properties:
211 compatible:
212 enum:
213 - ti,omap3-mailbox
214 then:
215 properties:
216 ti,mbox-num-users:
217 const: 2
218 ti,mbox-num-fifos:
219 const: 2
220 interrupts:
221 minItems: 1
222 maxItems: 1
223
224 - if:
225 properties:
226 compatible:
227 enum:
228 - ti,omap2-mailbox
229 then:
230 properties:
231 ti,mbox-num-users:
232 const: 4
233 ti,mbox-num-fifos:
234 const: 6
235 interrupts:
236 minItems: 1
237 maxItems: 2
238
239 additionalProperties: false
240
241 examples:
242 - |
243 /* OMAP4 */
244 #include <dt-bindings/interrupt-controller/arm-gic.h>
245 mailbox: mailbox@4a0f4000 {
246 compatible = "ti,omap4-mailbox";
247 reg = <0x4a0f4000 0x200>;
248 interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
249 #mbox-cells = <1>;
250 ti,mbox-num-users = <3>;
251 ti,mbox-num-fifos = <8>;
252
253 mbox_ipu: mbox-ipu {
254 ti,mbox-tx = <0 0 0>;
255 ti,mbox-rx = <1 0 0>;
256 };
257 mbox_dsp: mbox-dsp {
258 ti,mbox-tx = <3 0 0>;
259 ti,mbox-rx = <2 0 0>;
260 };
261 };
262
263 dsp {
264 mboxes = <&mailbox &mbox_dsp>;
265 };
266
267 - |
268 /* AM33xx */
269 mailbox1: mailbox@480c8000 {
270 compatible = "ti,omap4-mailbox";
271 reg = <0x480c8000 0x200>;
272 interrupts = <77>;
273 #mbox-cells = <1>;
274 ti,mbox-num-users = <4>;
275 ti,mbox-num-fifos = <8>;
276
277 mbox_wkupm3: mbox-wkup-m3 {
278 ti,mbox-tx = <0 0 0>;
279 ti,mbox-rx = <0 0 3>;
280 ti,mbox-send-noirq;
281 };
282 };
283
284 - |
285 /* AM65x */
286 mailbox0_cluster0: mailbox@31f80000 {
287 compatible = "ti,am654-mailbox";
288 reg = <0x31f80000 0x200>;
289 #mbox-cells = <1>;
290 ti,mbox-num-users = <4>;
291 ti,mbox-num-fifos = <16>;
292 interrupt-parent = <&intr_main_navss>;
293 interrupts = <436>;
294
295 mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
296 ti,mbox-tx = <1 0 0>;
297 ti,mbox-rx = <0 0 0>;
298 };
299 };
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.