| Message ID | 20230619092916.3028470-3-miquel.raynal@bootlin.com |
|---|---|
| State | Accepted |
| Commit | 46721a1c9f829fe934eb1ec03e19b9e2896b995a |
| Headers | show |
| Series | None | expand |
Hi Rob, robh@kernel.org wrote on Mon, 19 Jun 2023 16:50:38 -0600: > On Mon, Jun 19, 2023 at 11:29:01AM +0200, Miquel Raynal wrote: > > In an effort to constrain as much as we can the existing binding, we > > want to add "unevaluatedProperties: false" in all the NAND chip > > descriptions part of NAND controller bindings. But in order to do that > > properly, we also need to reference a file which contains all the > > "allowed" properties. Right now this file is nand-chip.yaml but in > > practice raw NAND controllers may use additional properties in their > > NAND chip children node. These properties are listed under > > nand-controller.yaml, which makes the "unevaluatedProperties" checks > > fail while the description are valid. We need to move these NAND chip > > related properties into another file, because we do not want to pollute > > nand-chip.yaml which is also referenced by eg. SPI-NAND devices. > > > > Let's create a raw-nand-chip.yaml file to reference all the properties a > > raw NAND chip description can contain. The chain of inheritance becomes: > > nand-controller.yaml <- raw-nand-chip.yaml > > raw-nand-chip.yaml <- nand-chip.yaml > > spi-nand.yaml <- nand-chip.yaml > > > > Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com> > > Reviewed-by: Rob Herring <robh@kernel.org> > > --- > > .../bindings/mtd/nand-controller.yaml | 85 +-------------- > > .../bindings/mtd/raw-nand-chip.yaml | 102 ++++++++++++++++++ > > 2 files changed, 104 insertions(+), 83 deletions(-) > > create mode 100644 Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml > > > > diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml > > index f70a32d2d9d4..83a4fe4cc29d 100644 > > --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml > > +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml > > @@ -16,16 +16,6 @@ description: | > > 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(@.*)?" > > @@ -51,79 +41,8 @@ properties: > > > > patternProperties: > > "^nand@[a-f0-9]$": > > - $ref: nand-chip.yaml# > > - > > - properties: > > - reg: > > - 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 ] > > - > > - 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 > > + type: object > > + $ref: raw-nand-chip.yaml# > > > > required: > > - "#address-cells" > > diff --git a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml > > new file mode 100644 > > index 000000000000..2caa6a9a73d3 > > --- /dev/null > > +++ b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml > > @@ -0,0 +1,102 @@ > > +# SPDX-License-Identifier: GPL-2.0 > > Should be dual licensed like the original. The original is not dual licensed, so I'll send a fix. Thanks, Miquèl
On Mon, 2023-06-19 at 09:29:01 UTC, Miquel Raynal wrote: > In an effort to constrain as much as we can the existing binding, we > want to add "unevaluatedProperties: false" in all the NAND chip > descriptions part of NAND controller bindings. But in order to do that > properly, we also need to reference a file which contains all the > "allowed" properties. Right now this file is nand-chip.yaml but in > practice raw NAND controllers may use additional properties in their > NAND chip children node. These properties are listed under > nand-controller.yaml, which makes the "unevaluatedProperties" checks > fail while the description are valid. We need to move these NAND chip > related properties into another file, because we do not want to pollute > nand-chip.yaml which is also referenced by eg. SPI-NAND devices. > > Let's create a raw-nand-chip.yaml file to reference all the properties a > raw NAND chip description can contain. The chain of inheritance becomes: > nand-controller.yaml <- raw-nand-chip.yaml > raw-nand-chip.yaml <- nand-chip.yaml > spi-nand.yaml <- nand-chip.yaml > > Signed-off-by: Miquel Raynal <miquel.raynal@bootlin.com> > Reviewed-by: Rob Herring <robh@kernel.org> Applied to https://git.kernel.org/pub/scm/linux/kernel/git/mtd/linux.git nand/next. Miquel
diff --git a/Documentation/devicetree/bindings/mtd/nand-controller.yaml b/Documentation/devicetree/bindings/mtd/nand-controller.yaml index f70a32d2d9d4..83a4fe4cc29d 100644 --- a/Documentation/devicetree/bindings/mtd/nand-controller.yaml +++ b/Documentation/devicetree/bindings/mtd/nand-controller.yaml @@ -16,16 +16,6 @@ description: | 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(@.*)?" @@ -51,79 +41,8 @@ properties: patternProperties: "^nand@[a-f0-9]$": - $ref: nand-chip.yaml# - - properties: - reg: - 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 ] - - 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 + type: object + $ref: raw-nand-chip.yaml# required: - "#address-cells" diff --git a/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml new file mode 100644 index 000000000000..2caa6a9a73d3 --- /dev/null +++ b/Documentation/devicetree/bindings/mtd/raw-nand-chip.yaml @@ -0,0 +1,102 @@ +# SPDX-License-Identifier: GPL-2.0 +%YAML 1.2 +--- +$id: http://devicetree.org/schemas/mtd/raw-nand-chip.yaml# +$schema: http://devicetree.org/meta-schemas/core.yaml# + +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, + they request the ECC engine to correct {strength} bit errors per + {size} bytes for a particular raw NAND chip. + + 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@[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 + 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 ] + + 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 + +# This is a generic file other binding inherit from and extend +additionalProperties: true