]>
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 | ||
99067b08 SW |
107 | CONFIG_SYS_NAND_MAX_CHIPS |
108 | The maximum number of NAND chips per device to be supported. | |
109 | ||
578931b3 SW |
110 | CONFIG_SYS_NAND_SELF_INIT |
111 | Traditionally, glue code in drivers/mtd/nand/nand.c has driven | |
112 | the initialization process -- it provides the mtd and nand | |
113 | structs, calls a board init function for a specific device, | |
114 | calls nand_scan(), and registers with mtd. | |
115 | ||
116 | This arrangement does not provide drivers with the flexibility to | |
117 | run code between nand_scan_ident() and nand_scan_tail(), or other | |
118 | deviations from the "normal" flow. | |
119 | ||
120 | If a board defines CONFIG_SYS_NAND_SELF_INIT, drivers/mtd/nand/nand.c | |
121 | will make one call to board_nand_init(), with no arguments. That | |
122 | function is responsible for calling a driver init function for | |
123 | each NAND device on the board, that performs all initialization | |
124 | tasks except setting mtd->name, and registering with the rest of | |
125 | U-Boot. Those last tasks are accomplished by calling nand_register() | |
126 | on the new mtd device. | |
127 | ||
128 | Example of new init to be added to the end of an existing driver | |
129 | init: | |
130 | ||
131 | /* | |
132 | * devnum is the device number to be used in nand commands | |
133 | * and in mtd->name. Must be less than | |
134 | * CONFIG_SYS_NAND_MAX_DEVICE. | |
135 | */ | |
136 | mtd = &nand_info[devnum]; | |
137 | ||
138 | /* chip is struct nand_chip, and is now provided by the driver. */ | |
139 | mtd->priv = &chip; | |
140 | ||
141 | /* | |
142 | * Fill in appropriate values if this driver uses these fields, | |
143 | * or uses the standard read_byte/write_buf/etc. functions from | |
144 | * nand_base.c that use these fields. | |
145 | */ | |
146 | chip.IO_ADDR_R = ...; | |
147 | chip.IO_ADDR_W = ...; | |
148 | ||
149 | if (nand_scan_ident(mtd, CONFIG_SYS_MAX_NAND_CHIPS, NULL)) | |
150 | error out | |
151 | ||
152 | /* | |
153 | * Insert here any code you wish to run after the chip has been | |
154 | * identified, but before any other I/O is done. | |
155 | */ | |
156 | ||
157 | if (nand_scan_tail(mtd)) | |
158 | error out | |
159 | ||
160 | if (nand_register(devnum)) | |
161 | error out | |
162 | ||
163 | In addition to providing more flexibility to the driver, it reduces | |
164 | the difference between a U-Boot driver and its Linux counterpart. | |
165 | nand_init() is now reduced to calling board_nand_init() once, and | |
166 | printing a size summary. This should also make it easier to | |
167 | transition to delayed NAND initialization. | |
168 | ||
169 | Please convert your driver even if you don't need the extra | |
170 | flexibility, so that one day we can eliminate the old mechanism. | |
171 | ||
4e3ccd26 WD |
172 | NOTE: |
173 | ===== | |
174 | ||
99067b08 | 175 | The current NAND implementation is based on what is in recent |
be33b046 | 176 | Linux kernels. The old legacy implementation has been removed. |
4e3ccd26 | 177 | |
99067b08 SW |
178 | If you have board code which used CONFIG_NAND_LEGACY, you'll need |
179 | to convert to the current NAND interface for it to continue to work. | |
2255b2d2 | 180 | |
99067b08 SW |
181 | The Disk On Chip driver is currently broken and has been for some time. |
182 | There is a driver in drivers/mtd/nand, taken from Linux, that works with | |
183 | the current NAND system but has not yet been adapted to the u-boot | |
184 | environment. | |
2255b2d2 | 185 | |
2255b2d2 SR |
186 | Additional improvements to the NAND subsystem by Guido Classen, 10-10-2006 |
187 | ||
188 | JFFS2 related commands: | |
189 | ||
190 | implement "nand erase clean" and old "nand erase" | |
191 | using both the new code which is able to skip bad blocks | |
192 | "nand erase clean" additionally writes JFFS2-cleanmarkers in the oob. | |
193 | ||
2255b2d2 SR |
194 | Miscellaneous and testing commands: |
195 | "markbad [offset]" | |
196 | create an artificial bad block (for testing bad block handling) | |
197 | ||
198 | "scrub [offset length]" | |
199 | like "erase" but don't skip bad block. Instead erase them. | |
200 | DANGEROUS!!! Factory set bad blocks will be lost. Use only | |
201 | to remove artificial bad blocks created with the "markbad" command. | |
202 | ||
3287f6d3 BT |
203 | "torture offset" |
204 | Torture block to determine if it is still reliable. | |
205 | Enabled by the CONFIG_CMD_NAND_TORTURE configuration option. | |
206 | This command returns 0 if the block is still reliable, else 1. | |
207 | If the block is detected as unreliable, it is up to the user to decide to | |
208 | mark this block as bad. | |
209 | The analyzed block is put through 3 erase / write cycles (or less if the block | |
210 | is detected as unreliable earlier). | |
211 | This command can be used in scripts, e.g. together with the markbad command to | |
212 | automate retries and handling of possibly newly detected bad blocks if the | |
213 | nand write command fails. | |
214 | It can also be used manually by users having seen some NAND errors in logs to | |
215 | search the root cause of these errors. | |
216 | The underlying nand_torture() function is also useful for code willing to | |
217 | automate actions following a nand->write() error. This would e.g. be required | |
218 | in order to program or update safely firmware to NAND, especially for the UBI | |
219 | part of such firmware. | |
220 | ||
2255b2d2 SR |
221 | |
222 | NAND locking command (for chips with active LOCKPRE pin) | |
223 | ||
224 | "nand lock" | |
225 | set NAND chip to lock state (all pages locked) | |
226 | ||
227 | "nand lock tight" | |
228 | set NAND chip to lock tight state (software can't change locking anymore) | |
229 | ||
230 | "nand lock status" | |
231 | displays current locking status of all pages | |
232 | ||
233 | "nand unlock [offset] [size]" | |
234 | unlock consecutive area (can be called multiple times for different areas) | |
235 | ||
eee623a5 JH |
236 | "nand unlock.allexcept [offset] [size]" |
237 | unlock all except specified consecutive area | |
2255b2d2 SR |
238 | |
239 | I have tested the code with board containing 128MiB NAND large page chips | |
240 | and 32MiB small page chips. |