Documentation/devicetree/bindings/mailbox/ti,omap-mailbox.yaml - linux - Git at Google

 # 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 <s-anna@ti.com>

 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 hierarachy, 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
     then:
       required:
         - interrupt-parent

   - 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 <dt-bindings/interrupt-controller/arm-gic.h>
     mailbox: mailbox@4a0f4000 {
         compatible = "ti,omap4-mailbox";
         reg = <0x4a0f4000 0x200>;
         interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
         #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>;
         };
     };
	# 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 <s-anna@ti.com>

	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 hierarachy, 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
	then:
	required:
	- interrupt-parent

	- 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 <dt-bindings/interrupt-controller/arm-gic.h>
	mailbox: mailbox@4a0f4000 {
	compatible = "ti,omap4-mailbox";
	reg = <0x4a0f4000 0x200>;
	interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
	#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>;
	};
	};