[PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Guomin Chen]

From: Guomin Chen <Guomin.Chen@cixtech.com>

This patch adds device tree binding for mailbox from Cixtech.

Reviewed-by: Peter Chen <peter.chen@cixtech.com>
Signed-off-by: Lihua Liu <Lihua.Liu@cixtech.com>
Signed-off-by: Guomin Chen <Guomin.Chen@cixtech.com>
---
 .../bindings/mailbox/cix-mailbox.yaml         | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml

diff --git a/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
new file mode 100644
index 000000000000..85cb54ae2e79
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/cix-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cix mailbox controller
+
+maintainers:
+  - Lihua Liu <Lihua.Liu@cixtech.com>
+
+description:
+  CIX mailbox controller is used to exchange message within
+  multiple processors, such as AP, AUDIO DSP, SensorHub MCU,
+  etc. It supports 10 mailbox channels with different operating
+  mode and every channel is unidirectional.
+
+properties:
+  compatible:
+    const: cix,sky1-mbox
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  "#mbox-cells":
+    description: |
+      <&phandle channel>
+      phandle   : Label name of controller
+      channel   : Channel number
+
+      This controller supports three types of unidirectional channels, they are
+      1 register based channel, 1 fifo based channel and 8 fast channels.
+      A total of 10 channels for each controller. Following types are
+      supported:
+      channel 0_7 - Fast channel with 32bit transmit register and IRQ support.
+      channel 8   - Reg based channel with 32*32bit transsmit register and
+                    Doorbell+transmit acknowledgment IRQ support
+      channel 9   - Fifo based channel with 32*32bit depth fifo and IRQ support.
+    const: 1
+
+  cix,mbox-dir:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Direction of the mailbox (0:TX or 1:RX)
+    enum: [0, 1]
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - "#mbox-cells"
+  - cix,mbox-dir
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    soc {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        mbox0: mailbox@30000000 {
+            compatible = "cix,sky1-mbox";
+            reg = <0 0x30000000 0 0x10000>;
+            interrupts = <GIC_SPI 136 IRQ_TYPE_LEVEL_HIGH 0>;
+            #mbox-cells = <1>;
+            cix,mbox-dir = <0>;
+            status = "okay";
+        };
+    };
-- 
2.34.1

Re: [PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Krzysztof Kozlowski]

On 13/03/2025 14:24, Guomin Chen wrote:
> From: Guomin Chen <Guomin.Chen@cixtech.com>
> 
> This patch adds device tree binding for mailbox from Cixtech.

Please do not use "This commit/patch/change", but imperative mood. See
longer explanation here:
https://elixir.bootlin.com/linux/v5.17.1/source/Documentation/process/submitting-patches.rst#L95

A nit, subject: drop second/last, redundant "device tree binding
documentation.". The "dt-bindings" prefix is already stating that these
are bindings.
See also:
https://elixir.bootlin.com/linux/v6.7-rc8/source/Documentation/devicetree/bindings/submitting-patches.rst#L18

Also, no full stop in the subject.

> 
> Reviewed-by: Peter Chen <peter.chen@cixtech.com>
> Signed-off-by: Lihua Liu <Lihua.Liu@cixtech.com>
> Signed-off-by: Guomin Chen <Guomin.Chen@cixtech.com>
> ---
>  .../bindings/mailbox/cix-mailbox.yaml         | 74 +++++++++++++++++++

Filename matching compatible.

>  1 file changed, 74 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
> 
> diff --git a/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
> new file mode 100644
> index 000000000000..85cb54ae2e79
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
> @@ -0,0 +1,74 @@
> +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mailbox/cix-mailbox.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Cix mailbox controller
> +
> +maintainers:
> +  - Lihua Liu <Lihua.Liu@cixtech.com>
> +
> +description:
> +  CIX mailbox controller is used to exchange message within
> +  multiple processors, such as AP, AUDIO DSP, SensorHub MCU,
> +  etc. It supports 10 mailbox channels with different operating
> +  mode and every channel is unidirectional.

uni but configurable or each channel has specific direction?

> +
> +properties:
> +  compatible:
> +    const: cix,sky1-mbox
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  "#mbox-cells":
> +    description: |
> +      <&phandle channel>
> +      phandle   : Label name of controller
> +      channel   : Channel number

Drop above and explain what the cell argument is.

> +
> +      This controller supports three types of unidirectional channels, they are
> +      1 register based channel, 1 fifo based channel and 8 fast channels.
> +      A total of 10 channels for each controller. Following types are
> +      supported:
> +      channel 0_7 - Fast channel with 32bit transmit register and IRQ support.
> +      channel 8   - Reg based channel with 32*32bit transsmit register and
> +                    Doorbell+transmit acknowledgment IRQ support
> +      channel 9   - Fifo based channel with 32*32bit depth fifo and IRQ support.
> +    const: 1
> +
> +  cix,mbox-dir:
> +    $ref: /schemas/types.yaml#/definitions/uint32
> +    description: Direction of the mailbox (0:TX or 1:RX)
> +    enum: [0, 1]

I don't understand why do you need it. By not sending us driver patch,
you are not making it easier. Why would provider care how consumers use
the mbox channel? Maybe consumer should choose the direction?

> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - "#mbox-cells"
> +  - cix,mbox-dir
> +
> +additionalProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> +
> +    soc {
> +        #address-cells = <2>;
> +        #size-cells = <2>;
> +
> +        mbox0: mailbox@30000000 {
> +            compatible = "cix,sky1-mbox";
> +            reg = <0 0x30000000 0 0x10000>;
> +            interrupts = <GIC_SPI 136 IRQ_TYPE_LEVEL_HIGH 0>;
> +            #mbox-cells = <1>;
> +            cix,mbox-dir = <0>;
> +            status = "okay";

Drop

> +        };
> +    };


Best regards,
Krzysztof

Re: [PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Guomin chen]

On Thu, Mar 13, 2025 at 02:28:36PM +0100, Krzysztof Kozlowski wrote:
> EXTERNAL EMAIL
> 
> On 13/03/2025 14:24, Guomin Chen wrote:
> > From: Guomin Chen <Guomin.Chen@cixtech.com>
> >
> > This patch adds device tree binding for mailbox from Cixtech.
> 
> Please do not use "This commit/patch/change", but imperative mood. See
> longer explanation here:
> https://elixir.bootlin.com/linux/v5.17.1/source/Documentation/process/submitting-patches.rst#L95
> 
> A nit, subject: drop second/last, redundant "device tree binding
> documentation.". The "dt-bindings" prefix is already stating that these
> are bindings.
> See also:
> https://elixir.bootlin.com/linux/v6.7-rc8/source/Documentation/devicetree/bindings/submitting-patches.rst#L18
> 
> Also, no full stop in the subject.
>
hi Krzysztof
  Thank you for your careful review. I will address the issues you mentioned in the next version.

> >
> > Reviewed-by: Peter Chen <peter.chen@cixtech.com>
> > Signed-off-by: Lihua Liu <Lihua.Liu@cixtech.com>
> > Signed-off-by: Guomin Chen <Guomin.Chen@cixtech.com>
> > ---
> >  .../bindings/mailbox/cix-mailbox.yaml         | 74 +++++++++++++++++++
> 
> Filename matching compatible.
> 
> >  1 file changed, 74 insertions(+)
> >  create mode 100644 Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
> >
> > diff --git a/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
> > new file mode 100644
> > index 000000000000..85cb54ae2e79
> > --- /dev/null
> > +++ b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
> > @@ -0,0 +1,74 @@
> > +# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
> > +%YAML 1.2
> > +---
> > +$id: http://devicetree.org/schemas/mailbox/cix-mailbox.yaml#
> > +$schema: http://devicetree.org/meta-schemas/core.yaml#
> > +
> > +title: Cix mailbox controller
> > +
> > +maintainers:
> > +  - Lihua Liu <Lihua.Liu@cixtech.com>
> > +
> > +description:
> > +  CIX mailbox controller is used to exchange message within
> > +  multiple processors, such as AP, AUDIO DSP, SensorHub MCU,
> > +  etc. It supports 10 mailbox channels with different operating
> > +  mode and every channel is unidirectional.
> 
> uni but configurable or each channel has specific direction?
> 
> > +
> > +properties:
> > +  compatible:
> > +    const: cix,sky1-mbox
> > +
> > +  reg:
> > +    maxItems: 1
> > +
> > +  interrupts:
> > +    maxItems: 1
> > +
> > +  "#mbox-cells":
> > +    description: |
> > +      <&phandle channel>
> > +      phandle   : Label name of controller
> > +      channel   : Channel number
> 
> Drop above and explain what the cell argument is.
> 
> > +
> > +      This controller supports three types of unidirectional channels, they are
> > +      1 register based channel, 1 fifo based channel and 8 fast channels.
> > +      A total of 10 channels for each controller. Following types are
> > +      supported:
> > +      channel 0_7 - Fast channel with 32bit transmit register and IRQ support.
> > +      channel 8   - Reg based channel with 32*32bit transsmit register and
> > +                    Doorbell+transmit acknowledgment IRQ support
> > +      channel 9   - Fifo based channel with 32*32bit depth fifo and IRQ support.
> > +    const: 1
> > +
> > +  cix,mbox-dir:
> > +    $ref: /schemas/types.yaml#/definitions/uint32
> > +    description: Direction of the mailbox (0:TX or 1:RX)
> > +    enum: [0, 1]
> 
> I don't understand why do you need it. By not sending us driver patch,
> you are not making it easier. Why would provider care how consumers use
> the mbox channel? Maybe consumer should choose the direction?
> 

As for the mbox-dir property, my driver code has already been submitted. 
On the Cixtech Soc platform, although each mbox is unidirectional, 
there are multiple mboxes—some for reading and some for writing. 
Therefore, the mbox controller has added the mbox-dir property. 

Consumers only need to reference the corresponding mbox controller node, 
and whether it is for reading or writing is already determined by the mbox controller, 
without needing to further understand the mbox-dir property.

> > +
> > +required:
> > +  - compatible
> > +  - reg
> > +  - interrupts
> > +  - "#mbox-cells"
> > +  - cix,mbox-dir
> > +
> > +additionalProperties: false
> > +
> > +examples:
> > +  - |
> > +    #include <dt-bindings/interrupt-controller/arm-gic.h>
> > +
> > +    soc {
> > +        #address-cells = <2>;
> > +        #size-cells = <2>;
> > +
> > +        mbox0: mailbox@30000000 {
> > +            compatible = "cix,sky1-mbox";
> > +            reg = <0 0x30000000 0 0x10000>;
> > +            interrupts = <GIC_SPI 136 IRQ_TYPE_LEVEL_HIGH 0>;
> > +            #mbox-cells = <1>;
> > +            cix,mbox-dir = <0>;
> > +            status = "okay";
> 
> Drop
> 
> > +        };
> > +    };
> 
> 
> Best regards,
> Krzysztof
Best regards
Guomin Chen

Re: [PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Krzysztof Kozlowski]

On 14/03/2025 09:09, Guomin chen wrote:
>>
>>> +
>>> +      This controller supports three types of unidirectional channels, they are
>>> +      1 register based channel, 1 fifo based channel and 8 fast channels.
>>> +      A total of 10 channels for each controller. Following types are
>>> +      supported:
>>> +      channel 0_7 - Fast channel with 32bit transmit register and IRQ support.
>>> +      channel 8   - Reg based channel with 32*32bit transsmit register and
>>> +                    Doorbell+transmit acknowledgment IRQ support
>>> +      channel 9   - Fifo based channel with 32*32bit depth fifo and IRQ support.
>>> +    const: 1
>>> +
>>> +  cix,mbox-dir:
>>> +    $ref: /schemas/types.yaml#/definitions/uint32
>>> +    description: Direction of the mailbox (0:TX or 1:RX)
>>> +    enum: [0, 1]
>>
>> I don't understand why do you need it. By not sending us driver patch,
>> you are not making it easier. Why would provider care how consumers use
>> the mbox channel? Maybe consumer should choose the direction?
>>
> 
> As for the mbox-dir property, my driver code has already been submitted. 

There is no thing in this thread, so next time be sure you use standard
submitting process, so your work will be threaded.

> On the Cixtech Soc platform, although each mbox is unidirectional, 
> there are multiple mboxes—some for reading and some for writing. 

So all mboxes in a controller have the same direction or not? Do you
configure it or is it defined by hardware?

> Therefore, the mbox controller has added the mbox-dir property. 
> 
> Consumers only need to reference the corresponding mbox controller node, 
> and whether it is for reading or writing is already determined by the mbox controller, 
> without needing to further understand the mbox-dir property.

Don't explain how DT works, I know. Why this property is needed in DT in
the first place?


Best regards,
Krzysztof

Re: [PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Krzysztof Kozlowski]

On 13/03/2025 14:24, Guomin Chen wrote:
> From: Guomin Chen <Guomin.Chen@cixtech.com>
> 
> This patch adds device tree binding for mailbox from Cixtech.
> 
> Reviewed-by: Peter Chen <peter.chen@cixtech.com>
> Signed-off-by: Lihua Liu <Lihua.Liu@cixtech.com>
> Signed-off-by: Guomin Chen <Guomin.Chen@cixtech.com>

<form letter>
Please use scripts/get_maintainers.pl to get a list of necessary people
and lists to CC. It might happen, that command when run on an older
kernel, gives you outdated entries. Therefore please be sure you base
your patches on recent Linux kernel.

Tools like b4 or scripts/get_maintainer.pl provide you proper list of
people, so fix your workflow. Tools might also fail if you work on some
ancient tree (don't, instead use mainline) or work on fork of kernel
(don't, instead use mainline). Just use b4 and everything should be
fine, although remember about `b4 prep --auto-to-cc` if you added new
patches to the patchset.

You missed at least devicetree list (maybe more), so this won't be
tested by automated tooling. Performing review on untested code might be
a waste of time.

Please kindly resend and include all necessary To/Cc entries.
</form letter>

Best regards,
Krzysztof

Re: [PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Guomin chen]

On Fri, Mar 14, 2025 at 08:25:40AM +0100, Krzysztof Kozlowski wrote:
> EXTERNAL EMAIL
> 
> On 13/03/2025 14:24, Guomin Chen wrote:
> > From: Guomin Chen <Guomin.Chen@cixtech.com>
> >
> > This patch adds device tree binding for mailbox from Cixtech.
> >
> > Reviewed-by: Peter Chen <peter.chen@cixtech.com>
> > Signed-off-by: Lihua Liu <Lihua.Liu@cixtech.com>
> > Signed-off-by: Guomin Chen <Guomin.Chen@cixtech.com>
> 
> <form letter>
> Please use scripts/get_maintainers.pl to get a list of necessary people
> and lists to CC. It might happen, that command when run on an older
> kernel, gives you outdated entries. Therefore please be sure you base
> your patches on recent Linux kernel.
> 
> Tools like b4 or scripts/get_maintainer.pl provide you proper list of
> people, so fix your workflow. Tools might also fail if you work on some
> ancient tree (don't, instead use mainline) or work on fork of kernel
> (don't, instead use mainline). Just use b4 and everything should be
> fine, although remember about `b4 prep --auto-to-cc` if you added new
> patches to the patchset.
> 
> You missed at least devicetree list (maybe more), so this won't be
> tested by automated tooling. Performing review on untested code might be
> a waste of time.
> 
> Please kindly resend and include all necessary To/Cc entries.
> </form letter>
> 
> Best regards,
> Krzysztof

Thank you for your hint. Although I have used scripts/get_maintainer.pl to
obtain the cc list, I do lack devicetree@vger.kernel.org
I will copy it in the next version. Thank you very much.

Best regards,
Guomin Chen

[PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding documentation.

[Guomin Chen]

From: Guomin Chen <Guomin.Chen@cixtech.com>

This patch adds device tree binding for mailbox from Cixtech.

Reviewed-by: Peter Chen <peter.chen@cixtech.com>
Signed-off-by: Lihua Liu <Lihua.Liu@cixtech.com>
Signed-off-by: Guomin Chen <Guomin.Chen@cixtech.com>
---
 .../bindings/mailbox/cix-mailbox.yaml         | 74 +++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml

diff --git a/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
new file mode 100644
index 000000000000..85cb54ae2e79
--- /dev/null
+++ b/Documentation/devicetree/bindings/mailbox/cix-mailbox.yaml
@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: (GPL-2.0 OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mailbox/cix-mailbox.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Cix mailbox controller
+
+maintainers:
+  - Lihua Liu <Lihua.Liu@cixtech.com>
+
+description:
+  CIX mailbox controller is used to exchange message within
+  multiple processors, such as AP, AUDIO DSP, SensorHub MCU,
+  etc. It supports 10 mailbox channels with different operating
+  mode and every channel is unidirectional.
+
+properties:
+  compatible:
+    const: cix,sky1-mbox
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  "#mbox-cells":
+    description: |
+      <&phandle channel>
+      phandle   : Label name of controller
+      channel   : Channel number
+
+      This controller supports three types of unidirectional channels, they are
+      1 register based channel, 1 fifo based channel and 8 fast channels.
+      A total of 10 channels for each controller. Following types are
+      supported:
+      channel 0_7 - Fast channel with 32bit transmit register and IRQ support.
+      channel 8   - Reg based channel with 32*32bit transsmit register and
+                    Doorbell+transmit acknowledgment IRQ support
+      channel 9   - Fifo based channel with 32*32bit depth fifo and IRQ support.
+    const: 1
+
+  cix,mbox-dir:
+    $ref: /schemas/types.yaml#/definitions/uint32
+    description: Direction of the mailbox (0:TX or 1:RX)
+    enum: [0, 1]
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - "#mbox-cells"
+  - cix,mbox-dir
+
+additionalProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/arm-gic.h>
+
+    soc {
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        mbox0: mailbox@30000000 {
+            compatible = "cix,sky1-mbox";
+            reg = <0 0x30000000 0 0x10000>;
+            interrupts = <GIC_SPI 136 IRQ_TYPE_LEVEL_HIGH 0>;
+            #mbox-cells = <1>;
+            cix,mbox-dir = <0>;
+            status = "okay";
+        };
+    };
-- 
2.34.1