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

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

[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
under 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 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         | 11 +++
 .../{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, 36 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..81d4ffc3fc1fa 100644
--- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml
+++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
@@ -16,6 +16,17 @@ description: |
   children nodes of the NAND controller. This representation should be
   enforced even for simple controllers supporting only one chip.
 
+select:
+  allOf:
+    - properties:
+        $nodename:
+          pattern: "^nand-controller(@.*)?"
+    - not:
+        properties:
+          compatible:
+            contains:
+              pattern: "^fsl,"
+
 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..5bbc93e506fd8 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 property 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

[PATCH v2 2/3] dt-bindings: mtd: gpmi-nand: ref to nand-controller-legacy.yaml

[Frank Li]

Ref to nand-controller-legacy.yaml instead nand-controller.yaml to allow
legacy DT layout.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---
change in v2
- none
---
 Documentation/devicetree/bindings/mtd/gpmi-nand.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml b/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml
index 0badb2e978c74..adb684e3207cd 100644
--- a/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml
+++ b/Documentation/devicetree/bindings/mtd/gpmi-nand.yaml
@@ -101,7 +101,7 @@ required:
 unevaluatedProperties: false
 
 allOf:
-  - $ref: nand-controller.yaml
+  - $ref: nand-controller-legacy.yaml
 
   - if:
       properties:
-- 
2.43.0

[PATCH v2 3/3] dt-bindings: mtd: mxc-nand: add missing compatible string and ref to nand-controller-legacy.yaml

[Frank Li]

Add compatible string fsl,imx51-nand, fsl,imx53-nand and fsl,imx35-nand.

Add missinge properties dmas and dma-names.

Change reg's maxItems to 2 because i.MX53 have addition NAND flash internal
buffer space.

Change ref to nand-controller-legacy.yaml allow legacy DT layout.

Signed-off-by: Frank Li <Frank.Li@nxp.com>
---
Changes in v2:
- use items for regs.
---
 .../devicetree/bindings/mtd/mxc-nand.yaml     | 20 +++++++++++++++++--
 1 file changed, 18 insertions(+), 2 deletions(-)

diff --git a/Documentation/devicetree/bindings/mtd/mxc-nand.yaml b/Documentation/devicetree/bindings/mtd/mxc-nand.yaml
index 433ae5727ad85..fbaff7d3eda85 100644
--- a/Documentation/devicetree/bindings/mtd/mxc-nand.yaml
+++ b/Documentation/devicetree/bindings/mtd/mxc-nand.yaml
@@ -10,7 +10,7 @@ maintainers:
   - Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
 
 allOf:
-  - $ref: nand-controller.yaml
+  - $ref: nand-controller-legacy.yaml
 
 properties:
   compatible:
@@ -18,12 +18,21 @@ properties:
       - enum:
           - fsl,imx25-nand
           - fsl,imx27-nand
+          - fsl,imx51-nand
+          - fsl,imx53-nand
+      - items:
+          - enum:
+              - fsl,imx35-nand
+          - const: fsl,imx25-nand
       - items:
           - enum:
               - fsl,imx31-nand
           - const: fsl,imx27-nand
   reg:
-    maxItems: 1
+    minItems: 1
+    items:
+      - description: IP register space
+      - description: Nand flash internal buffer space
 
   interrupts:
     maxItems: 1
@@ -31,6 +40,13 @@ properties:
   clocks:
     maxItems: 1
 
+  dmas:
+    maxItems: 1
+
+  dma-names:
+    items:
+      - const: rx-tx
+
 required:
   - compatible
   - reg
-- 
2.43.0

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

[Rob Herring]

On Mon, Mar 09, 2026 at 04:03:42PM -0400, Frank Li wrote:
> 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
> under the controller node because those controllers support only a single

s/under/within/

> 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 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         | 11 +++
>  .../{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, 36 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#

Shouldn't this be removed? The main thing is legacy bindings don't have 
these nand nodes.

>  
> -required:
> -  - "#address-cells"
> -  - "#size-cells"
> +  "^partition@[0-9a-f]+$":
> +    type: object
> +    $ref: /schemas/mtd/partitions/partition.yaml#/$defs/partition-node
> +    deprecated: true

Is there any .dts (in tree) with partition nodes not under 'partitions' 
node. Maybe this can be omitted.

Also, mtd.yaml covers alot of this. Can we just reference it?

> +
> +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..81d4ffc3fc1fa 100644
> --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml
> +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
> @@ -16,6 +16,17 @@ description: |
>    children nodes of the NAND controller. This representation should be
>    enforced even for simple controllers supporting only one chip.
>  
> +select:
> +  allOf:
> +    - properties:
> +        $nodename:
> +          pattern: "^nand-controller(@.*)?"
> +    - not:
> +        properties:
> +          compatible:
> +            contains:
> +              pattern: "^fsl,"

I would just do 'select: false' and make sure all non-legacy 
controller bindings reference nand-controller.yaml. 

> +
>  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..5bbc93e506fd8 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 property of a NAND chip. It implies that the

s/property/properties/

>    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
> 

Re: [PATCH v2 2/3] dt-bindings: mtd: gpmi-nand: ref to nand-controller-legacy.yaml

[Rob Herring (Arm)]

On Mon, 09 Mar 2026 16:03:43 -0400, Frank Li wrote:
> Ref to nand-controller-legacy.yaml instead nand-controller.yaml to allow
> legacy DT layout.
> 
> Signed-off-by: Frank Li <Frank.Li@nxp.com>
> ---
> change in v2
> - none
> ---
>  Documentation/devicetree/bindings/mtd/gpmi-nand.yaml | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 

Reviewed-by: Rob Herring (Arm) <robh@kernel.org>

Re: [PATCH v2 3/3] dt-bindings: mtd: mxc-nand: add missing compatible string and ref to nand-controller-legacy.yaml

[Rob Herring (Arm)]

On Mon, 09 Mar 2026 16:03:44 -0400, Frank Li wrote:
> Add compatible string fsl,imx51-nand, fsl,imx53-nand and fsl,imx35-nand.
> 
> Add missinge properties dmas and dma-names.
> 
> Change reg's maxItems to 2 because i.MX53 have addition NAND flash internal
> buffer space.
> 
> Change ref to nand-controller-legacy.yaml allow legacy DT layout.
> 
> Signed-off-by: Frank Li <Frank.Li@nxp.com>
> ---
> Changes in v2:
> - use items for regs.
> ---
>  .../devicetree/bindings/mtd/mxc-nand.yaml     | 20 +++++++++++++++++--
>  1 file changed, 18 insertions(+), 2 deletions(-)
> 

Reviewed-by: Rob Herring (Arm) <robh@kernel.org>

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

[Frank Li]

> > +select:
> > +  allOf:
> > +    - properties:
> > +        $nodename:
> > +          pattern: "^nand-controller(@.*)?"
> > +    - not:
> > +        properties:
> > +          compatible:
> > +            contains:
> > +              pattern: "^fsl,"
> 
> I would just do 'select: false' and make sure all non-legacy
> controller bindings reference nand-controller.yaml.

I found some controller have not compatible string, such as
arch/arm/boot/dts/broadcom/bcm4708-luxul-xwc-1000.dts

I am not sure if it is wrong. So I have not direct use "select false".

Is it okay omit these dts?

Frank
> 
> > 2.43.0
> >

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

[Rob Herring]

On Mon, Mar 16, 2026 at 9:37 AM Frank Li <frank.li@nxp.com> wrote:
>
> > > +select:
> > > +  allOf:
> > > +    - properties:
> > > +        $nodename:
> > > +          pattern: "^nand-controller(@.*)?"
> > > +    - not:
> > > +        properties:
> > > +          compatible:
> > > +            contains:
> > > +              pattern: "^fsl,"
> >
> > I would just do 'select: false' and make sure all non-legacy
> > controller bindings reference nand-controller.yaml.
>
> I found some controller have not compatible string, such as
> arch/arm/boot/dts/broadcom/bcm4708-luxul-xwc-1000.dts

It's there somewhere though the source structure makes it hard to
find. Converting the dtb back to flat dts gives this:

        nand-controller@18028000 {
                compatible = "brcm,nand-iproc", "brcm,brcmnand-v6.1",
"brcm,brcmnand";
                reg = <0x18028000 0x600 0x1811a408 0x600 0x18028f00 0x20>;
                reg-names = "nand", "iproc-idm", "iproc-ext";
                interrupts = <0x00 0x44 0x04>;
                #address-cells = <0x01>;
                #size-cells = <0x00>;
                brcm,nand-has-wp;

                nand@0 {
                        compatible = "brcm,nandcs";
                        reg = <0x00>;
                        #address-cells = <0x01>;
                        #size-cells = <0x01>;
                        nand-ecc-algo = "bch";
                        nand-ecc-strength = <0x08>;
                        nand-ecc-step-size = <0x200>;

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

                                partition@0 {
                                        label = "ubi";
                                        reg = <0x00 0x8000000>;
                                };
                        };
                };
        };


>
> I am not sure if it is wrong. So I have not direct use "select false".
>
> Is it okay omit these dts?

Even if there are cases, yes.

Rob

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

[Frank Li]

On Fri, Mar 13, 2026 at 06:34:50PM -0500, Rob Herring wrote:
> > --- 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#
>
> Shouldn't this be removed? The main thing is legacy bindings don't have
> these nand nodes.

Support both to provide migration path. Need support both to make existing
boards migration to new layout.

The i.MX8's old boards use old layer out. but new boards, we expect use new
layout, but they use the same compatible string.


>
> >
> > -required:
> > -  - "#address-cells"
> > -  - "#size-cells"
> > +  "^partition@[0-9a-f]+$":
> > +    type: object
> > +    $ref: /schemas/mtd/partitions/partition.yaml#/$defs/partition-node
> > +    deprecated: true
>
> Is there any .dts (in tree) with partition nodes not under 'partitions'
> node. Maybe this can be omitted.

arch/arm/boot/dts/nxp/imx/imx27-apf27.dts

Frank