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 - ti,mbox-num-users:    Number of targets (processor devices) that the mailbox
  47                         device can interrupt
  48 - ti,mbox-num-fifos:    Number of h/w fifo queues within the mailbox IP block
  49
  50 Child Nodes:
  51 ============
  52 A child node is used for representing the actual sub-mailbox device that is
  53 used for the communication between the host processor and a remote processor.
  54 Each child node should have a unique node name across all the different
  55 mailbox device nodes.
  56
  57 Required properties:
  58 --------------------
  59 - ti,mbox-tx:           sub-mailbox descriptor property defining a Tx fifo
  60 - ti,mbox-rx:           sub-mailbox descriptor property defining a Rx fifo
  61
  62 Sub-mailbox Descriptor Data
  63 ---------------------------
  64 Each of the above ti,mbox-tx and ti,mbox-rx properties should have 3 cells of
  65 data that represent the following:
  66     Cell #1 (fifo_id) - mailbox fifo id used either for transmitting
  67                         (ti,mbox-tx) or for receiving (ti,mbox-rx)
  68     Cell #2 (irq_id)  - irq identifier index number to use from the parent's
  69                         interrupts data. Should be 0 for most of the cases, a
  70                         positive index value is seen only on mailboxes that have
  71                         multiple interrupt lines connected to the MPU processor.
  72     Cell #3 (usr_id)  - mailbox user id for identifying the interrupt line
  73                         associated with generating a tx/rx fifo interrupt.
  74
  75 Example:
  76 --------
  77
  78 /* OMAP4 */
  79 mailbox: mailbox@4a0f4000 {
  80         compatible = "ti,omap4-mailbox";
  81         reg = <0x4a0f4000 0x200>;
  82         interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
  83         ti,hwmods = "mailbox";
  84         ti,mbox-num-users = <3>;
  85         ti,mbox-num-fifos = <8>;
  86         mbox_ipu: mbox_ipu {
  87                 ti,mbox-tx = <0 0 0>;
  88                 ti,mbox-rx = <1 0 0>;
  89         };
  90         mbox_dsp: mbox_dsp {
  91                 ti,mbox-tx = <3 0 0>;
  92                 ti,mbox-rx = <2 0 0>;
  93         };
  94 };
  95
  96 /* AM33xx */
  97 mailbox: mailbox@480C8000 {
  98         compatible = "ti,omap4-mailbox";
  99         reg = <0x480C8000 0x200>;
 100         interrupts = <77>;
 101         ti,hwmods = "mailbox";
 102         ti,mbox-num-users = <4>;
 103         ti,mbox-num-fifos = <8>;
 104         mbox_wkupm3: wkup_m3 {
 105                 ti,mbox-tx = <0 0 0>;
 106                 ti,mbox-rx = <0 0 3>;
 107         };
 108 };