0001 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
0002 %YAML 1.2
0003 ---
0004 $id: http://devicetree.org/schemas/mailbox/arm,mhuv2.yaml#
0005 $schema: http://devicetree.org/meta-schemas/core.yaml#
0006
0007 title: ARM MHUv2 Mailbox Controller
0008
0009 maintainers:
0010 - Tushar Khandelwal <tushar.khandelwal@arm.com>
0011 - Viresh Kumar <viresh.kumar@linaro.org>
0012
0013 description: |
0014 The Arm Message Handling Unit (MHU) Version 2 is a mailbox controller that has
0015 between 1 and 124 channel windows (each 32-bit wide) to provide unidirectional
0016 communication with remote processor(s), where the number of channel windows
0017 are implementation dependent.
0018
0019 Given the unidirectional nature of the controller, an MHUv2 mailbox may only
0020 be written to or read from. If a pair of MHU controllers is implemented
0021 between two processing elements to provide bidirectional communication, these
0022 must be specified as two separate mailboxes.
0023
0024 If the interrupts property is present in device tree node, then its treated as
0025 a "receiver" mailbox, otherwise a "sender".
0026
0027 An MHU controller must be specified along with the supported transport
0028 protocols. The transport protocols determine the method of data transmission
0029 as well as the number of provided mailbox channels.
0030
0031 Following are the possible transport protocols.
0032
0033 - Data-transfer: Each transfer is made of one or more words, using one or more
0034 channel windows.
0035
0036 - Doorbell: Each transfer is made up of single bit flag, using any one of the
0037 bits in a channel window. A channel window can support up to 32 doorbells
0038 and the entire window shall be used in doorbell protocol. Optionally, data
0039 may be transmitted through a shared memory region, wherein the MHU is used
0040 strictly as an interrupt generation mechanism but that is out of the scope
0041 of these bindings.
0042
0043 # We need a select here so we don't match all nodes with 'arm,primecell'
0044 select:
0045 properties:
0046 compatible:
0047 contains:
0048 enum:
0049 - arm,mhuv2-tx
0050 - arm,mhuv2-rx
0051 required:
0052 - compatible
0053
0054 properties:
0055 compatible:
0056 oneOf:
0057 - description: Sender mode
0058 items:
0059 - const: arm,mhuv2-tx
0060 - const: arm,primecell
0061
0062 - description: Receiver-mode
0063 items:
0064 - const: arm,mhuv2-rx
0065 - const: arm,primecell
0066
0067 reg:
0068 maxItems: 1
0069
0070 interrupts:
0071 description: |
0072 The MHUv2 controller always implements an interrupt in the "receiver"
0073 mode, while the interrupt in the "sender" mode was not available in the
0074 version MHUv2.0, but the later versions do have it.
0075 maxItems: 1
0076
0077 clocks:
0078 maxItems: 1
0079
0080 clock-names:
0081 maxItems: 1
0082
0083 arm,mhuv2-protocols:
0084 $ref: /schemas/types.yaml#/definitions/uint32-matrix
0085 description: |
0086 The MHUv2 controller may contain up to 124 channel windows (each 32-bit
0087 wide). The hardware and the DT bindings allows any combination of those to
0088 be used for various transport protocols.
0089
0090 This property allows a platform to describe how these channel windows are
0091 used in various transport protocols. The entries in this property shall be
0092 present as an array of tuples, where each tuple describes details about
0093 one of the transport protocol being implemented over some channel
0094 window(s).
0095
0096 The first field of a tuple signifies the transfer protocol, 0 is reserved
0097 for doorbell protocol, and 1 is reserved for data-transfer protocol.
0098 Using any other value in the first field of a tuple makes it invalid.
0099
0100 The second field of a tuple signifies the number of channel windows where
0101 the protocol would be used and should be set to a non zero value. For
0102 doorbell protocol this field signifies the number of 32-bit channel
0103 windows that implement the doorbell protocol. For data-transfer protocol,
0104 this field signifies the number of 32-bit channel windows that implement
0105 the data-transfer protocol.
0106
0107 The total number of channel windows specified here shouldn't be more than
0108 the ones implemented by the platform, though one can specify lesser number
0109 of windows here than what the platform implements.
0110
0111 mhu: mailbox@2b1f0000 {
0112 ...
0113
0114 arm,mhuv2-protocols = <0 2>, <1 1>, <1 5>, <1 7>;
0115 }
0116
0117 The above example defines the protocols of an ARM MHUv2 mailbox
0118 controller, where a total of 15 channel windows are used. The first two
0119 windows are used in doorbell protocol (64 doorbells), followed by 1, 5 and
0120 7 windows (separately) used in data-transfer protocol.
0121
0122 minItems: 1
0123 maxItems: 124
0124 items:
0125 items:
0126 - enum: [ 0, 1 ]
0127 - minimum: 0
0128 maximum: 124
0129
0130
0131 '#mbox-cells':
0132 description: |
0133 It is always set to 2. The first argument in the consumers 'mboxes'
0134 property represents the channel window group, which may be used in
0135 doorbell, or data-transfer protocol, and the second argument (only
0136 relevant in doorbell protocol, should be 0 otherwise) represents the
0137 doorbell number within the 32 bit wide channel window.
0138
0139 From the example given above for arm,mhuv2-protocols, here is how a client
0140 node can reference them.
0141
0142 mboxes = <&mhu 0 5>; // Channel Window Group 0, doorbell 5.
0143 mboxes = <&mhu 1 7>; // Channel Window Group 1, doorbell 7.
0144 mboxes = <&mhu 2 0>; // Channel Window Group 2, data transfer protocol with 1 window.
0145 mboxes = <&mhu 3 0>; // Channel Window Group 3, data transfer protocol with 5 windows.
0146 mboxes = <&mhu 4 0>; // Channel Window Group 4, data transfer protocol with 7 windows.
0147
0148 const: 2
0149
0150 if:
0151 # Interrupt is compulsory for receiver
0152 properties:
0153 compatible:
0154 contains:
0155 const: arm,mhuv2-rx
0156 then:
0157 required:
0158 - interrupts
0159
0160 required:
0161 - compatible
0162 - reg
0163 - '#mbox-cells'
0164 - arm,mhuv2-protocols
0165
0166 additionalProperties: false
0167
0168 examples:
0169 # Multiple transport protocols implemented by the mailbox controllers
0170 - |
0171 soc {
0172 #address-cells = <2>;
0173 #size-cells = <2>;
0174
0175 mhu_tx: mailbox@2b1f0000 {
0176 #mbox-cells = <2>;
0177 compatible = "arm,mhuv2-tx", "arm,primecell";
0178 reg = <0 0x2b1f0000 0 0x1000>;
0179 clocks = <&clock 0>;
0180 clock-names = "apb_pclk";
0181 interrupts = <0 45 4>;
0182 arm,mhuv2-protocols = <1 5>, <1 2>, <1 5>, <1 7>, <0 2>;
0183 };
0184
0185 mhu_rx: mailbox@2b1f1000 {
0186 #mbox-cells = <2>;
0187 compatible = "arm,mhuv2-rx", "arm,primecell";
0188 reg = <0 0x2b1f1000 0 0x1000>;
0189 clocks = <&clock 0>;
0190 clock-names = "apb_pclk";
0191 interrupts = <0 46 4>;
0192 arm,mhuv2-protocols = <1 1>, <1 7>, <0 2>;
0193 };
0194
0195 mhu_client: dsp@596e8000 {
0196 compatible = "fsl,imx8qxp-dsp";
0197 reg = <0 0x596e8000 0 0x88000>;
0198 clocks = <&adma_lpcg 0>, <&adma_lpcg 1>, <&adma_lpcg 2>;
0199 clock-names = "ipg", "ocram", "core";
0200 power-domains = <&pd 0>, <&pd 1>, <&pd 2>, <&pd 3>;
0201 mbox-names = "txdb0", "txdb1", "rxdb0", "rxdb1";
0202 mboxes = <&mhu_tx 2 0>, //data-transfer protocol with 5 windows, mhu-tx
0203 <&mhu_tx 3 0>, //data-transfer protocol with 7 windows, mhu-tx
0204 <&mhu_rx 2 27>, //doorbell protocol channel 2, doorbell 27, mhu-rx
0205 <&mhu_rx 0 0>; //data-transfer protocol with 1 window, mhu-rx
0206 memory-region = <&dsp_reserved>;
0207 };
0208 };
