]>
Commit | Line | Data |
---|---|---|
7a8e9bed WD |
1 | NAND FLASH commands and notes |
2 | ||
4e3ccd26 WD |
3 | See NOTE below!!! |
4 | ||
7a8e9bed WD |
5 | # (C) Copyright 2003 |
6 | # Dave Ellis, SIXNET, dge@sixnetio.com | |
7 | # | |
1a459660 | 8 | # SPDX-License-Identifier: GPL-2.0+ |
7a8e9bed WD |
9 | |
10 | Commands: | |
11 | ||
12 | nand bad | |
13 | Print a list of all of the bad blocks in the current device. | |
14 | ||
15 | nand device | |
16 | Print information about the current NAND device. | |
17 | ||
18 | nand device num | |
19 | Make device `num' the current device and print information about it. | |
20 | ||
856f0544 SR |
21 | nand erase off|partition size |
22 | nand erase clean [off|partition size] | |
23 | Erase `size' bytes starting at offset `off'. Alternatively partition | |
24 | name can be specified, in this case size will be eventually limited | |
25 | to not exceed partition size (this behaviour applies also to read | |
26 | and write commands). Only complete erase blocks can be erased. | |
27 | ||
28 | If `erase' is specified without an offset or size, the entire flash | |
29 | is erased. If `erase' is specified with partition but without an | |
30 | size, the entire partition is erased. | |
7a8e9bed WD |
31 | |
32 | If `clean' is specified, a JFFS2-style clean marker is written to | |
856f0544 | 33 | each block after it is erased. |
7a8e9bed WD |
34 | |
35 | This command will not erase blocks that are marked bad. There is | |
36 | a debug option in cmd_nand.c to allow bad blocks to be erased. | |
37 | Please read the warning there before using it, as blocks marked | |
38 | bad by the manufacturer must _NEVER_ be erased. | |
39 | ||
40 | nand info | |
41 | Print information about all of the NAND devices found. | |
42 | ||
856f0544 | 43 | nand read addr ofs|partition size |
984e03cd SW |
44 | Read `size' bytes from `ofs' in NAND flash to `addr'. Blocks that |
45 | are marked bad are skipped. If a page cannot be read because an | |
46 | uncorrectable data error is found, the command stops with an error. | |
7a8e9bed | 47 | |
856f0544 | 48 | nand read.oob addr ofs|partition size |
7a8e9bed WD |
49 | Read `size' bytes from the out-of-band data area corresponding to |
50 | `ofs' in NAND flash to `addr'. This is limited to the 16 bytes of | |
51 | data for one 512-byte page or 2 256-byte pages. There is no check | |
52 | for bad blocks or ECC errors. | |
53 | ||
856f0544 | 54 | nand write addr ofs|partition size |
984e03cd SW |
55 | Write `size' bytes from `addr' to `ofs' in NAND flash. Blocks that |
56 | are marked bad are skipped. If a page cannot be read because an | |
57 | uncorrectable data error is found, the command stops with an error. | |
58 | ||
59 | As JFFS2 skips blocks similarly, this allows writing a JFFS2 image, | |
60 | as long as the image is short enough to fit even after skipping the | |
61 | bad blocks. Compact images, such as those produced by mkfs.jffs2 | |
62 | should work well, but loading an image copied from another flash is | |
63 | going to be trouble if there are any bad blocks. | |
7a8e9bed | 64 | |
c9494866 BG |
65 | nand write.trimffs addr ofs|partition size |
66 | Enabled by the CONFIG_CMD_NAND_TRIMFFS macro. This command will write to | |
67 | the NAND flash in a manner identical to the 'nand write' command | |
68 | described above -- with the additional check that all pages at the end | |
69 | of eraseblocks which contain only 0xff data will not be written to the | |
70 | NAND flash. This behaviour is required when flashing UBI images | |
71 | containing UBIFS volumes as per the UBI FAQ[1]. | |
72 | ||
73 | [1] http://www.linux-mtd.infradead.org/doc/ubi.html#L_flasher_algo | |
74 | ||
856f0544 | 75 | nand write.oob addr ofs|partition size |
7a8e9bed WD |
76 | Write `size' bytes from `addr' to the out-of-band data area |
77 | corresponding to `ofs' in NAND flash. This is limited to the 16 bytes | |
78 | of data for one 512-byte page or 2 256-byte pages. There is no check | |
79 | for bad blocks. | |
80 | ||
418396e2 SW |
81 | nand read.raw addr ofs|partition [count] |
82 | nand write.raw addr ofs|partition [count] | |
83 | Read or write one or more pages at "ofs" in NAND flash, from or to | |
84 | "addr" in memory. This is a raw access, so ECC is avoided and the | |
85 | OOB area is transferred as well. If count is absent, it is assumed | |
86 | to be one page. As with .yaffs2 accesses, the data is formatted as | |
87 | a packed sequence of "data, oob, data, oob, ..." -- no alignment of | |
88 | individual pages is maintained. | |
fb3659ac | 89 | |
7a8e9bed WD |
90 | Configuration Options: |
91 | ||
b5501f7d JL |
92 | CONFIG_CMD_NAND |
93 | Enables NAND support and commmands. | |
7a8e9bed | 94 | |
3287f6d3 BT |
95 | CONFIG_CMD_NAND_TORTURE |
96 | Enables the torture command (see description of this command below). | |
97 | ||
7a8e9bed WD |
98 | CONFIG_MTD_NAND_ECC_JFFS2 |
99 | Define this if you want the Error Correction Code information in | |
100 | the out-of-band data to be formatted to match the JFFS2 file system. | |
101 | CONFIG_MTD_NAND_ECC_YAFFS would be another useful choice for | |
102 | someone to implement. | |
103 | ||
6d0f6bcf | 104 | CONFIG_SYS_MAX_NAND_DEVICE |
7a8e9bed WD |
105 | The maximum number of NAND devices you want to support. |
106 | ||
68ec9c85 PK |
107 | CONFIG_SYS_NAND_MAX_ECCPOS |
108 | If specified, overrides the maximum number of ECC bytes | |
109 | supported. Useful for reducing image size, especially with SPL. | |
110 | This must be at least 48 if nand_base.c is used. | |
111 | ||
112 | CONFIG_SYS_NAND_MAX_OOBFREE | |
113 | If specified, overrides the maximum number of free OOB regions | |
114 | supported. Useful for reducing image size, especially with SPL. | |
115 | This must be at least 2 if nand_base.c is used. | |
116 | ||
99067b08 SW |
117 | CONFIG_SYS_NAND_MAX_CHIPS |
118 | The maximum number of NAND chips per device to be supported. | |
119 | ||
578931b3 SW |
120 | CONFIG_SYS_NAND_SELF_INIT |
121 | Traditionally, glue code in drivers/mtd/nand/nand.c has driven | |
122 | the initialization process -- it provides the mtd and nand | |
123 | structs, calls a board init function for a specific device, | |
124 | calls nand_scan(), and registers with mtd. | |
125 | ||
126 | This arrangement does not provide drivers with the flexibility to | |
127 | run code between nand_scan_ident() and nand_scan_tail(), or other | |
128 | deviations from the "normal" flow. | |
129 | ||
130 | If a board defines CONFIG_SYS_NAND_SELF_INIT, drivers/mtd/nand/nand.c | |
131 | will make one call to board_nand_init(), with no arguments. That | |
132 | function is responsible for calling a driver init function for | |
133 | each NAND device on the board, that performs all initialization | |
134 | tasks except setting mtd->name, and registering with the rest of | |
135 | U-Boot. Those last tasks are accomplished by calling nand_register() | |
136 | on the new mtd device. | |
137 | ||
138 | Example of new init to be added to the end of an existing driver | |
139 | init: | |
140 | ||
141 | /* | |
142 | * devnum is the device number to be used in nand commands | |
143 | * and in mtd->name. Must be less than | |
144 | * CONFIG_SYS_NAND_MAX_DEVICE. | |
145 | */ | |
146 | mtd = &nand_info[devnum]; | |
147 | ||
148 | /* chip is struct nand_chip, and is now provided by the driver. */ | |
149 | mtd->priv = &chip; | |
150 | ||
151 | /* | |
152 | * Fill in appropriate values if this driver uses these fields, | |
153 | * or uses the standard read_byte/write_buf/etc. functions from | |
154 | * nand_base.c that use these fields. | |
155 | */ | |
156 | chip.IO_ADDR_R = ...; | |
157 | chip.IO_ADDR_W = ...; | |
158 | ||
159 | if (nand_scan_ident(mtd, CONFIG_SYS_MAX_NAND_CHIPS, NULL)) | |
160 | error out | |
161 | ||
162 | /* | |
163 | * Insert here any code you wish to run after the chip has been | |
164 | * identified, but before any other I/O is done. | |
165 | */ | |
166 | ||
167 | if (nand_scan_tail(mtd)) | |
168 | error out | |
169 | ||
170 | if (nand_register(devnum)) | |
171 | error out | |
172 | ||
173 | In addition to providing more flexibility to the driver, it reduces | |
174 | the difference between a U-Boot driver and its Linux counterpart. | |
175 | nand_init() is now reduced to calling board_nand_init() once, and | |
176 | printing a size summary. This should also make it easier to | |
177 | transition to delayed NAND initialization. | |
178 | ||
179 | Please convert your driver even if you don't need the extra | |
180 | flexibility, so that one day we can eliminate the old mechanism. | |
181 | ||
beba5f04 | 182 | |
d016dc42 | 183 | CONFIG_SYS_NAND_ONFI_DETECTION |
184 | Enables detection of ONFI compliant devices during probe. | |
185 | And fetching device parameters flashed on device, by parsing | |
186 | ONFI parameter page. | |
187 | ||
188 | CONFIG_BCH | |
189 | Enables software based BCH ECC algorithm present in lib/bch.c | |
190 | This is used by SoC platforms which do not have built-in ELM | |
191 | hardware engine required for BCH ECC correction. | |
192 | ||
193 | ||
beba5f04 | 194 | Platform specific options |
195 | ========================= | |
196 | CONFIG_NAND_OMAP_GPMC | |
197 | Enables omap_gpmc.c driver for OMAPx and AMxxxx platforms. | |
198 | GPMC controller is used for parallel NAND flash devices, and can | |
199 | do ECC calculation (not ECC error detection) for HAM1, BCH4, BCH8 | |
200 | and BCH16 ECC algorithms. | |
201 | ||
202 | CONFIG_NAND_OMAP_ELM | |
203 | Enables omap_elm.c driver for OMAPx and AMxxxx platforms. | |
204 | ELM controller is used for ECC error detection (not ECC calculation) | |
205 | of BCH4, BCH8 and BCH16 ECC algorithms. | |
206 | Some legacy platforms like OMAP3xx do not have in-built ELM h/w engine, | |
207 | thus such SoC platforms need to depend on software library for ECC error | |
208 | detection. However ECC calculation on such plaforms would still be | |
209 | done by GPMC controller. | |
210 | ||
3f719069 | 211 | CONFIG_NAND_OMAP_ECCSCHEME |
212 | On OMAP platforms, this CONFIG specifies NAND ECC scheme. | |
213 | It can take following values: | |
214 | OMAP_ECC_HAM1_CODE_SW | |
215 | 1-bit Hamming code using software lib. | |
216 | (for legacy devices only) | |
217 | OMAP_ECC_HAM1_CODE_HW | |
218 | 1-bit Hamming code using GPMC hardware. | |
219 | (for legacy devices only) | |
220 | OMAP_ECC_BCH4_CODE_HW_DETECTION_SW | |
221 | 4-bit BCH code (unsupported) | |
222 | OMAP_ECC_BCH4_CODE_HW | |
223 | 4-bit BCH code (unsupported) | |
224 | OMAP_ECC_BCH8_CODE_HW_DETECTION_SW | |
225 | 8-bit BCH code with | |
226 | - ecc calculation using GPMC hardware engine, | |
227 | - error detection using software library. | |
228 | - requires CONFIG_BCH to enable software BCH library | |
229 | (For legacy device which do not have ELM h/w engine) | |
230 | OMAP_ECC_BCH8_CODE_HW | |
231 | 8-bit BCH code with | |
232 | - ecc calculation using GPMC hardware engine, | |
233 | - error detection using ELM hardware engine. | |
beba5f04 | 234 | |
4e3ccd26 WD |
235 | NOTE: |
236 | ===== | |
237 | ||
99067b08 | 238 | The current NAND implementation is based on what is in recent |
be33b046 | 239 | Linux kernels. The old legacy implementation has been removed. |
4e3ccd26 | 240 | |
99067b08 SW |
241 | If you have board code which used CONFIG_NAND_LEGACY, you'll need |
242 | to convert to the current NAND interface for it to continue to work. | |
2255b2d2 | 243 | |
99067b08 SW |
244 | The Disk On Chip driver is currently broken and has been for some time. |
245 | There is a driver in drivers/mtd/nand, taken from Linux, that works with | |
246 | the current NAND system but has not yet been adapted to the u-boot | |
247 | environment. | |
2255b2d2 | 248 | |
2255b2d2 SR |
249 | Additional improvements to the NAND subsystem by Guido Classen, 10-10-2006 |
250 | ||
251 | JFFS2 related commands: | |
252 | ||
253 | implement "nand erase clean" and old "nand erase" | |
254 | using both the new code which is able to skip bad blocks | |
255 | "nand erase clean" additionally writes JFFS2-cleanmarkers in the oob. | |
256 | ||
2255b2d2 SR |
257 | Miscellaneous and testing commands: |
258 | "markbad [offset]" | |
259 | create an artificial bad block (for testing bad block handling) | |
260 | ||
261 | "scrub [offset length]" | |
262 | like "erase" but don't skip bad block. Instead erase them. | |
263 | DANGEROUS!!! Factory set bad blocks will be lost. Use only | |
264 | to remove artificial bad blocks created with the "markbad" command. | |
265 | ||
3287f6d3 BT |
266 | "torture offset" |
267 | Torture block to determine if it is still reliable. | |
268 | Enabled by the CONFIG_CMD_NAND_TORTURE configuration option. | |
269 | This command returns 0 if the block is still reliable, else 1. | |
270 | If the block is detected as unreliable, it is up to the user to decide to | |
271 | mark this block as bad. | |
272 | The analyzed block is put through 3 erase / write cycles (or less if the block | |
273 | is detected as unreliable earlier). | |
274 | This command can be used in scripts, e.g. together with the markbad command to | |
275 | automate retries and handling of possibly newly detected bad blocks if the | |
276 | nand write command fails. | |
277 | It can also be used manually by users having seen some NAND errors in logs to | |
278 | search the root cause of these errors. | |
279 | The underlying nand_torture() function is also useful for code willing to | |
280 | automate actions following a nand->write() error. This would e.g. be required | |
281 | in order to program or update safely firmware to NAND, especially for the UBI | |
282 | part of such firmware. | |
283 | ||
2255b2d2 SR |
284 | |
285 | NAND locking command (for chips with active LOCKPRE pin) | |
286 | ||
287 | "nand lock" | |
288 | set NAND chip to lock state (all pages locked) | |
289 | ||
290 | "nand lock tight" | |
291 | set NAND chip to lock tight state (software can't change locking anymore) | |
292 | ||
293 | "nand lock status" | |
294 | displays current locking status of all pages | |
295 | ||
296 | "nand unlock [offset] [size]" | |
297 | unlock consecutive area (can be called multiple times for different areas) | |
298 | ||
eee623a5 JH |
299 | "nand unlock.allexcept [offset] [size]" |
300 | unlock all except specified consecutive area | |
2255b2d2 SR |
301 | |
302 | I have tested the code with board containing 128MiB NAND large page chips | |
303 | and 32MiB small page chips. |