225 lines · yaml
1# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)2%YAML 1.23---4$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml#5$schema: http://devicetree.org/meta-schemas/core.yaml#6 7title: ARM MHUv3 Mailbox Controller8 9maintainers:10 - Sudeep Holla <sudeep.holla@arm.com>11 - Cristian Marussi <cristian.marussi@arm.com>12 13description: |14 The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that15 enables unidirectional communications with remote processors through various16 possible transport protocols.17 The controller can optionally support a varying number of extensions that, in18 turn, enable different kinds of transport to be used for communication.19 Number, type and characteristics of each supported extension can be discovered20 dynamically at runtime.21 22 Given the unidirectional nature of the controller, an MHUv3 mailbox controller23 is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU24 Receiver (MHUR) containing a MailBox (MBX) block, where25 26 PBX is used to27 - Configure the MHU28 - Send Transfers to the Receiver29 - Optionally receive acknowledgment of a Transfer from the Receiver30 31 MBX is used to32 - Configure the MHU33 - Receive Transfers from the Sender34 - Optionally acknowledge Transfers sent by the Sender35 36 Both PBX and MBX need to be present and defined in the DT description if you37 need to establish a bidirectional communication, since you will have to38 acquire two distinct unidirectional channels, one for each block.39 40 As a consequence both blocks needs to be represented separately and specified41 as distinct DT nodes in order to properly describe their resources.42 43 Note that, though, thanks to the runtime discoverability, there is no need to44 identify the type of blocks with distinct compatibles.45 46 Following are the MHUv3 possible extensions.47 48 - Doorbell Extension (DBE): DBE defines a type of channel called a Doorbell49 Channel (DBCH). DBCH enables a single bit Transfer to be sent from the50 Sender to Receiver. The Transfer indicates that an event has occurred.51 When DBE is implemented, the number of DBCHs that an implementation of the52 MHU can support is between 1 and 128, numbered starting from 0 in ascending53 order and discoverable at run-time.54 Each DBCH contains 32 individual fields, referred to as flags, each of which55 can be used independently. It is possible for the Sender to send multiple56 Transfers at once using a single DBCH, so long as each Transfer uses57 a different flag in the DBCH.58 Optionally, data may be transmitted through an out-of-band shared memory59 region, wherein the MHU Doorbell is used strictly as an interrupt generation60 mechanism, but this is out of the scope of these bindings.61 62 - FastChannel Extension (FCE): FCE defines a type of channel called a Fast63 Channel (FCH). FCH is intended for lower overhead communication between64 Sender and Receiver at the expense of determinism. An FCH allows the Sender65 to update the channel value at any time, regardless of whether the previous66 value has been seen by the Receiver. When the Receiver reads the channel's67 content it gets the last value written to the channel.68 FCH is considered lossy in nature, and means that the Sender has no way of69 knowing if, or when, the Receiver will act on the Transfer.70 FCHs are expected to behave as RAM which generates interrupts when writes71 occur to the locations within the RAM.72 When FCE is implemented, the number of FCHs that an implementation of the73 MHU can support is between 1-1024, if the FastChannel word-size is 32-bits,74 or between 1-512, when the FastChannel word-size is 64-bits.75 FCHs are numbered from 0 in ascending order.76 Note that the number of FCHs and the word-size are implementation defined,77 not configurable but discoverable at run-time.78 Optionally, data may be transmitted through an out-of-band shared memory79 region, wherein the MHU FastChannel is used as an interrupt generation80 mechanism which carries also a pointer to such out-of-band data, but this81 is out of the scope of these bindings.82 83 - FIFO Extension (FE): FE defines a Channel type called a FIFO Channel (FFCH).84 FFCH allows a Sender to send85 - Multiple Transfers to the Receiver without having to wait for the86 previous Transfer to be acknowledged by the Receiver, as long as the87 FIFO has room for the Transfer.88 - Transfers which require the Receiver to provide acknowledgment.89 - Transfers which have in-band payload.90 In all cases, the data is guaranteed to be observed by the Receiver in the91 same order which the Sender sent it.92 When FE is implemented, the number of FFCHs that an implementation of the93 MHU can support is between 1 and 64, numbered starting from 0 in ascending94 order. The number of FFCHs, their depth (same for all implemented FFCHs) and95 the access-granularity are implementation defined, not configurable but96 discoverable at run-time.97 Optionally, additional data may be transmitted through an out-of-band shared98 memory region, wherein the MHU FIFO is used to transmit, in order, a small99 part of the payload (like a header) and a reference to the shared memory100 area holding the remaining, bigger, chunk of the payload, but this is out of101 the scope of these bindings.102 103properties:104 compatible:105 const: arm,mhuv3106 107 reg:108 maxItems: 1109 110 interrupts:111 minItems: 1112 maxItems: 74113 114 interrupt-names:115 description: |116 The MHUv3 controller generates a number of events some of which are used117 to generate interrupts; as a consequence it can expose a varying number of118 optional PBX/MBX interrupts, representing the events generated during the119 operation of the various transport protocols associated with different120 extensions. All interrupts of the MHU are level-sensitive.121 Some of these optional interrupts are defined per-channel, where the122 number of channels effectively available is implementation defined and123 run-time discoverable.124 In the following names are enumerated using patterns, with per-channel125 interrupts implicitly capped at the maximum channels allowed by the126 specification for each extension type.127 For the sake of simplicity maxItems is anyway capped to a most plausible128 number, assuming way less channels would be implemented than actually129 possible.130 131 The only mandatory interrupts on the MHU are:132 - combined133 - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented.134 135 minItems: 1136 maxItems: 74137 items:138 oneOf:139 - const: combined140 description: PBX/MBX Combined interrupt141 - const: combined-ffch142 description: PBX/MBX FIFO Combined interrupt143 - pattern: '^ffch-low-tide-[0-9]+$'144 description: PBX/MBX FIFO Channel <N> Low Tide interrupt145 - pattern: '^ffch-high-tide-[0-9]+$'146 description: PBX/MBX FIFO Channel <N> High Tide interrupt147 - pattern: '^ffch-flush-[0-9]+$'148 description: PBX/MBX FIFO Channel <N> Flush interrupt149 - pattern: '^mbx-dbch-xfer-[0-9]+$'150 description: MBX Doorbell Channel <N> Transfer interrupt151 - pattern: '^mbx-fch-xfer-[0-9]+$'152 description: MBX FastChannel <N> Transfer interrupt153 - pattern: '^mbx-fchgrp-xfer-[0-9]+$'154 description: MBX FastChannel <N> Group Transfer interrupt155 - pattern: '^mbx-ffch-xfer-[0-9]+$'156 description: MBX FIFO Channel <N> Transfer interrupt157 - pattern: '^pbx-dbch-xfer-ack-[0-9]+$'158 description: PBX Doorbell Channel <N> Transfer Ack interrupt159 - pattern: '^pbx-ffch-xfer-ack-[0-9]+$'160 description: PBX FIFO Channel <N> Transfer Ack interrupt161 162 '#mbox-cells':163 description: |164 The first argument in the consumers 'mboxes' property represents the165 extension type, the second is for the channel number while the third166 depends on extension type.167 168 Extension types constants are defined in <dt-bindings/arm/mhuv3-dt.h>.169 170 Extension type for DBE is DBE_EXT and the third parameter represents the171 doorbell flag number to use.172 Extension type for FCE is FCE_EXT, third parameter unused.173 Extension type for FE is FE_EXT, third parameter unused.174 175 mboxes = <&mhu DBE_EXT 0 5>; // DBE, Doorbell Channel Window 0, doorbell 5.176 mboxes = <&mhu DBE_EXT 7>; // DBE, Doorbell Channel Window 1, doorbell 7.177 mboxes = <&mhu FCE_EXT 0 0>; // FCE, FastChannel Window 0.178 mboxes = <&mhu FCE_EXT 3 0>; // FCE, FastChannel Window 3.179 mboxes = <&mhu FE_EXT 1 0>; // FE, FIFO Channel Window 1.180 mboxes = <&mhu FE_EXT 7 0>; // FE, FIFO Channel Window 7.181 const: 3182 183 clocks:184 maxItems: 1185 186required:187 - compatible188 - reg189 - interrupts190 - interrupt-names191 - '#mbox-cells'192 193additionalProperties: false194 195examples:196 - |197 #include <dt-bindings/interrupt-controller/arm-gic.h>198 199 soc {200 #address-cells = <2>;201 #size-cells = <2>;202 203 mailbox@2aaa0000 {204 compatible = "arm,mhuv3";205 #mbox-cells = <3>;206 reg = <0 0x2aaa0000 0 0x10000>;207 clocks = <&clock 0>;208 interrupt-names = "combined", "pbx-dbch-xfer-ack-1",209 "ffch-high-tide-0";210 interrupts = <GIC_SPI 36 IRQ_TYPE_LEVEL_HIGH>,211 <GIC_SPI 37 IRQ_TYPE_LEVEL_HIGH>;212 };213 214 mailbox@2ab00000 {215 compatible = "arm,mhuv3";216 #mbox-cells = <3>;217 reg = <0 0x2aab0000 0 0x10000>;218 clocks = <&clock 0>;219 interrupt-names = "combined", "mbx-dbch-xfer-1", "ffch-low-tide-0";220 interrupts = <GIC_SPI 35 IRQ_TYPE_LEVEL_HIGH>,221 <GIC_SPI 38 IRQ_TYPE_LEVEL_HIGH>,222 <GIC_SPI 39 IRQ_TYPE_LEVEL_HIGH>;223 };224 };225