[PATCH 0/2] Convert atmel-ssc.txt to YAML

[PATCH 0/2] Convert atmel-ssc.txt to YAML

[Andrei Simion]

This patch set converts atmel-ssc.txt into atmel,at91-ssc.yaml and
update the documentation file supported for MICROCHIP SSC DRIVER

Andrei Simion (2):
  dt-bindings: misc: atmel,at91-ssc: Convert to YAML format
  MAINTAINERS: Update the documentation file supported for MICROCHIP SSC
    DRIVER

 .../bindings/misc/atmel,at91-ssc.yaml         | 111 ++++++++++++++++++
 .../devicetree/bindings/misc/atmel-ssc.txt    |  50 --------
 MAINTAINERS                                   |   2 +-
 3 files changed, 112 insertions(+), 51 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
 delete mode 100644 Documentation/devicetree/bindings/misc/atmel-ssc.txt


base-commit: 9a87ce288fe30f268b3a598422fe76af9bb2c2d2
-- 
2.34.1

[PATCH 1/2] dt-bindings: misc: atmel,at91-ssc: Convert to YAML format

[Andrei Simion]

Convert devicetree binding atmel-ssc.txt to YAML format.

Signed-off-by: Andrei Simion <andrei.simion@microchip.com>
---
 .../bindings/misc/atmel,at91-ssc.yaml         | 111 ++++++++++++++++++
 .../devicetree/bindings/misc/atmel-ssc.txt    |  50 --------
 2 files changed, 111 insertions(+), 50 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
 delete mode 100644 Documentation/devicetree/bindings/misc/atmel-ssc.txt

diff --git a/Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml b/Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
new file mode 100644
index 0000000000000..a37ee5e58fa58
--- /dev/null
+++ b/Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
@@ -0,0 +1,111 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/misc/atmel,at91-ssc.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel Serial Synchronous Serial (SSC)
+
+maintainers:
+  - Andrei Simion <andrei.simion@microchip.com>
+
+description:
+  The Atmel Synchronous Serial Controller (SSC) provides a versatile
+  synchronous communication link for audio and telecom applications,
+  supporting protocols like I2S, Short Frame Sync, and Long Frame Sync.
+
+properties:
+  compatible:
+    oneOf:
+      - enum:
+          - atmel,at91rm9200-ssc
+          - atmel,at91sam9g45-ssc
+      - items:
+          - const: microchip,sam9x7-ssc
+          - const: atmel,at91sam9g45-ssc
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    items:
+      - const: pclk
+
+  dmas:
+    items:
+      - description: TX DMA Channel
+      - description: RX DMA Channel
+
+  dma-names:
+    description: Names of the DMA channels.
+    items:
+      - const: tx
+      - const: rx
+
+  atmel,clk-from-rk-pin:
+    description:
+      Specify the clock source for the SSC (Synchronous Serial Controller)
+      when operating in slave mode. By default, the clock is sourced from
+      the TK pin. Set this property to true to source the clock from
+      the RK pin instead, based on your hardware design requirements.
+    type: boolean
+
+allOf:
+  - $ref: ../sound/dai-common.yaml#
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - atmel,at91sam9g45-ssc
+    then:
+      required:
+        - compatible
+        - reg
+        - interrupts
+        - dmas
+        - dma-names
+        - clocks
+        - clock-names
+    else:
+      required:
+        - compatible
+        - reg
+        - interrupts
+        - clocks
+        - clock-names
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/clock/at91.h>
+    #include <dt-bindings/dma/at91.h>
+    #include <dt-bindings/interrupt-controller/irq.h>
+
+    ssc@100000 {
+       compatible = "atmel,at91sam9g45-ssc";
+       reg = <0x100000 0x4000>;
+       interrupts = <28 IRQ_TYPE_LEVEL_HIGH 5>;
+       dmas = <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) |
+                     AT91_XDMAC_DT_PERID(38))>,
+              <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) |
+                     AT91_XDMAC_DT_PERID(39))>;
+       dma-names = "tx", "rx";
+       clocks = <&pmc PMC_TYPE_PERIPHERAL 28>;
+       clock-names = "pclk";
+    };
+
+    ssc@c00000 {
+      compatible = "atmel,at91rm9200-ssc";
+      reg = <0xc00000 0x4000>;
+      interrupts = <14 IRQ_TYPE_LEVEL_HIGH 5>;
+      clocks = <&pmc PMC_TYPE_PERIPHERAL 14>;
+      clock-names = "pclk";
+    };
diff --git a/Documentation/devicetree/bindings/misc/atmel-ssc.txt b/Documentation/devicetree/bindings/misc/atmel-ssc.txt
deleted file mode 100644
index f9fb412642fe0..0000000000000
--- a/Documentation/devicetree/bindings/misc/atmel-ssc.txt
+++ /dev/null
@@ -1,50 +0,0 @@
-* Atmel SSC driver.
-
-Required properties:
-- compatible: "atmel,at91rm9200-ssc" or "atmel,at91sam9g45-ssc"
-	- atmel,at91rm9200-ssc: support pdc transfer
-	- atmel,at91sam9g45-ssc: support dma transfer
-- reg: Should contain SSC registers location and length
-- interrupts: Should contain SSC interrupt
-- clock-names: tuple listing input clock names.
-	Required elements: "pclk"
-- clocks: phandles to input clocks.
-
-
-Required properties for devices compatible with "atmel,at91sam9g45-ssc":
-- dmas: DMA specifier, consisting of a phandle to DMA controller node,
-  the memory interface and SSC DMA channel ID (for tx and rx).
-  See Documentation/devicetree/bindings/dma/atmel-dma.txt for details.
-- dma-names: Must be "tx", "rx".
-
-Optional properties:
-  - atmel,clk-from-rk-pin: bool property.
-     - When SSC works in slave mode, according to the hardware design, the
-       clock can get from TK pin, and also can get from RK pin. So, add
-       this parameter to choose where the clock from.
-     - By default the clock is from TK pin, if the clock from RK pin, this
-       property is needed.
-  - #sound-dai-cells: Should contain <0>.
-     - This property makes the SSC into an automatically registered DAI.
-
-Examples:
-- PDC transfer:
-ssc0: ssc@fffbc000 {
-	compatible = "atmel,at91rm9200-ssc";
-	reg = <0xfffbc000 0x4000>;
-	interrupts = <14 4 5>;
-	clocks = <&ssc0_clk>;
-	clock-names = "pclk";
-};
-
-- DMA transfer:
-ssc0: ssc@f0010000 {
-      compatible = "atmel,at91sam9g45-ssc";
-      reg = <0xf0010000 0x4000>;
-      interrupts = <28 4 5>;
-      dmas = <&dma0 1 13>,
-	     <&dma0 1 14>;
-      dma-names = "tx", "rx";
-      pinctrl-names = "default";
-      pinctrl-0 = <&pinctrl_ssc0_tx &pinctrl_ssc0_rx>;
-};
-- 
2.34.1

Re: [PATCH 1/2] dt-bindings: misc: atmel,at91-ssc: Convert to YAML format

[Krzysztof Kozlowski]

On Tue, Jan 28, 2025 at 06:18:43PM +0200, Andrei Simion wrote:
> Convert devicetree binding atmel-ssc.txt to YAML format.
> 
> Signed-off-by: Andrei Simion <andrei.simion@microchip.com>
> ---
>  .../bindings/misc/atmel,at91-ssc.yaml         | 111 ++++++++++++++++++
>  .../devicetree/bindings/misc/atmel-ssc.txt    |  50 --------
>  2 files changed, 111 insertions(+), 50 deletions(-)
>  create mode 100644 Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml

Please place it in sound directory. Or soc if this is not ASoC, but
including dai-common is clear indication.

>  delete mode 100644 Documentation/devicetree/bindings/misc/atmel-ssc.txt
> 
> diff --git a/Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml b/Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
> new file mode 100644
> index 0000000000000..a37ee5e58fa58
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
> @@ -0,0 +1,111 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/misc/atmel,at91-ssc.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Atmel Serial Synchronous Serial (SSC)
> +
> +maintainers:
> +  - Andrei Simion <andrei.simion@microchip.com>
> +
> +description:
> +  The Atmel Synchronous Serial Controller (SSC) provides a versatile
> +  synchronous communication link for audio and telecom applications,
> +  supporting protocols like I2S, Short Frame Sync, and Long Frame Sync.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - atmel,at91rm9200-ssc
> +          - atmel,at91sam9g45-ssc
> +      - items:
> +          - const: microchip,sam9x7-ssc

This wasn't in the binding and your commit msg is silent. You need to
explain all changes done to the binding during conversion.

> +          - const: atmel,at91sam9g45-ssc
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    items:
> +      - const: pclk
> +
> +  dmas:
> +    items:
> +      - description: TX DMA Channel
> +      - description: RX DMA Channel
> +
> +  dma-names:
> +    description: Names of the DMA channels.

Drop description

> +    items:
> +      - const: tx
> +      - const: rx
> +
> +  atmel,clk-from-rk-pin:
> +    description:
> +      Specify the clock source for the SSC (Synchronous Serial Controller)
> +      when operating in slave mode. By default, the clock is sourced from
> +      the TK pin. Set this property to true to source the clock from

You cannot set this property to true. This can be present or can be
missing

> +      the RK pin instead, based on your hardware design requirements.
> +    type: boolean
> +

Missing dai-cells. Old binding said 0, now you say anything...

Missing required block

> +allOf:
> +  - $ref: ../sound/dai-common.yaml#

Full path, so /schemas/

> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - atmel,at91sam9g45-ssc
> +    then:
> +      required:
> +        - compatible
> +        - reg
> +        - interrupts
> +        - dmas
> +        - dma-names

So only dmas?

> +        - clocks
> +        - clock-names
> +    else:
> +      required:
> +        - compatible
> +        - reg
> +        - interrupts
> +        - clocks
> +        - clock-names

Drop entire required:

> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/clock/at91.h>
> +    #include <dt-bindings/dma/at91.h>
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +
> +    ssc@100000 {
> +       compatible = "atmel,at91sam9g45-ssc";
> +       reg = <0x100000 0x4000>;
> +       interrupts = <28 IRQ_TYPE_LEVEL_HIGH 5>;
> +       dmas = <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) |
> +                     AT91_XDMAC_DT_PERID(38))>,
> +              <&dma0 (AT91_XDMAC_DT_MEM_IF(0) | AT91_XDMAC_DT_PER_IF(1) |
> +                     AT91_XDMAC_DT_PERID(39))>;
> +       dma-names = "tx", "rx";
> +       clocks = <&pmc PMC_TYPE_PERIPHERAL 28>;
> +       clock-names = "pclk";

Make the binding complee - dai properties.

Best regards,
Krzysztof

Re: [PATCH 1/2] dt-bindings: misc: atmel,at91-ssc: Convert to YAML format

[Andrei Simion]

Hi,

Thank you for the review.

I will place this in: Documentation/devicetree/bindings/sound/
because the SSC it is used only for Audio.

>
> Missing dai-cells. Old binding said 0, now you say anything...
>
> Missing required block
>
>> +allOf:
>> +  - $ref: ../sound/dai-common.yaml#
>
> Full path, so /schemas/
>
>> +  - if:
>> +      properties:
>> +        compatible:
>> +          contains:
>> +            enum:
>> +              - atmel,at91sam9g45-ssc
>> +    then:
>> +      required:
>> +        - compatible
>> +        - reg
>> +        - interrupts
>> +        - dmas
>> +        - dma-names
>
> So only dmas?
>
>> +        - clocks
>> +        - clock-names
>> +    else:
>> +      required:
>> +        - compatible
>> +        - reg
>> +        - interrupts
>> +        - clocks
>> +        - clock-names
>
> Drop entire required:
>

I have a question:

1) The old binding said if "atmel,at91sam9g45-ssc": add dmas and DMA-names to the list:
	- compatible, reg, interrupts, clock-names, clocks
   Why do you ask: "drop entire required"?
   I intended to set the required through a conditional.
    case 1) dma transfer
    case 2) pdc transfer

Best Regards,
Andrei Simion

Re: [PATCH 1/2] dt-bindings: misc: atmel,at91-ssc: Convert to YAML format

[Conor Dooley]

[-- Attachment #1: Type: text/plain, Size: 1727 bytes --]

On Wed, Jan 29, 2025 at 03:28:23PM +0200, Andrei Simion wrote:
> Hi,
> 
> Thank you for the review.
> 
> I will place this in: Documentation/devicetree/bindings/sound/
> because the SSC it is used only for Audio.
> 
> >
> > Missing dai-cells. Old binding said 0, now you say anything...
> >
> > Missing required block
> >
> >> +allOf:
> >> +  - $ref: ../sound/dai-common.yaml#
> >
> > Full path, so /schemas/
> >
> >> +  - if:
> >> +      properties:
> >> +        compatible:
> >> +          contains:
> >> +            enum:
> >> +              - atmel,at91sam9g45-ssc
> >> +    then:
> >> +      required:
> >> +        - compatible
> >> +        - reg
> >> +        - interrupts
> >> +        - dmas
> >> +        - dma-names
> >
> > So only dmas?
> >
> >> +        - clocks
> >> +        - clock-names
> >> +    else:
> >> +      required:
> >> +        - compatible
> >> +        - reg
> >> +        - interrupts
> >> +        - clocks
> >> +        - clock-names
> >
> > Drop entire required:
> >
> 
> I have a question:
> 
> 1) The old binding said if "atmel,at91sam9g45-ssc": add dmas and DMA-names to the list:
> 	- compatible, reg, interrupts, clock-names, clocks
>    Why do you ask: "drop entire required"?

The bits that are required in both cases can be set outside the
conditional, so you can do something like

if:
  foo
then:
  required:
    - dmas
    - dma-names

required:
  - compatible
  - reg
  - interrupts
  - clocks
  - clock-names

which I think captures all of what you're trying to do in the quote
above.

>    I intended to set the required through a conditional.
>     case 1) dma transfer
>     case 2) pdc transfer


[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 1/2] dt-bindings: misc: atmel,at91-ssc: Convert to YAML format

[Krzysztof Kozlowski]

On 29/01/2025 14:28, Andrei Simion wrote:
> Hi,
> 
> Thank you for the review.
> 
> I will place this in: Documentation/devicetree/bindings/sound/
> because the SSC it is used only for Audio.
> 
>>
>> Missing dai-cells. Old binding said 0, now you say anything...
>>
>> Missing required block

Here, look.

>>
>>> +allOf:
>>> +  - $ref: ../sound/dai-common.yaml#
>>
>> Full path, so /schemas/
>>
>>> +  - if:
>>> +      properties:
>>> +        compatible:
>>> +          contains:
>>> +            enum:
>>> +              - atmel,at91sam9g45-ssc
>>> +    then:
>>> +      required:
>>> +        - compatible
>>> +        - reg
>>> +        - interrupts
>>> +        - dmas
>>> +        - dma-names
>>
>> So only dmas?
>>
>>> +        - clocks
>>> +        - clock-names
>>> +    else:
>>> +      required:
>>> +        - compatible
>>> +        - reg
>>> +        - interrupts
>>> +        - clocks
>>> +        - clock-names
>>
>> Drop entire required:
>>
> 
> I have a question:
> 
> 1) The old binding said if "atmel,at91sam9g45-ssc": add dmas and DMA-names to the list:
> 	- compatible, reg, interrupts, clock-names, clocks
>    Why do you ask: "drop entire required"?
>    I intended to set the required through a conditional.
>     case 1) dma transfer
>     case 2) pdc transfer

I commented earlier on missing required block in top-level.

Best regards,
Krzysztof

[PATCH 2/2] MAINTAINERS: Update the documentation file supported for MICROCHIP SSC DRIVER

[Andrei Simion]

Replace the documentation file supported after the conversion of
atmel-ssc.txt to YAML schema named atmel,at91-ssc.yaml.

Signed-off-by: Andrei Simion <andrei.simion@microchip.com>
---
 MAINTAINERS | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/MAINTAINERS b/MAINTAINERS
index 02430335012a6..113a2d17fb8bc 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -15633,7 +15633,7 @@ M:	Claudiu Beznea <claudiu.beznea@tuxon.dev>
 M:	Andrei Simion <andrei.simion@microchip.com>
 L:	linux-arm-kernel@lists.infradead.org (moderated for non-subscribers)
 S:	Supported
-F:	Documentation/devicetree/bindings/misc/atmel-ssc.txt
+F:	Documentation/devicetree/bindings/misc/atmel,at91-ssc.yaml
 F:	drivers/misc/atmel-ssc.c
 F:	include/linux/atmel-ssc.h
 
-- 
2.34.1

Re: [PATCH 2/2] MAINTAINERS: Update the documentation file supported for MICROCHIP SSC DRIVER

[Krzysztof Kozlowski]

On Tue, Jan 28, 2025 at 06:18:45PM +0200, Andrei Simion wrote:
> Replace the documentation file supported after the conversion of
> atmel-ssc.txt to YAML schema named atmel,at91-ssc.yaml.
> 
> Signed-off-by: Andrei Simion <andrei.simion@microchip.com>
>

NAK

That's NEVER a separate patch. Your patchset is not bisectable.

Best regards,
Krzysztof