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 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 52patternProperties: 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 167required: 168 - "#address-cells" 169 - "#size-cells" 170 171additionalProperties: true 172 173examples: 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 }; 194