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
7title: NAND Chip and NAND Controller Generic Binding
8
9maintainers:
10  - Miquel Raynal <miquel.raynal@bootlin.com>
11  - Richard Weinberger <richard@nod.at>
12
13description: |
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
29properties:
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
41patternProperties:
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      secure-regions:
147        $ref: /schemas/types.yaml#/definitions/uint64-matrix
148        description:
149          Regions in the NAND chip which are protected using a secure element
150          like Trustzone. This property contains the start address and size of
151          the secure regions present.
152
153    required:
154      - reg
155
156required:
157  - "#address-cells"
158  - "#size-cells"
159
160additionalProperties: true
161
162examples:
163  - |
164    nand-controller {
165      #address-cells = <1>;
166      #size-cells = <0>;
167
168      /* controller specific properties */
169
170      nand@0 {
171        reg = <0>;
172        nand-use-soft-ecc-engine;
173        nand-ecc-algo = "bch";
174
175        /* controller specific properties */
176      };
177    };
178