diff mbox series

dt-bindings: mmc: atmel,hsmci: Convert to json schema

Message ID 20241205-hsmci-v1-1-5a25e622dfed@microchip.com
State Superseded
Headers show
Series dt-bindings: mmc: atmel,hsmci: Convert to json schema | expand

Commit Message

Dharma Balasubiramani Dec. 5, 2024, 9:57 a.m. UTC 
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>
---
 .../devicetree/bindings/mmc/atmel,hsmci.yaml       | 124 +++++++++++++++++++++
 .../devicetree/bindings/mmc/atmel-hsmci.txt        |  73 ------------
 2 files changed, 124 insertions(+), 73 deletions(-)


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

Best regards,

Comments

Conor Dooley Dec. 5, 2024, 5:45 p.m. UTC | #1 
On Thu, Dec 05, 2024 at 03:27:02PM +0530, Dharma Balasubiramani wrote:

> +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
> +
> +      bus-width:
> +        description: Number of data lines connected to the controller.
> +        enum: [1, 4, 8]
> +
> +      cd-gpios:
> +        description: GPIO used for card detection.
> +
> +      cd-inverted:
> +        type: boolean

This type conflicts with mmc-controller.yaml, it's a flag there.

> +        description: Inverts the value of the card detection GPIO.
> +
> +      wp-gpios:
> +        description: GPIO used for write protection.
> +
> +    required:
> +      - reg
> +      - bus-width
> +
> +    unevaluatedProperties: false

Do you mean additionalProperties: false here? You listed properties
contained in mmc-controller.yaml which makes it seem like you're
restricting to this subset rather than allowing all properties - but you
need additionalProperties: false to do that.
Dharma Balasubiramani Dec. 6, 2024, 5:16 a.m. UTC | #2 
Hi Conor,

On 05/12/24 11:15 pm, Conor Dooley wrote:
> On Thu, Dec 05, 2024 at 03:27:02PM +0530, Dharma Balasubiramani wrote:
> 
>> +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
>> +
>> +      bus-width:
>> +        description: Number of data lines connected to the controller.
>> +        enum: [1, 4, 8]
>> +
>> +      cd-gpios:
>> +        description: GPIO used for card detection.
>> +
>> +      cd-inverted:
>> +        type: boolean
> This type conflicts with mmc-controller.yaml, it's a flag there.

Yes, I overlooked it. I'll simply remove the type here.

> 
>> +        description: Inverts the value of the card detection GPIO.
>> +
>> +      wp-gpios:
>> +        description: GPIO used for write protection.
>> +
>> +    required:
>> +      - reg
>> +      - bus-width
>> +
>> +    unevaluatedProperties: false
> Do you mean additionalProperties: false here? You listed properties
> contained in mmc-controller.yaml which makes it seem like you're
> restricting to this subset rather than allowing all properties - but you
> need additionalProperties: false to do that.

No, I'm not restricting the properties to this subset. There are 
additional properties, such as "non-removable," "broken-cd," and 
"disable-wp," that are used in our DTS files but are not defined in the 
old text bindings. For this reason, I used `unevaluatedProperties: 
false` instead of `additionalProperties: false`. Let me know if an 
`allOf` reference to `mmc-controller` alone would be sufficient in this 
context.
Conor Dooley Dec. 6, 2024, 5:02 p.m. UTC | #3 
On Fri, Dec 06, 2024 at 05:16:39AM +0000, Dharma.B@microchip.com wrote:
> Hi Conor,
> 
> On 05/12/24 11:15 pm, Conor Dooley wrote:
> > On Thu, Dec 05, 2024 at 03:27:02PM +0530, Dharma Balasubiramani wrote:
> > 
> >> +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
> >> +
> >> +      bus-width:
> >> +        description: Number of data lines connected to the controller.
> >> +        enum: [1, 4, 8]
> >> +
> >> +      cd-gpios:
> >> +        description: GPIO used for card detection.
> >> +
> >> +      cd-inverted:
> >> +        type: boolean
> > This type conflicts with mmc-controller.yaml, it's a flag there.
> 
> Yes, I overlooked it. I'll simply remove the type here.
> 
> > 
> >> +        description: Inverts the value of the card detection GPIO.
> >> +
> >> +      wp-gpios:
> >> +        description: GPIO used for write protection.
> >> +
> >> +    required:
> >> +      - reg
> >> +      - bus-width
> >> +
> >> +    unevaluatedProperties: false
> > Do you mean additionalProperties: false here? You listed properties
> > contained in mmc-controller.yaml which makes it seem like you're
> > restricting to this subset rather than allowing all properties - but you
> > need additionalProperties: false to do that.
> 
> No, I'm not restricting the properties to this subset. There are 
> additional properties, such as "non-removable," "broken-cd," and 
> "disable-wp," that are used in our DTS files but are not defined in the 
> old text bindings. For this reason, I used `unevaluatedProperties: 
> false` instead of `additionalProperties: false`.

> Let me know if an 
> `allOf` reference to `mmc-controller` alone would be sufficient in this 
> context.

Yes, there's no point duplicating properties from there, unless you're
restricting to a subset. I think all you need to keep (other than the
reference) is the required properties list because there seems to be
none in mmc-controller.yaml.
Dharma Balasubiramani Dec. 9, 2024, 2:37 a.m. UTC | #4 
On 06/12/24 10:32 pm, Conor Dooley wrote:
> 
> On Fri, Dec 06, 2024 at 05:16:39AM +0000,Dharma.B@microchip.com wrote:
>> Hi Conor,
>>
>> On 05/12/24 11:15 pm, Conor Dooley wrote:
>>> On Thu, Dec 05, 2024 at 03:27:02PM +0530, Dharma Balasubiramani wrote:
>>>
>>>> +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
>>>> +
>>>> +      bus-width:
>>>> +        description: Number of data lines connected to the controller.
>>>> +        enum: [1, 4, 8]
>>>> +
>>>> +      cd-gpios:
>>>> +        description: GPIO used for card detection.
>>>> +
>>>> +      cd-inverted:
>>>> +        type: boolean
>>> This type conflicts with mmc-controller.yaml, it's a flag there.
>> Yes, I overlooked it. I'll simply remove the type here.
>>
>>>> +        description: Inverts the value of the card detection GPIO.
>>>> +
>>>> +      wp-gpios:
>>>> +        description: GPIO used for write protection.
>>>> +
>>>> +    required:
>>>> +      - reg
>>>> +      - bus-width
>>>> +
>>>> +    unevaluatedProperties: false
>>> Do you mean additionalProperties: false here? You listed properties
>>> contained in mmc-controller.yaml which makes it seem like you're
>>> restricting to this subset rather than allowing all properties - but you
>>> need additionalProperties: false to do that.
>> No, I'm not restricting the properties to this subset. There are
>> additional properties, such as "non-removable," "broken-cd," and
>> "disable-wp," that are used in our DTS files but are not defined in the
>> old text bindings. For this reason, I used `unevaluatedProperties:
>> false` instead of `additionalProperties: false`.
>> Let me know if an
>> `allOf` reference to `mmc-controller` alone would be sufficient in this
>> context.
> Yes, there's no point duplicating properties from there, unless you're
> restricting to a subset. I think all you need to keep (other than the
> reference) is the required properties list because there seems to be
> none in mmc-controller.yaml.

Sure, I will update the binding and will send a v2.
Thanks.
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
new file mode 100644
index 000000000000..3870d464faa8
--- /dev/null
+++ b/Documentation/devicetree/bindings/mmc/atmel,hsmci.yaml
@@ -0,0 +1,124 @@ 
+# 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
+
+      bus-width:
+        description: Number of data lines connected to the controller.
+        enum: [1, 4, 8]
+
+      cd-gpios:
+        description: GPIO used for card detection.
+
+      cd-inverted:
+        type: boolean
+        description: Inverts the value of the card detection GPIO.
+
+      wp-gpios:
+        description: GPIO used for write protection.
+
+    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>;
-	};
-};