| Message ID | 75ad3b89e4a6f8ad5bc414c3dccbb1f99361495a.1554153146.git-series.maxime.ripard@bootlin.com |
|---|---|
| State | Changes Requested |
| Delegated to: | Miquel Raynal |
| Headers | show |
| Series | [1/4] dt-bindings: mtd: Add YAML schemas for the generic NAND options | expand |
On Mon, Apr 1, 2019 at 4:14 PM Maxime Ripard <maxime.ripard@bootlin.com> wrote: > > 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> > + - Miquel Raynal <miquel.raynal@bootlin.com> > + - Richard Weinberger <richard@nod.at> > + > +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. > + > + 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 'ranges' should not be here as nand chip addresses are not translatable. > + > +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 > + > + nand-ecc-algo: > + allOf: > + - $ref: /schemas/types.yaml#/definitions/string > + - enum: [ hamming, bch, rs ] > + description: > + Algorithm of NAND ECC. > + > + 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 > + > + nand-ecc-strength: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: > + Number of bits to correct per ECC step. Is there a range we can define here? Certainly there's a minimum values of at least 1. > + > + nand-ecc-step-size: > + $ref: /schemas/types.yaml#/definitions/uint32 > + description: > + Number of data bytes covered by a single ECC step. Same here. > + > + 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 > + 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. > + > + 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 */ > + }; > + }; > > base-commit: aa63f222af3e5991099ebcecca7c474d8285c7c4 > -- > git-series 0.9.1
Hi Rob, On Mon, Apr 01, 2019 at 08:58:49PM -0500, Rob Herring wrote: > On Mon, Apr 1, 2019 at 4:14 PM Maxime Ripard <maxime.ripard@bootlin.com> wrote: > > > > 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> > > + - Miquel Raynal <miquel.raynal@bootlin.com> > > + - Richard Weinberger <richard@nod.at> > > + > > +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. > > + > > + 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 > > 'ranges' should not be here as nand chip addresses are not translatable. Apparently, some are. It was part of the original binding, hence why it's there. https://github.com/torvalds/linux/blob/master/Documentation/devicetree/bindings/mtd/nand.txt#L16 > > + > > +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 > > + > > + nand-ecc-algo: > > + allOf: > > + - $ref: /schemas/types.yaml#/definitions/string > > + - enum: [ hamming, bch, rs ] > > + description: > > + Algorithm of NAND ECC. > > + > > + 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 > > + > > + nand-ecc-strength: > > + $ref: /schemas/types.yaml#/definitions/uint32 > > + description: > > + Number of bits to correct per ECC step. > > Is there a range we can define here? Certainly there's a minimum > values of at least 1. It doesn't look like there is from a quick grep. The DT seems to be in the 4 - 32 range, but I'm not sure if it would make sense to have something higher. I'll let Miquel and Boris comment. > > + > > + nand-ecc-step-size: > > + $ref: /schemas/types.yaml#/definitions/uint32 > > + description: > > + Number of data bytes covered by a single ECC step. > > Same here. Thanks! Maxime -- Maxime Ripard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
Hi Maxime, > > > + nand-ecc-strength: > > > + $ref: /schemas/types.yaml#/definitions/uint32 > > > + description: > > > + Number of bits to correct per ECC step. > > > > Is there a range we can define here? Certainly there's a minimum > > values of at least 1. > > It doesn't look like there is from a quick grep. The DT seems to be in > the 4 - 32 range, but I'm not sure if it would make sense to have > something higher. > > I'll let Miquel and Boris comment. A value of zero would not have any meaning IMHO. 1 is definitely the minimum (ECC Hamming algorithm). There is technically no maximum. Thanks, Miquèl
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
On Tue, Apr 2, 2019 at 3:19 AM Miquel Raynal <miquel.raynal@bootlin.com> wrote: > > 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. Yes, because MAINTAINERS is a kernel file and bindings are somewhat independent. And I found most binding files don't have a maintainer (other than me as default). If we ever go to per subsystem/directory MAiNTAiNERS files, then we can easily generate one from bindings for the kernel. Rob
Hi Rob, Rob Herring <robh+dt@kernel.org> wrote on Tue, 2 Apr 2019 03:49:41 -0500: > On Tue, Apr 2, 2019 at 3:19 AM Miquel Raynal <miquel.raynal@bootlin.com> wrote: > > > > 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. > > Yes, because MAINTAINERS is a kernel file and bindings are somewhat > independent. And I found most binding files don't have a maintainer > (other than me as default). I know DT and bindings are a bit specific but they are still in the kernel sources and right now in MAINTAINERS, under the MTD subsystem entry there is: F: Documentation/devicetree/bindings/mtd/ What I am saying is that this list is a duplicate and people will simply forget about it so it won't be updated naturally. > > If we ever go to per subsystem/directory MAiNTAiNERS files, then we > can easily generate one from bindings for the kernel. > > Rob Thanks, Miquèl
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> + - Miquel Raynal <miquel.raynal@bootlin.com> + - Richard Weinberger <richard@nod.at> + +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. + + 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 + + nand-ecc-algo: + allOf: + - $ref: /schemas/types.yaml#/definitions/string + - enum: [ hamming, bch, rs ] + description: + Algorithm of NAND ECC. + + 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 + + nand-ecc-strength: + $ref: /schemas/types.yaml#/definitions/uint32 + description: + Number of bits to correct 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 + 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. + + 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 */ + }; + };
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 base-commit: aa63f222af3e5991099ebcecca7c474d8285c7c4