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,mhuv2.yaml# 5$schema: http://devicetree.org/meta-schemas/core.yaml# 6 7title: ARM MHUv2 Mailbox Controller 8 9maintainers: 10 - Tushar Khandelwal <tushar.khandelwal@arm.com> 11 - Viresh Kumar <viresh.kumar@linaro.org> 12 13description: | 14 The Arm Message Handling Unit (MHU) Version 2 is a mailbox controller that has 15 between 1 and 124 channel windows (each 32-bit wide) to provide unidirectional 16 communication with remote processor(s), where the number of channel windows 17 are implementation dependent. 18 19 Given the unidirectional nature of the controller, an MHUv2 mailbox may only 20 be written to or read from. If a pair of MHU controllers is implemented 21 between two processing elements to provide bidirectional communication, these 22 must be specified as two separate mailboxes. 23 24 If the interrupts property is present in device tree node, then its treated as 25 a "receiver" mailbox, otherwise a "sender". 26 27 An MHU controller must be specified along with the supported transport 28 protocols. The transport protocols determine the method of data transmission 29 as well as the number of provided mailbox channels. 30 31 Following are the possible transport protocols. 32 33 - Data-transfer: Each transfer is made of one or more words, using one or more 34 channel windows. 35 36 - Doorbell: Each transfer is made up of single bit flag, using any one of the 37 bits in a channel window. A channel window can support up to 32 doorbells 38 and the entire window shall be used in doorbell protocol. Optionally, data 39 may be transmitted through a shared memory region, wherein the MHU is used 40 strictly as an interrupt generation mechanism but that is out of the scope 41 of these bindings. 42 43# We need a select here so we don't match all nodes with 'arm,primecell' 44select: 45 properties: 46 compatible: 47 contains: 48 enum: 49 - arm,mhuv2-tx 50 - arm,mhuv2-rx 51 required: 52 - compatible 53 54properties: 55 compatible: 56 oneOf: 57 - description: Sender mode 58 items: 59 - const: arm,mhuv2-tx 60 - const: arm,primecell 61 62 - description: Receiver-mode 63 items: 64 - const: arm,mhuv2-rx 65 - const: arm,primecell 66 67 reg: 68 maxItems: 1 69 70 interrupts: 71 description: | 72 The MHUv2 controller always implements an interrupt in the "receiver" 73 mode, while the interrupt in the "sender" mode was not available in the 74 version MHUv2.0, but the later versions do have it. 75 maxItems: 1 76 77 clocks: 78 maxItems: 1 79 80 clock-names: 81 maxItems: 1 82 83 arm,mhuv2-protocols: 84 $ref: /schemas/types.yaml#/definitions/uint32-matrix 85 description: | 86 The MHUv2 controller may contain up to 124 channel windows (each 32-bit 87 wide). The hardware and the DT bindings allows any combination of those to 88 be used for various transport protocols. 89 90 This property allows a platform to describe how these channel windows are 91 used in various transport protocols. The entries in this property shall be 92 present as an array of tuples, where each tuple describes details about 93 one of the transport protocol being implemented over some channel 94 window(s). 95 96 The first field of a tuple signifies the transfer protocol, 0 is reserved 97 for doorbell protocol, and 1 is reserved for data-transfer protocol. 98 Using any other value in the first field of a tuple makes it invalid. 99 100 The second field of a tuple signifies the number of channel windows where 101 the protocol would be used and should be set to a non zero value. For 102 doorbell protocol this field signifies the number of 32-bit channel 103 windows that implement the doorbell protocol. For data-transfer protocol, 104 this field signifies the number of 32-bit channel windows that implement 105 the data-transfer protocol. 106 107 The total number of channel windows specified here shouldn't be more than 108 the ones implemented by the platform, though one can specify lesser number 109 of windows here than what the platform implements. 110 111 mhu: mailbox@2b1f0000 { 112 ... 113 114 arm,mhuv2-protocols = <0 2>, <1 1>, <1 5>, <1 7>; 115 } 116 117 The above example defines the protocols of an ARM MHUv2 mailbox 118 controller, where a total of 15 channel windows are used. The first two 119 windows are used in doorbell protocol (64 doorbells), followed by 1, 5 and 120 7 windows (separately) used in data-transfer protocol. 121 122 minItems: 1 123 maxItems: 124 124 items: 125 items: 126 - enum: [ 0, 1 ] 127 - minimum: 0 128 maximum: 124 129 130 '#mbox-cells': 131 description: | 132 It is always set to 2. The first argument in the consumers 'mboxes' 133 property represents the channel window group, which may be used in 134 doorbell, or data-transfer protocol, and the second argument (only 135 relevant in doorbell protocol, should be 0 otherwise) represents the 136 doorbell number within the 32 bit wide channel window. 137 138 From the example given above for arm,mhuv2-protocols, here is how a client 139 node can reference them. 140 141 mboxes = <&mhu 0 5>; // Channel Window Group 0, doorbell 5. 142 mboxes = <&mhu 1 7>; // Channel Window Group 1, doorbell 7. 143 mboxes = <&mhu 2 0>; // Channel Window Group 2, data transfer protocol with 1 window. 144 mboxes = <&mhu 3 0>; // Channel Window Group 3, data transfer protocol with 5 windows. 145 mboxes = <&mhu 4 0>; // Channel Window Group 4, data transfer protocol with 7 windows. 146 147 const: 2 148 149if: 150 # Interrupt is compulsory for receiver 151 properties: 152 compatible: 153 contains: 154 const: arm,mhuv2-rx 155then: 156 required: 157 - interrupts 158 159required: 160 - compatible 161 - reg 162 - '#mbox-cells' 163 - arm,mhuv2-protocols 164 165additionalProperties: false 166 167examples: 168 # Multiple transport protocols implemented by the mailbox controllers 169 - | 170 soc { 171 #address-cells = <2>; 172 #size-cells = <2>; 173 174 mhu_tx: mailbox@2b1f0000 { 175 #mbox-cells = <2>; 176 compatible = "arm,mhuv2-tx", "arm,primecell"; 177 reg = <0 0x2b1f0000 0 0x1000>; 178 clocks = <&clock 0>; 179 clock-names = "apb_pclk"; 180 interrupts = <0 45 4>; 181 arm,mhuv2-protocols = <1 5>, <1 2>, <1 5>, <1 7>, <0 2>; 182 }; 183 184 mhu_rx: mailbox@2b1f1000 { 185 #mbox-cells = <2>; 186 compatible = "arm,mhuv2-rx", "arm,primecell"; 187 reg = <0 0x2b1f1000 0 0x1000>; 188 clocks = <&clock 0>; 189 clock-names = "apb_pclk"; 190 interrupts = <0 46 4>; 191 arm,mhuv2-protocols = <1 1>, <1 7>, <0 2>; 192 }; 193 194 mhu_client: dsp@596e8000 { 195 compatible = "fsl,imx8qxp-dsp"; 196 reg = <0 0x596e8000 0 0x88000>; 197 clocks = <&adma_lpcg 0>, <&adma_lpcg 1>, <&adma_lpcg 2>; 198 clock-names = "ipg", "ocram", "core"; 199 power-domains = <&pd 0>, <&pd 1>; 200 mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1"; 201 mboxes = <&mhu_tx 2 0>, //data-transfer protocol with 5 windows, mhu-tx 202 <&mhu_tx 3 0>, //data-transfer protocol with 7 windows, mhu-tx 203 <&mhu_rx 2 27>, //doorbell protocol channel 2, doorbell 27, mhu-rx 204 <&mhu_rx 0 0>; //data-transfer protocol with 1 window, mhu-rx 205 memory-region = <&dsp_reserved>; 206 }; 207 }; 208