dt-bindings: mtd: convert "fixed-partitions" to the json-schema

From: Rafał Miłecki <[email protected]>

This standardizes its documentation, allows validating with Makefile checks and helps writing DTS files.

Noticeable changes:
1. Dropped "Partitions can be represented by sub-nodes of a flash device." as we also support subpartitions (don't have to be part of flash device node)
2. Dropped "to Linux" as bindings are meant to be os agnostic.

Signed-off-by Rafał Miłecki <[email protected]>

---
 .../devicetree/bindings/mtd/partition.txt     | 131 +---------------
 .../mtd/partitions/fixed-partitions.yaml      | 146 ++++++++++++++++++
 2 files changed, 148 insertions(+), 129 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml

Documentation/devicetree/bindings/mtd/partition.txt +2 -129

index 4a39698221a2..ead90e8274d6 100644
@@ -24,137 +24,10 @@ another partitioning method.
 Available bindings are listed in the "partitions" subdirectory.
 
 
-Fixed Partitions
-================
-
-Partitions can be represented by sub-nodes of a flash device. This can be used
-on platforms which have strong conventions about which portions of a flash are
-used for what purposes, but which don't use an on-flash partition table such
-as RedBoot.
-
-The partition table should be a subnode of the flash node and should be named
-'partitions'. This node should have the following property:
-- compatible : (required) must be "fixed-partitions"
-Partitions are then defined in subnodes of the partitions node.
+Deprecated: partitions defined in flash node
+============================================
 
 For backwards compatibility partitions as direct subnodes of the flash device are
 supported. This use is discouraged.
 NOTE: also for backwards compatibility, direct subnodes that have a compatible
 string are not considered partitions, as they may be used for other bindings.
-
-#address-cells & #size-cells must both be present in the partitions subnode of the
-flash device. There are two valid values for both:
-<1>: for partitions that require a single 32-bit cell to represent their
-     size/address (aka the value is below 4 GiB)
-<2>: for partitions that require two 32-bit cells to represent their
-     size/address (aka the value is 4 GiB or greater).
-
-Required properties:
-- reg : The partition's offset and size within the flash
-
-Optional properties:
-- label : The label / name for this partition.  If omitted, the label is taken
-  from the node name (excluding the unit address).
-- read-only : This parameter, if present, is a hint to Linux that this
-  partition should only be mounted read-only. This is usually used for flash
-  partitions containing early-boot firmware images or data which should not be
-  clobbered.
-- lock : Do not unlock the partition at initialization time (not supported on
-  all devices)
-- slc-mode: This parameter, if present, allows one to emulate SLC mode on a
-  partition attached to an MLC NAND thus making this partition immune to
-  paired-pages corruptions
-
-Examples:
-
-
-flash@0 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <1>;
-		#size-cells = <1>;
-
-		partition@0 {
-			label = "u-boot";
-			reg = <0x0000000 0x100000>;
-			read-only;
-		};
-
-		uimage@100000 {
-			reg = <0x0100000 0x200000>;
-		};
-	};
-};
-
-flash@1 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <1>;
-		#size-cells = <2>;
-
-		/* a 4 GiB partition */
-		partition@0 {
-			label = "filesystem";
-			reg = <0x00000000 0x1 0x00000000>;
-		};
-	};
-};
-
-flash@2 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <2>;
-		#size-cells = <2>;
-
-		/* an 8 GiB partition */
-		partition@0 {
-			label = "filesystem #1";
-			reg = <0x0 0x00000000 0x2 0x00000000>;
-		};
-
-		/* a 4 GiB partition */
-		partition@200000000 {
-			label = "filesystem #2";
-			reg = <0x2 0x00000000 0x1 0x00000000>;
-		};
-	};
-};
-
-flash@3 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <1>;
-		#size-cells = <1>;
-
-		partition@0 {
-			label = "bootloader";
-			reg = <0x000000 0x100000>;
-			read-only;
-		};
-
-		firmware@100000 {
-			label = "firmware";
-			reg = <0x100000 0xe00000>;
-			compatible = "brcm,trx";
-		};
-
-		calibration@f00000 {
-			label = "calibration";
-			reg = <0xf00000 0x100000>;
-			compatible = "fixed-partitions";
-			ranges = <0 0xf00000 0x100000>;
-			#address-cells = <1>;
-			#size-cells = <1>;
-
-			partition@0 {
-				label = "wifi0";
-				reg = <0x000000 0x080000>;
-			};
-
-			partition@80000 {
-				label = "wifi1";
-				reg = <0x080000 0x080000>;
-			};
-		};
-	};
-};

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +15 -0

new file mode 100644
index 000000000000..c5e509e08f31
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/fixed-partitions.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fixed partitions
+
+description: |
+  This binding can be used on platforms which have strong conventions about
+  which portions of a flash are used for what purposes, but which don't use an
+  on-flash partition table such as RedBoot.
+
+  The partition table should be a node named "partitions". Partitions are then
+  defined as subnodes.

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +30 -0

+
+      label:
+        description: The label / name for this partition. If omitted, the label
+          is taken from the node name (excluding the unit address).
+
+      read-only:
+        description: This parameter, if present, is a hint that this partition
+          should only be mounted read-only. This is usually used for flash
+          partitions containing early-boot firmware images or data which should
+          not be clobbered.
+        type: boolean
+
+      lock:
+        description: Do not unlock the partition at initialization time (not
+          supported on all devices)
+        type: boolean
+
+      slc-mode:
+        description: This parameter, if present, allows one to emulate SLC mode
+          on a partition attached to an MLC NAND thus making this partition
+          immune to paired-pages corruptions
+        type: boolean
+
+    required:
+      - reg
+
+required:
+  - compatible
+
+additionalProperties: true

Quoted 183 lines · Rafał Miłecki

From: Rafał Miłecki <[email protected]>

This standardizes its documentation, allows validating with Makefile checks and helps writing DTS files.

Noticeable changes:
1. Dropped "Partitions can be represented by sub-nodes of a flash device." as we also support subpartitions (don't have to be part of flash device node)
2. Dropped "to Linux" as bindings are meant to be os agnostic.

Signed-off-by Rafał Miłecki <[email protected]>

---
  .../devicetree/bindings/mtd/partition.txt     | 131 +---------------
  .../mtd/partitions/fixed-partitions.yaml      | 146 ++++++++++++++++++
  2 files changed, 148 insertions(+), 129 deletions(-)

create mode 100644 Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml

Documentation/devicetree/bindings/mtd/partition.txt +2 -129

index 4a39698221a2..ead90e8274d6 100644
@@ -24,137 +24,10 @@ another partitioning method.
  Available bindings are listed in the "partitions" subdirectory.
 
 
-Fixed Partitions
-================
-
-Partitions can be represented by sub-nodes of a flash device. This can be used
-on platforms which have strong conventions about which portions of a flash are
-used for what purposes, but which don't use an on-flash partition table such
-as RedBoot.
-
-The partition table should be a subnode of the flash node and should be named
-'partitions'. This node should have the following property:
-- compatible : (required) must be "fixed-partitions"
-Partitions are then defined in subnodes of the partitions node.
+Deprecated: partitions defined in flash node
+============================================
 
  For backwards compatibility partitions as direct subnodes of the flash device are
  supported. This use is discouraged.
  NOTE: also for backwards compatibility, direct subnodes that have a compatible
  string are not considered partitions, as they may be used for other bindings.
-
-#address-cells & #size-cells must both be present in the partitions subnode of the
-flash device. There are two valid values for both:
-<1>: for partitions that require a single 32-bit cell to represent their
-     size/address (aka the value is below 4 GiB)
-<2>: for partitions that require two 32-bit cells to represent their
-     size/address (aka the value is 4 GiB or greater).
-
-Required properties:
-- reg : The partition's offset and size within the flash
-
-Optional properties:
-- label : The label / name for this partition.  If omitted, the label is taken
-  from the node name (excluding the unit address).
-- read-only : This parameter, if present, is a hint to Linux that this
-  partition should only be mounted read-only. This is usually used for flash
-  partitions containing early-boot firmware images or data which should not be
-  clobbered.
-- lock : Do not unlock the partition at initialization time (not supported on
-  all devices)
-- slc-mode: This parameter, if present, allows one to emulate SLC mode on a
-  partition attached to an MLC NAND thus making this partition immune to
-  paired-pages corruptions
-
-Examples:
-
-
-flash@0 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <1>;
-		#size-cells = <1>;
-
-		partition@0 {
-			label = "u-boot";
-			reg = <0x0000000 0x100000>;
-			read-only;
-		};
-
-		uimage@100000 {
-			reg = <0x0100000 0x200000>;
-		};
-	};
-};
-
-flash@1 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <1>;
-		#size-cells = <2>;
-
-		/* a 4 GiB partition */
-		partition@0 {
-			label = "filesystem";
-			reg = <0x00000000 0x1 0x00000000>;
-		};
-	};
-};
-
-flash@2 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <2>;
-		#size-cells = <2>;
-
-		/* an 8 GiB partition */
-		partition@0 {
-			label = "filesystem #1";
-			reg = <0x0 0x00000000 0x2 0x00000000>;
-		};
-
-		/* a 4 GiB partition */
-		partition@200000000 {
-			label = "filesystem #2";
-			reg = <0x2 0x00000000 0x1 0x00000000>;
-		};
-	};
-};
-
-flash@3 {
-	partitions {
-		compatible = "fixed-partitions";
-		#address-cells = <1>;
-		#size-cells = <1>;
-
-		partition@0 {
-			label = "bootloader";
-			reg = <0x000000 0x100000>;
-			read-only;
-		};
-
-		firmware@100000 {
-			label = "firmware";
-			reg = <0x100000 0xe00000>;
-			compatible = "brcm,trx";
-		};
-
-		calibration@f00000 {
-			label = "calibration";
-			reg = <0xf00000 0x100000>;
-			compatible = "fixed-partitions";
-			ranges = <0 0xf00000 0x100000>;
-			#address-cells = <1>;
-			#size-cells = <1>;
-
-			partition@0 {
-				label = "wifi0";
-				reg = <0x000000 0x080000>;
-			};
-
-			partition@80000 {
-				label = "wifi1";
-				reg = <0x080000 0x080000>;
-			};
-		};
-	};
-};

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +15 -0

new file mode 100644
index 000000000000..c5e509e08f31
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/fixed-partitions.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fixed partitions
+
+description: |
+  This binding can be used on platforms which have strong conventions about
+  which portions of a flash are used for what purposes, but which don't use an
+  on-flash partition table such as RedBoot.
+
+  The partition table should be a node named "partitions". Partitions are then
+  defined as subnodes.

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml line 25

Quoted 10 lines

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +10 -0

+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+properties:
+  compatible:
+    const: fixed-partitions
+
+patternProperties:
+  "^.*@[0-9a-f]+$":

You can drop '^.*'.

This needs to recurse to nested nodes.

I think here you can do just:

$ref: #/

And drop 'compatible' as required. It's redundant anyways because the schema will only be applied if compatible matches.

Quoted 53 lines · Rob Herring

Quoted 39 lines · Rafał Miłecki

From: Rafał Miłecki <[email protected]>

This standardizes its documentation, allows validating with Makefile checks and helps writing DTS files.

Noticeable changes:
1. Dropped "Partitions can be represented by sub-nodes of a flash device." as we also support subpartitions (don't have to be part of flash device node)
2. Dropped "to Linux" as bindings are meant to be os agnostic.

Signed-off-by Rafał Miłecki <[email protected]>

---
  .../devicetree/bindings/mtd/partition.txt     | 131 +---------------
  .../mtd/partitions/fixed-partitions.yaml      | 146 ++++++++++++++++++
  2 files changed, 148 insertions(+), 129 deletions(-)

create mode 100644 Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +15 -0

new file mode 100644
index 000000000000..c5e509e08f31
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/fixed-partitions.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fixed partitions
+
+description: |
+  This binding can be used on platforms which have strong conventions about
+  which portions of a flash are used for what purposes, but which don't use an
+  on-flash partition table such as RedBoot.
+
+  The partition table should be a node named "partitions". Partitions are then
+  defined as subnodes.

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml line 25

Quoted 10 lines

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +10 -0

+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+properties:
+  compatible:
+    const: fixed-partitions
+
+patternProperties:
+  "^.*@[0-9a-f]+$":

You can drop '^.*'.

Quoted 8 lines

This needs to recurse to nested nodes.

I think here you can do just:

$ref: #/

And drop 'compatible' as required. It's redundant anyways because the schema will only be applied if compatible matches.

I managed to implement recursive schema but then I run dt_binding_check and realized it may be not what we really want.

The error I got was:
Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.example.dt.yaml: partitions: firmware@100000:compatible:0: 'fixed-partitions' was expected
From schema: Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml

and was caused by the following example:

partitions {
        compatible = "fixed-partitions";
        #address-cells = <1>;
        #size-cells = <1>;

        (...)

        firmware@100000 {
                label = "firmware";
                reg = <0x100000 0xe00000>;
                compatible = "brcm,trx";
        };

        (...)
}

As you can see a single partition can use any available parser, so we can't require only "fixed-partitions" to be nested in the "fixed-partitions".

In this situation I think this commit may be OK after all if I just fix regex and required (drop "compatible").

What do you think?

FWIW:

properties:
compatible:
const: fixed-partitions

patternProperties:
"@[0-9a-f]+$":
allOf:
- $ref: "#"
- properties:
reg:
maxItems: 1
description: partition's offset and size within the flash

label:
description: The label / name for this partition. If omitted, the label
is taken from the node name (excluding the unit address).

read-only:
description: This parameter, if present, is a hint that this partition
should only be mounted read-only. This is usually used for flash partitions containing early-boot firmware images or data which should not be clobbered.
type: boolean

lock:
description: Do not unlock the partition at initialization time (not
supported on all devices)
type: boolean

slc-mode:
description: This parameter, if present, allows one to emulate SLC mode
on a partition attached to an MLC NAND thus making this partition immune to paired-pages corruptions
type: boolean

required:
- reg

From: Rafał Miłecki <[email protected]>

This standardizes its documentation, allows validating with Makefile checks and helps writing DTS files.

Noticeable changes:
1. Dropped "Partitions can be represented by sub-nodes of a flash device." as we also support subpartitions (don't have to be part of flash device node)
2. Dropped "to Linux" as bindings are meant to be os agnostic.

Signed-off-by Rafał Miłecki <[email protected]>

---
 .../devicetree/bindings/mtd/partition.txt     | 131 +---------------
 .../mtd/partitions/fixed-partitions.yaml      | 146 ++++++++++++++++++
 2 files changed, 148 insertions(+), 129 deletions(-)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +12 -0

new file mode 100644
index 000000000000..c5e509e08f31
@@ -0,0 +1,146 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/fixed-partitions.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: Fixed partitions
+
+description: |
+  This binding can be used on platforms which have strong conventions about
+  which portions of a flash are used for what purposes, but which don't use an
+  on-flash partition table such as RedBoot.

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +93 -0

+
+patternProperties:
+  "^.*@[0-9a-f]+$":
+    description: node describing a single flash partition
+    type: object
+
+    properties:
+      reg:
+        description: partition's offset and size within the flash
+
+      label:
+        description: The label / name for this partition. If omitted, the label
+          is taken from the node name (excluding the unit address).
+
+      read-only:
+        description: This parameter, if present, is a hint that this partition
+          should only be mounted read-only. This is usually used for flash
+          partitions containing early-boot firmware images or data which should
+          not be clobbered.
+        type: boolean
+
+      lock:
+        description: Do not unlock the partition at initialization time (not
+          supported on all devices)
+        type: boolean
+
+      slc-mode:
+        description: This parameter, if present, allows one to emulate SLC mode
+          on a partition attached to an MLC NAND thus making this partition
+          immune to paired-pages corruptions
+        type: boolean
+
+    required:
+      - reg
+
+required:
+  - compatible
+
+additionalProperties: true
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
+            label = "u-boot";
+            reg = <0x0000000 0x100000>;
+            read-only;
+        };
+
+        uimage@100000 {
+            reg = <0x0100000 0x200000>;
+        };
+    };
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <2>;
+
+        /* a 4 GiB partition */
+        partition@0 {
+            label = "filesystem";
+            reg = <0x00000000 0x1 0x00000000>;
+        };
+    };
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <2>;
+        #size-cells = <2>;
+
+        /* an 8 GiB partition */
+        partition@0 {
+            label = "filesystem #1";
+            reg = <0x0 0x00000000 0x2 0x00000000>;
+        };
+
+        /* a 4 GiB partition */
+        partition@200000000 {
+            label = "filesystem #2";
+            reg = <0x2 0x00000000 0x1 0x00000000>;
+        };
+    };
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+

Documentation/devicetree/bindings/mtd/partitions/fixed-partitions.yaml new file +21 -1

+        };
+
+        calibration@f00000 {
+            label = "calibration";
+            reg = <0xf00000 0x100000>;
+            compatible = "fixed-partitions";
+            ranges = <0 0xf00000 0x100000>;
+            #address-cells = <1>;
+            #size-cells = <1>;
+
+            partition@0 {
+                label = "wifi0";
+                reg = <0x000000 0x080000>;
+            };
+
+            partition@80000 {
+                label = "wifi1";
+                reg = <0x080000 0x080000>;
+            };
+        };
+    };
--

2.26.2