Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel os linux

dt-bindings: mailbox: arm,mhuv3: Add bindings

Add bindings for the ARM MHUv3 Mailbox controller.

Reviewed-by: Rob Herring <robh@kernel.org>
Signed-off-by: Cristian Marussi <cristian.marussi@arm.com>
Signed-off-by: Jassi Brar <jassisinghbrar@gmail.com>

authored by

Cristian Marussi and committed by
Jassi Brar
cd251970 3f58c1f4

+237
+224
Documentation/devicetree/bindings/mailbox/arm,mhuv3.yaml
··· 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 <sudeep.holla@arm.com> 11 + - Cristian Marussi <cristian.marussi@arm.com> 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 + };
+13
include/dt-bindings/arm/mhuv3-dt.h
··· 1 + /* SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause) */ 2 + /* 3 + * This header provides constants for the defined MHUv3 types. 4 + */ 5 + 6 + #ifndef _DT_BINDINGS_ARM_MHUV3_DT_H 7 + #define _DT_BINDINGS_ARM_MHUV3_DT_H 8 + 9 + #define DBE_EXT 0 10 + #define FCE_EXT 1 11 + #define FE_EXT 2 12 + 13 + #endif /* _DT_BINDINGS_ARM_MHUV3_DT_H */