Documentation/devicetree/bindings/mailbox/arm,mhuv2.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,mhuv2.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: ARM MHUv2 Mailbox Controller
   8
   9 maintainers:
  10   - Tushar Khandelwal <tushar.khandelwal@arm.com>
  11   - Viresh Kumar <viresh.kumar@linaro.org>
  12
  13 description: |
  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'
  44 select:
  45   properties:
  46     compatible:
  47       contains:
  48         enum:
  49           - arm,mhuv2-tx
  50           - arm,mhuv2-rx
  51   required:
  52     - compatible
  53
  54 properties:
  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
 150 if:
 151   # Interrupt is compulsory for receiver
 152   properties:
 153     compatible:
 154       contains:
 155         const: arm,mhuv2-rx
 156 then:
 157   required:
 158     - interrupts
 159
 160 required:
 161   - compatible
 162   - reg
 163   - '#mbox-cells'
 164   - arm,mhuv2-protocols
 165
 166 additionalProperties: false
 167
 168 examples:
 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     };