Documentation/devicetree/bindings/mtd/nand-controller.yaml

   1 # SPDX-License-Identifier: GPL-2.0
   2 %YAML 1.2
   3 ---
   4 $id: http://devicetree.org/schemas/mtd/nand-controller.yaml#
   5 $schema: http://devicetree.org/meta-schemas/core.yaml#
   6
   7 title: NAND Chip and NAND Controller Generic Binding
   8
   9 maintainers:
  10   - Miquel Raynal <miquel.raynal@bootlin.com>
  11   - Richard Weinberger <richard@nod.at>
  12
  13 description: |
  14   The NAND controller should be represented with its own DT node, and
  15   all NAND chips attached to this controller should be defined as
  16   children nodes of the NAND controller. This representation should be
  17   enforced even for simple controllers supporting only one chip.
  18
  19   The ECC strength and ECC step size properties define the user
  20   desires in terms of correction capability of a controller. Together,
  21   they request the ECC engine to correct {strength} bit errors per
  22   {size} bytes.
  23
  24   The interpretation of these parameters is implementation-defined, so
  25   not all implementations must support all possible
  26   combinations. However, implementations are encouraged to further
  27   specify the value(s) they support.
  28
  29 properties:
  30   $nodename:
  31     pattern: "^nand-controller(@.*)?"
  32
  33   "#address-cells":
  34     const: 1
  35
  36   "#size-cells":
  37     const: 0
  38
  39   ranges: true
  40
  41 patternProperties:
  42   "^nand@[a-f0-9]$":
  43     type: object
  44     properties:
  45       reg:
  46         description:
  47           Contains the native Ready/Busy IDs.
  48
  49       nand-ecc-engine:
  50         allOf:
  51           - $ref: /schemas/types.yaml#/definitions/phandle
  52         description: |
  53           A phandle on the hardware ECC engine if any. There are
  54           basically three possibilities:
  55           1/ The ECC engine is part of the NAND controller, in this
  56           case the phandle should reference the parent node.
  57           2/ The ECC engine is part of the NAND part (on-die), in this
  58           case the phandle should reference the node itself.
  59           3/ The ECC engine is external, in this case the phandle should
  60           reference the specific ECC engine node.
  61
  62       nand-use-soft-ecc-engine:
  63         type: boolean
  64         description: Use a software ECC engine.
  65
  66       nand-no-ecc-engine:
  67         type: boolean
  68         description: Do not use any ECC correction.
  69
  70       nand-ecc-placement:
  71         allOf:
  72           - $ref: /schemas/types.yaml#/definitions/string
  73           - enum: [ oob, interleaved ]
  74         description:
  75           Location of the ECC bytes. This location is unknown by default
  76           but can be explicitly set to "oob", if all ECC bytes are
  77           known to be stored in the OOB area, or "interleaved" if ECC
  78           bytes will be interleaved with regular data in the main area.
  79
  80       nand-ecc-algo:
  81         description:
  82           Desired ECC algorithm.
  83         $ref: /schemas/types.yaml#/definitions/string
  84         enum: [hamming, bch, rs]
  85
  86       nand-bus-width:
  87         description:
  88           Bus width to the NAND chip
  89         $ref: /schemas/types.yaml#/definitions/uint32
  90         enum: [8, 16]
  91         default: 8
  92
  93       nand-on-flash-bbt:
  94         $ref: /schemas/types.yaml#/definitions/flag
  95         description:
  96           With this property, the OS will search the device for a Bad
  97           Block Table (BBT). If not found, it will create one, reserve
  98           a few blocks at the end of the device to store it and update
  99           it as the device ages. Otherwise, the out-of-band area of a
 100           few pages of all the blocks will be scanned at boot time to
 101           find Bad Block Markers (BBM). These markers will help to
 102           build a volatile BBT in RAM.
 103
 104       nand-ecc-strength:
 105         description:
 106           Maximum number of bits that can be corrected per ECC step.
 107         $ref: /schemas/types.yaml#/definitions/uint32
 108         minimum: 1
 109
 110       nand-ecc-step-size:
 111         description:
 112           Number of data bytes covered by a single ECC step.
 113         $ref: /schemas/types.yaml#/definitions/uint32
 114         minimum: 1
 115
 116       nand-ecc-maximize:
 117         $ref: /schemas/types.yaml#/definitions/flag
 118         description:
 119           Whether or not the ECC strength should be maximized. The
 120           maximum ECC strength is both controller and chip
 121           dependent. The ECC engine has to select the ECC config
 122           providing the best strength and taking the OOB area size
 123           constraint into account. This is particularly useful when
 124           only the in-band area is used by the upper layers, and you
 125           want to make your NAND as reliable as possible.
 126
 127       nand-is-boot-medium:
 128         $ref: /schemas/types.yaml#/definitions/flag
 129         description:
 130           Whether or not the NAND chip is a boot medium. Drivers might
 131           use this information to select ECC algorithms supported by
 132           the boot ROM or similar restrictions.
 133
 134       nand-rb:
 135         $ref: /schemas/types.yaml#/definitions/uint32-array
 136         description:
 137           Contains the native Ready/Busy IDs.
 138
 139       rb-gpios:
 140         description:
 141           Contains one or more GPIO descriptor (the numper of descriptor
 142           depends on the number of R/B pins exposed by the flash) for the
 143           Ready/Busy pins. Active state refers to the NAND ready state and
 144           should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
 145
 146     required:
 147       - reg
 148
 149 required:
 150   - "#address-cells"
 151   - "#size-cells"
 152
 153 additionalProperties: true
 154
 155 examples:
 156   - |
 157     nand-controller {
 158       #address-cells = <1>;
 159       #size-cells = <0>;
 160
 161       /* controller specific properties */
 162
 163       nand@0 {
 164         reg = <0>;
 165         nand-use-soft-ecc-engine;
 166         nand-ecc-algo = "bch";
 167
 168         /* controller specific properties */
 169       };
 170     };