1OMAP2+ Mailbox Driver
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 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.
27
28Mailbox Device Node:
29====================
30A Mailbox device node is used to represent a Mailbox IP instance within a SoC.
31The sub-mailboxes are represented as child nodes of this parent node.
32
33Required properties:
34--------------------
35- compatible:		Should be one of the following,
36			    "ti,omap2-mailbox" for OMAP2420, OMAP2430 SoCs
37			    "ti,omap3-mailbox" for OMAP3430, OMAP3630 SoCs
38			    "ti,omap4-mailbox" for OMAP44xx, OMAP54xx, AM33xx,
39						   AM43xx and DRA7xx SoCs
40- reg:			Contains the mailbox register address range (base
41			address and length)
42- interrupts:		Contains the interrupt information for the mailbox
43			device. The format is dependent on which interrupt
44			controller the OMAP device uses
45- ti,hwmods:		Name of the hwmod associated with the mailbox
46- #mbox-cells:		Common mailbox binding property to identify the number
47			of cells required for the mailbox specifier. Should be
48			1
49- ti,mbox-num-users:	Number of targets (processor devices) that the mailbox
50			device can interrupt
51- ti,mbox-num-fifos:	Number of h/w fifo queues within the mailbox IP block
52
53Child Nodes:
54============
55A child node is used for representing the actual sub-mailbox device that is
56used for the communication between the host processor and a remote processor.
57Each child node should have a unique node name across all the different
58mailbox device nodes.
59
60Required properties:
61--------------------
62- ti,mbox-tx:		sub-mailbox descriptor property defining a Tx fifo
63- ti,mbox-rx:		sub-mailbox descriptor property defining a Rx fifo
64
65Sub-mailbox Descriptor Data
66---------------------------
67Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of
68data that represent the following:
69    Cell #1 (fifo_id) - mailbox fifo id used either for transmitting
70                        (ti,mbox-tx) or for receiving (ti,mbox-rx)
71    Cell #2 (irq_id)  - irq identifier index number to use from the parent's
72                        interrupts data. Should be 0 for most of the cases, a
73                        positive index value is seen only on mailboxes that have
74                        multiple interrupt lines connected to the MPU processor.
75    Cell #3 (usr_id)  - mailbox user id for identifying the interrupt line
76                        associated with generating a tx/rx fifo interrupt.
77
78Mailbox Users:
79==============
80A device needing to communicate with a target processor device should specify
81them using the common mailbox binding properties, "mboxes" and the optional
82"mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
83for details). Each value of the mboxes property should contain a phandle to the
84mailbox controller device node and an args specifier that will be the phandle to
85the intended sub-mailbox child node to be used for communication. The equivalent
86"mbox-names" property value can be used to give a name to the communication channel
87to be used by the client user.
88
89
90Example:
91--------
92
93/* OMAP4 */
94mailbox: mailbox@4a0f4000 {
95	compatible = "ti,omap4-mailbox";
96	reg = <0x4a0f4000 0x200>;
97	interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
98	ti,hwmods = "mailbox";
99	#mbox-cells = <1>;
100	ti,mbox-num-users = <3>;
101	ti,mbox-num-fifos = <8>;
102	mbox_ipu: mbox_ipu {
103		ti,mbox-tx = <0 0 0>;
104		ti,mbox-rx = <1 0 0>;
105	};
106	mbox_dsp: mbox_dsp {
107		ti,mbox-tx = <3 0 0>;
108		ti,mbox-rx = <2 0 0>;
109	};
110};
111
112dsp {
113	...
114	mboxes = <&mailbox &mbox_dsp>;
115	...
116};
117
118/* AM33xx */
119mailbox: mailbox@480C8000 {
120	compatible = "ti,omap4-mailbox";
121	reg = <0x480C8000 0x200>;
122	interrupts = <77>;
123	ti,hwmods = "mailbox";
124	#mbox-cells = <1>;
125	ti,mbox-num-users = <4>;
126	ti,mbox-num-fifos = <8>;
127	mbox_wkupm3: wkup_m3 {
128		ti,mbox-tx = <0 0 0>;
129		ti,mbox-rx = <0 0 3>;
130	};
131};
132