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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <27cf6dab-da29-458a-b376-4013c05434ab@kernel.org>
Date: Thu, 13 Mar 2025 14:28:36 +0100
From: Krzysztof Kozlowski <krzk@...nel.org>
To: Guomin Chen <guomin.chen@...tech.com>,
 Jassi Brar <jassisinghbrar@...il.com>, Rob Herring <robh@...nel.org>,
 Krzysztof Kozlowski <krzk+dt@...nel.org>, Conor Dooley <conor+dt@...nel.org>
Cc: linux-kernel@...r.kernel.org, cix-kernel-upstream@...tech.com,
 Peter Chen <peter.chen@...tech.com>, Lihua Liu <Lihua.Liu@...tech.com>
Subject: Re: [PATCH 1/2] dt-bindings: mailbox: cix: add device tree binding
 documentation.

On 13/03/2025 14:24, Guomin Chen wrote:
> From: Guomin Chen <Guomin.Chen@...tech.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@...tech.com>
> Signed-off-by: Lihua Liu <Lihua.Liu@...tech.com>
> Signed-off-by: Guomin Chen <Guomin.Chen@...tech.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@...tech.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@...00000 {
> +            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