Re: [PATCH v3] dt-bindings: dma: convert atmel-dma.txt to YAML

[<Charan.Pedumuru@microchip.com>]

On 28/01/25 02:16, Rob Herring wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
>
> On Mon, Jan 27, 2025 at 03:51:58PM +0530, Charan Pedumuru wrote:
>> From: Durai Manickam KR <durai.manickamkr@microchip.com>
>>
>> Add a description, required properties, appropriate compatibles and
>> missing properties like clocks and clock-names which are not defined in
>> the text binding for all the SoCs that are supported by microchip.
>> Update the text binding name `atmel-dma.txt` to
>> `atmel,at91sam9g45-dma.yaml` for the files which reference to
>> `atmel-dma.txt`. Drop Tudor name from maintainers.
>>
>> Signed-off-by: Durai Manickam KR <durai.manickamkr@microchip.com>
>> Signed-off-by: Charan Pedumuru <charan.pedumuru@microchip.com>
>> ---
>> Changes in v3:
>> - Renamed the text binding name `atmel-dma.txt` to
>>    `atmel,at91sam9g45-dma.yaml` for the files which reference to
>>    `atmel-dma.txt`.
>> - Removed `oneOf` and add a blank line in properties.
>> - Dropped Tudor name from maintainers.
>> - Link to v2: https://lore.kernel.org/r/20250123-dma-v1-1-054f1a77e733@microchip.com
>>
>> Changes in v2:
>> - Renamed the yaml file to a compatible.
>> - Removed `|` and description for common properties.
>> - Modified the commit message.
>> - Dropped the label for the node in examples.
>> - Link to v1: https://lore.kernel.org/all/20240215-dmac-v1-1-8f1c6f031c98@microchip.com
>> ---
>>   .../bindings/dma/atmel,at91sam9g45-dma.yaml        | 66 ++++++++++++++++++++++
>>   .../devicetree/bindings/dma/atmel-dma.txt          | 42 --------------
>>   .../devicetree/bindings/misc/atmel-ssc.txt         |  2 +-
>>   MAINTAINERS                                        |  2 +-
>>   4 files changed, 68 insertions(+), 44 deletions(-)
>>
>> diff --git a/Documentation/devicetree/bindings/dma/atmel,at91sam9g45-dma.yaml b/Documentation/devicetree/bindings/dma/atmel,at91sam9g45-dma.yaml
>> new file mode 100644
>> index 000000000000..d6d16869b7db
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/dma/atmel,at91sam9g45-dma.yaml
>> @@ -0,0 +1,66 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/dma/atmel,at91sam9g45-dma.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Atmel Direct Memory Access Controller (DMA)
>> +
>> +maintainers:
>> +  - Ludovic Desroches <ludovic.desroches@microchip.com>
>> +
>> +description:
>> +  The Atmel Direct Memory Access Controller (DMAC) transfers data from a source
>> +  peripheral to a destination peripheral over one or more AMBA buses. One channel
>> +  is required for each source/destination pair. In the most basic configuration,
>> +  the DMAC has one master interface and one channel. The master interface reads
>> +  the data from a source and writes it to a destination. Two AMBA transfers are
>> +  required for each DMAC data transfer. This is also known as a dual-access transfer.
>> +  The DMAC is programmed via the APB interface.
>> +
>> +properties:
>> +  compatible:
>> +    enum:
>> +      - atmel,at91sam9g45-dma
>> +      - atmel,at91sam9rl-dma
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    maxItems: 1
>> +
>> +  "#dma-cells":
>> +    description:
>> +      Must be <2>, used to represent the number of integer cells in the dmas
>> +      property of client devices.
> You failed to address Conor's comment on this. The above is useless
> because the schema says it is 2 and the description is for any #dma-cells.
>
> What's missing is answering "what do the 2 cells contain exactly?" That
> was captured in this text:

Sure, thanks for pointing it out, I will rewrite the description 
following the below format excluding the phandle part.

>
>> -The three cells in order are:
>> -
>> -1. A phandle pointing to the DMA controller.
>> -2. The memory interface (16 most significant bits), the peripheral interface
>> -(16 less significant bits).
>> -3. Parameters for the at91 DMA configuration register which are device
>> -dependent:
>> -  - bit 7-0: peripheral identifier for the hardware handshaking interface. The
>> -  identifier can be different for tx and rx.
>> -  - bit 11-8: FIFO configuration. 0 for half FIFO, 1 for ALAP, 2 for ASAP.
> Adapt this for the description. (Note it is phandle plus 2 cells, not 3
> cells, so you *can* omit the phandle part.)
>
> Rob


-- 
Best Regards,
Charan.