| Message ID | 74b8a52ce98b09d7906f988c107793a86c0c5f6b.1554216856.git-series.maxime.ripard@bootlin.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2,1/2] dt-bindings: mtd: Add YAML schemas for the generic NAND options | expand |
On Tue, Apr 2, 2019 at 9:54 AM 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> > > --- > > Changes from v1: > - Removed free form text binding > - Enhanced properties descriptions > - Fixed the SPDX license tag > - Added minimums for nand-ecc-strength and nand-ecc-step-size > - Removed Boris from the maintainers > --- > Documentation/devicetree/bindings/mtd/nand-controller.yaml | 141 +++++++- > Documentation/devicetree/bindings/mtd/nand.txt | 75 +---- > 2 files changed, 141 insertions(+), 75 deletions(-) > create mode 100644 Documentation/devicetree/bindings/mtd/nand-controller.yaml > delete mode 100644 Documentation/devicetree/bindings/mtd/nand.txt > > diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml > new file mode 100644 > index 000000000000..ebc7833ffc0c > --- /dev/null > +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml > @@ -0,0 +1,141 @@ > +# SPDX-License-Identifier: GPL-2.0 > +%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: > + - 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 user > + desires in terms of correction capability of a controller. Together, > + they request the ECC engine to 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]$": 'a-f' as this should be hex number. > + 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: > + Desired ECC engine, either hardware (most of the time > + embedded in the NAND controller) or software correction > + (Linux will handle the calculations). 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: > + Desired ECC algorithm. > + > + 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: > + 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. > + > + nand-ecc-strength: > + $ref: /schemas/types.yaml#/definitions/uint32 > + minimum: 1 While I wished this worked, these 2 have to be under 'allOf'. Unfortunately, this will also silently pass validation in json-schema. > + description: > + Maximum number of bits that can be corrected per ECC step. > + > + nand-ecc-step-size: > + $ref: /schemas/types.yaml#/definitions/uint32 > + minimum: 1 > + 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 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. > + > + 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 */ > + }; > + }; > diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt > deleted file mode 100644 > index e949c778e983..000000000000 > --- a/Documentation/devicetree/bindings/mtd/nand.txt > +++ /dev/null > @@ -1,75 +0,0 @@ > -* NAND chip and NAND controller generic binding > - > -NAND controller/NAND chip representation: > - > -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. > - > -Mandatory NAND controller properties: > -- #address-cells: depends on your controller. Should at least be 1 to > - encode the CS line id. > -- #size-cells: depends on your controller. Put zero unless you need a > - mapping between CS lines and dedicated memory regions > - > -Optional NAND controller properties > -- ranges: only needed if you need to define a mapping between CS lines and > - memory regions > - > -Optional NAND chip properties: > - > -- nand-ecc-mode : String, operation mode of the NAND ecc mode. > - Supported values are: "none", "soft", "hw", "hw_syndrome", > - "hw_oob_first", "on-die". > - Deprecated values: > - "soft_bch": use "soft" and nand-ecc-algo instead > -- nand-ecc-algo: string, algorithm of NAND ECC. > - Valid values are: "hamming", "bch", "rs". > -- nand-bus-width : 8 or 16 bus width if not present 8 > -- nand-on-flash-bbt: boolean to enable on flash bbt option if not present false > - > -- nand-ecc-strength: integer representing the number of bits to correct > - per ECC step. > - > -- nand-ecc-step-size: integer representing the number of data bytes > - that are covered by a single ECC step. > - > -- nand-ecc-maximize: boolean used to specify that you want to maximize ECC > - strength. 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: Whether 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: shall contain the native Ready/Busy ids. > - > -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. > - > -Example: > - > - 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: 1244df4693747552c8efba995f4ebc3b247536cf > -- > git-series 0.9.1
Hi Rob, On Tue, Apr 02, 2019 at 08:20:58PM -0500, Rob Herring wrote: > > + nand-ecc-strength: > > + $ref: /schemas/types.yaml#/definitions/uint32 > > + minimum: 1 > > While I wished this worked, these 2 have to be under 'allOf'. > Unfortunately, this will also silently pass validation in json-schema. Unfortunately, I'm not sure I fully get how the ref system is supposed to work yet. Can you elaborate a bit on why we should put the ref and whatever constraint we have in an allOf? Should we do the same in a separate schema that would reference another entire schema (like the second patch does with the first one)? Thanks! Maxime -- Maxime Ripard, Bootlin Embedded Linux and Kernel engineering https://bootlin.com
On Wed, Apr 3, 2019 at 2:35 AM Maxime Ripard <maxime.ripard@bootlin.com> wrote: > > Hi Rob, > > On Tue, Apr 02, 2019 at 08:20:58PM -0500, Rob Herring wrote: > > > + nand-ecc-strength: > > > + $ref: /schemas/types.yaml#/definitions/uint32 > > > + minimum: 1 > > > > While I wished this worked, these 2 have to be under 'allOf'. > > Unfortunately, this will also silently pass validation in json-schema. > > Unfortunately, I'm not sure I fully get how the ref system is supposed > to work yet. Can you elaborate a bit on why we should put the ref and > whatever constraint we have in an allOf? TL;DR is that is how sub-classing or extending schemas works. I think I read something at one point which explained why it doesn't work without allOf, but couldn't find it. Certainly, it seems like it should at first. > Should we do the same in a separate schema that would reference > another entire schema (like the second patch does with the first > one)? That would just split defining the type from the additional constraints. I prefer to keep the top-level 'allOf' including classes of devices. Rob
diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml new file mode 100644 index 000000000000..ebc7833ffc0c --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -0,0 +1,141 @@ +# SPDX-License-Identifier: GPL-2.0 +%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: + - 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 user + desires in terms of correction capability of a controller. Together, + they request the ECC engine to 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: + Desired ECC engine, either hardware (most of the time + embedded in the NAND controller) or software correction + (Linux will handle the calculations). 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: + Desired ECC algorithm. + + 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: + 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. + + nand-ecc-strength: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + description: + Maximum number of bits that can be corrected per ECC step. + + nand-ecc-step-size: + $ref: /schemas/types.yaml#/definitions/uint32 + minimum: 1 + 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 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. + + 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 */ + }; + }; diff --git a/Documentation/devicetree/bindings/mtd/nand.txt b/Documentation/devicetree/bindings/mtd/nand.txt deleted file mode 100644 index e949c778e983..000000000000 --- a/Documentation/devicetree/bindings/mtd/nand.txt +++ /dev/null @@ -1,75 +0,0 @@ -* NAND chip and NAND controller generic binding - -NAND controller/NAND chip representation: - -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. - -Mandatory NAND controller properties: -- #address-cells: depends on your controller. Should at least be 1 to - encode the CS line id. -- #size-cells: depends on your controller. Put zero unless you need a - mapping between CS lines and dedicated memory regions - -Optional NAND controller properties -- ranges: only needed if you need to define a mapping between CS lines and - memory regions - -Optional NAND chip properties: - -- nand-ecc-mode : String, operation mode of the NAND ecc mode. - Supported values are: "none", "soft", "hw", "hw_syndrome", - "hw_oob_first", "on-die". - Deprecated values: - "soft_bch": use "soft" and nand-ecc-algo instead -- nand-ecc-algo: string, algorithm of NAND ECC. - Valid values are: "hamming", "bch", "rs". -- nand-bus-width : 8 or 16 bus width if not present 8 -- nand-on-flash-bbt: boolean to enable on flash bbt option if not present false - -- nand-ecc-strength: integer representing the number of bits to correct - per ECC step. - -- nand-ecc-step-size: integer representing the number of data bytes - that are covered by a single ECC step. - -- nand-ecc-maximize: boolean used to specify that you want to maximize ECC - strength. 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: Whether 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: shall contain the native Ready/Busy ids. - -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. - -Example: - - 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> --- Changes from v1: - Removed free form text binding - Enhanced properties descriptions - Fixed the SPDX license tag - Added minimums for nand-ecc-strength and nand-ecc-step-size - Removed Boris from the maintainers --- Documentation/devicetree/bindings/mtd/nand-controller.yaml | 141 +++++++- Documentation/devicetree/bindings/mtd/nand.txt | 75 +---- 2 files changed, 141 insertions(+), 75 deletions(-) create mode 100644 Documentation/devicetree/bindings/mtd/nand-controller.yaml delete mode 100644 Documentation/devicetree/bindings/mtd/nand.txt base-commit: 1244df4693747552c8efba995f4ebc3b247536cf