0001 # SPDX-License-Identifier: (GPL-2.0-only or BSD-2-Clause)
0002 %YAML 1.2
0003 ---
0004 $id: http://devicetree.org/schemas/mailbox/ti,omap-mailbox.yaml#
0005 $schema: http://devicetree.org/meta-schemas/core.yaml#
0006
0007 title: TI OMAP2+ and K3 Mailbox devices
0008
0009 maintainers:
0010 - Suman Anna <s-anna@ti.com>
0011
0012 description: |
0013 The OMAP Mailbox hardware facilitates communication between different
0014 processors using a queued mailbox interrupt mechanism. The IP block is
0015 external to the various processor subsystems and is connected on an
0016 interconnect bus. The communication is achieved through a set of registers
0017 for message storage and interrupt configuration registers.
0018
0019 Each mailbox IP block/cluster has a certain number of h/w fifo queues and
0020 output interrupt lines. An output interrupt line is routed to an interrupt
0021 controller within a processor subsystem, and there can be more than one line
0022 going to a specific processor's interrupt controller. The interrupt line
0023 connections are fixed for an instance and are dictated by the IP integration
0024 into the SoC (excluding the SoCs that have an Interrupt Crossbar or an
0025 Interrupt Router IP). Each interrupt line is programmable through a set of
0026 interrupt configuration registers, and have a rx and tx interrupt source per
0027 h/w fifo. Communication between different processors is achieved through the
0028 appropriate programming of the rx and tx interrupt sources on the appropriate
0029 interrupt lines.
0030
0031 The number of h/w fifo queues and interrupt lines dictate the usable
0032 registers. All the current OMAP SoCs except for the newest DRA7xx SoC has a
0033 single IP instance. DRA7xx has multiple instances with different number of
0034 h/w fifo queues and interrupt lines between different instances. The interrupt
0035 lines can also be routed to different processor sub-systems on DRA7xx as they
0036 are routed through the Crossbar, a kind of interrupt router/multiplexer. The
0037 K3 AM65x, J721E and J7200 SoCs has each of these instances form a cluster and
0038 combine multiple clusters into a single IP block present within the Main
0039 NavSS. The interrupt lines from all these clusters are multiplexed and routed
0040 to different processor subsystems over a limited number of common interrupt
0041 output lines of an Interrupt Router. The AM64x SoCS also uses a single IP
0042 block comprising of multiple clusters, but the number of clusters are
0043 smaller, and the interrupt output lines are connected directly to various
0044 processors.
0045
0046 Mailbox Controller Nodes
0047 =========================
0048 A Mailbox device node is used to represent a Mailbox IP instance/cluster
0049 within a SoC. The sub-mailboxes (actual communication channels) are
0050 represented as child nodes of this parent node.
0051
0052 Mailbox Users
0053 ==============
0054 A device needing to communicate with a target processor device should specify
0055 them using the common mailbox binding properties, "mboxes" and the optional
0056 "mbox-names" (please see Documentation/devicetree/bindings/mailbox/mailbox.txt
0057 for details). Each value of the mboxes property should contain a phandle to
0058 the mailbox controller device node and an args specifier that will be the
0059 phandle to the intended sub-mailbox child node to be used for communication.
0060 The equivalent "mbox-names" property value can be used to give a name to the
0061 communication channel to be used by the client user.
0062
0063 $defs:
0064 omap-mbox-descriptor:
0065 $ref: /schemas/types.yaml#/definitions/uint32-array
0066 description:
0067 The omap-mbox-descriptor is made of up of 3 cells and represents a single
0068 uni-directional communication channel. A typical sub-mailbox device uses
0069 two such channels - one for transmitting (Tx) and one for receiving (Rx).
0070 items:
0071 - description:
0072 mailbox fifo id used either for transmitting on ti,mbox-tx channel or
0073 for receiving on ti,mbox-rx channel (fifo_id). This is the hardware
0074 fifo number within a mailbox cluster.
0075 - description:
0076 irq identifier index number to use from the parent's interrupts data.
0077 Should be 0 for most of the cases, a positive index value is seen only
0078 on mailboxes that have multiple interrupt lines connected to the MPU
0079 processor (irq_id). This is an index number in the listed interrupts
0080 property in the DT nodes.
0081 - description:
0082 mailbox user id for identifying the interrupt line associated with
0083 generating a tx/rx fifo interrupt (usr_id). This is the hardware
0084 user id number within a mailbox cluster.
0085
0086 omap-sub-mailbox:
0087 type: object
0088 description:
0089 The omap-sub-mailbox is a child node within a Mailbox controller device
0090 node and represents the actual communication channel used to send and
0091 receive messages between the host processor and a remote processor. Each
0092 child node should have a unique node name across all the different mailbox
0093 device nodes.
0094
0095 properties:
0096 ti,mbox-tx:
0097 $ref: "#/$defs/omap-mbox-descriptor"
0098 description: sub-mailbox descriptor property defining a Tx fifo.
0099
0100 ti,mbox-rx:
0101 $ref: "#/$defs/omap-mbox-descriptor"
0102 description: sub-mailbox descriptor property defining a Rx fifo.
0103
0104 ti,mbox-send-noirq:
0105 type: boolean
0106 description:
0107 Quirk flag to allow the client user of this sub-mailbox to send
0108 messages without triggering a Tx ready interrupt, and to control
0109 the Tx ticker. Should be used only on sub-mailboxes used to
0110 communicate with WkupM3 remote processor on AM33xx/AM43xx SoCs.
0111
0112 required:
0113 - ti,mbox-tx
0114 - ti,mbox-rx
0115
0116 properties:
0117 compatible:
0118 enum:
0119 - ti,omap2-mailbox # for OMAP2420, OMAP2430 SoCs
0120 - ti,omap3-mailbox # for OMAP3430, OMAP3630 SoCs
0121 - ti,omap4-mailbox # for OMAP44xx, OMAP54xx, AM33xx, AM43xx and DRA7xx SoCs
0122 - ti,am654-mailbox # for K3 AM65x, J721E and J7200 SoCs
0123 - ti,am64-mailbox # for K3 AM64x SoCs
0124
0125 reg:
0126 maxItems: 1
0127
0128 interrupts:
0129 description:
0130 Contains the interrupt information for the mailbox device. The format is
0131 dependent on which interrupt controller the Mailbox device uses. The
0132 number of interrupts listed will at most be the value specified in
0133 ti,mbox-num-users property, but is usually limited by the number of
0134 interrupts reaching the main processor. An interrupt-parent property
0135 is required on SoCs where the interrupt lines are connected through a
0136 Interrupt Router before reaching the main processor's GIC.
0137
0138 "#mbox-cells":
0139 const: 1
0140 description:
0141 The specifier is a phandle to an omap-sub-mailbox device.
0142
0143 ti,mbox-num-users:
0144 $ref: /schemas/types.yaml#/definitions/uint32
0145 description:
0146 Number of targets (processor devices) that the mailbox device can
0147 interrupt.
0148
0149 ti,mbox-num-fifos:
0150 $ref: /schemas/types.yaml#/definitions/uint32
0151 description: Number of h/w fifo queues within the mailbox IP block.
0152
0153 ti,hwmods:
0154 $ref: /schemas/types.yaml#/definitions/string
0155 deprecated: true
0156 description:
0157 Name of the hwmod associated with the mailbox. This should be defined
0158 in the mailbox node only if the node is not defined as a child node of
0159 a corresponding sysc interconnect node.
0160
0161 This property is only needed on some legacy OMAP SoCs which have not
0162 yet been converted to the ti,sysc interconnect hierarachy, but is
0163 otherwise considered obsolete.
0164
0165 patternProperties:
0166 "^mbox-[a-z0-9-]+$":
0167 $ref: "#/$defs/omap-sub-mailbox"
0168
0169 required:
0170 - compatible
0171 - reg
0172 - interrupts
0173 - "#mbox-cells"
0174 - ti,mbox-num-users
0175 - ti,mbox-num-fifos
0176
0177 allOf:
0178 - if:
0179 properties:
0180 compatible:
0181 enum:
0182 - ti,am654-mailbox
0183 - ti,am64-mailbox
0184 then:
0185 properties:
0186 ti,mbox-num-users:
0187 const: 4
0188 ti,mbox-num-fifos:
0189 const: 16
0190 interrupts:
0191 minItems: 1
0192 maxItems: 4
0193
0194 - if:
0195 properties:
0196 compatible:
0197 enum:
0198 - ti,omap4-mailbox
0199 then:
0200 properties:
0201 ti,mbox-num-users:
0202 enum: [3, 4]
0203 ti,mbox-num-fifos:
0204 enum: [8, 12]
0205 interrupts:
0206 minItems: 1
0207 maxItems: 4
0208
0209 - if:
0210 properties:
0211 compatible:
0212 enum:
0213 - ti,omap3-mailbox
0214 then:
0215 properties:
0216 ti,mbox-num-users:
0217 const: 2
0218 ti,mbox-num-fifos:
0219 const: 2
0220 interrupts:
0221 minItems: 1
0222 maxItems: 1
0223
0224 - if:
0225 properties:
0226 compatible:
0227 enum:
0228 - ti,omap2-mailbox
0229 then:
0230 properties:
0231 ti,mbox-num-users:
0232 const: 4
0233 ti,mbox-num-fifos:
0234 const: 6
0235 interrupts:
0236 minItems: 1
0237 maxItems: 2
0238
0239 additionalProperties: false
0240
0241 examples:
0242 - |
0243 /* OMAP4 */
0244 #include <dt-bindings/interrupt-controller/arm-gic.h>
0245 mailbox: mailbox@4a0f4000 {
0246 compatible = "ti,omap4-mailbox";
0247 reg = <0x4a0f4000 0x200>;
0248 interrupts = <GIC_SPI 26 IRQ_TYPE_LEVEL_HIGH>;
0249 #mbox-cells = <1>;
0250 ti,mbox-num-users = <3>;
0251 ti,mbox-num-fifos = <8>;
0252
0253 mbox_ipu: mbox-ipu {
0254 ti,mbox-tx = <0 0 0>;
0255 ti,mbox-rx = <1 0 0>;
0256 };
0257 mbox_dsp: mbox-dsp {
0258 ti,mbox-tx = <3 0 0>;
0259 ti,mbox-rx = <2 0 0>;
0260 };
0261 };
0262
0263 dsp {
0264 mboxes = <&mailbox &mbox_dsp>;
0265 };
0266
0267 - |
0268 /* AM33xx */
0269 mailbox1: mailbox@480c8000 {
0270 compatible = "ti,omap4-mailbox";
0271 reg = <0x480c8000 0x200>;
0272 interrupts = <77>;
0273 #mbox-cells = <1>;
0274 ti,mbox-num-users = <4>;
0275 ti,mbox-num-fifos = <8>;
0276
0277 mbox_wkupm3: mbox-wkup-m3 {
0278 ti,mbox-tx = <0 0 0>;
0279 ti,mbox-rx = <0 0 3>;
0280 ti,mbox-send-noirq;
0281 };
0282 };
0283
0284 - |
0285 /* AM65x */
0286 mailbox0_cluster0: mailbox@31f80000 {
0287 compatible = "ti,am654-mailbox";
0288 reg = <0x31f80000 0x200>;
0289 #mbox-cells = <1>;
0290 ti,mbox-num-users = <4>;
0291 ti,mbox-num-fifos = <16>;
0292 interrupt-parent = <&intr_main_navss>;
0293 interrupts = <436>;
0294
0295 mbox_mcu_r5fss0_core0: mbox-mcu-r5fss0-core0 {
0296 ti,mbox-tx = <1 0 0>;
0297 ti,mbox-rx = <0 0 0>;
0298 };
0299 };
