|
| 1 | +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) |
| 2 | +%YAML 1.2 |
| 3 | +--- |
| 4 | +$id: http://devicetree.org/schemas/mailbox/arm,mhuv3.yaml# |
| 5 | +$schema: http://devicetree.org/meta-schemas/core.yaml# |
| 6 | + |
| 7 | +title: ARM MHUv3 Mailbox Controller |
| 8 | + |
| 9 | +maintainers: |
| 10 | + - Sudeep Holla <[email protected]> |
| 11 | + - Cristian Marussi <[email protected]> |
| 12 | + |
| 13 | +description: | |
| 14 | + The Arm Message Handling Unit (MHU) Version 3 is a mailbox controller that |
| 15 | + enables unidirectional communications with remote processors through various |
| 16 | + possible transport protocols. |
| 17 | + The controller can optionally support a varying number of extensions that, in |
| 18 | + turn, enable different kinds of transport to be used for communication. |
| 19 | + Number, type and characteristics of each supported extension can be discovered |
| 20 | + dynamically at runtime. |
| 21 | +
|
| 22 | + Given the unidirectional nature of the controller, an MHUv3 mailbox controller |
| 23 | + is composed of a MHU Sender (MHUS) containing a PostBox (PBX) block and a MHU |
| 24 | + Receiver (MHUR) containing a MailBox (MBX) block, where |
| 25 | +
|
| 26 | + PBX is used to |
| 27 | + - Configure the MHU |
| 28 | + - Send Transfers to the Receiver |
| 29 | + - Optionally receive acknowledgment of a Transfer from the Receiver |
| 30 | +
|
| 31 | + MBX is used to |
| 32 | + - Configure the MHU |
| 33 | + - Receive Transfers from the Sender |
| 34 | + - Optionally acknowledge Transfers sent by the Sender |
| 35 | +
|
| 36 | + Both PBX and MBX need to be present and defined in the DT description if you |
| 37 | + need to establish a bidirectional communication, since you will have to |
| 38 | + acquire two distinct unidirectional channels, one for each block. |
| 39 | +
|
| 40 | + As a consequence both blocks needs to be represented separately and specified |
| 41 | + 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 to |
| 44 | + 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 Doorbell |
| 49 | + Channel (DBCH). DBCH enables a single bit Transfer to be sent from the |
| 50 | + Sender to Receiver. The Transfer indicates that an event has occurred. |
| 51 | + When DBE is implemented, the number of DBCHs that an implementation of the |
| 52 | + MHU can support is between 1 and 128, numbered starting from 0 in ascending |
| 53 | + order and discoverable at run-time. |
| 54 | + Each DBCH contains 32 individual fields, referred to as flags, each of which |
| 55 | + can be used independently. It is possible for the Sender to send multiple |
| 56 | + Transfers at once using a single DBCH, so long as each Transfer uses |
| 57 | + a different flag in the DBCH. |
| 58 | + Optionally, data may be transmitted through an out-of-band shared memory |
| 59 | + region, wherein the MHU Doorbell is used strictly as an interrupt generation |
| 60 | + mechanism, but this is out of the scope of these bindings. |
| 61 | +
|
| 62 | + - FastChannel Extension (FCE): FCE defines a type of channel called a Fast |
| 63 | + Channel (FCH). FCH is intended for lower overhead communication between |
| 64 | + Sender and Receiver at the expense of determinism. An FCH allows the Sender |
| 65 | + to update the channel value at any time, regardless of whether the previous |
| 66 | + value has been seen by the Receiver. When the Receiver reads the channel's |
| 67 | + 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 of |
| 69 | + knowing if, or when, the Receiver will act on the Transfer. |
| 70 | + FCHs are expected to behave as RAM which generates interrupts when writes |
| 71 | + occur to the locations within the RAM. |
| 72 | + When FCE is implemented, the number of FCHs that an implementation of the |
| 73 | + 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 memory |
| 79 | + region, wherein the MHU FastChannel is used as an interrupt generation |
| 80 | + mechanism which carries also a pointer to such out-of-band data, but this |
| 81 | + 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 send |
| 85 | + - Multiple Transfers to the Receiver without having to wait for the |
| 86 | + previous Transfer to be acknowledged by the Receiver, as long as the |
| 87 | + 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 the |
| 91 | + same order which the Sender sent it. |
| 92 | + When FE is implemented, the number of FFCHs that an implementation of the |
| 93 | + MHU can support is between 1 and 64, numbered starting from 0 in ascending |
| 94 | + order. The number of FFCHs, their depth (same for all implemented FFCHs) and |
| 95 | + the access-granularity are implementation defined, not configurable but |
| 96 | + discoverable at run-time. |
| 97 | + Optionally, additional data may be transmitted through an out-of-band shared |
| 98 | + memory region, wherein the MHU FIFO is used to transmit, in order, a small |
| 99 | + part of the payload (like a header) and a reference to the shared memory |
| 100 | + area holding the remaining, bigger, chunk of the payload, but this is out of |
| 101 | + the scope of these bindings. |
| 102 | +
|
| 103 | +properties: |
| 104 | + compatible: |
| 105 | + const: arm,mhuv3 |
| 106 | + |
| 107 | + reg: |
| 108 | + maxItems: 1 |
| 109 | + |
| 110 | + interrupts: |
| 111 | + minItems: 1 |
| 112 | + maxItems: 74 |
| 113 | + |
| 114 | + interrupt-names: |
| 115 | + description: | |
| 116 | + The MHUv3 controller generates a number of events some of which are used |
| 117 | + to generate interrupts; as a consequence it can expose a varying number of |
| 118 | + optional PBX/MBX interrupts, representing the events generated during the |
| 119 | + operation of the various transport protocols associated with different |
| 120 | + extensions. All interrupts of the MHU are level-sensitive. |
| 121 | + Some of these optional interrupts are defined per-channel, where the |
| 122 | + number of channels effectively available is implementation defined and |
| 123 | + run-time discoverable. |
| 124 | + In the following names are enumerated using patterns, with per-channel |
| 125 | + interrupts implicitly capped at the maximum channels allowed by the |
| 126 | + specification for each extension type. |
| 127 | + For the sake of simplicity maxItems is anyway capped to a most plausible |
| 128 | + number, assuming way less channels would be implemented than actually |
| 129 | + possible. |
| 130 | +
|
| 131 | + The only mandatory interrupts on the MHU are: |
| 132 | + - combined |
| 133 | + - mbx-fch-xfer-<N> but only if mbx-fcgrp-xfer-<N> is not implemented. |
| 134 | +
|
| 135 | + minItems: 1 |
| 136 | + maxItems: 74 |
| 137 | + items: |
| 138 | + oneOf: |
| 139 | + - const: combined |
| 140 | + description: PBX/MBX Combined interrupt |
| 141 | + - const: combined-ffch |
| 142 | + description: PBX/MBX FIFO Combined interrupt |
| 143 | + - pattern: '^ffch-low-tide-[0-9]+$' |
| 144 | + description: PBX/MBX FIFO Channel <N> Low Tide interrupt |
| 145 | + - pattern: '^ffch-high-tide-[0-9]+$' |
| 146 | + description: PBX/MBX FIFO Channel <N> High Tide interrupt |
| 147 | + - pattern: '^ffch-flush-[0-9]+$' |
| 148 | + description: PBX/MBX FIFO Channel <N> Flush interrupt |
| 149 | + - pattern: '^mbx-dbch-xfer-[0-9]+$' |
| 150 | + description: MBX Doorbell Channel <N> Transfer interrupt |
| 151 | + - pattern: '^mbx-fch-xfer-[0-9]+$' |
| 152 | + description: MBX FastChannel <N> Transfer interrupt |
| 153 | + - pattern: '^mbx-fchgrp-xfer-[0-9]+$' |
| 154 | + description: MBX FastChannel <N> Group Transfer interrupt |
| 155 | + - pattern: '^mbx-ffch-xfer-[0-9]+$' |
| 156 | + description: MBX FIFO Channel <N> Transfer interrupt |
| 157 | + - pattern: '^pbx-dbch-xfer-ack-[0-9]+$' |
| 158 | + description: PBX Doorbell Channel <N> Transfer Ack interrupt |
| 159 | + - pattern: '^pbx-ffch-xfer-ack-[0-9]+$' |
| 160 | + description: PBX FIFO Channel <N> Transfer Ack interrupt |
| 161 | + |
| 162 | + '#mbox-cells': |
| 163 | + description: | |
| 164 | + The first argument in the consumers 'mboxes' property represents the |
| 165 | + extension type, the second is for the channel number while the third |
| 166 | + 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 the |
| 171 | + 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: 3 |
| 182 | + |
| 183 | + clocks: |
| 184 | + maxItems: 1 |
| 185 | + |
| 186 | +required: |
| 187 | + - compatible |
| 188 | + - reg |
| 189 | + - interrupts |
| 190 | + - interrupt-names |
| 191 | + - '#mbox-cells' |
| 192 | + |
| 193 | +additionalProperties: false |
| 194 | + |
| 195 | +examples: |
| 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 | + }; |
0 commit comments