[RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings

[RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings

[Viresh Kumar]

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

Re: [RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings

[Viresh Kumar]

Updated Morten's email id as he is no longer with ARM.

On Wed, 7 Oct 2020 at 20:58, Viresh Kumar <viresh.kumar@linaro.org> wrote:
>
> 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
>

Re: [RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings

[Rob Herring]

On Wed, Oct 7, 2020 at 10:28 AM Viresh Kumar <viresh.kumar@linaro.org> wrote:
>
> 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

Just 'maxItems: 1' is fine here as the name is already defined.

> +
> +  arm-mhuv2-mode:

arm,mhuv2-mode.

Needs a type reference.

> +    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.

These are based on IP configuration or a software decision?

> +      The total number of channel windows specified here shouldn't be more than
> +      the ones implemented by the platform.

But can be less? Then do you need this to be a mask or range?

> +
> +      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
>

Re: [RFC V2] dt-bindings: mailbox : arm,mhuv2: Add bindings

[Viresh Kumar]

On 08-10-20, 09:30, Rob Herring wrote:
> On Wed, Oct 7, 2020 at 10:28 AM Viresh Kumar <viresh.kumar@linaro.org> wrote:
> > +  clock-names:
> > +    items:
> > +      - const: apb_pclk
> 
> Just 'maxItems: 1' is fine here as the name is already defined.
> 
> > +
> > +  arm-mhuv2-mode:
> 
> arm,mhuv2-mode.

This is what I did initially but was getting errors with it...

> Needs a type reference.

And this fixed it.

> > +    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.
> 
> These are based on IP configuration or a software decision?

Software/firmware.

The platform only fixes the total number of 32-bit registers available
(channel windows) for use, how we use them is left to us. I tried to
make it as generic as possible so any combinations of protocols can be
used here.

> > +      The total number of channel windows specified here shouldn't be more than
> > +      the ones implemented by the platform.
> 
> But can be less? Then do you need this to be a mask or range?

Yes, we don't need to use all the windows that are available to us. I
am not sure why we would need a mask/range here.

Just to clarify a little, as it took me some time to come to this
understanding, the maximum number of channel windows (these aren't
necessarily mailbox channels) supported by the hardware is 124, i.e.
124 32-bit registers. Though a platform may implement only 8 of them,
for example and the OS may want to use only 4 of them.

If we use the entire thing in:

- multi-word mode, we can create a single mailbox channel which is
  capable of transferring 124 words in one go.

- single-word mode, we will end up having 124 mailbox channels, each
  32 bit wide.

- doorbell mode, we will end up having 124 * 32 mailbox channels.

-- 
viresh