On Tue, Apr 2, 2019 at 9:54 AM Maxime Ripard <maxime.ripard@xxxxxxxxxxx> 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@xxxxxxxxxxx> > > --- > > 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@xxxxxxxxxxx> > + - Richard Weinberger <richard@xxxxxx> > + > +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
