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     description:
  43       Array of chip-select available to the controller. The first
  44       entries are a 1:1 mapping of the available chip-select on the
  45       NAND controller (even if they are not used). As many additional
  46       chip-select as needed may follow and should be phandles of GPIO
  47       lines. 'reg' entries of the NAND chip subnodes become indexes of
  48       this array when this property is present.
  49     minItems: 1
  50     maxItems: 8
  51
  52 patternProperties:
  53   "^nand@[a-f0-9]$":
  54     type: object
  55     $ref: "nand-chip.yaml#"
  56
  57     properties:
  58       reg:
  59         description:
  60           Contains the chip-select IDs.
  61
  62       nand-ecc-placement:
  63         description:
  64           Location of the ECC bytes. This location is unknown by default
  65           but can be explicitly set to "oob", if all ECC bytes are
  66           known to be stored in the OOB area, or "interleaved" if ECC
  67           bytes will be interleaved with regular data in the main area.
  68         $ref: /schemas/types.yaml#/definitions/string
  69         enum: [ oob, interleaved ]
  70
  71       nand-bus-width:
  72         description:
  73           Bus width to the NAND chip
  74         $ref: /schemas/types.yaml#/definitions/uint32
  75         enum: [8, 16]
  76         default: 8
  77
  78       nand-on-flash-bbt:
  79         description:
  80           With this property, the OS will search the device for a Bad
  81           Block Table (BBT). If not found, it will create one, reserve
  82           a few blocks at the end of the device to store it and update
  83           it as the device ages. Otherwise, the out-of-band area of a
  84           few pages of all the blocks will be scanned at boot time to
  85           find Bad Block Markers (BBM). These markers will help to
  86           build a volatile BBT in RAM.
  87         $ref: /schemas/types.yaml#/definitions/flag
  88
  89       nand-ecc-maximize:
  90         description:
  91           Whether or not the ECC strength should be maximized. The
  92           maximum ECC strength is both controller and chip
  93           dependent. The ECC engine has to select the ECC config
  94           providing the best strength and taking the OOB area size
  95           constraint into account. This is particularly useful when
  96           only the in-band area is used by the upper layers, and you
  97           want to make your NAND as reliable as possible.
  98         $ref: /schemas/types.yaml#/definitions/flag
  99
 100       nand-is-boot-medium:
 101         description:
 102           Whether or not the NAND chip is a boot medium. Drivers might
 103           use this information to select ECC algorithms supported by
 104           the boot ROM or similar restrictions.
 105         $ref: /schemas/types.yaml#/definitions/flag
 106
 107       nand-rb:
 108         description:
 109           Contains the native Ready/Busy IDs.
 110         $ref: /schemas/types.yaml#/definitions/uint32-array
 111
 112       rb-gpios:
 113         description:
 114           Contains one or more GPIO descriptor (the numper of descriptor
 115           depends on the number of R/B pins exposed by the flash) for the
 116           Ready/Busy pins. Active state refers to the NAND ready state and
 117           should be set to GPIOD_ACTIVE_HIGH unless the signal is inverted.
 118
 119       wp-gpios:
 120         description:
 121           Contains one GPIO descriptor for the Write Protect pin.
 122           Active state refers to the NAND Write Protect state and should be
 123           set to GPIOD_ACTIVE_LOW unless the signal is inverted.
 124         maxItems: 1
 125
 126     required:
 127       - reg
 128
 129 required:
 130   - "#address-cells"
 131   - "#size-cells"
 132
 133 additionalProperties: true
 134
 135 examples:
 136   - |
 137     nand-controller {
 138       #address-cells = <1>;
 139       #size-cells = <0>;
 140       cs-gpios = <0>, <&gpioA 1>; /* A single native CS is available */
 141
 142       /* controller specific properties */
 143
 144       nand@0 {
 145         reg = <0>; /* Native CS */
 146         /* NAND chip specific properties */
 147       };
 148
 149       nand@1 {
 150         reg = <1>; /* GPIO CS */
 151       };
 152     };