Re: [PATCH 1/4] dt-bindings: mtd: Add YAML schemas for the generic NAND options

[Miquel Raynal <miquel.raynal@bootlin.com>]

Hi Maxime,

Maxime Ripard <maxime.ripard@bootlin.com> wrote on Mon,  1 Apr 2019
23:13:53 +0200:

> The NAND chips in MTD have a bunch of generic options that are needed in a
> device tree. Add a YAML schemas for those.
> 
> Signed-off-by: Maxime Ripard <maxime.ripard@bootlin.com>
> ---
>  Documentation/devicetree/bindings/mtd/nand-controller.yaml | 131 +++++++-
>  1 file changed, 131 insertions(+)
>  create mode 100644 Documentation/devicetree/bindings/mtd/nand-controller.yaml
> 
> diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
> new file mode 100644
> index 000000000000..05b1afb34972
> --- /dev/null
> +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml
> @@ -0,0 +1,131 @@
> +# SPDX-License-Identifier: (GPL-2.0+ OR BSD-2-Clause)
> +%YAML 1.2
> +---
> +$id: http://devicetree.org/schemas/mtd/nand-controller.yaml#
> +$schema: http://devicetree.org/meta-schemas/core.yaml#
> +
> +title: NAND Chip and NAND Controller Generic Binding
> +
> +maintainers:
> +  - Boris Brezillon <bbrezillon@kernel.org>

Unfortunately Boris is leaving.

> +  - Miquel Raynal <miquel.raynal@bootlin.com>
> +  - Richard Weinberger <richard@nod.at>

Is this really needed? There is already a section for that purpose in
MAINTAINERS.

> +
> +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.
> +
> +  The ECC strength and ECC step size properties define the correction
> +  capability of a controller. Together, they say a controller can
> +  correct {strength} bit errors per {size} bytes.

Not exactly. The driver knows what the controller's ECC engine is
capable of.

The NAND chip has some minimum requirements in terms of correction. One
may use a softer correction, at his own risks though. The controller
has a range of possible corrections too which are not part of the DT
neither. These two properties are set to force the user desired
correction.

> +
> +  The interpretation of these parameters is implementation-defined, so
> +  not all implementations must support all possible
> +  combinations. However, implementations are encouraged to further
> +  specify the value(s) they support.
> +
> +properties:
> +  $nodename:
> +    pattern: "^nand-controller(@.*)?"
> +
> +  "#address-cells":
> +    const: 1
> +
> +  "#size-cells":
> +    const: 0
> +
> +  ranges: true
> +
> +patternProperties:
> +  "^nand@[a-z0-9]$":
> +    properties:
> +      reg:
> +        description:
> +          Contains the native Ready/Busy IDs.
> +
> +      nand-ecc-mode:
> +        allOf:
> +          - $ref: /schemas/types.yaml#/definitions/string
> +          - enum: [ none, soft, hw, hw_syndrome, hw_oob_first, on-die ]
> +        description:
> +          Operation mode of the NAND ecc mode. soft_bch is deprecated
> +          and should be replaced by soft and nand-ecc-algo

What about "Desired ECC engine, either hardware (most of the time embedded in the NAND controller) or software correction (Linux will handle the calculations)."

> +
> +      nand-ecc-algo:
> +        allOf:
> +          - $ref: /schemas/types.yaml#/definitions/string
> +          - enum: [ hamming, bch, rs ]
> +        description:
> +          Algorithm of NAND ECC.

This is also a user desire more than a hardware limitation.
And this is not needed if nand-ecc-mode = "none" or when the ECC engine
does not handle more than one algorithm (ie. old engines only support
Hamming correction, if one chooses nand-ecc-mode = 'hw', there is no
need for a nand-ecc-algo property).

> +
> +      nand-bus-width:
> +        allOf:
> +          - $ref: /schemas/types.yaml#/definitions/uint32
> +          - enum: [ 8, 16 ]
> +          - default: 8
> +        description:
> +          Bus width to the NAND chip
> +
> +      nand-on-flash-bbt:
> +        $ref: /schemas/types.yaml#/definitions/flag
> +        description:
> +          Enable the on-flash Bad Block Table

It is not actually enabling anything, but Linux will search the device
for a a bad block table and if it does not find it, will create one and
update it.

> +
> +      nand-ecc-strength:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Number of bits to correct per ECC step.

Maximum number of bits that can be corrected per ECC step ?

> +
> +      nand-ecc-step-size:
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +        description:
> +          Number of data bytes covered by a single ECC step.
> +
> +      nand-ecc-maximize:
> +        $ref: /schemas/types.yaml#/definitions/flag
> +        description:
> +          Whether or not the ECC strength should be maximized. The
> +          maximum ECC strength is both controller and chip
> +          dependent. The controller side has to select the ECC config
> +          providing the best strength and taking the OOB area size

s/The controller side/The ECC engine/ ?

> +          constraint into account.  This is particularly useful when

Double space here?

> +          only the in-band area is used by the upper layers, and you
> +          want to make your NAND as reliable as possible.
> +
> +      nand-is-boot-medium:
> +        $ref: /schemas/types.yaml#/definitions/flag
> +        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.
> +
> +      nand-rb:
> +        $ref: /schemas/types.yaml#/definitions/uint32-array
> +        description:
> +          Contains the native Ready/Busy IDs.
> +
> +    required:
> +      - reg
> +
> +required:
> +  - "#address-cells"
> +  - "#size-cells"
> +
> +examples:
> +  - |
> +    nand-controller {
> +      #address-cells = <1>;
> +      #size-cells = <0>;
> +
> +      /* controller specific properties */
> +
> +      nand@0 {
> +        reg = <0>;
> +        nand-ecc-mode = "soft";
> +        nand-ecc-algo = "bch";
> +
> +        /* controller specific properties */
> +      };

What about partitions? Shall they be described here?

> +    };
> 
> base-commit: aa63f222af3e5991099ebcecca7c474d8285c7c4


Thanks for doing that!
Miquèl

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