Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Viresh Kumar <viresh.kumar@linaro.org>
To:     Rob Herring <robh+dt@kernel.org>,
        Jassi Brar <jaswinder.singh@linaro.org>,
        Borup Petersen <morten.petersen@arm.com>,
        Viresh Kumar <viresh.kumar@linaro.org>
Cc:     linux-arm-kernel@lists.infradead.org,
        Vincent Guittot <vincent.guittot@linaro.org>,
        devicetree@vger.kernel.org, Sudeep.Holla@arm.com,
        Frank Rowand <frowand.list@gmail.com>,
        Tushar Khandelwal <tushar.khandelwal@arm.com>,
        linux-kernel@vger.kernel.org
Subject: [RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings
Date:   Wed,  7 Oct 2020 20:58:44 +0530
Message-Id: <ca2f491fc97bdf6d7fc8d6fee5f702be27db6702.1602084104.git.viresh.kumar@linaro.org>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

This patch adds device tree binding for ARM Message Handling Unit (MHU)
controller version 2.

Based on earlier work by Morten Borup Petersen.

Co-developed-by: Morten Borup Petersen <morten.petersen@arm.com>
Signed-off-by: Morten Borup Petersen <morten.petersen@arm.com>
Signed-off-by: Tushar Khandelwal <tushar.khandelwal@arm.com>
Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>

---
Morten/Tushar,

I have prepared this based on the best of my understanding about the
hardware, but since I haven't worked on the actual hardware yet there
are chances that I may have misunderstood some of it. Please lemme know
if any of my understanding is incorrect.

Here is the link to the previous attempt by Tushar to get it upstreamed
long back:

https://lore.kernel.org/lkml/20190717192616.1731-1-tushar.khandelwal@arm.com/

This is very much a new approach and so I am not pointing out the
differences from the previous one.

I haven't started with redesigning the driver as of now and would like
to get some feedback on the bindings first. Thanks in advance.
---
 .../bindings/mailbox/arm,mhuv2.yaml           | 170 ++++++++++++++++++
 1 file changed, 170 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml

diff --git a/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml
new file mode 100644
index 000000000000..3cbdc97f1f4c
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/arm,mhuv2.yaml
@@ -0,0 +1,170 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/arm,mhuv2.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: ARM MHUv2 Mailbox Controller
+
+maintainers:
+  - Morten Borup Petersen <morten.petersen@arm.com>
+  - Viresh Kumar <viresh.kumar@linaro.org>
+
+description: |
+  The Arm Message Handling Unit (MHU) Version 2 is a mailbox controller that has
+  between 1 and 124 channel windows (each 32-bit wide) to provide unidirectional
+  communication with remote processor(s), where the number of channel windows
+  are implementation dependent.
+
+  Given the unidirectional nature of the controller, an MHUv2 mailbox may only
+  be written to or read from. If a pair of MHU controllers is implemented
+  between two processing elements to provide bidirectional communication, these
+  must be specified as two separate mailboxes.
+
+  If the interrupts property is present in device tree node, then its treated as
+  a receiver mailbox, otherwise a sender.
+
+  An MHU controller must be specified along with the supported transport
+  protocols. The transport protocols determine the method of data transmission
+  as well as the number of provided mailbox channels.
+
+  Following are the possible transport protocols.
+
+  - Doorbell: Each transfer is made up of single bit flag, using any one of the
+    bits in a channel window. A channel window can support up to 32 doorbells
+    and the entire window shall be used in doorbell mode.  Optionally, data may
+    be transmitted through a shared memory region, wherein the MHU is used
+    strictly as an interrupt generation mechanism but that is out of the scope
+    of these bindings.
+
+  - Single-word: Each transfer is single word, using a single Channel window.
+
+  - Multi-word: Each transfer is made of two or more words, using two or more
+    channel windows.
+
+# We need a select here so we don't match all nodes with 'arm,primecell'
+select:
+  properties:
+    compatible:
+      contains:
+        const: arm,mhuv2
+  required:
+    - compatible
+
+properties:
+  compatible:
+        items:
+          - const: arm,mhuv2
+          - const: arm,primecell
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    items:
+      - const: apb_pclk
+
+  arm-mhuv2-mode:
+    description: |
+      The MHUv2 controller may contain up to 124 channel windows (each 32-bit
+      wide). The hardware and the DT bindings allows any combination of those to
+      be used for various transport protocols.
+
+      This property allows a platform to describe how these channel windows are
+      used in various transport protocols. The entries in this property shall be
+      present as an array of tuples, where each tuple describes details about
+      one of the transport protocol being implemented over some channel
+      window(s).
+
+      The first field of a tuple signifies the transfer protocol, 0 is reserved
+      for doorbell protocol, 1 is reserved for single-word protocol and 2 is
+      reserved for multi-word protocol. Using any other value in the first field
+      of a tuple makes it invalid.
+
+      The second field of a tuple signifies the number of channel windows where
+      the protocol would be used. For doorbell protocol this field signifies the
+      number of 32-bit channel windows that implement the doorbell protocol. For
+      single-word protocol this field signifies the number of 32-bit channel
+      windows that implement separate single-word protocol mailbox channels. For
+      multi-word protocol this field signifies the number of channel windows
+      used for a multi-word protocol, it should be 2 or more.
+
+      The total number of channel windows specified here shouldn't be more than
+      the ones implemented by the platform.
+
+      mhu: mailbox@2b1f0000 {
+          ...
+
+          arm-mhuv2-mode = <0 2>, <1 3>, <2 5>, <2 7>;
+      }
+
+      The above example defines the mode of an ARM MHUv2 mailbox controller,
+      where a total of 17 channel windows are used. The first two windows are
+      used in doorbell mode (64 doorbells), the next 3 windows are (separately)
+      used in single-word mode, and the last two mailbox channels are used in
+      multi-word mode of length 5 and 7 channel windows.
+
+  '#mbox-cells':
+    description: |
+      It contains two fields, the first field represents the channel number,
+      which may be used in doorbell, single-word, or multi-word mode, and the
+      second field (only relevant in doorbell mode, ignored otherwise)
+      represents the doorbell number within the 32 bit wide channel window.
+
+      From the example given above for the arm-mhuv2-mode, here is how a client
+      node can reference them.
+
+      mboxes = <&mhu 0 5>; // Mailbox channel 0, doorbell 5.
+      mboxes = <&mhu 1 7>; // Mailbox channel 1, doorbell 7.
+      mboxes = <&mhu 2 0>; // Mailbox channel 2, single-word mode.
+      mboxes = <&mhu 4 0>; // Mailbox channel 4, single-word mode.
+      mboxes = <&mhu 6 0>; // Mailbox channel 6, multi-word mode with 7 windows.
+
+    const: 2
+
+required:
+  - compatible
+  - reg
+  - '#mbox-cells'
+  - arm-mhuv2-mode
+
+additionalProperties: false
+
+examples:
+  # Multiple transport protocols implemented by the mailbox controller
+  # configured in sender mode
+  - |
+    soc {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        mhu: mailbox@2b1f0000 {
+            #mbox-cells = <2>;
+            compatible = "arm,mhuv2", "arm,primecell";
+            reg = <0 0x2b1f0000 0 0x1000>;
+            clocks = <&clock 0>;
+            clock-names = "apb_pclk";
+            arm-mhuv2-mode = <1 5>, <2 2>, <2 5>, <2 7>, <0 2>;
+        };
+
+        mhu_client: scb@2e000000 {
+            compatible = "fujitsu,mb86s70-scb-1.0";
+            reg = <0 0x2e000000 0 0x4000>;
+
+            mboxes =
+                     //single-word protocol channel 0
+                     <&mhu 0 0>,
+                     //single-word protocol channel 4
+                     <&mhu 4 0>,
+                     //multi-word protocol channel 6 with 5 windows
+                     <&mhu 6 0>,
+                     //doorbell protocol channel 9, doorbell 27
+                     <&mhu 9 27>;
+        };
+    };
-- 
2.25.0.rc1.19.g042ed3e048af