Skip to contentSkip to conversation

dt-bindings: mtd: partitions: add UBI binding

PATCH In review Rafał Miłecki 3 participants 6 messages Feb 17, 2022 – Jun 10, 2022

Subsystems (2)
lore
Share & tools
lore
#0 lore raw

PATCH 1/1 dt-bindings: mtd: partitions: add UBI binding

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

UBI is often used on embedded devices to store UBI volumes with device configuration / calibration data. Such volumes may need to be documented and referenced for proper boot & setup.

Some examples:
1. U-Boot environment variables
2. Device calibration data
3. Default setup (e.g. initial password)

---
 .../bindings/mtd/partitions/ubi.yaml          | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/ubi.yaml
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +67 -0
new file mode 100644
index 000000000000..cd081f06d4cb
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/ubi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UBI (Unsorted Block Images) device
+
+description: |
+  UBI is a layer providing logical volumes (consisting of logical blocks) on top
+  of raw flash devices. It deals with low-level flash issues (bit-flips, bad
+  physical eraseblocks, wearing) providing a reliable data storage.
+
+  UBI device is built and stored in a single flash partition.
+
+  Some (usually embedded) devices use UBI volumes of specific names or indexes
+  to store setup / configuration data. This binding allows describing such
+  volumes so they can be identified and referenced by consumers.
+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+allOf:
+  - $ref: partition.yaml#
+
+properties:
+  compatible:
+    const: ubi
+
+patternProperties:
+  "^volume-[0-9a-f]+$":
+    type: object
+    description: UBI volume
+    properties:
+      volume-name:
+        $ref: /schemas/types.yaml#/definitions/string
+      volume-id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+    anyOf:
+      - required:
+          - volume-name
+      - required:
+          - volume-id
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
+            compatible = "ubi";
+            reg = <0x0000000 0x1000000>;
+            label = "filesystem";
+
+            env: volume-0 {
+                volume-name = "u-boot-env";
+            };
+
+            calibration: volume-1 {
+                volume-id = <99>;
+            };
+        };
+    };
Signature · 1 line
2.34.1
maintainer
#1 lore raw
Quoted 73 lines · Rafał Miłecki

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

UBI is often used on embedded devices to store UBI volumes with device configuration / calibration data. Such volumes may need to be documented and referenced for proper boot & setup.

Some examples:
1. U-Boot environment variables
2. Device calibration data
3. Default setup (e.g. initial password)

---
 .../bindings/mtd/partitions/ubi.yaml          | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/ubi.yaml
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +50 -0
new file mode 100644
index 000000000000..cd081f06d4cb
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/ubi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UBI (Unsorted Block Images) device
+
+description: |
+  UBI is a layer providing logical volumes (consisting of logical blocks) on top
+  of raw flash devices. It deals with low-level flash issues (bit-flips, bad
+  physical eraseblocks, wearing) providing a reliable data storage.
+
+  UBI device is built and stored in a single flash partition.
+
+  Some (usually embedded) devices use UBI volumes of specific names or indexes
+  to store setup / configuration data. This binding allows describing such
+  volumes so they can be identified and referenced by consumers.
+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+allOf:
+  - $ref: partition.yaml#
+
+properties:
+  compatible:
+    const: ubi
+
+patternProperties:
+  "^volume-[0-9a-f]+$":
+    type: object
+    description: UBI volume
+    properties:
+      volume-name:
+        $ref: /schemas/types.yaml#/definitions/string
+      volume-id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+    anyOf:
+      - required:
+          - volume-name
+      - required:
+          - volume-id
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 60

Quoted 10 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +10 -0
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
+            compatible = "ubi";
+            reg = <0x0000000 0x1000000>;
+            label = "filesystem";
+
+            env: volume-0 {
+                volume-name = "u-boot-env";

Why not do 'compatible = "u-boot,env";' to align with normal partitions?

Or 'label'?

We have enough ways to identify things, I don't think we need another.

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 63

Quoted 3 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +3 -0
+            };
+
+            calibration: volume-1 {

Are 0 and 1 meaningful or just made up indexing?

Quoted 8 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +4 -0
+                volume-id = <99>;
+            };
+        };
+    };
Signature · 1 line
2.34.1
#2 lore raw
Quoted 78 lines · Rob Herring
Quoted 77 lines · Rafał Miłecki

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

UBI is often used on embedded devices to store UBI volumes with device configuration / calibration data. Such volumes may need to be documented and referenced for proper boot & setup.

Some examples:
1. U-Boot environment variables
2. Device calibration data
3. Default setup (e.g. initial password)

---
  .../bindings/mtd/partitions/ubi.yaml          | 67 +++++++++++++++++++
  1 file changed, 67 insertions(+)

create mode 100644 Documentation/devicetree/bindings/mtd/partitions/ubi.yaml

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +54 -0
new file mode 100644
index 000000000000..cd081f06d4cb
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/ubi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UBI (Unsorted Block Images) device
+
+description: |
+  UBI is a layer providing logical volumes (consisting of logical blocks) on top
+  of raw flash devices. It deals with low-level flash issues (bit-flips, bad
+  physical eraseblocks, wearing) providing a reliable data storage.
+
+  UBI device is built and stored in a single flash partition.
+
+  Some (usually embedded) devices use UBI volumes of specific names or indexes
+  to store setup / configuration data. This binding allows describing such
+  volumes so they can be identified and referenced by consumers.
+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+allOf:
+  - $ref: partition.yaml#
+
+properties:
+  compatible:
+    const: ubi
+
+patternProperties:
+  "^volume-[0-9a-f]+$":
+    type: object
+    description: UBI volume
+    properties:
+      volume-name:
+        $ref: /schemas/types.yaml#/definitions/string
+      volume-id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+    anyOf:
+      - required:
+          - volume-name
+      - required:
+          - volume-id
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
Quoted 8 lines

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 60

Quoted 6 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +6 -0
+            compatible = "ubi";
+            reg = <0x0000000 0x1000000>;
+            label = "filesystem";
+
+            env: volume-0 {
+                volume-name = "u-boot-env";

Why not do 'compatible = "u-boot,env";' to align with normal partitions?

I mean to reserve "compatible" for describing UBI volume content.

If I manage to get
[PATCH V3] dt-bindings: nvmem: add U-Boot environment variables binding
https://patchwork.ozlabs.org/project/devicetree-bindings/patch/[email protected]/
accepted, it'll allow me to later work on something like:

env: volume-0 {
    compatible = "u-boot,env";
    volume-name = "u-boot-env";
};

(I believe) I'll need (in the final shape) two properties:
1. One for describing UBI volume ("compatible")
2. One for identifying UBI volume ("volume-name" / "volume-id")

It's similar design to the "compatible" vs. "reg" in IO hw blocks.

Quoted 1 line

Or 'label'?

I could replace "volume-name" with "label" but someone once told me that:

Quoted 2 lines

'label' is supposed to correspond to a sticker on a port or something human identifiable

;) https://patchwork.ozlabs.org/comment/2812214/

So I don't want to abuse "label" here.

Quoted 7 lines

We have enough ways to identify things, I don't think we need another.

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 63

Quoted 3 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +3 -0
+            };
+
+            calibration: volume-1 {

Are 0 and 1 meaningful or just made up indexing?

Made up indexing. I need unique nodenames but @[0-9a-f] doesn't appply here.

Quoted 6 lines
Quoted 6 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +4 -0
+                volume-id = <99>;
+            };
+        };
+    };
Signature · 1 line
2.34.1
#3 lore raw

Hi Rob, could you re-review my patch as I provided answers (see below), please?

Quoted 135 lines · Rafał Miłecki
Quoted 78 lines · Rob Herring
Quoted 77 lines · Rafał Miłecki

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

UBI is often used on embedded devices to store UBI volumes with device configuration / calibration data. Such volumes may need to be documented and referenced for proper boot & setup.

Some examples:
1. U-Boot environment variables
2. Device calibration data
3. Default setup (e.g. initial password)

---
  .../bindings/mtd/partitions/ubi.yaml          | 67 +++++++++++++++++++

  1 file changed, 67 insertions(+)

  create mode 100644 Documentation/devicetree/bindings/mtd/partitions/ubi.yaml

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +54 -0
new file mode 100644
index 000000000000..cd081f06d4cb
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/ubi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UBI (Unsorted Block Images) device
+
+description: |
+  UBI is a layer providing logical volumes (consisting of logical blocks) on top
+  of raw flash devices. It deals with low-level flash issues (bit-flips, bad
+  physical eraseblocks, wearing) providing a reliable data storage.
+
+  UBI device is built and stored in a single flash partition.
+
+  Some (usually embedded) devices use UBI volumes of specific names or indexes
+  to store setup / configuration data. This binding allows describing such
+  volumes so they can be identified and referenced by consumers.
+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+allOf:
+  - $ref: partition.yaml#
+
+properties:
+  compatible:
+    const: ubi
+
+patternProperties:
+  "^volume-[0-9a-f]+$":
+    type: object
+    description: UBI volume
+    properties:
+      volume-name:
+        $ref: /schemas/types.yaml#/definitions/string
+      volume-id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+    anyOf:
+      - required:
+          - volume-name
+      - required:
+          - volume-id
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
Quoted 8 lines

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 60

Quoted 6 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +6 -0
+            compatible = "ubi";
+            reg = <0x0000000 0x1000000>;
+            label = "filesystem";
+
+            env: volume-0 {
+                volume-name = "u-boot-env";

Why not do 'compatible = "u-boot,env";' to align with normal partitions?

I mean to reserve "compatible" for describing UBI volume content.

If I manage to get
[PATCH V3] dt-bindings: nvmem: add U-Boot environment variables binding
https://patchwork.ozlabs.org/project/devicetree-bindings/patch/[email protected]/
accepted, it'll allow me to later work on something like:

env: volume-0 {
    compatible = "u-boot,env";
    volume-name = "u-boot-env";
};

(I believe) I'll need (in the final shape) two properties:
1. One for describing UBI volume ("compatible")
2. One for identifying UBI volume ("volume-name" / "volume-id")

It's similar design to the "compatible" vs. "reg" in IO hw blocks.

Quoted 1 line

Or 'label'?

I could replace "volume-name" with "label" but someone once told me that:

Quoted 2 lines

'label' is supposed to correspond to a sticker on a port or something human identifiable

;) https://patchwork.ozlabs.org/comment/2812214/

So I don't want to abuse "label" here.

Quoted 7 lines

We have enough ways to identify things, I don't think we need another.

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 63

Quoted 3 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +3 -0
+            };
+
+            calibration: volume-1 {

Are 0 and 1 meaningful or just made up indexing?

Made up indexing. I need unique nodenames but @[0-9a-f] doesn't appply here.

Quoted 6 lines
Quoted 6 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +4 -0
+                volume-id = <99>;
+            };
+        };
+    };
Signature · 1 line
2.34.1
maintainer
#4 lore raw
In reply to Rafał Miłecki
Quoted 101 lines · Rafał Miłecki
Quoted 78 lines · Rob Herring
Quoted 77 lines · Rafał Miłecki

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

UBI is often used on embedded devices to store UBI volumes with device configuration / calibration data. Such volumes may need to be documented and referenced for proper boot & setup.

Some examples:
1. U-Boot environment variables
2. Device calibration data
3. Default setup (e.g. initial password)

---
  .../bindings/mtd/partitions/ubi.yaml          | 67 +++++++++++++++++++
  1 file changed, 67 insertions(+)

create mode 100644 Documentation/devicetree/bindings/mtd/partitions/ubi.yaml

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +54 -0
new file mode 100644
index 000000000000..cd081f06d4cb
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/ubi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UBI (Unsorted Block Images) device
+
+description: |
+  UBI is a layer providing logical volumes (consisting of logical blocks) on top
+  of raw flash devices. It deals with low-level flash issues (bit-flips, bad
+  physical eraseblocks, wearing) providing a reliable data storage.
+
+  UBI device is built and stored in a single flash partition.
+
+  Some (usually embedded) devices use UBI volumes of specific names or indexes
+  to store setup / configuration data. This binding allows describing such
+  volumes so they can be identified and referenced by consumers.
+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+allOf:
+  - $ref: partition.yaml#
+
+properties:
+  compatible:
+    const: ubi
+
+patternProperties:
+  "^volume-[0-9a-f]+$":
+    type: object
+    description: UBI volume
+    properties:
+      volume-name:
+        $ref: /schemas/types.yaml#/definitions/string
+      volume-id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+    anyOf:
+      - required:
+          - volume-name
+      - required:
+          - volume-id
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
Quoted 8 lines

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 60

Quoted 6 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +6 -0
+            compatible = "ubi";
+            reg = <0x0000000 0x1000000>;
+            label = "filesystem";
+
+            env: volume-0 {
+                volume-name = "u-boot-env";

Why not do 'compatible = "u-boot,env";' to align with normal partitions?

I mean to reserve "compatible" for describing UBI volume content.

If I manage to get
[PATCH V3] dt-bindings: nvmem: add U-Boot environment variables binding
https://patchwork.ozlabs.org/project/devicetree-bindings/patch/[email protected]/
accepted, it'll allow me to later work on something like:

env: volume-0 {
     compatible = "u-boot,env";
     volume-name = "u-boot-env";
};
Quoted 5 lines

(I believe) I'll need (in the final shape) two properties:
1. One for describing UBI volume ("compatible")
2. One for identifying UBI volume ("volume-name" / "volume-id")

It's similar design to the "compatible" vs. "reg" in IO hw blocks.

That's what it is vs. what instance. You need a better example if that's what you are trying to show. I guess if you were doing A/B updates you'd have something like 'volume-name = "u-boot-env-b"'?

Quoted 7 lines
Quoted 3 lines

Or 'label'?

I could replace "volume-name" with "label" but someone once told me that:

Quoted 2 lines

'label' is supposed to correspond to a sticker on a port or something human identifiable

Yes, it could be a human wanting to identify it. The question is whether s/w does too.

The other aspect is there's also filesystem/partition label's. Those are generally set by humans and opaque to the s/w. If the use is aligned with how those labels are used, then I'd be okay with the DT 'label' here.

Quoted 8 lines

;) https://patchwork.ozlabs.org/comment/2812214/

So I don't want to abuse "label" here.

Quoted 2 lines

We have enough ways to identify things, I don't think we need another.

Quoted 7 lines
Quoted 5 lines

Documentation/devicetree/bindings/mtd/partitions/ubi.yaml line 63

Quoted 3 lines
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +3 -0
+            };
+
+            calibration: volume-1 {

Are 0 and 1 meaningful or just made up indexing?

Made up indexing. I need unique nodenames but @[0-9a-f] doesn't appply here.

Maybe use "volume-$volumename" or "volume-$volumeid" instead?

Rob

Reviewed-by on v1 1/1
#5 lore raw
In reply to Rafał Miłecki
Quoted 6 lines · Rafał Miłecki

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

UBI is often used on embedded devices to store UBI volumes with device configuration / calibration data. Such volumes may need to be documented and referenced for proper boot & setup.

Quoted 6 lines

Some examples:
1. U-Boot environment variables
2. Device calibration data
3. Default setup (e.g. initial password)

This is very useful and can replace the downstream hacks we are currently using for this purpose in OpenWrt.

Quoted 81 lines
---
 .../bindings/mtd/partitions/ubi.yaml          | 67 +++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 Documentation/devicetree/bindings/mtd/partitions/ubi.yaml
Documentation/devicetree/bindings/mtd/partitions/ubi.yaml new file +67 -0
new file mode 100644
index 000000000000..cd081f06d4cb
@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: GPL-2.0-only OR BSD-2-Clause
+%YAML 1.2
+---
+$id: http://devicetree.org/schemas/mtd/partitions/ubi.yaml#
+$schema: http://devicetree.org/meta-schemas/core.yaml#
+
+title: UBI (Unsorted Block Images) device
+
+description: |
+  UBI is a layer providing logical volumes (consisting of logical blocks) on top
+  of raw flash devices. It deals with low-level flash issues (bit-flips, bad
+  physical eraseblocks, wearing) providing a reliable data storage.
+
+  UBI device is built and stored in a single flash partition.
+
+  Some (usually embedded) devices use UBI volumes of specific names or indexes
+  to store setup / configuration data. This binding allows describing such
+  volumes so they can be identified and referenced by consumers.
+
+maintainers:
+  - Rafał Miłecki <[email protected]>
+
+allOf:
+  - $ref: partition.yaml#
+
+properties:
+  compatible:
+    const: ubi
+
+patternProperties:
+  "^volume-[0-9a-f]+$":
+    type: object
+    description: UBI volume
+    properties:
+      volume-name:
+        $ref: /schemas/types.yaml#/definitions/string
+      volume-id:
+        $ref: /schemas/types.yaml#/definitions/uint32
+    anyOf:
+      - required:
+          - volume-name
+      - required:
+          - volume-id
+
+unevaluatedProperties: false
+
+examples:
+  - |
+    partitions {
+        compatible = "fixed-partitions";
+        #address-cells = <1>;
+        #size-cells = <1>;
+
+        partition@0 {
+            compatible = "ubi";
+            reg = <0x0000000 0x1000000>;
+            label = "filesystem";
+
+            env: volume-0 {
+                volume-name = "u-boot-env";
+            };
+
+            calibration: volume-1 {
+                volume-id = <99>;
+            };
+        };
+    };
Signature · 1 line
2.34.1