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 };