# SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause) %YAML 1.2 --- $id: http://devicetree.org/schemas/mailbox/ti,omap-mailbox.yaml# $schema: http://devicetree.org/meta-schemas/core.yaml# title: TI OMAP2+ and K3 Mailbox devices maintainers: - Suman Anna description: | The OMAP Mailbox hardware facilitates communication between different processors using a queued mailbox interrupt mechanism. The IP block is external to the various processor subsystems and is connected on an interconnect bus. The communication is achieved through a set of registers for message storage and interrupt configuration registers. Each mailbox IP block/cluster has a certain number of h/w fifo queues and output interrupt lines. An output interrupt line is routed to an interrupt controller within a processor subsystem, and there can be more than one line going to a specific processor's interrupt controller. The interrupt line connections are fixed for an instance and are dictated by the IP integration into the SoC (excluding the SoCs that have an Interrupt Crossbar or an Interrupt Router IP). Each interrupt line is programmable through a set of interrupt configuration registers, and have a rx and tx interrupt source per h/w fifo. Communication between different processors is achieved through the appropriate programming of the rx and tx interrupt sources on the appropriate interrupt lines. The number of h/w fifo queues and interrupt lines dictate the usable registers. All the current OMAP SoCs except for the newest DRA7xx SoC has a single IP instance. DRA7xx has multiple instances with different number of h/w fifo queues and interrupt lines between different instances. The interrupt lines can also be routed to different processor sub-systems on DRA7xx as they are routed through the Crossbar, a kind of interrupt router/multiplexer. The K3 AM65x, J721E and J7200 SoCs has each of these instances form a cluster and combine multiple clusters into a single IP block present within the Main NavSS. The interrupt lines from all these clusters are multiplexed and routed to different processor subsystems over a limited number of common interrupt output lines of an Interrupt Router. The AM64x SoCS also uses a single IP block comprising of multiple clusters, but the number of clusters are smaller, and the interrupt output lines are connected directly to various processors. Mailbox Controller Nodes ========================= A Mailbox device node is used to represent a Mailbox IP instance/cluster within a SoC. The sub-mailboxes (actual communication channels) are represented as child nodes of this parent node. Mailbox Users ============== A device needing to communicate with a target processor device should specify them using the common mailbox binding properties, "mboxes" and the optional "mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt for details). Each value of the mboxes property should contain a phandle to the mailbox controller device node and an args specifier that will be the phandle to the intended sub-mailbox child node to be used for communication. The equivalent "mbox-names" property value can be used to give a name to the communication channel to be used by the client user. $defs: omap-mbox-descriptor: $ref: /schemas/types.yaml#/definitions/uint32-array description: The omap-mbox-descriptor is made of up of 3 cells and represents a single uni-directional communication channel. A typical sub-mailbox device uses two such channels - one for transmitting (Tx) and one for receiving (Rx). items: - description: mailbox fifo id used either for transmitting on ti,mbox-tx channel or for receiving on ti,mbox-rx channel (fifo_id). This is the hardware fifo number within a mailbox cluster. - description: irq identifier index number to use from the parent's interrupts data. Should be 0 for most of the cases, a positive index value is seen only on mailboxes that have multiple interrupt lines connected to the MPU processor (irq_id). This is an index number in the listed interrupts property in the DT nodes. - description: mailbox user id for identifying the interrupt line associated with generating a tx/rx fifo interrupt (usr_id). This is the hardware user id number within a mailbox cluster. omap-sub-mailbox: type: object description: The omap-sub-mailbox is a child node within a Mailbox controller device node and represents the actual communication channel used to send and receive messages between the host processor and a remote processor. Each child node should have a unique node name across all the different mailbox device nodes. properties: ti,mbox-tx: $ref: "#/$defs/omap-mbox-descriptor" description: sub-mailbox descriptor property defining a Tx fifo. ti,mbox-rx: $ref: "#/$defs/omap-mbox-descriptor" description: sub-mailbox descriptor property defining a Rx fifo. ti,mbox-send-noirq: type: boolean description: Quirk flag to allow the client user of this sub-mailbox to send messages without triggering a Tx ready interrupt, and to control the Tx ticker. Should be used only on sub-mailboxes used to communicate with WkupM3 remote processor on AM33xx/AM43xx SoCs. required: - ti,mbox-tx - ti,mbox-rx properties: compatible: enum: - ti,omap2-mailbox # for OMAP2420, OMAP2430 SoCs - ti,omap3-mailbox # for OMAP3430, OMAP3630 SoCs - ti,omap4-mailbox # for OMAP44xx, OMAP54xx, AM33xx, AM43xx and DRA7xx SoCs - ti,am654-mailbox # for K3 AM65x, J721E and J7200 SoCs - ti,am64-mailbox # for K3 AM64x SoCs reg: maxItems: 1 interrupts: description: Contains the interrupt information for the mailbox device. The format is dependent on which interrupt controller the Mailbox device uses. The number of interrupts listed will at most be the value specified in ti,mbox-num-users property, but is usually limited by the number of interrupts reaching the main processor. An interrupt-parent property is required on SoCs where the interrupt lines are connected through a Interrupt Router before reaching the main processor's GIC. "#mbox-cells": const: 1 description: The specifier is a phandle to an omap-sub-mailbox device. ti,mbox-num-users: $ref: /schemas/types.yaml#/definitions/uint32 description: Number of targets (processor devices) that the mailbox device can interrupt. ti,mbox-num-fifos: $ref: /schemas/types.yaml#/definitions/uint32 description: Number of h/w fifo queues within the mailbox IP block. ti,hwmods: $ref: /schemas/types.yaml#/definitions/string deprecated: true description: Name of the hwmod associated with the mailbox. This should be defined in the mailbox node only if the node is not defined as a child node of a corresponding sysc interconnect node. This property is only needed on some legacy OMAP SoCs which have not yet been converted to the ti,sysc interconnect hierarchy, but is otherwise considered obsolete. patternProperties: "^mbox-[a-z0-9-]+$": $ref: "#/$defs/omap-sub-mailbox" required: - compatible - reg - interrupts - "#mbox-cells" - ti,mbox-num-users - ti,mbox-num-fifos allOf: - if: properties: compatible: enum: - ti,am654-mailbox - ti,am64-mailbox then: properties: ti,mbox-num-users: const: 4 ti,mbox-num-fifos: const: 16 interrupts: minItems: 1 maxItems: 4 - if: properties: compatible: enum: - ti,omap4-mailbox then: properties: ti,mbox-num-users: enum: [3, 4] ti,mbox-num-fifos: enum: [8, 12] interrupts: minItems: 1 maxItems: 4 - if: properties: compatible: enum: - ti,omap3-mailbox then: properties: ti,mbox-num-users: const: 2 ti,mbox-num-fifos: const: 2 interrupts: minItems: 1 maxItems: 1 - if: properties: compatible: enum: - ti,omap2-mailbox then: properties: ti,mbox-num-users: const: 4 ti,mbox-num-fifos: const: 6 interrupts: minItems: 1 maxItems: 2 additionalProperties: false examples: - | /* OMAP4 */ #include mailbox: mailbox@4a0f4000 { compatible = "ti,omap4-mailbox"; reg = <0x4a0f4000 0x200>; interrupts = ; #mbox-cells = <1>; ti,mbox-num-users = <3>; ti,mbox-num-fifos = <8>; mbox_ipu: mbox-ipu { ti,mbox-tx = <0 0 0>; ti,mbox-rx = <1 0 0>; }; mbox_dsp: mbox-dsp { ti,mbox-tx = <3 0 0>; ti,mbox-rx = <2 0 0>; }; }; dsp { mboxes = <&mailbox &mbox_dsp>; }; - | /* AM33xx */ mailbox1: mailbox@480c8000 { compatible = "ti,omap4-mailbox"; reg = <0x480c8000 0x200>; interrupts = <77>; #mbox-cells = <1>; ti,mbox-num-users = <4>; ti,mbox-num-fifos = <8>; mbox_wkupm3: mbox-wkup-m3 { ti,mbox-tx = <0 0 0>; ti,mbox-rx = <0 0 3>; ti,mbox-send-noirq; }; }; - | /* AM65x */ mailbox0_cluster0: mailbox@31f80000 { compatible = "ti,am654-mailbox"; reg = <0x31f80000 0x200>; #mbox-cells = <1>; ti,mbox-num-users = <4>; ti,mbox-num-fifos = <16>; interrupt-parent = <&intr_main_navss>; interrupts = <436>; mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 { ti,mbox-tx = <1 0 0>; ti,mbox-rx = <0 0 0>; }; };