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