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 hierarchy, 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             - ti,am64-mailbox
 184     then:
 185       properties:
 186         ti,mbox-num-users:
 187           const: 4
 188         ti,mbox-num-fifos:
 189           const: 16
 190         interrupts:
 191           minItems: 1
 192           maxItems: 4
 193
 194   - if:
 195       properties:
 196         compatible:
 197           enum:
 198             - ti,omap4-mailbox
 199     then:
 200       properties:
 201         ti,mbox-num-users:
 202           enum: [3, 4]
 203         ti,mbox-num-fifos:
 204           enum: [8, 12]
 205         interrupts:
 206           minItems: 1
 207           maxItems: 4
 208
 209   - if:
 210       properties:
 211         compatible:
 212           enum:
 213             - ti,omap3-mailbox
 214     then:
 215       properties:
 216         ti,mbox-num-users:
 217           const: 2
 218         ti,mbox-num-fifos:
 219           const: 2
 220         interrupts:
 221           minItems: 1
 222           maxItems: 1
 223
 224   - if:
 225       properties:
 226         compatible:
 227           enum:
 228             - ti,omap2-mailbox
 229     then:
 230       properties:
 231         ti,mbox-num-users:
 232           const: 4
 233         ti,mbox-num-fifos:
 234           const: 6
 235         interrupts:
 236           minItems: 1
 237           maxItems: 2
 238
 239 additionalProperties: false
 240
 241 examples:
 242   - |
 243     /* OMAP4 */
 244     #include <dt-bindings/interrupt-controller/arm-gic.h>
 245     mailbox: mailbox@4a0f4000 {
 246         compatible = "ti,omap4-mailbox";
 247         reg = <0x4a0f4000 0x200>;
 248         interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
 249         #mbox-cells = <1>;
 250         ti,mbox-num-users = <3>;
 251         ti,mbox-num-fifos = <8>;
 252
 253         mbox_ipu: mbox-ipu {
 254             ti,mbox-tx = <0 0 0>;
 255             ti,mbox-rx = <1 0 0>;
 256         };
 257         mbox_dsp: mbox-dsp {
 258             ti,mbox-tx = <3 0 0>;
 259             ti,mbox-rx = <2 0 0>;
 260         };
 261     };
 262
 263     dsp {
 264         mboxes = <&mailbox &mbox_dsp>;
 265     };
 266
 267   - |
 268     /* AM33xx */
 269     mailbox1: mailbox@480c8000 {
 270         compatible = "ti,omap4-mailbox";
 271         reg = <0x480c8000 0x200>;
 272         interrupts = <77>;
 273         #mbox-cells = <1>;
 274         ti,mbox-num-users = <4>;
 275         ti,mbox-num-fifos = <8>;
 276
 277         mbox_wkupm3: mbox-wkup-m3 {
 278             ti,mbox-tx = <0 0 0>;
 279             ti,mbox-rx = <0 0 3>;
 280             ti,mbox-send-noirq;
 281         };
 282     };
 283
 284   - |
 285     /* AM65x */
 286     mailbox0_cluster0: mailbox@31f80000 {
 287         compatible = "ti,am654-mailbox";
 288         reg = <0x31f80000 0x200>;
 289         #mbox-cells = <1>;
 290         ti,mbox-num-users = <4>;
 291         ti,mbox-num-fifos = <16>;
 292         interrupt-parent = <&intr_main_navss>;
 293         interrupts = <436>;
 294
 295         mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
 296             ti,mbox-tx = <1 0 0>;
 297             ti,mbox-rx = <0 0 0>;
 298         };
 299     };