[PATCH v2 0/2] Update sdhci-atmel dt-binding documentation

[PATCH v2 0/2] Update sdhci-atmel dt-binding documentation

[Dharma Balasubiramani]

This patch series converts the sdhci-atmel dt-binding to yaml format and adds
the sama7d65,sama7g5 compatibles to the list.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
Changes in v2:
- Add missing deleted file to the patch 
"Documentation/devicetree/bindings/mmc/sdhci-atmel.txt"
- Link to v1: https://lore.kernel.org/r/20240830-atmel-sdhci-v1-0-01e3ec8c9804@microchip.com

---
Dharma Balasubiramani (2):
      dt-bindings: mmc: sdhci-atmel: Convert to json schema
      dt-bindings: mmc: atmel,sama5d2-sdhci: Add sama7d65 compatible

 .../bindings/mmc/atmel,sama5d2-sdhci.yaml          | 103 +++++++++++++++++++++
 .../devicetree/bindings/mmc/sdhci-atmel.txt        |  35 -------
 2 files changed, 103 insertions(+), 35 deletions(-)
---
base-commit: 985bf40edf4343dcb04c33f58b40b4a85c1776d4
change-id: 20240830-atmel-sdhci-c9a92b710624

Best regards,
-- 
Dharma Balasubiramani <dharma.b@microchip.com>

[PATCH v2 1/2] dt-bindings: mmc: sdhci-atmel: Convert to json schema

[Dharma Balasubiramani]

Convert sdhci-atmel documentation to yaml format. The new file will inherit
from sdhci-common.yaml.

Note: Add microchip,sama7g5-sdhci to compatible list as we already use it
in the DT.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
 .../bindings/mmc/atmel,sama5d2-sdhci.yaml          | 98 ++++++++++++++++++++++
 .../devicetree/bindings/mmc/sdhci-atmel.txt        | 35 --------
 2 files changed, 98 insertions(+), 35 deletions(-)

diff --git a/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
new file mode 100644
index 000000000000..91d18b2545e1
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/atmel,sama5d2-sdhci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel SDHCI controller
+
+maintainers:
+  - Aubin Constans <aubin.constans@microchip.com>
+  - Nicolas Ferre <nicolas.ferre@microchip.com>
+
+description:
+  Bindings for the SDHCI controller found in Atmel/Microchip SoCs.
+
+properties:
+  compatible:
+    oneOf:
+      - enum:
+          - atmel,sama5d2-sdhci
+          - atmel,sama5d3-sdhci
+          - atmel,sama5d4-sdhci
+          - microchip,sam9x60-sdhci
+      - items:
+          - enum:
+              - microchip,sama7g5-sdhci
+          - const: microchip,sam9x60-sdhci
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  clocks:
+    minItems: 2
+    maxItems: 3
+    description: |
+      The sama5d2 family includes three clocks: `hclock`, `multclk`, and `baseclk`.
+      For other families, including sam9x60 and sam9x7, only `hclock` and `multclk` are used.
+
+  clock-names:
+    minItems: 2
+    maxItems: 3
+
+  microchip,sdcal-inverted:
+    type: boolean
+    description:
+      When present, polarity on the SDCAL SoC pin is inverted.
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+
+allOf:
+  - $ref: sdhci-common.yaml#
+  - if:
+      properties:
+        compatible:
+          contains:
+            enum:
+              - atmel,sama5d2-sdhci
+    then:
+      properties:
+        clocks:
+          maxItems: 3
+        clock-names:
+          items:
+            - const: hclock
+            - const: multclk
+            - const: baseclk
+    else:
+      properties:
+        clocks:
+          maxItems: 2
+        clock-names:
+          items:
+            - const: hclock
+            - const: multclk
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/clock/at91.h>
+    mmc@a0000000 {
+        compatible = "atmel,sama5d2-sdhci";
+        reg = <0xa0000000 0x300>;
+        interrupts = <31 IRQ_TYPE_LEVEL_HIGH 0>;
+        clocks = <&sdmmc0_hclk>, <&sdmmc0_gclk>, <&main>;
+        clock-names = "hclock", "multclk", "baseclk";
+        assigned-clocks = <&sdmmc0_gclk>;
+        assigned-clock-rates = <480000000>;
+    };
diff --git a/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt b/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt
deleted file mode 100644
index a9fb0a91245f..000000000000
--- a/Documentation/devicetree/bindings/mmc/sdhci-atmel.txt
+++ /dev/null
@@ -1,35 +0,0 @@
-* Atmel SDHCI controller
-
-This file documents the differences between the core properties in
-Documentation/devicetree/bindings/mmc/mmc.txt and the properties used by the
-sdhci-of-at91 driver.
-
-Required properties:
-- compatible:		Must be "atmel,sama5d2-sdhci" or "microchip,sam9x60-sdhci"
-			or "microchip,sam9x7-sdhci", "microchip,sam9x60-sdhci".
-- clocks:		Phandlers to the clocks.
-- clock-names:		Must be "hclock", "multclk", "baseclk" for
-			"atmel,sama5d2-sdhci".
-			Must be "hclock", "multclk" for "microchip,sam9x60-sdhci".
-			Must be "hclock", "multclk" for "microchip,sam9x7-sdhci".
-
-Optional properties:
-- assigned-clocks:	The same with "multclk".
-- assigned-clock-rates	The rate of "multclk" in order to not rely on the
-			gck configuration set by previous components.
-- microchip,sdcal-inverted: when present, polarity on the SDCAL SoC pin is
-  inverted. The default polarity for this signal is described in the datasheet.
-  For instance on SAMA5D2, the pin is usually tied to the GND with a resistor
-  and a capacitor (see "SDMMC I/O Calibration" chapter).
-
-Example:
-
-mmc0: sdio-host@a0000000 {
-	compatible = "atmel,sama5d2-sdhci";
-	reg = <0xa0000000 0x300>;
-	interrupts = <31 IRQ_TYPE_LEVEL_HIGH 0>;
-	clocks = <&sdmmc0_hclk>, <&sdmmc0_gclk>, <&main>;
-	clock-names = "hclock", "multclk", "baseclk";
-	assigned-clocks = <&sdmmc0_gclk>;
-	assigned-clock-rates = <480000000>;
-};

-- 
2.43.0

[PATCH v2 2/2] dt-bindings: mmc: atmel,sama5d2-sdhci: Add sama7d65 compatible

[Dharma Balasubiramani]

Add mmc binding documentation for sama7d65.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
 Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
index 91d18b2545e1..31b3c719b3e2 100644
--- a/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
+++ b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
@@ -25,6 +25,11 @@ properties:
           - enum:
               - microchip,sama7g5-sdhci
           - const: microchip,sam9x60-sdhci
+      - items:
+          - enum:
+              - microchip,sama7d65-sdhci
+          - const: microchip,sama7g5-sdhci
+          - const: microchip,sam9x60-sdhci
 
   reg:
     maxItems: 1

-- 
2.43.0

Re: [PATCH v2 1/2] dt-bindings: mmc: sdhci-atmel: Convert to json schema

[Conor Dooley]

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

On Fri, Aug 30, 2024 at 01:49:42PM +0530, Dharma Balasubiramani wrote:
> Convert sdhci-atmel documentation to yaml format. The new file will inherit
> from sdhci-common.yaml.
> 
> Note: Add microchip,sama7g5-sdhci to compatible list as we already use it
> in the DT.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> ---
>  .../bindings/mmc/atmel,sama5d2-sdhci.yaml          | 98 ++++++++++++++++++++++
>  .../devicetree/bindings/mmc/sdhci-atmel.txt        | 35 --------
>  2 files changed, 98 insertions(+), 35 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
> new file mode 100644
> index 000000000000..91d18b2545e1
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
> @@ -0,0 +1,98 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mmc/atmel,sama5d2-sdhci.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Atmel SDHCI controller
> +
> +maintainers:
> +  - Aubin Constans <aubin.constans@microchip.com>
> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
> +
> +description:
> +  Bindings for the SDHCI controller found in Atmel/Microchip SoCs.
> +
> +properties:
> +  compatible:
> +    oneOf:
> +      - enum:
> +          - atmel,sama5d2-sdhci
> +          - atmel,sama5d3-sdhci
> +          - atmel,sama5d4-sdhci
> +          - microchip,sam9x60-sdhci
> +      - items:
> +          - enum:
> +              - microchip,sama7g5-sdhci
> +          - const: microchip,sam9x60-sdhci
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  clocks:
> +    minItems: 2
> +    maxItems: 3
> +    description: |
> +      The sama5d2 family includes three clocks: `hclock`, `multclk`, and `baseclk`.
> +      For other families, including sam9x60 and sam9x7, only `hclock` and `multclk` are used.

This should instead be an items list, rather than a text based
description.

> +
> +  clock-names:
> +    minItems: 2
> +    maxItems: 3

We prefer that you describe the entries at this level, and constrain
them in the conditional bits below. IOW, move the items list here,
and only use minItems/maxItems below.

> +
> +  microchip,sdcal-inverted:
> +    type: boolean
> +    description:
> +      When present, polarity on the SDCAL SoC pin is inverted.
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +
> +allOf:
> +  - $ref: sdhci-common.yaml#
> +  - if:
> +      properties:
> +        compatible:
> +          contains:
> +            enum:
> +              - atmel,sama5d2-sdhci
> +    then:
> +      properties:
> +        clocks:
> +          maxItems: 3

maxItems: 3 or minItems: 3? Your answer will depend on whether or not
baseclk is optional on sama5d2.

Cheers,
Conor.

> +        clock-names:
> +          items:
> +            - const: hclock
> +            - const: multclk
> +            - const: baseclk
> +    else:
> +      properties:
> +        clocks:
> +          maxItems: 2
> +        clock-names:
> +          items:
> +            - const: hclock
> +            - const: multclk
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    #include <dt-bindings/clock/at91.h>
> +    mmc@a0000000 {
> +        compatible = "atmel,sama5d2-sdhci";
> +        reg = <0xa0000000 0x300>;
> +        interrupts = <31 IRQ_TYPE_LEVEL_HIGH 0>;
> +        clocks = <&sdmmc0_hclk>, <&sdmmc0_gclk>, <&main>;
> +        clock-names = "hclock", "multclk", "baseclk";
> +        assigned-clocks = <&sdmmc0_gclk>;
> +        assigned-clock-rates = <480000000>;
> +    };

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

Re: [PATCH v2 1/2] dt-bindings: mmc: sdhci-atmel: Convert to json schema

[Dharma.B]

Hi Conor,

On 30/08/24 7:18 pm, Conor Dooley wrote:
> On Fri, Aug 30, 2024 at 01:49:42PM +0530, Dharma Balasubiramani wrote:
>> Convert sdhci-atmel documentation to yaml format. The new file will inherit
>> from sdhci-common.yaml.
>>
>> Note: Add microchip,sama7g5-sdhci to compatible list as we already use it
>> in the DT.
>>
>> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
>> ---
>>   .../bindings/mmc/atmel,sama5d2-sdhci.yaml          | 98 ++++++++++++++++++++++
>>   .../devicetree/bindings/mmc/sdhci-atmel.txt        | 35 --------
>>   2 files changed, 98 insertions(+), 35 deletions(-)
>>
>> diff --git a/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
>> new file mode 100644
>> index 000000000000..91d18b2545e1
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
>> @@ -0,0 +1,98 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id:http://devicetree.org/schemas/mmc/atmel,sama5d2-sdhci.yaml#
>> +$schema:http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Atmel SDHCI controller
>> +
>> +maintainers:
>> +  - Aubin Constans<aubin.constans@microchip.com>
>> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
>> +
>> +description:
>> +  Bindings for the SDHCI controller found in Atmel/Microchip SoCs.
>> +
>> +properties:
>> +  compatible:
>> +    oneOf:
>> +      - enum:
>> +          - atmel,sama5d2-sdhci
>> +          - atmel,sama5d3-sdhci
>> +          - atmel,sama5d4-sdhci
>> +          - microchip,sam9x60-sdhci
>> +      - items:
>> +          - enum:
>> +              - microchip,sama7g5-sdhci
>> +          - const: microchip,sam9x60-sdhci
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    maxItems: 1
>> +
>> +  clocks:
>> +    minItems: 2
>> +    maxItems: 3
>> +    description: |
>> +      The sama5d2 family includes three clocks: `hclock`, `multclk`, and `baseclk`.
>> +      For other families, including sam9x60 and sam9x7, only `hclock` and `multclk` are used.
> This should instead be an items list, rather than a text based
> description.
Sure, I will update it like this below

clocks:
   items:
     - description: hclock
     - description: multclk
     - description: baseclk
   minItems: 2
   maxItems: 3

> 
>> +
>> +  clock-names:
>> +    minItems: 2
>> +    maxItems: 3
> We prefer that you describe the entries at this level, and constrain
> them in the conditional bits below. IOW, move the items list here,
> and only use minItems/maxItems below.

Sure, I will move the items list here

clock-names:
   items:
     - const: hclock
     - const: multclk
     - const: baseclk
   minItems: 2
   maxItems: 3

> 
>> +
>> +  microchip,sdcal-inverted:
>> +    type: boolean
>> +    description:
>> +      When present, polarity on the SDCAL SoC pin is inverted.
>> +
>> +required:
>> +  - compatible
>> +  - reg
>> +  - interrupts
>> +  - clocks
>> +  - clock-names
>> +
>> +allOf:
>> +  - $ref: sdhci-common.yaml#
>> +  - if:
>> +      properties:
>> +        compatible:
>> +          contains:
>> +            enum:
>> +              - atmel,sama5d2-sdhci
>> +    then:
>> +      properties:
>> +        clocks:
>> +          maxItems: 3
> maxItems: 3 or minItems: 3? Your answer will depend on whether or not
> baseclk is optional on sama5d2.

baseclk is must, hence I will modify it as below

allOf:
   - $ref: sdhci-common.yaml#
   - if:
       properties:
         compatible:
           contains:
             enum:
               - atmel,sama5d2-sdhci
     then:
       properties:
         clocks:
           minItems: 3
         clock-names:
           minItems: 3


> 
> Cheers,
> Conor.
> 
>> +        clock-names:
>> +          items:
>> +            - const: hclock
>> +            - const: multclk
>> +            - const: baseclk
>> +    else:
>> +      properties:
>> +        clocks:
>> +          maxItems: 2
>> +        clock-names:
>> +          items:
>> +            - const: hclock
>> +            - const: multclk
>> +
>> +unevaluatedProperties: false
>> +
>> +examples:
>> +  - |
>> +    #include <dt-bindings/interrupt-controller/irq.h>
>> +    #include <dt-bindings/clock/at91.h>
>> +    mmc@a0000000 {
>> +        compatible = "atmel,sama5d2-sdhci";
>> +        reg = <0xa0000000 0x300>;
>> +        interrupts = <31 IRQ_TYPE_LEVEL_HIGH 0>;
>> +        clocks = <&sdmmc0_hclk>, <&sdmmc0_gclk>, <&main>;
>> +        clock-names = "hclock", "multclk", "baseclk";
>> +        assigned-clocks = <&sdmmc0_gclk>;
>> +        assigned-clock-rates = <480000000>;
>> +    };


-- 
With Best Regards,
Dharma B.

Re: [PATCH v2 1/2] dt-bindings: mmc: sdhci-atmel: Convert to json schema

[Conor Dooley]

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

On Fri, Aug 30, 2024 at 02:12:48PM +0000, Dharma.B@microchip.com wrote:
> Hi Conor,
> 
> On 30/08/24 7:18 pm, Conor Dooley wrote:
> > On Fri, Aug 30, 2024 at 01:49:42PM +0530, Dharma Balasubiramani wrote:
> >> Convert sdhci-atmel documentation to yaml format. The new file will inherit
> >> from sdhci-common.yaml.
> >>
> >> Note: Add microchip,sama7g5-sdhci to compatible list as we already use it
> >> in the DT.
> >>
> >> Signed-off-by: Dharma Balasubiramani<dharma.b@microchip.com>
> >> ---
> >>   .../bindings/mmc/atmel,sama5d2-sdhci.yaml          | 98 ++++++++++++++++++++++
> >>   .../devicetree/bindings/mmc/sdhci-atmel.txt        | 35 --------
> >>   2 files changed, 98 insertions(+), 35 deletions(-)
> >>
> >> diff --git a/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
> >> new file mode 100644
> >> index 000000000000..91d18b2545e1
> >> --- /dev/null
> >> +++ b/Documentation/devicetree/bindings/mmc/atmel,sama5d2-sdhci.yaml
> >> @@ -0,0 +1,98 @@
> >> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> >> +%YAML 1.2
> >> +---
> >> +$id:http://devicetree.org/schemas/mmc/atmel,sama5d2-sdhci.yaml#
> >> +$schema:http://devicetree.org/meta-schemas/core.yaml#
> >> +
> >> +title: Atmel SDHCI controller
> >> +
> >> +maintainers:
> >> +  - Aubin Constans<aubin.constans@microchip.com>
> >> +  - Nicolas Ferre<nicolas.ferre@microchip.com>
> >> +
> >> +description:
> >> +  Bindings for the SDHCI controller found in Atmel/Microchip SoCs.
> >> +
> >> +properties:
> >> +  compatible:
> >> +    oneOf:
> >> +      - enum:
> >> +          - atmel,sama5d2-sdhci
> >> +          - atmel,sama5d3-sdhci
> >> +          - atmel,sama5d4-sdhci
> >> +          - microchip,sam9x60-sdhci
> >> +      - items:
> >> +          - enum:
> >> +              - microchip,sama7g5-sdhci
> >> +          - const: microchip,sam9x60-sdhci
> >> +
> >> +  reg:
> >> +    maxItems: 1
> >> +
> >> +  interrupts:
> >> +    maxItems: 1
> >> +
> >> +  clocks:
> >> +    minItems: 2
> >> +    maxItems: 3
> >> +    description: |
> >> +      The sama5d2 family includes three clocks: `hclock`, `multclk`, and `baseclk`.
> >> +      For other families, including sam9x60 and sam9x7, only `hclock` and `multclk` are used.
> > This should instead be an items list, rather than a text based
> > description.
> Sure, I will update it like this below
> 
> clocks:
>    items:
>      - description: hclock
>      - description: multclk
>      - description: baseclk
>    minItems: 2
>    maxItems: 3

This shouldn't pass dt_binding_check, because the max in this snippet is
redundant due to it matching the size of the items list.

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

Re: [PATCH v2 1/2] dt-bindings: mmc: sdhci-atmel: Convert to json schema

[Dharma.B]

On 30/08/24 7:46 pm, Conor Dooley wrote:
>> Sure, I will update it like this below
>>
>> clocks:
>>     items:
>>       - description: hclock
>>       - description: multclk
>>       - description: baseclk
>>     minItems: 2
>>     maxItems: 3
> This shouldn't pass dt_binding_check, because the max in this snippet is
> redundant due to it matching the size of the items list.
Yes, hint: "maxItems" is not needed with an "items" list
I will remove it from both clocks and clock-names properties.
Thanks.

-- 
With Best Regards,
Dharma B.