summaryrefslogtreecommitdiffstats
path: root/Documentation/devicetree/bindings/mailbox/omap-mailbox.txt
blob: 35c3f56b7f7bf56b7a2485addbf8140a441cc85a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
OMAP2+ and K3 Mailbox
=====================

The OMAP mailbox hardware facilitates communication between different processors
using a queued mailbox interrupt mechanism. The IP block is external to the
various processor subsystems and is connected on an interconnect bus. The
communication is achieved through a set of registers for message storage and
interrupt configuration registers.

Each mailbox IP block/cluster has a certain number of h/w fifo queues and output
interrupt lines. An output interrupt line is routed to an interrupt controller
within a processor subsystem, and there can be more than one line going to a
specific processor's interrupt controller. The interrupt line connections are
fixed for an instance and are dictated by the IP integration into the SoC
(excluding the SoCs that have a Interrupt Crossbar IP). Each interrupt line is
programmable through a set of interrupt configuration registers, and have a rx
and tx interrupt source per h/w fifo. Communication between different processors
is achieved through the appropriate programming of the rx and tx interrupt
sources on the appropriate interrupt lines.

The number of h/w fifo queues and interrupt lines dictate the usable registers.
All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP
instance. DRA7xx has multiple instances with different number of h/w fifo queues
and interrupt lines between different instances. The interrupt lines can also be
routed to different processor sub-systems on DRA7xx as they are routed through
the Crossbar, a kind of interrupt router/multiplexer. The K3 AM65x and J721E
SoCs has each of these instances form a cluster and combine multiple clusters
into a single IP block present within the Main NavSS. The interrupt lines from
all these clusters are multiplexed and routed to different processor subsystems
over a limited number of common interrupt output lines of an Interrupt Router.

Mailbox Device Node:
====================
A Mailbox device node is used to represent a Mailbox IP instance/cluster within
a SoC. The sub-mailboxes are represented as child nodes of this parent node.

Required properties:
--------------------
- compatible:		Should be one of the following,
			    "ti,omap2-mailbox" for OMAP2420, OMAP2430 SoCs
			    "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs
			    "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx,
						   AM43xx and DRA7xx SoCs
			    "ti,am654-mailbox" for K3 AM65x and J721E SoCs
- reg:			Contains the mailbox register address range (base
			address and length)
- interrupts:		Contains the interrupt information for the mailbox
			device. The format is dependent on which interrupt
			controller the Mailbox device uses
- #mbox-cells:		Common mailbox binding property to identify the number
			of cells required for the mailbox specifier. Should be
			1
- ti,mbox-num-users:	Number of targets (processor devices) that the mailbox
			device can interrupt
- ti,mbox-num-fifos:	Number of h/w fifo queues within the mailbox IP block

SoC-specific Required properties:
---------------------------------
The following are mandatory properties for the OMAP architecture based SoCs
only:
- ti,hwmods:		Name of the hwmod associated with the mailbox. This
			should be defined in the mailbox node only if the node
			is not defined as a child node of a corresponding sysc
			interconnect node.

The following are mandatory properties for the K3 AM65x and J721E SoCs only:
- interrupt-parent:	Should contain a phandle to the TI-SCI interrupt
			controller node that is used to dynamically program
			the interrupt routes between the IP and the main GIC
			controllers. See the following binding for additional
			details,
			Documentation/devicetree/bindings/interrupt-controller/ti,sci-intr.txt

Child Nodes:
============
A child node is used for representing the actual sub-mailbox device that is
used for the communication between the host processor and a remote processor.
Each child node should have a unique node name across all the different
mailbox device nodes.

Required properties:
--------------------
- ti,mbox-tx:		sub-mailbox descriptor property defining a Tx fifo
- ti,mbox-rx:		sub-mailbox descriptor property defining a Rx fifo

Sub-mailbox Descriptor Data
---------------------------
Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of
data that represent the following:
    Cell #1 (fifo_id) - mailbox fifo id used either for transmitting
                        (ti,mbox-tx) or for receiving (ti,mbox-rx)
    Cell #2 (irq_id)  - irq identifier index number to use from the parent's
                        interrupts data. Should be 0 for most of the cases, a
                        positive index value is seen only on mailboxes that have
                        multiple interrupt lines connected to the MPU processor.
    Cell #3 (usr_id)  - mailbox user id for identifying the interrupt line
                        associated with generating a tx/rx fifo interrupt.

Optional Properties:
--------------------
- ti,mbox-send-noirq:   Quirk flag to allow the client user of this sub-mailbox
                        to send messages without triggering a Tx ready interrupt,
                        and to control the Tx ticker. Should be used only on
                        sub-mailboxes used to communicate with WkupM3 remote
                        processor on AM33xx/AM43xx SoCs.

Mailbox Users:
==============
A device needing to communicate with a target processor device should specify
them using the common mailbox binding properties, "mboxes" and the optional
"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
for details). Each value of the mboxes property should contain a phandle to the
mailbox controller device node and an args specifier that will be the phandle to
the intended sub-mailbox child node to be used for communication. The equivalent
"mbox-names" property value can be used to give a name to the communication channel
to be used by the client user.


Example:
--------

1. /* OMAP4 */
mailbox: mailbox@4a0f4000 {
	compatible = "ti,omap4-mailbox";
	reg = <0x4a0f4000 0x200>;
	interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
	ti,hwmods = "mailbox";
	#mbox-cells = <1>;
	ti,mbox-num-users = <3>;
	ti,mbox-num-fifos = <8>;
	mbox_ipu: mbox_ipu {
		ti,mbox-tx = <0 0 0>;
		ti,mbox-rx = <1 0 0>;
	};
	mbox_dsp: mbox_dsp {
		ti,mbox-tx = <3 0 0>;
		ti,mbox-rx = <2 0 0>;
	};
};

dsp {
	...
	mboxes = <&mailbox &mbox_dsp>;
	...
};

2. /* AM33xx */
mailbox: mailbox@480c8000 {
	compatible = "ti,omap4-mailbox";
	reg = <0x480C8000 0x200>;
	interrupts = <77>;
	ti,hwmods = "mailbox";
	#mbox-cells = <1>;
	ti,mbox-num-users = <4>;
	ti,mbox-num-fifos = <8>;
	mbox_wkupm3: wkup_m3 {
		ti,mbox-tx = <0 0 0>;
		ti,mbox-rx = <0 0 3>;
	};
};

3. /* AM65x */
&cbass_main {
	cbass_main_navss: interconnect0 {
		mailbox0_cluster0: mailbox@31f80000 {
			compatible = "ti,am654-mailbox";
			reg = <0x00 0x31f80000 0x00 0x200>;
			#mbox-cells = <1>;
			ti,mbox-num-users = <4>;
			ti,mbox-num-fifos = <16>;
			interrupt-parent = <&intr_main_navss>;
			interrupts = <164 0>;

			mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
				ti,mbox-tx = <1 0 0>;
				ti,mbox-rx = <0 0 0>;
			};
		};
	};
};