Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Message-ID: <61fce1da-c8dd-f911-e4bb-b2198612e7c6@linaro.org>
Date:   Wed, 26 Jul 2023 20:35:09 +0200
MIME-Version: 1.0
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:102.0) Gecko/20100101
 Thunderbird/102.13.0
Subject: Re: [PATCH 1/2] Documentation: bindings: adi,axi-tdd.yaml: Add new
 TDD engine driver
Content-Language: en-US
To:     Eliza Balas <eliza.balas@analog.com>
Cc:     Rob Herring <robh+dt@kernel.org>,
        Krzysztof Kozlowski <krzysztof.kozlowski+dt@linaro.org>,
        Conor Dooley <conor+dt@kernel.org>,
        Derek Kiernan <derek.kiernan@amd.com>,
        Dragan Cvetic <dragan.cvetic@amd.com>,
        Arnd Bergmann <arnd@arndb.de>,
        Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
        linux-kernel@vger.kernel.org, devicetree@vger.kernel.org
References: <20230726071103.12172-1-eliza.balas@analog.com>
From:   Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org>
In-Reply-To: <20230726071103.12172-1-eliza.balas@analog.com>
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 7bit
Precedence: bulk

On 26/07/2023 09:11, Eliza Balas wrote:
> Add device tree documentation for the AXI TDD Core.
> The generic TDD controller is in essence a waveform generator
> capable of addressing RF applications which require Time Division
> Duplexing, as well as controlling other modules of general
> applications through its dedicated 32 channel outputs.
> 
> The reason of creating the generic TDD controller was to reduce
> the naming confusion around the existing repurposed TDD core
> built for AD9361, as well as expanding its number of output
> channels for systems which require more than six controlling signals.

Please use subject prefixes matching the subsystem. You can get them for
example with `git log --oneline -- DIRECTORY_OR_FILE` on the directory
your patch is touching.

Subject: drop driver. Bindings are for hardware, not drivers... unless
driver is here a hardware term?

> 
> Signed-off-by: Eliza Balas <eliza.balas@analog.com>
> ---
>  .../devicetree/bindings/misc/adi,axi-tdd.yaml | 51 +++++++++++++++++++
>  MAINTAINERS                                   |  7 +++
>  2 files changed, 58 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/misc/adi,axi-tdd.yaml
> 
> diff --git a/Documentation/devicetree/bindings/misc/adi,axi-tdd.yaml b/Documentation/devicetree/bindings/misc/adi,axi-tdd.yaml
> new file mode 100644
> index 000000000000..1894c1c34d4f
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/misc/adi,axi-tdd.yaml

Why is this in misc? No suitable directory?

> @@ -0,0 +1,51 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +# Copyright 2023 Analog Devices Inc.
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/misc/adi,axi-tdd.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Analog Devices AXI TDD Core
> +
> +maintainers:
> +  - Eliza Balas <eliza.balas@analog.com>
> +
> +description: |
> +  Bindings for the new generic TDD CORE, which is part of the Analog Devices hdl reference designs.

Drop boiler plate, so "Bindings for the new generic". Instead, describe
the hardware.

> +  For more information see the wiki: https://wiki.analog.com/resources/fpga/docs/axi_tdd

Not enough. Describe it more. Here.

Also, wrap according to Linux style, so at 80.

> +
> +properties:
> +  compatible:
> +    enum:
> +      - adi,axi-tdd-2.00.a

Versioned blocks... https://wiki.analog.com/resources/fpga/docs/axi_tdd
says nothing about 2.00.a


> +
> +  reg:
> +    maxItems: 1
> +
> +  clocks:
> +    items:
> +      - description: System clock
> +      - description: TDD Core clock
> +
> +  clock-names:
> +    items:
> +      - const: s_axi_aclk
> +      - const: intf_clk
> +
> +required:
> +  - compatible
> +  - reg
> +  - clocks
> +  - clock-names
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    tdd: tdd@84a00000 {

Drop label, not used.

> +            compatible = "adi,axi-tdd-2.00.a";

Use 4 spaces for example indentation.

> +            reg = <0x84a00000 0x10000>;
> +            clocks = <&zynqmp_clk_PL0_REF>, <&zynqmp_clk_PL1_REF>;
> +            clock-names = "s_axi_aclk", "intf_clk";
> +    };
> +...
> diff --git a/MAINTAINERS b/MAINTAINERS
> index aee340630eca..280e66ccdd56 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1360,6 +1360,13 @@ F:	Documentation/devicetree/bindings/hwmon/adi,max31760.yaml
>  F:	Documentation/hwmon/max31760.rst
>  F:	drivers/hwmon/max31760.c
>  
> +ANALOG DEVICES INC GENERIC TDD ENGINE DRIVER

I am pretty sure G is before M. It's difficult, I know.

https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=c192ac7357683f78c2e6d6e75adfcc29deb8c4ae


Best regards,
Krzysztof