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   cs-gpios:
  42     minItems: 1
  43     maxItems: 8
  44     description:
  45       Array of chip-select available to the controller. The first
  46       entries are a 1:1 mapping of the available chip-select on the
  47       NAND controller (even if they are not used). As many additional
  48       chip-select as needed may follow and should be phandles of GPIO
  49       lines. 'reg' entries of the NAND chip subnodes become indexes of
  50       this array when this property is present.
  51
  52 patternProperties:
  53   "^nand@[a-f0-9]$":
  54     type: object
  55     properties:
  56       reg:
  57         description:
  58           Contains the native Ready/Busy IDs.
  59
  60       nand-ecc-engine:
  61         allOf:
  62           - $ref: /schemas/types.yaml#/definitions/phandle
  63         description: |
  64           A phandle on the hardware ECC engine if any. There are
  65           basically three possibilities:
  66           1/ The ECC engine is part of the NAND controller, in this
  67           case the phandle should reference the parent node.
  68           2/ The ECC engine is part of the NAND part (on-die), in this
  69           case the phandle should reference the node itself.
  70           3/ The ECC engine is external, in this case the phandle should
  71           reference the specific ECC engine node.
  72
  73       nand-use-soft-ecc-engine:
  74         type: boolean
  75         description: Use a software ECC engine.
  76
  77       nand-no-ecc-engine:
  78         type: boolean
  79         description: Do not use any ECC correction.
  80
  81       nand-ecc-placement:
  82         allOf:
  83           - $ref: /schemas/types.yaml#/definitions/string
  84           - enum: [ oob, interleaved ]
  85         description:
  86           Location of the ECC bytes. This location is unknown by default
  87           but can be explicitly set to "oob", if all ECC bytes are
  88           known to be stored in the OOB area, or "interleaved" if ECC
  89           bytes will be interleaved with regular data in the main area.
  90
  91       nand-ecc-algo:
  92         description:
  93           Desired ECC algorithm.
  94         $ref: /schemas/types.yaml#/definitions/string
  95         enum: [hamming, bch, rs]
  96
  97       nand-bus-width:
  98         description:
  99           Bus width to the NAND chip
 100         $ref: /schemas/types.yaml#/definitions/uint32
 101         enum: [8, 16]
 102         default: 8
 103
 104       nand-on-flash-bbt:
 105         $ref: /schemas/types.yaml#/definitions/flag
 106         description:
 107           With this property, the OS will search the device for a Bad
 108           Block Table (BBT). If not found, it will create one, reserve
 109           a few blocks at the end of the device to store it and update
 110           it as the device ages. Otherwise, the out-of-band area of a
 111           few pages of all the blocks will be scanned at boot time to
 112           find Bad Block Markers (BBM). These markers will help to
 113           build a volatile BBT in RAM.
 114
 115       nand-ecc-strength:
 116         description:
 117           Maximum number of bits that can be corrected per ECC step.
 118         $ref: /schemas/types.yaml#/definitions/uint32
 119         minimum: 1
 120
 121       nand-ecc-step-size:
 122         description:
 123           Number of data bytes covered by a single ECC step.
 124         $ref: /schemas/types.yaml#/definitions/uint32
 125         minimum: 1
 126
 127       nand-ecc-maximize:
 128         $ref: /schemas/types.yaml#/definitions/flag
 129         description:
 130           Whether or not the ECC strength should be maximized. The
 131           maximum ECC strength is both controller and chip
 132           dependent. The ECC engine has to select the ECC config
 133           providing the best strength and taking the OOB area size
 134           constraint into account. This is particularly useful when
 135           only the in-band area is used by the upper layers, and you
 136           want to make your NAND as reliable as possible.
 137
 138       nand-is-boot-medium:
 139         $ref: /schemas/types.yaml#/definitions/flag
 140         description:
 141           Whether or not the NAND chip is a boot medium. Drivers might
 142           use this information to select ECC algorithms supported by
 143           the boot ROM or similar restrictions.
 144
 145       nand-rb:
 146         $ref: /schemas/types.yaml#/definitions/uint32-array
 147         description:
 148           Contains the native Ready/Busy IDs.
 149
 150       rb-gpios:
 151         description:
 152           Contains one or more GPIO descriptor (the numper of descriptor
 153           depends on the number of R/B pins exposed by the flash) for the
 154           Ready/Busy pins. Active state refers to the NAND ready state and
 155           should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
 156
 157       secure-regions:
 158         $ref: /schemas/types.yaml#/definitions/uint64-matrix
 159         description:
 160           Regions in the NAND chip which are protected using a secure element
 161           like Trustzone. This property contains the start address and size of
 162           the secure regions present.
 163
 164     required:
 165       - reg
 166
 167 required:
 168   - "#address-cells"
 169   - "#size-cells"
 170
 171 additionalProperties: true
 172
 173 examples:
 174   - |
 175     nand-controller {
 176       #address-cells = <1>;
 177       #size-cells = <0>;
 178       cs-gpios = <0>, <&gpioA 1>; /* A single native CS is available */
 179
 180       /* controller specific properties */
 181
 182       nand@0 {
 183         reg = <0>; /* Native CS */
 184         nand-use-soft-ecc-engine;
 185         nand-ecc-algo = "bch";
 186
 187         /* controller specific properties */
 188       };
 189
 190       nand@1 {
 191         reg = <1>; /* GPIO CS */
 192       };
 193     };