209 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,mhuv2.yaml#5$schema: http://devicetree.org/meta-schemas/core.yaml#6 7title: ARM MHUv2 Mailbox Controller8 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 has15 between 1 and 124 channel windows (each 32-bit wide) to provide unidirectional16 communication with remote processor(s), where the number of channel windows17 are implementation dependent.18 19 Given the unidirectional nature of the controller, an MHUv2 mailbox may only20 be written to or read from. If a pair of MHU controllers is implemented21 between two processing elements to provide bidirectional communication, these22 must be specified as two separate mailboxes.23 24 If the interrupts property is present in device tree node, then its treated as25 a "receiver" mailbox, otherwise a "sender".26 27 An MHU controller must be specified along with the supported transport28 protocols. The transport protocols determine the method of data transmission29 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 more34 channel windows.35 36 - Doorbell: Each transfer is made up of single bit flag, using any one of the37 bits in a channel window. A channel window can support up to 32 doorbells38 and the entire window shall be used in doorbell protocol. Optionally, data39 may be transmitted through a shared memory region, wherein the MHU is used40 strictly as an interrupt generation mechanism but that is out of the scope41 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-tx50 - arm,mhuv2-rx51 required:52 - compatible53 54properties:55 compatible:56 oneOf:57 - description: Sender mode58 items:59 - const: arm,mhuv2-tx60 - const: arm,primecell61 62 - description: Receiver-mode63 items:64 - const: arm,mhuv2-rx65 - const: arm,primecell66 67 reg:68 maxItems: 169 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 the74 version MHUv2.0, but the later versions do have it.75 maxItems: 176 77 clocks:78 maxItems: 179 80 clock-names:81 maxItems: 182 83 arm,mhuv2-protocols:84 $ref: /schemas/types.yaml#/definitions/uint32-matrix85 description: |86 The MHUv2 controller may contain up to 124 channel windows (each 32-bit87 wide). The hardware and the DT bindings allows any combination of those to88 be used for various transport protocols.89 90 This property allows a platform to describe how these channel windows are91 used in various transport protocols. The entries in this property shall be92 present as an array of tuples, where each tuple describes details about93 one of the transport protocol being implemented over some channel94 window(s).95 96 The first field of a tuple signifies the transfer protocol, 0 is reserved97 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 where101 the protocol would be used and should be set to a non zero value. For102 doorbell protocol this field signifies the number of 32-bit channel103 windows that implement the doorbell protocol. For data-transfer protocol,104 this field signifies the number of 32-bit channel windows that implement105 the data-transfer protocol.106 107 The total number of channel windows specified here shouldn't be more than108 the ones implemented by the platform, though one can specify lesser number109 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 mailbox118 controller, where a total of 15 channel windows are used. The first two119 windows are used in doorbell protocol (64 doorbells), followed by 1, 5 and120 7 windows (separately) used in data-transfer protocol.121 122 minItems: 1123 maxItems: 124124 items:125 items:126 - enum: [ 0, 1 ]127 - minimum: 0128 maximum: 124129 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 in135 doorbell, or data-transfer protocol, and the second argument (only136 relevant in doorbell protocol, should be 0 otherwise) represents the137 doorbell number within the 32 bit wide channel window.138 139 From the example given above for arm,mhuv2-protocols, here is how a client140 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: 2149 150if:151 # Interrupt is compulsory for receiver152 properties:153 compatible:154 contains:155 const: arm,mhuv2-rx156then:157 required:158 - interrupts159 160required:161 - compatible162 - reg163 - '#mbox-cells'164 - arm,mhuv2-protocols165 166additionalProperties: false167 168examples:169 # Multiple transport protocols implemented by the mailbox controllers170 - |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: dsp@596e8000 {196 compatible = "fsl,imx8qxp-dsp";197 reg = <0 0x596e8000 0 0x88000>;198 clocks = <&adma_lpcg 0>, <&adma_lpcg 1>, <&adma_lpcg 2>;199 clock-names = "ipg", "ocram", "core";200 power-domains = <&pd 0>, <&pd 1>, <&pd 2>, <&pd 3>;201 mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1";202 mboxes = <&mhu_tx 2 0>, //data-transfer protocol with 5 windows, mhu-tx203 <&mhu_tx 3 0>, //data-transfer protocol with 7 windows, mhu-tx204 <&mhu_rx 2 27>, //doorbell protocol channel 2, doorbell 27, mhu-rx205 <&mhu_rx 0 0>; //data-transfer protocol with 1 window, mhu-rx206 memory-region = <&dsp_reserved>;207 };208 };209