Documentation/devicetree/bindings/mailbox/omap-mailbox.txt

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