GNU Linux-libre 4.14.266-gnu1
[releases.git] / Documentation / devicetree / bindings / mailbox / omap-mailbox.txt
1 OMAP2+ Mailbox Driver
2 =====================
3
4 The OMAP mailbox hardware facilitates communication between different processors
5 using a queued mailbox interrupt mechanism. The IP block is external to the
6 various processor subsystems and is connected on an interconnect bus. The
7 communication is achieved through a set of registers for message storage and
8 interrupt configuration registers.
9
10 Each mailbox IP block has a certain number of h/w fifo queues and output
11 interrupt lines. An output interrupt line is routed to an interrupt controller
12 within a processor subsystem, and there can be more than one line going to a
13 specific processor's interrupt controller. The interrupt line connections are
14 fixed 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
16 programmable through a set of interrupt configuration registers, and have a rx
17 and tx interrupt source per h/w fifo. Communication between different processors
18 is achieved through the appropriate programming of the rx and tx interrupt
19 sources on the appropriate interrupt lines.
20
21 The number of h/w fifo queues and interrupt lines dictate the usable registers.
22 All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP
23 instance. DRA7xx has multiple instances with different number of h/w fifo queues
24 and interrupt lines between different instances. The interrupt lines can also be
25 routed to different processor sub-systems on DRA7xx as they are routed through
26 the Crossbar, a kind of interrupt router/multiplexer.
27
28 Mailbox Device Node:
29 ====================
30 A Mailbox device node is used to represent a Mailbox IP instance within a SoC.
31 The sub-mailboxes are represented as child nodes of this parent node.
32
33 Required 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
53 Child Nodes:
54 ============
55 A child node is used for representing the actual sub-mailbox device that is
56 used for the communication between the host processor and a remote processor.
57 Each child node should have a unique node name across all the different
58 mailbox device nodes.
59
60 Required 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
65 Sub-mailbox Descriptor Data
66 ---------------------------
67 Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of
68 data 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
78 Optional Properties:
79 --------------------
80 - ti,mbox-send-noirq:   Quirk flag to allow the client user of this sub-mailbox
81                         to send messages without triggering a Tx ready interrupt,
82                         and to control the Tx ticker. Should be used only on
83                         sub-mailboxes used to communicate with WkupM3 remote
84                         processor on AM33xx/AM43xx SoCs.
85
86 Mailbox Users:
87 ==============
88 A device needing to communicate with a target processor device should specify
89 them using the common mailbox binding properties, "mboxes" and the optional
90 "mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
91 for details). Each value of the mboxes property should contain a phandle to the
92 mailbox controller device node and an args specifier that will be the phandle to
93 the intended sub-mailbox child node to be used for communication. The equivalent
94 "mbox-names" property value can be used to give a name to the communication channel
95 to be used by the client user.
96
97
98 Example:
99 --------
100
101 /* OMAP4 */
102 mailbox: mailbox@4a0f4000 {
103         compatible = "ti,omap4-mailbox";
104         reg = <0x4a0f4000 0x200>;
105         interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
106         ti,hwmods = "mailbox";
107         #mbox-cells = <1>;
108         ti,mbox-num-users = <3>;
109         ti,mbox-num-fifos = <8>;
110         mbox_ipu: mbox_ipu {
111                 ti,mbox-tx = <0 0 0>;
112                 ti,mbox-rx = <1 0 0>;
113         };
114         mbox_dsp: mbox_dsp {
115                 ti,mbox-tx = <3 0 0>;
116                 ti,mbox-rx = <2 0 0>;
117         };
118 };
119
120 dsp {
121         ...
122         mboxes = <&mailbox &mbox_dsp>;
123         ...
124 };
125
126 /* AM33xx */
127 mailbox: mailbox@480C8000 {
128         compatible = "ti,omap4-mailbox";
129         reg = <0x480C8000 0x200>;
130         interrupts = <77>;
131         ti,hwmods = "mailbox";
132         #mbox-cells = <1>;
133         ti,mbox-num-users = <4>;
134         ti,mbox-num-fifos = <8>;
135         mbox_wkupm3: wkup_m3 {
136                 ti,mbox-tx = <0 0 0>;
137                 ti,mbox-rx = <0 0 3>;
138         };
139 };