[PATCH v3 1/3] dt-bindings: mtd: refactor NAND bindings and add nand-controller-legacy.yaml

* [PATCH v3 1/3] dt-bindings: mtd: refactor NAND bindings and add nand-controller-legacy.yaml
@ 2026-03-24 22:16 Frank Li
  2026-03-24 22:16 ` [PATCH v3 2/3] dt-bindings: mtd: gpmi-nand: ref to nand-controller-legacy.yaml Frank Li
                   ` (3 more replies)
  0 siblings, 4 replies; 5+ messages in thread
From: Frank Li @ 2026-03-24 22:16 UTC (permalink / raw)
  To: Miquel Raynal, Richard Weinberger, Vignesh Raghavendra,
	Rob Herring, Krzysztof Kozlowski, Conor Dooley,
	open list:MEMORY TECHNOLOGY DEVICES (MTD),
	open list:OPEN FIRMWARE AND FLATTENED DEVICE TREE BINDINGS,
	open list
  Cc: imx, Frank Li

The modern NAND controller binding requires NAND chips to be described as
child nodes of the controller, for example:

  nand-controller {
          ...
          nand@0 {
                  /* raw NAND chip properties */
          };
  };

However, many existing device trees place NAND chip properties directly
within the controller node because those controllers support only a single
chip. This layout is still widely used by older platforms and by other DT
consumers such as U-Boot. Migrating all existing users to the new layout
will take time.

Several kernel drivers, such as ams-delta.c, davinci_nand.c and
fsmc_nand.c, still expect the legacy layout where raw NAND properties are
defined in the controller node.

To support both layouts during the transition:

- Extract NAND chip-related properties into separate schemas
  (nand-property.yaml and raw-nand-property.yaml) from
  nand-chip.yaml and raw-nand-chip.yaml.
- Introduce nand-controller-legacy.yaml to allow both the
  legacy and modern layouts.
- Add a select condition in nand-controller.yaml to prevent
  node name pattern matching for fsl,* NAND controllers.

Keep compatibility with existing device trees while allowing gradual
migration to the modern binding structure.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---
change in v3
- use select: false
- s/under/within/
- s/property/properties/

two problem left:
1. about "^nand@[a-f0-9]$" in nand-controller-legacy.yaml

allow dts to do mirgeration from legacy layout to modern layouts for different
boards, which use the same compatible string.

2. ref to mtd.yaml

mtd.yaml force node name as flash@, nand@  ..., but here is parent node
name is nand-controller@.  Only two properties, duplicate these should be
simple and clean enough now.

change in v2
- none

change dts layout break boot
https://lore.kernel.org/imx/177281063848.253518.12995342124719933118.b4-ty@nxp.com/T/#t
---
 .../devicetree/bindings/mtd/nand-chip.yaml    | 46 +-----------
 ...oller.yaml => nand-controller-legacy.yaml} | 46 +++++-------
 .../bindings/mtd/nand-controller.yaml         |  2 +
 .../{nand-chip.yaml => nand-property.yaml}    | 14 +---
 .../bindings/mtd/raw-nand-chip.yaml           | 74 +------------------
 ...-nand-chip.yaml => raw-nand-property.yaml} | 15 +---
 6 files changed, 27 insertions(+), 170 deletions(-)
 copy Documentation/devicetree/bindings/mtd/{nand-controller.yaml => nand-controller-legacy.yaml} (69%)
 copy Documentation/devicetree/bindings/mtd/{nand-chip.yaml => nand-property.yaml} (89%)
 copy Documentation/devicetree/bindings/mtd/{raw-nand-chip.yaml => raw-nand-property.yaml} (94%)

diff --git a/Documentation/devicetree/bindings/mtd/nand-chip.yaml b/Documentation/devicetree/bindings/mtd/nand-chip.yaml
index 609d4a4ddd80e..8800d1d072665 100644
--- a/Documentation/devicetree/bindings/mtd/nand-chip.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-chip.yaml
@@ -11,6 +11,7 @@ maintainers:
 
 allOf:
   - $ref: mtd.yaml#
+  - $ref: nand-property.yaml
 
 description: |
   This file covers the generic description of a NAND chip. It implies that the
@@ -22,51 +23,6 @@ properties:
     description:
       Contains the chip-select IDs.
 
-  nand-ecc-engine:
-    description: |
-      A phandle on the hardware ECC engine if any. There are
-      basically three possibilities:
-      1/ The ECC engine is part of the NAND controller, in this
-      case the phandle should reference the parent node.
-      2/ The ECC engine is part of the NAND part (on-die), in this
-      case the phandle should reference the node itself.
-      3/ The ECC engine is external, in this case the phandle should
-      reference the specific ECC engine node.
-    $ref: /schemas/types.yaml#/definitions/phandle
-
-  nand-use-soft-ecc-engine:
-    description: Use a software ECC engine.
-    type: boolean
-
-  nand-no-ecc-engine:
-    description: Do not use any ECC correction.
-    type: boolean
-
-  nand-ecc-algo:
-    description:
-      Desired ECC algorithm.
-    $ref: /schemas/types.yaml#/definitions/string
-    enum: [hamming, bch, rs]
-
-  nand-ecc-strength:
-    description:
-      Maximum number of bits that can be corrected per ECC step.
-    $ref: /schemas/types.yaml#/definitions/uint32
-    minimum: 1
-
-  nand-ecc-step-size:
-    description:
-      Number of data bytes covered by a single ECC step.
-    $ref: /schemas/types.yaml#/definitions/uint32
-    minimum: 1
-
-  secure-regions:
-    description:
-      Regions in the NAND chip which are protected using a secure element
-      like Trustzone. This property contains the start address and size of
-      the secure regions present.
-    $ref: /schemas/types.yaml#/definitions/uint64-matrix
-
 required:
   - reg
 
diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller-legacy.yaml
similarity index 69%
copy from Documentation/devicetree/bindings/mtd/nand-controller.yaml
copy to Documentation/devicetree/bindings/mtd/nand-controller-legacy.yaml
index 28167c0cf2719..d6e612413df19 100644
--- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-controller-legacy.yaml
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
 %YAML 1.2
 ---
-$id: http://devicetree.org/schemas/mtd/nand-controller.yaml#
+$id: http://devicetree.org/schemas/mtd/nand-controller-legacy.yaml#
 $schema: http://devicetree.org/meta-schemas/core.yaml#
 
 title: NAND Controller Common Properties
@@ -10,21 +10,22 @@ maintainers:
   - Miquel Raynal <miquel.raynal@bootlin.com>
   - Richard Weinberger <richard@nod.at>
 
-description: |
+description: >
   The NAND controller should be represented with its own DT node, and
   all NAND chips attached to this controller should be defined as
   children nodes of the NAND controller. This representation should be
   enforced even for simple controllers supporting only one chip.
 
+  This is only for legacy nand controller, new controller should use
+  nand-controller.yaml
+
 properties:
-  $nodename:
-    pattern: "^nand-controller(@.*)?"
 
   "#address-cells":
     const: 1
 
   "#size-cells":
-    const: 0
+    enum: [0, 1]
 
   ranges: true
 
@@ -39,33 +40,26 @@ properties:
     minItems: 1
     maxItems: 8
 
+  partitions:
+    type: object
+
+    required:
+      - compatible
+
 patternProperties:
   "^nand@[a-f0-9]$":
     type: object
     $ref: raw-nand-chip.yaml#
 
-required:
-  - "#address-cells"
-  - "#size-cells"
+  "^partition@[0-9a-f]+$":
+    type: object
+    $ref: /schemas/mtd/partitions/partition.yaml#/$defs/partition-node
+    deprecated: true
+
+allOf:
+  - $ref: raw-nand-property.yaml#
+  - $ref: nand-property.yaml#
 
 # This is a generic file other binding inherit from and extend
 additionalProperties: true
 
-examples:
-  - |
-    nand-controller {
-      #address-cells = <1>;
-      #size-cells = <0>;
-      cs-gpios = <0>, <&gpioA 1>; /* A single native CS is available */
-
-      /* controller specific properties */
-
-      nand@0 {
-        reg = <0>; /* Native CS */
-        /* NAND chip specific properties */
-      };
-
-      nand@1 {
-        reg = <1>; /* GPIO CS */
-      };
-    };
diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
index 28167c0cf2719..0aa61d5fa50b1 100644
--- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
@@ -16,6 +16,8 @@ description: |
   children nodes of the NAND controller. This representation should be
   enforced even for simple controllers supporting only one chip.
 
+select: false
+
 properties:
   $nodename:
     pattern: "^nand-controller(@.*)?"
diff --git a/Documentation/devicetree/bindings/mtd/nand-chip.yaml b/Documentation/devicetree/bindings/mtd/nand-property.yaml
similarity index 89%
copy from Documentation/devicetree/bindings/mtd/nand-chip.yaml
copy to Documentation/devicetree/bindings/mtd/nand-property.yaml
index 609d4a4ddd80e..55488a4b15487 100644
--- a/Documentation/devicetree/bindings/mtd/nand-chip.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-property.yaml
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
 %YAML 1.2
 ---
-$id: http://devicetree.org/schemas/mtd/nand-chip.yaml#
+$id: http://devicetree.org/schemas/mtd/nand-property.yaml#
 $schema: http://devicetree.org/meta-schemas/core.yaml#
 
 title: NAND Chip Common Properties
@@ -9,19 +9,12 @@ title: NAND Chip Common Properties
 maintainers:
   - Miquel Raynal <miquel.raynal@bootlin.com>
 
-allOf:
-  - $ref: mtd.yaml#
-
 description: |
-  This file covers the generic description of a NAND chip. It implies that the
+  This file covers the generic properties of a NAND chip. It implies that the
   bus interface should not be taken into account: both raw NAND devices and
   SPI-NAND devices are concerned by this description.
 
 properties:
-  reg:
-    description:
-      Contains the chip-select IDs.
-
   nand-ecc-engine:
     description: |
       A phandle on the hardware ECC engine if any. There are
@@ -67,8 +60,5 @@ properties:
       the secure regions present.
     $ref: /schemas/types.yaml#/definitions/uint64-matrix
 
-required:
-  - reg
-
 # This file can be referenced by more specific devices (like spi-nands)
 additionalProperties: true
diff --git a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
index 092448d7bfc5c..792de3e3c6eee 100644
--- a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
+++ b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
@@ -11,6 +11,7 @@ maintainers:
 
 allOf:
   - $ref: nand-chip.yaml#
+  - $ref: raw-nand-property.yaml#
 
 description: |
   The ECC strength and ECC step size properties define the user
@@ -31,79 +32,6 @@ properties:
     description:
       Contains the chip-select IDs.
 
-  nand-ecc-placement:
-    description:
-      Location of the ECC bytes. This location is unknown by default
-      but can be explicitly set to "oob", if all ECC bytes are
-      known to be stored in the OOB area, or "interleaved" if ECC
-      bytes will be interleaved with regular data in the main area.
-    $ref: /schemas/types.yaml#/definitions/string
-    enum: [ oob, interleaved ]
-    deprecated: true
-
-  nand-ecc-mode:
-    description:
-      Legacy ECC configuration mixing the ECC engine choice and
-      configuration.
-    $ref: /schemas/types.yaml#/definitions/string
-    enum: [none, soft, soft_bch, hw, hw_syndrome, on-die]
-    deprecated: true
-
-  nand-bus-width:
-    description:
-      Bus width to the NAND chip
-    $ref: /schemas/types.yaml#/definitions/uint32
-    enum: [8, 16]
-    default: 8
-
-  nand-on-flash-bbt:
-    description:
-      With this property, the OS will search the device for a Bad
-      Block Table (BBT). If not found, it will create one, reserve
-      a few blocks at the end of the device to store it and update
-      it as the device ages. Otherwise, the out-of-band area of a
-      few pages of all the blocks will be scanned at boot time to
-      find Bad Block Markers (BBM). These markers will help to
-      build a volatile BBT in RAM.
-    $ref: /schemas/types.yaml#/definitions/flag
-
-  nand-ecc-maximize:
-    description:
-      Whether or not the ECC strength should be maximized. The
-      maximum ECC strength is both controller and chip
-      dependent. The ECC engine has to select the ECC config
-      providing the best strength and taking the OOB area size
-      constraint into account. This is particularly useful when
-      only the in-band area is used by the upper layers, and you
-      want to make your NAND as reliable as possible.
-    $ref: /schemas/types.yaml#/definitions/flag
-
-  nand-is-boot-medium:
-    description:
-      Whether or not the NAND chip is a boot medium. Drivers might
-      use this information to select ECC algorithms supported by
-      the boot ROM or similar restrictions.
-    $ref: /schemas/types.yaml#/definitions/flag
-
-  nand-rb:
-    description:
-      Contains the native Ready/Busy IDs.
-    $ref: /schemas/types.yaml#/definitions/uint32-array
-
-  rb-gpios:
-    description:
-      Contains one or more GPIO descriptor (the numper of descriptor
-      depends on the number of R/B pins exposed by the flash) for the
-      Ready/Busy pins. Active state refers to the NAND ready state and
-      should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
-
-  wp-gpios:
-    description:
-      Contains one GPIO descriptor for the Write Protect pin.
-      Active state refers to the NAND Write Protect state and should be
-      set to GPIOD_ACTIVE_LOW unless the signal is inverted.
-    maxItems: 1
-
 required:
   - reg
 
diff --git a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml b/Documentation/devicetree/bindings/mtd/raw-nand-property.yaml
similarity index 94%
copy from Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
copy to Documentation/devicetree/bindings/mtd/raw-nand-property.yaml
index 092448d7bfc5c..f853b72426c43 100644
--- a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml
+++ b/Documentation/devicetree/bindings/mtd/raw-nand-property.yaml
@@ -1,7 +1,7 @@
 # SPDX-License-Identifier: (GPL-2.0-only OR BSD-2-Clause)
 %YAML 1.2
 ---
-$id: http://devicetree.org/schemas/mtd/raw-nand-chip.yaml#
+$id: http://devicetree.org/schemas/mtd/raw-nand-property.yaml#
 $schema: http://devicetree.org/meta-schemas/core.yaml#
 
 title: Raw NAND Chip Common Properties
@@ -9,9 +9,6 @@ title: Raw NAND Chip Common Properties
 maintainers:
   - Miquel Raynal <miquel.raynal@bootlin.com>
 
-allOf:
-  - $ref: nand-chip.yaml#
-
 description: |
   The ECC strength and ECC step size properties define the user
   desires in terms of correction capability of a controller. Together,
@@ -24,13 +21,6 @@ description: |
   specify the value(s) they support.
 
 properties:
-  $nodename:
-    pattern: "^nand@[a-f0-9]$"
-
-  reg:
-    description:
-      Contains the chip-select IDs.
-
   nand-ecc-placement:
     description:
       Location of the ECC bytes. This location is unknown by default
@@ -104,8 +94,5 @@ properties:
       set to GPIOD_ACTIVE_LOW unless the signal is inverted.
     maxItems: 1
 
-required:
-  - reg
-
 # This is a generic file other binding inherit from and extend
 additionalProperties: true
-- 
2.43.0


______________________________________________________
Linux MTD discussion mailing list
http://lists.infradead.org/mailman/listinfo/linux-mtd/

^ permalink raw reply related	[flat|nested] 5+ messages in thread