1OMAP2+ and K3 Mailbox
2=====================
3
4The OMAP mailbox hardware facilitates communication between different processors
5using a queued mailbox interrupt mechanism. The IP block is external to the
6various processor subsystems and is connected on an interconnect bus. The
7communication is achieved through a set of registers for message storage and
8interrupt configuration registers.
9
10Each mailbox IP block/cluster has a certain number of h/w fifo queues and output
11interrupt lines. An output interrupt line is routed to an interrupt controller
12within a processor subsystem, and there can be more than one line going to a
13specific processor's interrupt controller. The interrupt line connections are
14fixed for an instance and are dictated by the IP integration into the SoC
15(excluding the SoCs that have a Interrupt Crossbar IP). Each interrupt line is
16programmable through a set of interrupt configuration registers, and have a rx
17and tx interrupt source per h/w fifo. Communication between different processors
18is achieved through the appropriate programming of the rx and tx interrupt
19sources on the appropriate interrupt lines.
20
21The number of h/w fifo queues and interrupt lines dictate the usable registers.
22All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP
23instance. DRA7xx has multiple instances with different number of h/w fifo queues
24and interrupt lines between different instances. The interrupt lines can also be
25routed to different processor sub-systems on DRA7xx as they are routed through
26the Crossbar, a kind of interrupt router/multiplexer. The K3 AM65x and J721E
27SoCs has each of these instances form a cluster and combine multiple clusters
28into a single IP block present within the Main NavSS. The interrupt lines from
29all these clusters are multiplexed and routed to different processor subsystems
30over a limited number of common interrupt output lines of an Interrupt Router.
31The AM64x SoCS also uses a single IP block comprising of multiple clusters,
32but the number of clusters are smaller, and the interrupt output lines are
33connected directly to various processors.
34
35Mailbox Device Node:
36====================
37A Mailbox device node is used to represent a Mailbox IP instance/cluster within
38a SoC. The sub-mailboxes are represented as child nodes of this parent node.
39
40Required properties:
41--------------------
42- compatible:		Should be one of the following,
43			    "ti,omap2-mailbox" for OMAP2420, OMAP2430 SoCs
44			    "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs
45			    "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx,
46						   AM43xx and DRA7xx SoCs
47			    "ti,am654-mailbox" for K3 AM65x and J721E SoCs
48			    "ti,am64-mailbox" for K3 AM64x SoCs
49- reg:			Contains the mailbox register address range (base
50			address and length)
51- interrupts:		Contains the interrupt information for the mailbox
52			device. The format is dependent on which interrupt
53			controller the Mailbox device uses
54- #mbox-cells:		Common mailbox binding property to identify the number
55			of cells required for the mailbox specifier. Should be
56			1
57- ti,mbox-num-users:	Number of targets (processor devices) that the mailbox
58			device can interrupt
59- ti,mbox-num-fifos:	Number of h/w fifo queues within the mailbox IP block
60
61SoC-specific Required properties:
62---------------------------------
63The following are mandatory properties for the OMAP architecture based SoCs
64only:
65- ti,hwmods:		Name of the hwmod associated with the mailbox. This
66			should be defined in the mailbox node only if the node
67			is not defined as a child node of a corresponding sysc
68			interconnect node.
69
70The following are mandatory properties for the K3 AM65x and J721E SoCs only:
71- interrupt-parent:	Should contain a phandle to the TI-SCI interrupt
72			controller node that is used to dynamically program
73			the interrupt routes between the IP and the main GIC
74			controllers. See the following binding for additional
75			details,
76			Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.yaml
77
78Child Nodes:
79============
80A child node is used for representing the actual sub-mailbox device that is
81used for the communication between the host processor and a remote processor.
82Each child node should have a unique node name across all the different
83mailbox device nodes.
84
85Required properties:
86--------------------
87- ti,mbox-tx:		sub-mailbox descriptor property defining a Tx fifo
88- ti,mbox-rx:		sub-mailbox descriptor property defining a Rx fifo
89
90Sub-mailbox Descriptor Data
91---------------------------
92Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of
93data that represent the following:
94    Cell #1 (fifo_id) - mailbox fifo id used either for transmitting
95                        (ti,mbox-tx) or for receiving (ti,mbox-rx)
96    Cell #2 (irq_id)  - irq identifier index number to use from the parent's
97                        interrupts data. Should be 0 for most of the cases, a
98                        positive index value is seen only on mailboxes that have
99                        multiple interrupt lines connected to the MPU processor.
100    Cell #3 (usr_id)  - mailbox user id for identifying the interrupt line
101                        associated with generating a tx/rx fifo interrupt.
102
103Optional Properties:
104--------------------
105- ti,mbox-send-noirq:   Quirk flag to allow the client user of this sub-mailbox
106                        to send messages without triggering a Tx ready interrupt,
107                        and to control the Tx ticker. Should be used only on
108                        sub-mailboxes used to communicate with WkupM3 remote
109                        processor on AM33xx/AM43xx SoCs.
110
111Mailbox Users:
112==============
113A device needing to communicate with a target processor device should specify
114them using the common mailbox binding properties, "mboxes" and the optional
115"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
116for details). Each value of the mboxes property should contain a phandle to the
117mailbox controller device node and an args specifier that will be the phandle to
118the intended sub-mailbox child node to be used for communication. The equivalent
119"mbox-names" property value can be used to give a name to the communication channel
120to be used by the client user.
121
122
123Example:
124--------
125
1261. /* OMAP4 */
127mailbox: mailbox@4a0f4000 {
128	compatible = "ti,omap4-mailbox";
129	reg = <0x4a0f4000 0x200>;
130	interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
131	ti,hwmods = "mailbox";
132	#mbox-cells = <1>;
133	ti,mbox-num-users = <3>;
134	ti,mbox-num-fifos = <8>;
135	mbox_ipu: mbox_ipu {
136		ti,mbox-tx = <0 0 0>;
137		ti,mbox-rx = <1 0 0>;
138	};
139	mbox_dsp: mbox_dsp {
140		ti,mbox-tx = <3 0 0>;
141		ti,mbox-rx = <2 0 0>;
142	};
143};
144
145dsp {
146	...
147	mboxes = <&mailbox &mbox_dsp>;
148	...
149};
150
1512. /* AM33xx */
152mailbox: mailbox@480c8000 {
153	compatible = "ti,omap4-mailbox";
154	reg = <0x480C8000 0x200>;
155	interrupts = <77>;
156	ti,hwmods = "mailbox";
157	#mbox-cells = <1>;
158	ti,mbox-num-users = <4>;
159	ti,mbox-num-fifos = <8>;
160	mbox_wkupm3: wkup_m3 {
161		ti,mbox-tx = <0 0 0>;
162		ti,mbox-rx = <0 0 3>;
163	};
164};
165
1663. /* AM65x */
167&cbass_main {
168	cbass_main_navss: interconnect0 {
169		mailbox0_cluster0: mailbox@31f80000 {
170			compatible = "ti,am654-mailbox";
171			reg = <0x00 0x31f80000 0x00 0x200>;
172			#mbox-cells = <1>;
173			ti,mbox-num-users = <4>;
174			ti,mbox-num-fifos = <16>;
175			interrupt-parent = <&intr_main_navss>;
176			interrupts = <164 0>;
177
178			mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
179				ti,mbox-tx = <1 0 0>;
180				ti,mbox-rx = <0 0 0>;
181			};
182		};
183	};
184};
185