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

[Krzysztof Kozlowski <krzk@kernel.org>]

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