Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml

   1 # SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/mailbox/ti,omap-mailbox.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: TI OMAP2+ and K3 Mailbox devices
   8
   9 maintainers:
  10   - Suman Anna <s-anna@ti.com>
  11
  12 description: |
  13   The OMAP Mailbox hardware facilitates communication between different
  14   processors using a queued mailbox interrupt mechanism. The IP block is
  15   external to the various processor subsystems and is connected on an
  16   interconnect bus. The communication is achieved through a set of registers
  17   for message storage and interrupt configuration registers.
  18
  19   Each mailbox IP block/cluster has a certain number of h/w fifo queues and
  20   output interrupt lines. An output interrupt line is routed to an interrupt
  21   controller within a processor subsystem, and there can be more than one line
  22   going to a specific processor's interrupt controller. The interrupt line
  23   connections are fixed for an instance and are dictated by the IP integration
  24   into the SoC (excluding the SoCs that have an Interrupt Crossbar or an
  25   Interrupt Router IP). Each interrupt line is programmable through a set of
  26   interrupt configuration registers, and have a rx and tx interrupt source per
  27   h/w fifo. Communication between different processors is achieved through the
  28   appropriate programming of the rx and tx interrupt sources on the appropriate
  29   interrupt lines.
  30
  31   The number of h/w fifo queues and interrupt lines dictate the usable
  32   registers. All the current OMAP SoCs except for the newest DRA7xx SoC has a
  33   single IP instance. DRA7xx has multiple instances with different number of
  34   h/w fifo queues and interrupt lines between different instances. The interrupt
  35   lines can also be routed to different processor sub-systems on DRA7xx as they
  36   are routed through the Crossbar, a kind of interrupt router/multiplexer. The
  37   K3 AM65x, J721E and J7200 SoCs has each of these instances form a cluster and
  38   combine multiple clusters into a single IP block present within the Main
  39   NavSS. The interrupt lines from all these clusters are multiplexed and routed
  40   to different processor subsystems over a limited number of common interrupt
  41   output lines of an Interrupt Router. The AM64x SoCS also uses a single IP
  42   block comprising of multiple clusters, but the number of clusters are
  43   smaller, and the interrupt output lines are connected directly to various
  44   processors.
  45
  46   Mailbox Controller Nodes
  47   =========================
  48   A Mailbox device node is used to represent a Mailbox IP instance/cluster
  49   within a SoC. The sub-mailboxes (actual communication channels) are
  50   represented as child nodes of this parent node.
  51
  52   Mailbox Users
  53   ==============
  54   A device needing to communicate with a target processor device should specify
  55   them using the common mailbox binding properties, "mboxes" and the optional
  56   "mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
  57   for details). Each value of the mboxes property should contain a phandle to
  58   the mailbox controller device node and an args specifier that will be the
  59   phandle to the intended sub-mailbox child node to be used for communication.
  60   The equivalent "mbox-names" property value can be used to give a name to the
  61   communication channel to be used by the client user.
  62
  63 $defs:
  64   omap-mbox-descriptor:
  65     $ref: /schemas/types.yaml#/definitions/uint32-array
  66     description:
  67       The omap-mbox-descriptor is made of up of 3 cells and represents a single
  68       uni-directional communication channel. A typical sub-mailbox device uses
  69       two such channels - one for transmitting (Tx) and one for receiving (Rx).
  70     items:
  71       - description:
  72           mailbox fifo id used either for transmitting on ti,mbox-tx channel or
  73           for receiving on ti,mbox-rx channel (fifo_id). This is the hardware
  74           fifo number within a mailbox cluster.
  75       - description:
  76           irq identifier index number to use from the parent's interrupts data.
  77           Should be 0 for most of the cases, a positive index value is seen only
  78           on mailboxes that have multiple interrupt lines connected to the MPU
  79           processor (irq_id). This is an index number in the listed interrupts
  80           property in the DT nodes.
  81       - description:
  82           mailbox user id for identifying the interrupt line associated with
  83           generating a tx/rx fifo interrupt (usr_id). This is the hardware
  84           user id number within a mailbox cluster.
  85
  86   omap-sub-mailbox:
  87     type: object
  88     description:
  89       The omap-sub-mailbox is a child node within a Mailbox controller device
  90       node and represents the actual communication channel used to send and
  91       receive messages between the host processor and a remote processor. Each
  92       child node should have a unique node name across all the different mailbox
  93       device nodes.
  94
  95     properties:
  96       ti,mbox-tx:
  97         $ref: "#/$defs/omap-mbox-descriptor"
  98         description: sub-mailbox descriptor property defining a Tx fifo.
  99
 100       ti,mbox-rx:
 101         $ref: "#/$defs/omap-mbox-descriptor"
 102         description: sub-mailbox descriptor property defining a Rx fifo.
 103
 104       ti,mbox-send-noirq:
 105         type: boolean
 106         description:
 107           Quirk flag to allow the client user of this sub-mailbox to send
 108           messages without triggering a Tx ready interrupt, and to control
 109           the Tx ticker. Should be used only on sub-mailboxes used to
 110           communicate with WkupM3 remote processor on AM33xx/AM43xx SoCs.
 111
 112     required:
 113       - ti,mbox-tx
 114       - ti,mbox-rx
 115
 116 properties:
 117   compatible:
 118     enum:
 119       - ti,omap2-mailbox # for OMAP2420, OMAP2430 SoCs
 120       - ti,omap3-mailbox # for OMAP3430, OMAP3630 SoCs
 121       - ti,omap4-mailbox # for OMAP44xx, OMAP54xx, AM33xx, AM43xx and DRA7xx SoCs
 122       - ti,am654-mailbox # for K3 AM65x, J721E and J7200 SoCs
 123       - ti,am64-mailbox  # for K3 AM64x SoCs
 124
 125   reg:
 126     maxItems: 1
 127
 128   interrupts:
 129     description:
 130       Contains the interrupt information for the mailbox device. The format is
 131       dependent on which interrupt controller the Mailbox device uses. The
 132       number of interrupts listed will at most be the value specified in
 133       ti,mbox-num-users property, but is usually limited by the number of
 134       interrupts reaching the main processor. An interrupt-parent property
 135       is required on SoCs where the interrupt lines are connected through a
 136       Interrupt Router before reaching the main processor's GIC.
 137
 138   "#mbox-cells":
 139     const: 1
 140     description:
 141       The specifier is a phandle to an omap-sub-mailbox device.
 142
 143   ti,mbox-num-users:
 144     $ref: /schemas/types.yaml#/definitions/uint32
 145     description:
 146       Number of targets (processor devices) that the mailbox device can
 147       interrupt.
 148
 149   ti,mbox-num-fifos:
 150     $ref: /schemas/types.yaml#/definitions/uint32
 151     description: Number of h/w fifo queues within the mailbox IP block.
 152
 153   ti,hwmods:
 154     $ref: /schemas/types.yaml#/definitions/string
 155     deprecated: true
 156     description:
 157       Name of the hwmod associated with the mailbox. This should be defined
 158       in the mailbox node only if the node is not defined as a child node of
 159       a corresponding sysc interconnect node.
 160
 161       This property is only needed on some legacy OMAP SoCs which have not
 162       yet been converted to the ti,sysc interconnect hierarachy, but is
 163       otherwise considered obsolete.
 164
 165 patternProperties:
 166   "^mbox-[a-z0-9-]+$":
 167     $ref: "#/$defs/omap-sub-mailbox"
 168
 169 required:
 170   - compatible
 171   - reg
 172   - interrupts
 173   - "#mbox-cells"
 174   - ti,mbox-num-users
 175   - ti,mbox-num-fifos
 176
 177 allOf:
 178   - if:
 179       properties:
 180         compatible:
 181           enum:
 182             - ti,am654-mailbox
 183     then:
 184       required:
 185         - interrupt-parent
 186
 187   - if:
 188       properties:
 189         compatible:
 190           enum:
 191             - ti,am654-mailbox
 192             - ti,am64-mailbox
 193     then:
 194       properties:
 195         ti,mbox-num-users:
 196           const: 4
 197         ti,mbox-num-fifos:
 198           const: 16
 199         interrupts:
 200           minItems: 1
 201           maxItems: 4
 202
 203   - if:
 204       properties:
 205         compatible:
 206           enum:
 207             - ti,omap4-mailbox
 208     then:
 209       properties:
 210         ti,mbox-num-users:
 211           enum: [3, 4]
 212         ti,mbox-num-fifos:
 213           enum: [8, 12]
 214         interrupts:
 215           minItems: 1
 216           maxItems: 4
 217
 218   - if:
 219       properties:
 220         compatible:
 221           enum:
 222             - ti,omap3-mailbox
 223     then:
 224       properties:
 225         ti,mbox-num-users:
 226           const: 2
 227         ti,mbox-num-fifos:
 228           const: 2
 229         interrupts:
 230           minItems: 1
 231           maxItems: 1
 232
 233   - if:
 234       properties:
 235         compatible:
 236           enum:
 237             - ti,omap2-mailbox
 238     then:
 239       properties:
 240         ti,mbox-num-users:
 241           const: 4
 242         ti,mbox-num-fifos:
 243           const: 6
 244         interrupts:
 245           minItems: 1
 246           maxItems: 2
 247
 248 additionalProperties: false
 249
 250 examples:
 251   - |
 252     /* OMAP4 */
 253     #include <dt-bindings/interrupt-controller/arm-gic.h>
 254     mailbox: mailbox@4a0f4000 {
 255         compatible = "ti,omap4-mailbox";
 256         reg = <0x4a0f4000 0x200>;
 257         interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
 258         #mbox-cells = <1>;
 259         ti,mbox-num-users = <3>;
 260         ti,mbox-num-fifos = <8>;
 261
 262         mbox_ipu: mbox-ipu {
 263             ti,mbox-tx = <0 0 0>;
 264             ti,mbox-rx = <1 0 0>;
 265         };
 266         mbox_dsp: mbox-dsp {
 267             ti,mbox-tx = <3 0 0>;
 268             ti,mbox-rx = <2 0 0>;
 269         };
 270     };
 271
 272     dsp {
 273         mboxes = <&mailbox &mbox_dsp>;
 274     };
 275
 276   - |
 277     /* AM33xx */
 278     mailbox1: mailbox@480c8000 {
 279         compatible = "ti,omap4-mailbox";
 280         reg = <0x480c8000 0x200>;
 281         interrupts = <77>;
 282         #mbox-cells = <1>;
 283         ti,mbox-num-users = <4>;
 284         ti,mbox-num-fifos = <8>;
 285
 286         mbox_wkupm3: mbox-wkup-m3 {
 287             ti,mbox-tx = <0 0 0>;
 288             ti,mbox-rx = <0 0 3>;
 289             ti,mbox-send-noirq;
 290         };
 291     };
 292
 293   - |
 294     /* AM65x */
 295     mailbox0_cluster0: mailbox@31f80000 {
 296         compatible = "ti,am654-mailbox";
 297         reg = <0x31f80000 0x200>;
 298         #mbox-cells = <1>;
 299         ti,mbox-num-users = <4>;
 300         ti,mbox-num-fifos = <16>;
 301         interrupt-parent = <&intr_main_navss>;
 302         interrupts = <436>;
 303
 304         mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
 305             ti,mbox-tx = <1 0 0>;
 306             ti,mbox-rx = <0 0 0>;
 307         };
 308     };