[PATCH v2] dt-bindings: mmc: atmel,hsmci: Convert to json schema

[PATCH v2] dt-bindings: mmc: atmel,hsmci: Convert to json schema

[Dharma Balasubiramani]

Convert atmel,hsmci documentation to yaml format. The new file will inherit
from mmc-controller.yaml.

Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
---
Changes in v2:
- Drop the duplicate properties in the slot node.
- Link to v1: https://lore.kernel.org/r/20241205-hsmci-v1-1-5a25e622dfed@microchip.com
---
 .../devicetree/bindings/mmc/atmel,hsmci.yaml       | 110 +++++++++++++++++++++
 .../devicetree/bindings/mmc/atmel-hsmci.txt        |  73 --------------
 2 files changed, 110 insertions(+), 73 deletions(-)

diff --git a/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
new file mode 100644
index 000000000000..26686ada6288
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mmc/atmel,hsmci.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Atmel High-Speed MultiMedia Card Interface (HSMCI)
+
+description:
+  The Atmel HSMCI controller provides an interface for MMC, SD, and SDIO memory
+  cards.
+
+maintainers:
+  - Nicolas Ferre <nicolas.ferre@microchip.com>
+  - Aubin Constans <aubin.constans@microchip.com>
+
+allOf:
+  - $ref: mmc-controller.yaml
+
+properties:
+  compatible:
+    const: atmel,hsmci
+
+  reg:
+    maxItems: 1
+
+  interrupts:
+    maxItems: 1
+
+  dmas:
+    maxItems: 1
+
+  dma-names:
+    const: rxtx
+
+  clocks:
+    maxItems: 1
+
+  clock-names:
+    const: mci_clk
+
+  "#address-cells":
+    const: 1
+    description: Used for slot IDs.
+
+  "#size-cells":
+    const: 0
+
+patternProperties:
+  "^slot@[0-9]+$":
+    type: object
+    description: A slot node representing an MMC, SD, or SDIO slot.
+
+    allOf:
+      - $ref: mmc-controller.yaml
+
+    properties:
+      reg:
+        description: Slot ID.
+        minimum: 0
+
+    required:
+      - reg
+      - bus-width
+
+    unevaluatedProperties: false
+
+required:
+  - compatible
+  - reg
+  - interrupts
+  - clocks
+  - clock-names
+  - "#address-cells"
+  - "#size-cells"
+
+anyOf:
+  - required:
+      - slot@0
+  - required:
+      - slot@1
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    #include <dt-bindings/interrupt-controller/irq.h>
+    #include <dt-bindings/clock/at91.h>
+    mmc@f0008000 {
+      compatible = "atmel,hsmci";
+      reg = <0xf0008000 0x600>;
+      interrupts = <12 IRQ_TYPE_LEVEL_HIGH>;
+      clocks = <&mci0_clk>;
+      clock-names = "mci_clk";
+      #address-cells = <1>;
+      #size-cells = <0>;
+
+      slot@0 {
+        reg = <0>;
+        bus-width = <4>;
+        cd-gpios = <&pioD 15 0>;
+        cd-inverted;
+      };
+
+      slot@1 {
+        reg = <1>;
+        bus-width = <4>;
+      };
+    };
+...
diff --git a/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt b/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt
deleted file mode 100644
index 07ad02075a93..000000000000
--- a/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt
+++ /dev/null
@@ -1,73 +0,0 @@
-* Atmel High Speed MultiMedia Card Interface
-
-This controller on atmel products provides an interface for MMC, SD and SDIO
-types of memory cards.
-
-This file documents differences between the core properties described
-by mmc.txt and the properties used by the atmel-mci driver.
-
-1) MCI node
-
-Required properties:
-- compatible: should be "atmel,hsmci"
-- #address-cells: should be one. The cell is the slot id.
-- #size-cells: should be zero.
-- at least one slot node
-- clock-names: tuple listing input clock names.
-	Required elements: "mci_clk"
-- clocks: phandles to input clocks.
-
-The node contains child nodes for each slot that the platform uses
-
-Example MCI node:
-
-mmc0: mmc@f0008000 {
-	compatible = "atmel,hsmci";
-	reg = <0xf0008000 0x600>;
-	interrupts = <12 4>;
-	#address-cells = <1>;
-	#size-cells = <0>;
-	clock-names = "mci_clk";
-	clocks = <&mci0_clk>;
-
-	[ child node definitions...]
-};
-
-2) slot nodes
-
-Required properties:
-- reg: should contain the slot id.
-- bus-width: number of data lines connected to the controller
-
-Optional properties:
-- cd-gpios: specify GPIOs for card detection
-- cd-inverted: invert the value of external card detect gpio line
-- wp-gpios: specify GPIOs for write protection
-
-Example slot node:
-
-slot@0 {
-	reg = <0>;
-	bus-width = <4>;
-	cd-gpios = <&pioD 15 0>
-	cd-inverted;
-};
-
-Example full MCI node:
-mmc0: mmc@f0008000 {
-	compatible = "atmel,hsmci";
-	reg = <0xf0008000 0x600>;
-	interrupts = <12 4>;
-	#address-cells = <1>;
-	#size-cells = <0>;
-	slot@0 {
-		reg = <0>;
-		bus-width = <4>;
-		cd-gpios = <&pioD 15 0>
-		cd-inverted;
-	};
-	slot@1 {
-		reg = <1>;
-		bus-width = <4>;
-	};
-};

---
base-commit: feffde684ac29a3b7aec82d2df850fbdbdee55e4
change-id: 20241205-hsmci-7ac3ea915777

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

Re: [PATCH v2] dt-bindings: mmc: atmel,hsmci: Convert to json schema

[Charan.Pedumuru]

On 09/12/24 10:02, Dharma Balasubiramani wrote:
> Convert atmel,hsmci documentation to yaml format. The new file will inherit
> from mmc-controller.yaml.
>
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>

Reviewed-by: Charan Pedumuru <charan.pedumuru@microchip.com>

> ---
> Changes in v2:
> - Drop the duplicate properties in the slot node.
> - Link to v1: https://lore.kernel.org/r/20241205-hsmci-v1-1-5a25e622dfed@microchip.com
> ---
>   .../devicetree/bindings/mmc/atmel,hsmci.yaml       | 110 +++++++++++++++++++++
>   .../devicetree/bindings/mmc/atmel-hsmci.txt        |  73 --------------
>   2 files changed, 110 insertions(+), 73 deletions(-)
>
> diff --git a/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
> new file mode 100644
> index 000000000000..26686ada6288
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
> @@ -0,0 +1,110 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mmc/atmel,hsmci.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Atmel High-Speed MultiMedia Card Interface (HSMCI)
> +
> +description:
> +  The Atmel HSMCI controller provides an interface for MMC, SD, and SDIO memory
> +  cards.
> +
> +maintainers:
> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
> +  - Aubin Constans <aubin.constans@microchip.com>
> +
> +allOf:
> +  - $ref: mmc-controller.yaml
> +
> +properties:
> +  compatible:
> +    const: atmel,hsmci
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  dmas:
> +    maxItems: 1
> +
> +  dma-names:
> +    const: rxtx
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: mci_clk
> +
> +  "#address-cells":
> +    const: 1
> +    description: Used for slot IDs.
> +
> +  "#size-cells":
> +    const: 0
> +
> +patternProperties:
> +  "^slot@[0-9]+$":
> +    type: object
> +    description: A slot node representing an MMC, SD, or SDIO slot.
> +
> +    allOf:
> +      - $ref: mmc-controller.yaml
> +
> +    properties:
> +      reg:
> +        description: Slot ID.
> +        minimum: 0
> +
> +    required:
> +      - reg
> +      - bus-width
> +
> +    unevaluatedProperties: false
> +
> +required:
> +  - compatible
> +  - reg
> +  - interrupts
> +  - clocks
> +  - clock-names
> +  - "#address-cells"
> +  - "#size-cells"
> +
> +anyOf:
> +  - required:
> +      - slot@0
> +  - required:
> +      - slot@1
> +
> +unevaluatedProperties: false
> +
> +examples:
> +  - |
> +    #include <dt-bindings/interrupt-controller/irq.h>
> +    #include <dt-bindings/clock/at91.h>
> +    mmc@f0008000 {
> +      compatible = "atmel,hsmci";
> +      reg = <0xf0008000 0x600>;
> +      interrupts = <12 IRQ_TYPE_LEVEL_HIGH>;
> +      clocks = <&mci0_clk>;
> +      clock-names = "mci_clk";
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      slot@0 {
> +        reg = <0>;
> +        bus-width = <4>;
> +        cd-gpios = <&pioD 15 0>;
> +        cd-inverted;
> +      };
> +
> +      slot@1 {
> +        reg = <1>;
> +        bus-width = <4>;
> +      };
> +    };
> +...
> diff --git a/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt b/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt
> deleted file mode 100644
> index 07ad02075a93..000000000000
> --- a/Documentation/devicetree/bindings/mmc/atmel-hsmci.txt
> +++ /dev/null
> @@ -1,73 +0,0 @@
> -* Atmel High Speed MultiMedia Card Interface
> -
> -This controller on atmel products provides an interface for MMC, SD and SDIO
> -types of memory cards.
> -
> -This file documents differences between the core properties described
> -by mmc.txt and the properties used by the atmel-mci driver.
> -
> -1) MCI node
> -
> -Required properties:
> -- compatible: should be "atmel,hsmci"
> -- #address-cells: should be one. The cell is the slot id.
> -- #size-cells: should be zero.
> -- at least one slot node
> -- clock-names: tuple listing input clock names.
> -	Required elements: "mci_clk"
> -- clocks: phandles to input clocks.
> -
> -The node contains child nodes for each slot that the platform uses
> -
> -Example MCI node:
> -
> -mmc0: mmc@f0008000 {
> -	compatible = "atmel,hsmci";
> -	reg = <0xf0008000 0x600>;
> -	interrupts = <12 4>;
> -	#address-cells = <1>;
> -	#size-cells = <0>;
> -	clock-names = "mci_clk";
> -	clocks = <&mci0_clk>;
> -
> -	[ child node definitions...]
> -};
> -
> -2) slot nodes
> -
> -Required properties:
> -- reg: should contain the slot id.
> -- bus-width: number of data lines connected to the controller
> -
> -Optional properties:
> -- cd-gpios: specify GPIOs for card detection
> -- cd-inverted: invert the value of external card detect gpio line
> -- wp-gpios: specify GPIOs for write protection
> -
> -Example slot node:
> -
> -slot@0 {
> -	reg = <0>;
> -	bus-width = <4>;
> -	cd-gpios = <&pioD 15 0>
> -	cd-inverted;
> -};
> -
> -Example full MCI node:
> -mmc0: mmc@f0008000 {
> -	compatible = "atmel,hsmci";
> -	reg = <0xf0008000 0x600>;
> -	interrupts = <12 4>;
> -	#address-cells = <1>;
> -	#size-cells = <0>;
> -	slot@0 {
> -		reg = <0>;
> -		bus-width = <4>;
> -		cd-gpios = <&pioD 15 0>
> -		cd-inverted;
> -	};
> -	slot@1 {
> -		reg = <1>;
> -		bus-width = <4>;
> -	};
> -};
>
> ---
> base-commit: feffde684ac29a3b7aec82d2df850fbdbdee55e4
> change-id: 20241205-hsmci-7ac3ea915777
>
> Best regards,


-- 
Best Regards,
Charan.

Re: [PATCH v2] dt-bindings: mmc: atmel,hsmci: Convert to json schema

[Rob Herring]

On Mon, Dec 09, 2024 at 10:02:30AM +0530, Dharma Balasubiramani wrote:
> Convert atmel,hsmci documentation to yaml format. The new file will inherit
> from mmc-controller.yaml.
> 
> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
> ---
> Changes in v2:
> - Drop the duplicate properties in the slot node.
> - Link to v1: https://lore.kernel.org/r/20241205-hsmci-v1-1-5a25e622dfed@microchip.com
> ---
>  .../devicetree/bindings/mmc/atmel,hsmci.yaml       | 110 +++++++++++++++++++++
>  .../devicetree/bindings/mmc/atmel-hsmci.txt        |  73 --------------
>  2 files changed, 110 insertions(+), 73 deletions(-)
> 
> diff --git a/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
> new file mode 100644
> index 000000000000..26686ada6288
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
> @@ -0,0 +1,110 @@
> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mmc/atmel,hsmci.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: Atmel High-Speed MultiMedia Card Interface (HSMCI)
> +
> +description:
> +  The Atmel HSMCI controller provides an interface for MMC, SD, and SDIO memory
> +  cards.
> +
> +maintainers:
> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
> +  - Aubin Constans <aubin.constans@microchip.com>
> +
> +allOf:
> +  - $ref: mmc-controller.yaml
> +
> +properties:
> +  compatible:
> +    const: atmel,hsmci
> +
> +  reg:
> +    maxItems: 1
> +
> +  interrupts:
> +    maxItems: 1
> +
> +  dmas:
> +    maxItems: 1
> +
> +  dma-names:
> +    const: rxtx
> +
> +  clocks:
> +    maxItems: 1
> +
> +  clock-names:
> +    const: mci_clk
> +
> +  "#address-cells":
> +    const: 1
> +    description: Used for slot IDs.
> +
> +  "#size-cells":
> +    const: 0
> +
> +patternProperties:
> +  "^slot@[0-9]+$":
> +    type: object
> +    description: A slot node representing an MMC, SD, or SDIO slot.

There's a schema for slots now queued for 6.14[1]. You should use that. 
One issue is 'compatible' is required. Either that would have to be 
dropped as required or you could just add it in your .dts files.

Rob

Re: [PATCH v2] dt-bindings: mmc: atmel,hsmci: Convert to json schema

[Dharma.B]

Hi Rob,

On 17/12/24 6:13 pm, Rob Herring wrote:
> EXTERNAL EMAIL: Do not click links or open attachments unless you know the content is safe
> 
> On Mon, Dec 09, 2024 at 10:02:30AM +0530, Dharma Balasubiramani wrote:
>> Convert atmel,hsmci documentation to yaml format. The new file will inherit
>> from mmc-controller.yaml.
>>
>> Signed-off-by: Dharma Balasubiramani <dharma.b@microchip.com>
>> ---
>> Changes in v2:
>> - Drop the duplicate properties in the slot node.
>> - Link to v1: https://lore.kernel.org/r/20241205-hsmci-v1-1-5a25e622dfed@microchip.com
>> ---
>>   .../devicetree/bindings/mmc/atmel,hsmci.yaml       | 110 +++++++++++++++++++++
>>   .../devicetree/bindings/mmc/atmel-hsmci.txt        |  73 --------------
>>   2 files changed, 110 insertions(+), 73 deletions(-)
>>
>> diff --git a/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
>> new file mode 100644
>> index 000000000000..26686ada6288
>> --- /dev/null
>> +++ b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
>> @@ -0,0 +1,110 @@
>> +# SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
>> +%YAML 1.2
>> +---
>> +$id: http://devicetree.org/schemas/mmc/atmel,hsmci.yaml#
>> +$schema: http://devicetree.org/meta-schemas/core.yaml#
>> +
>> +title: Atmel High-Speed MultiMedia Card Interface (HSMCI)
>> +
>> +description:
>> +  The Atmel HSMCI controller provides an interface for MMC, SD, and SDIO memory
>> +  cards.
>> +
>> +maintainers:
>> +  - Nicolas Ferre <nicolas.ferre@microchip.com>
>> +  - Aubin Constans <aubin.constans@microchip.com>
>> +
>> +allOf:
>> +  - $ref: mmc-controller.yaml
>> +
>> +properties:
>> +  compatible:
>> +    const: atmel,hsmci
>> +
>> +  reg:
>> +    maxItems: 1
>> +
>> +  interrupts:
>> +    maxItems: 1
>> +
>> +  dmas:
>> +    maxItems: 1
>> +
>> +  dma-names:
>> +    const: rxtx
>> +
>> +  clocks:
>> +    maxItems: 1
>> +
>> +  clock-names:
>> +    const: mci_clk
>> +
>> +  "#address-cells":
>> +    const: 1
>> +    description: Used for slot IDs.
>> +
>> +  "#size-cells":
>> +    const: 0
>> +
>> +patternProperties:
>> +  "^slot@[0-9]+$":
>> +    type: object
>> +    description: A slot node representing an MMC, SD, or SDIO slot.
> 
> There's a schema for slots now queued for 6.14[1]. You should use that.

Sure,
I will drop these and will just add the REF to mmc-slot

  patternProperties:
    "^slot@[0-9]+$":
-    type: object
-    description: A slot node representing an MMC, SD, or SDIO slot.
-
-    allOf:
-      - $ref: mmc-controller.yaml
-
-    properties:
-      reg:
-        description: Slot ID.
-        minimum: 0
+    $ref: mmc-slot.yaml

> One issue is 'compatible' is required. Either that would have to be
> dropped as required 
How to do that?

dt_binding_check complains that mmc@f0008000: slot@0: 'compatible' is a 
required property.

If the mmc-slot yaml is a generic binding then shall we move the 
compatible to its specific binding(amlogic,meson-mx-sdio.yaml)?

or you could just add it in your .dts files.

Won't it be redundant to have it?
> 
> Rob


-- 
With Best Regards,
Dharma B.