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 131 '#mbox-cells': 132 description: | 133 It is always set to 2. The first argument in the consumers 'mboxes' 134 property represents the channel window group, which may be used in 135 doorbell, or data-transfer protocol, and the second argument (only 136 relevant in doorbell protocol, should be 0 otherwise) represents the 137 doorbell number within the 32 bit wide channel window. 138 139 From the example given above for arm,mhuv2-protocols, here is how a client 140 node can reference them. 141 142 mboxes = <&mhu 0 5>; // Channel Window Group 0, doorbell 5. 143 mboxes = <&mhu 1 7>; // Channel Window Group 1, doorbell 7. 144 mboxes = <&mhu 2 0>; // Channel Window Group 2, data transfer protocol with 1 window. 145 mboxes = <&mhu 3 0>; // Channel Window Group 3, data transfer protocol with 5 windows. 146 mboxes = <&mhu 4 0>; // Channel Window Group 4, data transfer protocol with 7 windows. 147 148 const: 2 149 150if: 151 # Interrupt is compulsory for receiver 152 properties: 153 compatible: 154 contains: 155 const: arm,mhuv2-rx 156then: 157 required: 158 - interrupts 159 160required: 161 - compatible 162 - reg 163 - '#mbox-cells' 164 - arm,mhuv2-protocols 165 166additionalProperties: false 167 168examples: 169 # Multiple transport protocols implemented by the mailbox controllers 170 - | 171 soc { 172 #address-cells = <2>; 173 #size-cells = <2>; 174 175 mhu_tx: mailbox@2b1f0000 { 176 #mbox-cells = <2>; 177 compatible = "arm,mhuv2-tx", "arm,primecell"; 178 reg = <0 0x2b1f0000 0 0x1000>; 179 clocks = <&clock 0>; 180 clock-names = "apb_pclk"; 181 interrupts = <0 45 4>; 182 arm,mhuv2-protocols = <1 5>, <1 2>, <1 5>, <1 7>, <0 2>; 183 }; 184 185 mhu_rx: mailbox@2b1f1000 { 186 #mbox-cells = <2>; 187 compatible = "arm,mhuv2-rx", "arm,primecell"; 188 reg = <0 0x2b1f1000 0 0x1000>; 189 clocks = <&clock 0>; 190 clock-names = "apb_pclk"; 191 interrupts = <0 46 4>; 192 arm,mhuv2-protocols = <1 1>, <1 7>, <0 2>; 193 }; 194 195 mhu_client: scb@2e000000 { 196 compatible = "fujitsu,mb86s70-scb-1.0"; 197 reg = <0 0x2e000000 0 0x4000>; 198 199 mboxes = 200 //data-transfer protocol with 5 windows, mhu-tx 201 <&mhu_tx 2 0>, 202 //data-transfer protocol with 7 windows, mhu-tx 203 <&mhu_tx 3 0>, 204 //doorbell protocol channel 4, doorbell 27, mhu-tx 205 <&mhu_tx 4 27>, 206 //data-transfer protocol with 1 window, mhu-rx 207 <&mhu_rx 0 0>; 208 }; 209 }; 210