]>
Commit | Line | Data |
---|---|---|
1da177e4 LT |
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> | |
4 | ||
5 | <book id="MTD-NAND-Guide"> | |
6 | <bookinfo> | |
7 | <title>MTD NAND Driver Programming Interface</title> | |
8 | ||
9 | <authorgroup> | |
10 | <author> | |
11 | <firstname>Thomas</firstname> | |
12 | <surname>Gleixner</surname> | |
13 | <affiliation> | |
14 | <address> | |
15 | <email>tglx@linutronix.de</email> | |
16 | </address> | |
17 | </affiliation> | |
18 | </author> | |
19 | </authorgroup> | |
20 | ||
21 | <copyright> | |
22 | <year>2004</year> | |
23 | <holder>Thomas Gleixner</holder> | |
24 | </copyright> | |
25 | ||
26 | <legalnotice> | |
27 | <para> | |
28 | This documentation is free software; you can redistribute | |
29 | it and/or modify it under the terms of the GNU General Public | |
30 | License version 2 as published by the Free Software Foundation. | |
31 | </para> | |
32 | ||
33 | <para> | |
34 | This program is distributed in the hope that it will be | |
35 | useful, but WITHOUT ANY WARRANTY; without even the implied | |
36 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
37 | See the GNU General Public License for more details. | |
38 | </para> | |
39 | ||
40 | <para> | |
41 | You should have received a copy of the GNU General Public | |
42 | License along with this program; if not, write to the Free | |
43 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, | |
44 | MA 02111-1307 USA | |
45 | </para> | |
46 | ||
47 | <para> | |
48 | For more details see the file COPYING in the source | |
49 | distribution of Linux. | |
50 | </para> | |
51 | </legalnotice> | |
52 | </bookinfo> | |
53 | ||
54 | <toc></toc> | |
55 | ||
56 | <chapter id="intro"> | |
57 | <title>Introduction</title> | |
58 | <para> | |
59 | The generic NAND driver supports almost all NAND and AG-AND based | |
60 | chips and connects them to the Memory Technology Devices (MTD) | |
61 | subsystem of the Linux Kernel. | |
62 | </para> | |
63 | <para> | |
64 | This documentation is provided for developers who want to implement | |
65 | board drivers or filesystem drivers suitable for NAND devices. | |
66 | </para> | |
67 | </chapter> | |
68 | ||
69 | <chapter id="bugs"> | |
70 | <title>Known Bugs And Assumptions</title> | |
71 | <para> | |
72 | None. | |
73 | </para> | |
74 | </chapter> | |
75 | ||
76 | <chapter id="dochints"> | |
77 | <title>Documentation hints</title> | |
78 | <para> | |
79 | The function and structure docs are autogenerated. Each function and | |
80 | struct member has a short description which is marked with an [XXX] identifier. | |
81 | The following chapters explain the meaning of those identifiers. | |
82 | </para> | |
70d6d9db | 83 | <sect1 id="Function_identifiers_XXX"> |
1da177e4 LT |
84 | <title>Function identifiers [XXX]</title> |
85 | <para> | |
86 | The functions are marked with [XXX] identifiers in the short | |
87 | comment. The identifiers explain the usage and scope of the | |
88 | functions. Following identifiers are used: | |
89 | </para> | |
90 | <itemizedlist> | |
91 | <listitem><para> | |
92 | [MTD Interface]</para><para> | |
93 | These functions provide the interface to the MTD kernel API. | |
8011b3c9 | 94 | They are not replaceable and provide functionality |
1da177e4 LT |
95 | which is complete hardware independent. |
96 | </para></listitem> | |
97 | <listitem><para> | |
98 | [NAND Interface]</para><para> | |
99 | These functions are exported and provide the interface to the NAND kernel API. | |
100 | </para></listitem> | |
101 | <listitem><para> | |
102 | [GENERIC]</para><para> | |
8011b3c9 | 103 | Generic functions are not replaceable and provide functionality |
1da177e4 LT |
104 | which is complete hardware independent. |
105 | </para></listitem> | |
106 | <listitem><para> | |
107 | [DEFAULT]</para><para> | |
108 | Default functions provide hardware related functionality which is suitable | |
109 | for most of the implementations. These functions can be replaced by the | |
8011b3c9 | 110 | board driver if necessary. Those functions are called via pointers in the |
1da177e4 | 111 | NAND chip description structure. The board driver can set the functions which |
ea9b6dcc | 112 | should be replaced by board dependent functions before calling nand_scan(). |
1da177e4 LT |
113 | If the function pointer is NULL on entry to nand_scan() then the pointer |
114 | is set to the default function which is suitable for the detected chip type. | |
115 | </para></listitem> | |
116 | </itemizedlist> | |
117 | </sect1> | |
70d6d9db | 118 | <sect1 id="Struct_member_identifiers_XXX"> |
1da177e4 LT |
119 | <title>Struct member identifiers [XXX]</title> |
120 | <para> | |
121 | The struct members are marked with [XXX] identifiers in the | |
122 | comment. The identifiers explain the usage and scope of the | |
123 | members. Following identifiers are used: | |
124 | </para> | |
125 | <itemizedlist> | |
126 | <listitem><para> | |
127 | [INTERN]</para><para> | |
128 | These members are for NAND driver internal use only and must not be | |
129 | modified. Most of these values are calculated from the chip geometry | |
130 | information which is evaluated during nand_scan(). | |
131 | </para></listitem> | |
132 | <listitem><para> | |
133 | [REPLACEABLE]</para><para> | |
134 | Replaceable members hold hardware related functions which can be | |
135 | provided by the board driver. The board driver can set the functions which | |
ea9b6dcc | 136 | should be replaced by board dependent functions before calling nand_scan(). |
1da177e4 LT |
137 | If the function pointer is NULL on entry to nand_scan() then the pointer |
138 | is set to the default function which is suitable for the detected chip type. | |
139 | </para></listitem> | |
140 | <listitem><para> | |
141 | [BOARDSPECIFIC]</para><para> | |
142 | Board specific members hold hardware related information which must | |
143 | be provided by the board driver. The board driver must set the function | |
144 | pointers and datafields before calling nand_scan(). | |
145 | </para></listitem> | |
146 | <listitem><para> | |
147 | [OPTIONAL]</para><para> | |
148 | Optional members can hold information relevant for the board driver. The | |
149 | generic NAND driver code does not use this information. | |
150 | </para></listitem> | |
151 | </itemizedlist> | |
152 | </sect1> | |
153 | </chapter> | |
154 | ||
155 | <chapter id="basicboarddriver"> | |
156 | <title>Basic board driver</title> | |
157 | <para> | |
158 | For most boards it will be sufficient to provide just the | |
ea9b6dcc | 159 | basic functions and fill out some really board dependent |
1da177e4 | 160 | members in the nand chip description structure. |
1da177e4 | 161 | </para> |
70d6d9db | 162 | <sect1 id="Basic_defines"> |
1da177e4 LT |
163 | <title>Basic defines</title> |
164 | <para> | |
3eb064e4 BB |
165 | At least you have to provide a nand_chip structure |
166 | and a storage for the ioremap'ed chip address. | |
167 | You can allocate the nand_chip structure using | |
168 | kmalloc or you can allocate it statically. | |
169 | The NAND chip structure embeds an mtd structure | |
170 | which will be registered to the MTD subsystem. | |
171 | You can extract a pointer to the mtd structure | |
172 | from a nand_chip pointer using the nand_to_mtd() | |
173 | helper. | |
1da177e4 LT |
174 | </para> |
175 | <para> | |
176 | Kmalloc based example | |
177 | </para> | |
178 | <programlisting> | |
179 | static struct mtd_info *board_mtd; | |
8d9f99c3 | 180 | static void __iomem *baseaddr; |
1da177e4 LT |
181 | </programlisting> |
182 | <para> | |
183 | Static example | |
184 | </para> | |
185 | <programlisting> | |
1da177e4 | 186 | static struct nand_chip board_chip; |
8d9f99c3 | 187 | static void __iomem *baseaddr; |
1da177e4 LT |
188 | </programlisting> |
189 | </sect1> | |
70d6d9db | 190 | <sect1 id="Partition_defines"> |
1da177e4 LT |
191 | <title>Partition defines</title> |
192 | <para> | |
741c80c2 | 193 | If you want to divide your device into partitions, then |
6a8a98b2 | 194 | define a partitioning scheme suitable to your board. |
1da177e4 LT |
195 | </para> |
196 | <programlisting> | |
197 | #define NUM_PARTITIONS 2 | |
198 | static struct mtd_partition partition_info[] = { | |
199 | { .name = "Flash partition 1", | |
200 | .offset = 0, | |
201 | .size = 8 * 1024 * 1024 }, | |
202 | { .name = "Flash partition 2", | |
203 | .offset = MTDPART_OFS_NEXT, | |
204 | .size = MTDPART_SIZ_FULL }, | |
205 | }; | |
206 | </programlisting> | |
207 | </sect1> | |
70d6d9db | 208 | <sect1 id="Hardware_control_functions"> |
1da177e4 LT |
209 | <title>Hardware control function</title> |
210 | <para> | |
211 | The hardware control function provides access to the | |
212 | control pins of the NAND chip(s). | |
213 | The access can be done by GPIO pins or by address lines. | |
214 | If you use address lines, make sure that the timing | |
215 | requirements are met. | |
216 | </para> | |
217 | <para> | |
218 | <emphasis>GPIO based example</emphasis> | |
219 | </para> | |
220 | <programlisting> | |
221 | static void board_hwcontrol(struct mtd_info *mtd, int cmd) | |
222 | { | |
223 | switch(cmd){ | |
224 | case NAND_CTL_SETCLE: /* Set CLE pin high */ break; | |
225 | case NAND_CTL_CLRCLE: /* Set CLE pin low */ break; | |
226 | case NAND_CTL_SETALE: /* Set ALE pin high */ break; | |
227 | case NAND_CTL_CLRALE: /* Set ALE pin low */ break; | |
228 | case NAND_CTL_SETNCE: /* Set nCE pin low */ break; | |
229 | case NAND_CTL_CLRNCE: /* Set nCE pin high */ break; | |
230 | } | |
231 | } | |
232 | </programlisting> | |
233 | <para> | |
234 | <emphasis>Address lines based example.</emphasis> It's assumed that the | |
235 | nCE pin is driven by a chip select decoder. | |
236 | </para> | |
237 | <programlisting> | |
238 | static void board_hwcontrol(struct mtd_info *mtd, int cmd) | |
239 | { | |
1e6460ab | 240 | struct nand_chip *this = mtd_to_nand(mtd); |
1da177e4 LT |
241 | switch(cmd){ |
242 | case NAND_CTL_SETCLE: this->IO_ADDR_W |= CLE_ADRR_BIT; break; | |
243 | case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; | |
244 | case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break; | |
245 | case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break; | |
246 | } | |
247 | } | |
248 | </programlisting> | |
249 | </sect1> | |
70d6d9db | 250 | <sect1 id="Device_ready_function"> |
1da177e4 LT |
251 | <title>Device ready function</title> |
252 | <para> | |
253 | If the hardware interface has the ready busy pin of the NAND chip connected to a | |
b595076a | 254 | GPIO or other accessible I/O pin, this function is used to read back the state of the |
1da177e4 LT |
255 | pin. The function has no arguments and should return 0, if the device is busy (R/B pin |
256 | is low) and 1, if the device is ready (R/B pin is high). | |
257 | If the hardware interface does not give access to the ready busy pin, then | |
258 | the function must not be defined and the function pointer this->dev_ready is set to NULL. | |
259 | </para> | |
260 | </sect1> | |
70d6d9db | 261 | <sect1 id="Init_function"> |
1da177e4 LT |
262 | <title>Init function</title> |
263 | <para> | |
264 | The init function allocates memory and sets up all the board | |
265 | specific parameters and function pointers. When everything | |
266 | is set up nand_scan() is called. This function tries to | |
267 | detect and identify then chip. If a chip is found all the | |
268 | internal data fields are initialized accordingly. | |
8011b3c9 | 269 | The structure(s) have to be zeroed out first and then filled with the necessary |
1da177e4 LT |
270 | information about the device. |
271 | </para> | |
272 | <programlisting> | |
0af76d95 | 273 | static int __init board_init (void) |
1da177e4 LT |
274 | { |
275 | struct nand_chip *this; | |
276 | int err = 0; | |
277 | ||
278 | /* Allocate memory for MTD device structure and private data */ | |
3eb064e4 BB |
279 | this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL); |
280 | if (!this) { | |
1da177e4 LT |
281 | printk ("Unable to allocate NAND MTD device structure.\n"); |
282 | err = -ENOMEM; | |
283 | goto out; | |
284 | } | |
285 | ||
3eb064e4 BB |
286 | board_mtd = nand_to_mtd(this); |
287 | ||
0f035b8e | 288 | /* map physical address */ |
8d9f99c3 HS |
289 | baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024); |
290 | if (!baseaddr) { | |
1da177e4 LT |
291 | printk("Ioremap to access NAND chip failed\n"); |
292 | err = -EIO; | |
293 | goto out_mtd; | |
294 | } | |
295 | ||
1da177e4 LT |
296 | /* Set address of NAND IO lines */ |
297 | this->IO_ADDR_R = baseaddr; | |
298 | this->IO_ADDR_W = baseaddr; | |
299 | /* Reference hardware control function */ | |
300 | this->hwcontrol = board_hwcontrol; | |
301 | /* Set command delay time, see datasheet for correct value */ | |
302 | this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; | |
303 | /* Assign the device ready function, if available */ | |
304 | this->dev_ready = board_dev_ready; | |
305 | this->eccmode = NAND_ECC_SOFT; | |
306 | ||
0f035b8e | 307 | /* Scan to find existence of the device */ |
1da177e4 LT |
308 | if (nand_scan (board_mtd, 1)) { |
309 | err = -ENXIO; | |
310 | goto out_ior; | |
311 | } | |
312 | ||
313 | add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS); | |
314 | goto out; | |
315 | ||
316 | out_ior: | |
8d9f99c3 | 317 | iounmap(baseaddr); |
1da177e4 | 318 | out_mtd: |
3eb064e4 | 319 | kfree (this); |
1da177e4 LT |
320 | out: |
321 | return err; | |
322 | } | |
323 | module_init(board_init); | |
324 | </programlisting> | |
325 | </sect1> | |
70d6d9db | 326 | <sect1 id="Exit_function"> |
1da177e4 LT |
327 | <title>Exit function</title> |
328 | <para> | |
8011b3c9 | 329 | The exit function is only necessary if the driver is |
1da177e4 LT |
330 | compiled as a module. It releases all resources which |
331 | are held by the chip driver and unregisters the partitions | |
332 | in the MTD layer. | |
333 | </para> | |
334 | <programlisting> | |
335 | #ifdef MODULE | |
336 | static void __exit board_cleanup (void) | |
337 | { | |
338 | /* Release resources, unregister device */ | |
339 | nand_release (board_mtd); | |
340 | ||
0f035b8e | 341 | /* unmap physical address */ |
8d9f99c3 | 342 | iounmap(baseaddr); |
1da177e4 LT |
343 | |
344 | /* Free the MTD device structure */ | |
3eb064e4 | 345 | kfree (mtd_to_nand(board_mtd)); |
1da177e4 LT |
346 | } |
347 | module_exit(board_cleanup); | |
348 | #endif | |
349 | </programlisting> | |
350 | </sect1> | |
351 | </chapter> | |
352 | ||
353 | <chapter id="boarddriversadvanced"> | |
354 | <title>Advanced board driver functions</title> | |
355 | <para> | |
356 | This chapter describes the advanced functionality of the NAND | |
357 | driver. For a list of functions which can be overridden by the board | |
358 | driver see the documentation of the nand_chip structure. | |
359 | </para> | |
70d6d9db | 360 | <sect1 id="Multiple_chip_control"> |
1da177e4 LT |
361 | <title>Multiple chip control</title> |
362 | <para> | |
af901ca1 | 363 | The nand driver can control chip arrays. Therefore the |
1da177e4 LT |
364 | board driver must provide an own select_chip function. This |
365 | function must (de)select the requested chip. | |
366 | The function pointer in the nand_chip structure must | |
367 | be set before calling nand_scan(). The maxchip parameter | |
368 | of nand_scan() defines the maximum number of chips to | |
369 | scan for. Make sure that the select_chip function can | |
370 | handle the requested number of chips. | |
371 | </para> | |
372 | <para> | |
373 | The nand driver concatenates the chips to one virtual | |
374 | chip and provides this virtual chip to the MTD layer. | |
375 | </para> | |
376 | <para> | |
377 | <emphasis>Note: The driver can only handle linear chip arrays | |
378 | of equally sized chips. There is no support for | |
379 | parallel arrays which extend the buswidth.</emphasis> | |
380 | </para> | |
381 | <para> | |
382 | <emphasis>GPIO based example</emphasis> | |
383 | </para> | |
384 | <programlisting> | |
385 | static void board_select_chip (struct mtd_info *mtd, int chip) | |
386 | { | |
387 | /* Deselect all chips, set all nCE pins high */ | |
388 | GPIO(BOARD_NAND_NCE) |= 0xff; | |
389 | if (chip >= 0) | |
390 | GPIO(BOARD_NAND_NCE) &= ~ (1 << chip); | |
391 | } | |
392 | </programlisting> | |
393 | <para> | |
394 | <emphasis>Address lines based example.</emphasis> | |
395 | Its assumed that the nCE pins are connected to an | |
396 | address decoder. | |
397 | </para> | |
398 | <programlisting> | |
399 | static void board_select_chip (struct mtd_info *mtd, int chip) | |
400 | { | |
1e6460ab | 401 | struct nand_chip *this = mtd_to_nand(mtd); |
1da177e4 LT |
402 | |
403 | /* Deselect all chips */ | |
404 | this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; | |
405 | this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; | |
406 | switch (chip) { | |
407 | case 0: | |
408 | this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; | |
409 | this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; | |
410 | break; | |
411 | .... | |
412 | case n: | |
413 | this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; | |
414 | this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; | |
415 | break; | |
416 | } | |
417 | } | |
418 | </programlisting> | |
419 | </sect1> | |
70d6d9db | 420 | <sect1 id="Hardware_ECC_support"> |
1da177e4 | 421 | <title>Hardware ECC support</title> |
70d6d9db | 422 | <sect2 id="Functions_and_constants"> |
1da177e4 LT |
423 | <title>Functions and constants</title> |
424 | <para> | |
425 | The nand driver supports three different types of | |
426 | hardware ECC. | |
427 | <itemizedlist> | |
428 | <listitem><para>NAND_ECC_HW3_256</para><para> | |
429 | Hardware ECC generator providing 3 bytes ECC per | |
430 | 256 byte. | |
431 | </para> </listitem> | |
432 | <listitem><para>NAND_ECC_HW3_512</para><para> | |
433 | Hardware ECC generator providing 3 bytes ECC per | |
434 | 512 byte. | |
435 | </para> </listitem> | |
436 | <listitem><para>NAND_ECC_HW6_512</para><para> | |
437 | Hardware ECC generator providing 6 bytes ECC per | |
438 | 512 byte. | |
439 | </para> </listitem> | |
440 | <listitem><para>NAND_ECC_HW8_512</para><para> | |
441 | Hardware ECC generator providing 6 bytes ECC per | |
442 | 512 byte. | |
443 | </para> </listitem> | |
444 | </itemizedlist> | |
445 | If your hardware generator has a different functionality | |
446 | add it at the appropriate place in nand_base.c | |
447 | </para> | |
448 | <para> | |
449 | The board driver must provide following functions: | |
450 | <itemizedlist> | |
451 | <listitem><para>enable_hwecc</para><para> | |
452 | This function is called before reading / writing to | |
453 | the chip. Reset or initialize the hardware generator | |
454 | in this function. The function is called with an | |
455 | argument which let you distinguish between read | |
456 | and write operations. | |
457 | </para> </listitem> | |
458 | <listitem><para>calculate_ecc</para><para> | |
459 | This function is called after read / write from / to | |
460 | the chip. Transfer the ECC from the hardware to | |
461 | the buffer. If the option NAND_HWECC_SYNDROME is set | |
462 | then the function is only called on write. See below. | |
463 | </para> </listitem> | |
464 | <listitem><para>correct_data</para><para> | |
465 | In case of an ECC error this function is called for | |
466 | error detection and correction. Return 1 respectively 2 | |
467 | in case the error can be corrected. If the error is | |
468 | not correctable return -1. If your hardware generator | |
469 | matches the default algorithm of the nand_ecc software | |
470 | generator then use the correction function provided | |
471 | by nand_ecc instead of implementing duplicated code. | |
472 | </para> </listitem> | |
473 | </itemizedlist> | |
474 | </para> | |
475 | </sect2> | |
70d6d9db | 476 | <sect2 id="Hardware_ECC_with_syndrome_calculation"> |
1da177e4 LT |
477 | <title>Hardware ECC with syndrome calculation</title> |
478 | <para> | |
479 | Many hardware ECC implementations provide Reed-Solomon | |
480 | codes and calculate an error syndrome on read. The syndrome | |
481 | must be converted to a standard Reed-Solomon syndrome | |
482 | before calling the error correction code in the generic | |
483 | Reed-Solomon library. | |
484 | </para> | |
485 | <para> | |
25985edc | 486 | The ECC bytes must be placed immediately after the data |
1da177e4 LT |
487 | bytes in order to make the syndrome generator work. This |
488 | is contrary to the usual layout used by software ECC. The | |
3ad2f3fb | 489 | separation of data and out of band area is not longer |
1da177e4 LT |
490 | possible. The nand driver code handles this layout and |
491 | the remaining free bytes in the oob area are managed by | |
492 | the autoplacement code. Provide a matching oob-layout | |
493 | in this case. See rts_from4.c and diskonchip.c for | |
494 | implementation reference. In those cases we must also | |
495 | use bad block tables on FLASH, because the ECC layout is | |
8011b3c9 | 496 | interfering with the bad block marker positions. |
1da177e4 LT |
497 | See bad block table support for details. |
498 | </para> | |
499 | </sect2> | |
500 | </sect1> | |
70d6d9db | 501 | <sect1 id="Bad_Block_table_support"> |
1da177e4 LT |
502 | <title>Bad block table support</title> |
503 | <para> | |
504 | Most NAND chips mark the bad blocks at a defined | |
505 | position in the spare area. Those blocks must | |
506 | not be erased under any circumstances as the bad | |
507 | block information would be lost. | |
508 | It is possible to check the bad block mark each | |
509 | time when the blocks are accessed by reading the | |
510 | spare area of the first page in the block. This | |
511 | is time consuming so a bad block table is used. | |
512 | </para> | |
513 | <para> | |
514 | The nand driver supports various types of bad block | |
515 | tables. | |
516 | <itemizedlist> | |
517 | <listitem><para>Per device</para><para> | |
518 | The bad block table contains all bad block information | |
519 | of the device which can consist of multiple chips. | |
520 | </para> </listitem> | |
521 | <listitem><para>Per chip</para><para> | |
522 | A bad block table is used per chip and contains the | |
523 | bad block information for this particular chip. | |
524 | </para> </listitem> | |
525 | <listitem><para>Fixed offset</para><para> | |
526 | The bad block table is located at a fixed offset | |
527 | in the chip (device). This applies to various | |
528 | DiskOnChip devices. | |
529 | </para> </listitem> | |
530 | <listitem><para>Automatic placed</para><para> | |
531 | The bad block table is automatically placed and | |
532 | detected either at the end or at the beginning | |
533 | of a chip (device) | |
534 | </para> </listitem> | |
535 | <listitem><para>Mirrored tables</para><para> | |
536 | The bad block table is mirrored on the chip (device) to | |
537 | allow updates of the bad block table without data loss. | |
538 | </para> </listitem> | |
539 | </itemizedlist> | |
540 | </para> | |
541 | <para> | |
542 | nand_scan() calls the function nand_default_bbt(). | |
543 | nand_default_bbt() selects appropriate default | |
8011b3c9 | 544 | bad block table descriptors depending on the chip information |
1da177e4 LT |
545 | which was retrieved by nand_scan(). |
546 | </para> | |
547 | <para> | |
548 | The standard policy is scanning the device for bad | |
549 | blocks and build a ram based bad block table which | |
550 | allows faster access than always checking the | |
551 | bad block information on the flash chip itself. | |
552 | </para> | |
70d6d9db | 553 | <sect2 id="Flash_based_tables"> |
1da177e4 LT |
554 | <title>Flash based tables</title> |
555 | <para> | |
8011b3c9 | 556 | It may be desired or necessary to keep a bad block table in FLASH. |
1da177e4 LT |
557 | For AG-AND chips this is mandatory, as they have no factory marked |
558 | bad blocks. They have factory marked good blocks. The marker pattern | |
559 | is erased when the block is erased to be reused. So in case of | |
560 | powerloss before writing the pattern back to the chip this block | |
3ad2f3fb | 561 | would be lost and added to the bad blocks. Therefore we scan the |
1da177e4 LT |
562 | chip(s) when we detect them the first time for good blocks and |
563 | store this information in a bad block table before erasing any | |
564 | of the blocks. | |
565 | </para> | |
566 | <para> | |
8011b3c9 | 567 | The blocks in which the tables are stored are protected against |
1da177e4 | 568 | accidental access by marking them bad in the memory bad block |
3dbda77e | 569 | table. The bad block table management functions are allowed |
8011b3c9 | 570 | to circumvent this protection. |
1da177e4 LT |
571 | </para> |
572 | <para> | |
573 | The simplest way to activate the FLASH based bad block table support | |
bb9ebd4e | 574 | is to set the option NAND_BBT_USE_FLASH in the bbt_option field of |
1da177e4 LT |
575 | the nand chip structure before calling nand_scan(). For AG-AND |
576 | chips is this done by default. | |
577 | This activates the default FLASH based bad block table functionality | |
578 | of the NAND driver. The default bad block table options are | |
579 | <itemizedlist> | |
580 | <listitem><para>Store bad block table per chip</para></listitem> | |
581 | <listitem><para>Use 2 bits per block</para></listitem> | |
582 | <listitem><para>Automatic placement at the end of the chip</para></listitem> | |
583 | <listitem><para>Use mirrored tables with version numbers</para></listitem> | |
584 | <listitem><para>Reserve 4 blocks at the end of the chip</para></listitem> | |
585 | </itemizedlist> | |
586 | </para> | |
587 | </sect2> | |
70d6d9db | 588 | <sect2 id="User_defined_tables"> |
1da177e4 LT |
589 | <title>User defined tables</title> |
590 | <para> | |
591 | User defined tables are created by filling out a | |
592 | nand_bbt_descr structure and storing the pointer in the | |
593 | nand_chip structure member bbt_td before calling nand_scan(). | |
8011b3c9 | 594 | If a mirror table is necessary a second structure must be |
1da177e4 LT |
595 | created and a pointer to this structure must be stored |
596 | in bbt_md inside the nand_chip structure. If the bbt_md | |
597 | member is set to NULL then only the main table is used | |
598 | and no scan for the mirrored table is performed. | |
599 | </para> | |
600 | <para> | |
601 | The most important field in the nand_bbt_descr structure | |
602 | is the options field. The options define most of the | |
603 | table properties. Use the predefined constants from | |
604 | nand.h to define the options. | |
605 | <itemizedlist> | |
606 | <listitem><para>Number of bits per block</para> | |
607 | <para>The supported number of bits is 1, 2, 4, 8.</para></listitem> | |
608 | <listitem><para>Table per chip</para> | |
609 | <para>Setting the constant NAND_BBT_PERCHIP selects that | |
610 | a bad block table is managed for each chip in a chip array. | |
611 | If this option is not set then a per device bad block table | |
612 | is used.</para></listitem> | |
613 | <listitem><para>Table location is absolute</para> | |
614 | <para>Use the option constant NAND_BBT_ABSPAGE and | |
615 | define the absolute page number where the bad block | |
616 | table starts in the field pages. If you have selected bad block | |
617 | tables per chip and you have a multi chip array then the start page | |
618 | must be given for each chip in the chip array. Note: there is no scan | |
619 | for a table ident pattern performed, so the fields | |
620 | pattern, veroffs, offs, len can be left uninitialized</para></listitem> | |
621 | <listitem><para>Table location is automatically detected</para> | |
622 | <para>The table can either be located in the first or the last good | |
623 | blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place | |
624 | the bad block table at the end of the chip (device). The | |
625 | bad block tables are marked and identified by a pattern which | |
626 | is stored in the spare area of the first page in the block which | |
627 | holds the bad block table. Store a pointer to the pattern | |
628 | in the pattern field. Further the length of the pattern has to be | |
629 | stored in len and the offset in the spare area must be given | |
25985edc | 630 | in the offs member of the nand_bbt_descr structure. For mirrored |
1da177e4 LT |
631 | bad block tables different patterns are mandatory.</para></listitem> |
632 | <listitem><para>Table creation</para> | |
633 | <para>Set the option NAND_BBT_CREATE to enable the table creation | |
634 | if no table can be found during the scan. Usually this is done only | |
635 | once if a new chip is found. </para></listitem> | |
636 | <listitem><para>Table write support</para> | |
637 | <para>Set the option NAND_BBT_WRITE to enable the table write support. | |
638 | This allows the update of the bad block table(s) in case a block has | |
639 | to be marked bad due to wear. The MTD interface function block_markbad | |
640 | is calling the update function of the bad block table. If the write | |
641 | support is enabled then the table is updated on FLASH.</para> | |
642 | <para> | |
643 | Note: Write support should only be enabled for mirrored tables with | |
644 | version control. | |
645 | </para></listitem> | |
646 | <listitem><para>Table version control</para> | |
647 | <para>Set the option NAND_BBT_VERSION to enable the table version control. | |
648 | It's highly recommended to enable this for mirrored tables with write | |
25985edc | 649 | support. It makes sure that the risk of losing the bad block |
1da177e4 LT |
650 | table information is reduced to the loss of the information about the |
651 | one worn out block which should be marked bad. The version is stored in | |
652 | 4 consecutive bytes in the spare area of the device. The position of | |
653 | the version number is defined by the member veroffs in the bad block table | |
654 | descriptor.</para></listitem> | |
655 | <listitem><para>Save block contents on write</para> | |
656 | <para> | |
657 | In case that the block which holds the bad block table does contain | |
658 | other useful information, set the option NAND_BBT_SAVECONTENT. When | |
659 | the bad block table is written then the whole block is read the bad | |
660 | block table is updated and the block is erased and everything is | |
661 | written back. If this option is not set only the bad block table | |
662 | is written and everything else in the block is ignored and erased. | |
663 | </para></listitem> | |
664 | <listitem><para>Number of reserved blocks</para> | |
665 | <para> | |
666 | For automatic placement some blocks must be reserved for | |
667 | bad block table storage. The number of reserved blocks is defined | |
8011b3c9 | 668 | in the maxblocks member of the bad block table description structure. |
1da177e4 LT |
669 | Reserving 4 blocks for mirrored tables should be a reasonable number. |
670 | This also limits the number of blocks which are scanned for the bad | |
671 | block table ident pattern. | |
672 | </para></listitem> | |
673 | </itemizedlist> | |
674 | </para> | |
675 | </sect2> | |
676 | </sect1> | |
70d6d9db | 677 | <sect1 id="Spare_area_placement"> |
1da177e4 LT |
678 | <title>Spare area (auto)placement</title> |
679 | <para> | |
680 | The nand driver implements different possibilities for | |
681 | placement of filesystem data in the spare area, | |
682 | <itemizedlist> | |
683 | <listitem><para>Placement defined by fs driver</para></listitem> | |
684 | <listitem><para>Automatic placement</para></listitem> | |
685 | </itemizedlist> | |
686 | The default placement function is automatic placement. The | |
687 | nand driver has built in default placement schemes for the | |
688 | various chiptypes. If due to hardware ECC functionality the | |
689 | default placement does not fit then the board driver can | |
690 | provide a own placement scheme. | |
691 | </para> | |
692 | <para> | |
693 | File system drivers can provide a own placement scheme which | |
694 | is used instead of the default placement scheme. | |
695 | </para> | |
696 | <para> | |
697 | Placement schemes are defined by a nand_oobinfo structure | |
698 | <programlisting> | |
699 | struct nand_oobinfo { | |
700 | int useecc; | |
701 | int eccbytes; | |
702 | int eccpos[24]; | |
703 | int oobfree[8][2]; | |
704 | }; | |
705 | </programlisting> | |
706 | <itemizedlist> | |
707 | <listitem><para>useecc</para><para> | |
708 | The useecc member controls the ecc and placement function. The header | |
709 | file include/mtd/mtd-abi.h contains constants to select ecc and | |
710 | placement. MTD_NANDECC_OFF switches off the ecc complete. This is | |
711 | not recommended and available for testing and diagnosis only. | |
712 | MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE | |
713 | selects automatic placement. | |
714 | </para></listitem> | |
715 | <listitem><para>eccbytes</para><para> | |
716 | The eccbytes member defines the number of ecc bytes per page. | |
717 | </para></listitem> | |
718 | <listitem><para>eccpos</para><para> | |
719 | The eccpos array holds the byte offsets in the spare area where | |
720 | the ecc codes are placed. | |
721 | </para></listitem> | |
722 | <listitem><para>oobfree</para><para> | |
723 | The oobfree array defines the areas in the spare area which can be | |
724 | used for automatic placement. The information is given in the format | |
725 | {offset, size}. offset defines the start of the usable area, size the | |
726 | length in bytes. More than one area can be defined. The list is terminated | |
727 | by an {0, 0} entry. | |
728 | </para></listitem> | |
729 | </itemizedlist> | |
730 | </para> | |
70d6d9db | 731 | <sect2 id="Placement_defined_by_fs_driver"> |
1da177e4 LT |
732 | <title>Placement defined by fs driver</title> |
733 | <para> | |
734 | The calling function provides a pointer to a nand_oobinfo | |
735 | structure which defines the ecc placement. For writes the | |
736 | caller must provide a spare area buffer along with the | |
737 | data buffer. The spare area buffer size is (number of pages) * | |
738 | (size of spare area). For reads the buffer size is | |
739 | (number of pages) * ((size of spare area) + (number of ecc | |
740 | steps per page) * sizeof (int)). The driver stores the | |
741 | result of the ecc check for each tuple in the spare buffer. | |
742 | The storage sequence is | |
743 | </para> | |
744 | <para> | |
745 | <spare data page 0><ecc result 0>...<ecc result n> | |
746 | </para> | |
747 | <para> | |
748 | ... | |
749 | </para> | |
750 | <para> | |
751 | <spare data page n><ecc result 0>...<ecc result n> | |
752 | </para> | |
753 | <para> | |
754 | This is a legacy mode used by YAFFS1. | |
755 | </para> | |
756 | <para> | |
757 | If the spare area buffer is NULL then only the ECC placement is | |
758 | done according to the given scheme in the nand_oobinfo structure. | |
759 | </para> | |
760 | </sect2> | |
70d6d9db | 761 | <sect2 id="Automatic_placement"> |
1da177e4 LT |
762 | <title>Automatic placement</title> |
763 | <para> | |
764 | Automatic placement uses the built in defaults to place the | |
765 | ecc bytes in the spare area. If filesystem data have to be stored / | |
766 | read into the spare area then the calling function must provide a | |
767 | buffer. The buffer size per page is determined by the oobfree array in | |
768 | the nand_oobinfo structure. | |
769 | </para> | |
770 | <para> | |
771 | If the spare area buffer is NULL then only the ECC placement is | |
772 | done according to the default builtin scheme. | |
773 | </para> | |
774 | </sect2> | |
1da177e4 | 775 | </sect1> |
70d6d9db | 776 | <sect1 id="Spare_area_autoplacement_default"> |
1da177e4 | 777 | <title>Spare area autoplacement default schemes</title> |
70d6d9db | 778 | <sect2 id="pagesize_256"> |
1da177e4 LT |
779 | <title>256 byte pagesize</title> |
780 | <informaltable><tgroup cols="3"><tbody> | |
781 | <row> | |
782 | <entry>Offset</entry> | |
783 | <entry>Content</entry> | |
784 | <entry>Comment</entry> | |
785 | </row> | |
786 | <row> | |
787 | <entry>0x00</entry> | |
788 | <entry>ECC byte 0</entry> | |
789 | <entry>Error correction code byte 0</entry> | |
790 | </row> | |
791 | <row> | |
792 | <entry>0x01</entry> | |
793 | <entry>ECC byte 1</entry> | |
794 | <entry>Error correction code byte 1</entry> | |
795 | </row> | |
796 | <row> | |
797 | <entry>0x02</entry> | |
798 | <entry>ECC byte 2</entry> | |
799 | <entry>Error correction code byte 2</entry> | |
800 | </row> | |
801 | <row> | |
802 | <entry>0x03</entry> | |
803 | <entry>Autoplace 0</entry> | |
804 | <entry></entry> | |
805 | </row> | |
806 | <row> | |
807 | <entry>0x04</entry> | |
808 | <entry>Autoplace 1</entry> | |
809 | <entry></entry> | |
810 | </row> | |
811 | <row> | |
812 | <entry>0x05</entry> | |
813 | <entry>Bad block marker</entry> | |
814 | <entry>If any bit in this byte is zero, then this block is bad. | |
815 | This applies only to the first page in a block. In the remaining | |
816 | pages this byte is reserved</entry> | |
817 | </row> | |
818 | <row> | |
819 | <entry>0x06</entry> | |
820 | <entry>Autoplace 2</entry> | |
821 | <entry></entry> | |
822 | </row> | |
823 | <row> | |
824 | <entry>0x07</entry> | |
825 | <entry>Autoplace 3</entry> | |
826 | <entry></entry> | |
827 | </row> | |
828 | </tbody></tgroup></informaltable> | |
829 | </sect2> | |
70d6d9db | 830 | <sect2 id="pagesize_512"> |
1da177e4 LT |
831 | <title>512 byte pagesize</title> |
832 | <informaltable><tgroup cols="3"><tbody> | |
833 | <row> | |
834 | <entry>Offset</entry> | |
835 | <entry>Content</entry> | |
836 | <entry>Comment</entry> | |
837 | </row> | |
838 | <row> | |
839 | <entry>0x00</entry> | |
840 | <entry>ECC byte 0</entry> | |
841 | <entry>Error correction code byte 0 of the lower 256 Byte data in | |
842 | this page</entry> | |
843 | </row> | |
844 | <row> | |
845 | <entry>0x01</entry> | |
846 | <entry>ECC byte 1</entry> | |
847 | <entry>Error correction code byte 1 of the lower 256 Bytes of data | |
848 | in this page</entry> | |
849 | </row> | |
850 | <row> | |
851 | <entry>0x02</entry> | |
852 | <entry>ECC byte 2</entry> | |
853 | <entry>Error correction code byte 2 of the lower 256 Bytes of data | |
854 | in this page</entry> | |
855 | </row> | |
856 | <row> | |
857 | <entry>0x03</entry> | |
858 | <entry>ECC byte 3</entry> | |
859 | <entry>Error correction code byte 0 of the upper 256 Bytes of data | |
860 | in this page</entry> | |
861 | </row> | |
862 | <row> | |
863 | <entry>0x04</entry> | |
864 | <entry>reserved</entry> | |
865 | <entry>reserved</entry> | |
866 | </row> | |
867 | <row> | |
868 | <entry>0x05</entry> | |
869 | <entry>Bad block marker</entry> | |
870 | <entry>If any bit in this byte is zero, then this block is bad. | |
871 | This applies only to the first page in a block. In the remaining | |
872 | pages this byte is reserved</entry> | |
873 | </row> | |
874 | <row> | |
875 | <entry>0x06</entry> | |
876 | <entry>ECC byte 4</entry> | |
877 | <entry>Error correction code byte 1 of the upper 256 Bytes of data | |
878 | in this page</entry> | |
879 | </row> | |
880 | <row> | |
881 | <entry>0x07</entry> | |
882 | <entry>ECC byte 5</entry> | |
883 | <entry>Error correction code byte 2 of the upper 256 Bytes of data | |
884 | in this page</entry> | |
885 | </row> | |
886 | <row> | |
887 | <entry>0x08 - 0x0F</entry> | |
888 | <entry>Autoplace 0 - 7</entry> | |
889 | <entry></entry> | |
890 | </row> | |
891 | </tbody></tgroup></informaltable> | |
892 | </sect2> | |
70d6d9db | 893 | <sect2 id="pagesize_2048"> |
1da177e4 LT |
894 | <title>2048 byte pagesize</title> |
895 | <informaltable><tgroup cols="3"><tbody> | |
896 | <row> | |
897 | <entry>Offset</entry> | |
898 | <entry>Content</entry> | |
899 | <entry>Comment</entry> | |
900 | </row> | |
901 | <row> | |
902 | <entry>0x00</entry> | |
903 | <entry>Bad block marker</entry> | |
904 | <entry>If any bit in this byte is zero, then this block is bad. | |
905 | This applies only to the first page in a block. In the remaining | |
906 | pages this byte is reserved</entry> | |
907 | </row> | |
908 | <row> | |
909 | <entry>0x01</entry> | |
910 | <entry>Reserved</entry> | |
911 | <entry>Reserved</entry> | |
912 | </row> | |
913 | <row> | |
914 | <entry>0x02-0x27</entry> | |
915 | <entry>Autoplace 0 - 37</entry> | |
916 | <entry></entry> | |
917 | </row> | |
918 | <row> | |
919 | <entry>0x28</entry> | |
920 | <entry>ECC byte 0</entry> | |
921 | <entry>Error correction code byte 0 of the first 256 Byte data in | |
922 | this page</entry> | |
923 | </row> | |
924 | <row> | |
925 | <entry>0x29</entry> | |
926 | <entry>ECC byte 1</entry> | |
927 | <entry>Error correction code byte 1 of the first 256 Bytes of data | |
928 | in this page</entry> | |
929 | </row> | |
930 | <row> | |
931 | <entry>0x2A</entry> | |
932 | <entry>ECC byte 2</entry> | |
933 | <entry>Error correction code byte 2 of the first 256 Bytes data in | |
934 | this page</entry> | |
935 | </row> | |
936 | <row> | |
937 | <entry>0x2B</entry> | |
938 | <entry>ECC byte 3</entry> | |
939 | <entry>Error correction code byte 0 of the second 256 Bytes of data | |
940 | in this page</entry> | |
941 | </row> | |
942 | <row> | |
943 | <entry>0x2C</entry> | |
944 | <entry>ECC byte 4</entry> | |
945 | <entry>Error correction code byte 1 of the second 256 Bytes of data | |
946 | in this page</entry> | |
947 | </row> | |
948 | <row> | |
949 | <entry>0x2D</entry> | |
950 | <entry>ECC byte 5</entry> | |
951 | <entry>Error correction code byte 2 of the second 256 Bytes of data | |
952 | in this page</entry> | |
953 | </row> | |
954 | <row> | |
955 | <entry>0x2E</entry> | |
956 | <entry>ECC byte 6</entry> | |
957 | <entry>Error correction code byte 0 of the third 256 Bytes of data | |
958 | in this page</entry> | |
959 | </row> | |
960 | <row> | |
961 | <entry>0x2F</entry> | |
962 | <entry>ECC byte 7</entry> | |
963 | <entry>Error correction code byte 1 of the third 256 Bytes of data | |
964 | in this page</entry> | |
965 | </row> | |
966 | <row> | |
967 | <entry>0x30</entry> | |
968 | <entry>ECC byte 8</entry> | |
969 | <entry>Error correction code byte 2 of the third 256 Bytes of data | |
970 | in this page</entry> | |
971 | </row> | |
972 | <row> | |
973 | <entry>0x31</entry> | |
974 | <entry>ECC byte 9</entry> | |
975 | <entry>Error correction code byte 0 of the fourth 256 Bytes of data | |
976 | in this page</entry> | |
977 | </row> | |
978 | <row> | |
979 | <entry>0x32</entry> | |
980 | <entry>ECC byte 10</entry> | |
981 | <entry>Error correction code byte 1 of the fourth 256 Bytes of data | |
982 | in this page</entry> | |
983 | </row> | |
984 | <row> | |
985 | <entry>0x33</entry> | |
986 | <entry>ECC byte 11</entry> | |
987 | <entry>Error correction code byte 2 of the fourth 256 Bytes of data | |
988 | in this page</entry> | |
989 | </row> | |
990 | <row> | |
991 | <entry>0x34</entry> | |
992 | <entry>ECC byte 12</entry> | |
993 | <entry>Error correction code byte 0 of the fifth 256 Bytes of data | |
994 | in this page</entry> | |
995 | </row> | |
996 | <row> | |
997 | <entry>0x35</entry> | |
998 | <entry>ECC byte 13</entry> | |
999 | <entry>Error correction code byte 1 of the fifth 256 Bytes of data | |
1000 | in this page</entry> | |
1001 | </row> | |
1002 | <row> | |
1003 | <entry>0x36</entry> | |
1004 | <entry>ECC byte 14</entry> | |
1005 | <entry>Error correction code byte 2 of the fifth 256 Bytes of data | |
1006 | in this page</entry> | |
1007 | </row> | |
1008 | <row> | |
1009 | <entry>0x37</entry> | |
1010 | <entry>ECC byte 15</entry> | |
1011 | <entry>Error correction code byte 0 of the sixt 256 Bytes of data | |
1012 | in this page</entry> | |
1013 | </row> | |
1014 | <row> | |
1015 | <entry>0x38</entry> | |
1016 | <entry>ECC byte 16</entry> | |
1017 | <entry>Error correction code byte 1 of the sixt 256 Bytes of data | |
1018 | in this page</entry> | |
1019 | </row> | |
1020 | <row> | |
1021 | <entry>0x39</entry> | |
1022 | <entry>ECC byte 17</entry> | |
1023 | <entry>Error correction code byte 2 of the sixt 256 Bytes of data | |
1024 | in this page</entry> | |
1025 | </row> | |
1026 | <row> | |
1027 | <entry>0x3A</entry> | |
1028 | <entry>ECC byte 18</entry> | |
1029 | <entry>Error correction code byte 0 of the seventh 256 Bytes of | |
1030 | data in this page</entry> | |
1031 | </row> | |
1032 | <row> | |
1033 | <entry>0x3B</entry> | |
1034 | <entry>ECC byte 19</entry> | |
1035 | <entry>Error correction code byte 1 of the seventh 256 Bytes of | |
1036 | data in this page</entry> | |
1037 | </row> | |
1038 | <row> | |
1039 | <entry>0x3C</entry> | |
1040 | <entry>ECC byte 20</entry> | |
1041 | <entry>Error correction code byte 2 of the seventh 256 Bytes of | |
1042 | data in this page</entry> | |
1043 | </row> | |
1044 | <row> | |
1045 | <entry>0x3D</entry> | |
1046 | <entry>ECC byte 21</entry> | |
25985edc | 1047 | <entry>Error correction code byte 0 of the eighth 256 Bytes of data |
1da177e4 LT |
1048 | in this page</entry> |
1049 | </row> | |
1050 | <row> | |
1051 | <entry>0x3E</entry> | |
1052 | <entry>ECC byte 22</entry> | |
25985edc | 1053 | <entry>Error correction code byte 1 of the eighth 256 Bytes of data |
1da177e4 LT |
1054 | in this page</entry> |
1055 | </row> | |
1056 | <row> | |
1057 | <entry>0x3F</entry> | |
1058 | <entry>ECC byte 23</entry> | |
25985edc | 1059 | <entry>Error correction code byte 2 of the eighth 256 Bytes of data |
1da177e4 LT |
1060 | in this page</entry> |
1061 | </row> | |
1062 | </tbody></tgroup></informaltable> | |
1063 | </sect2> | |
1064 | </sect1> | |
1065 | </chapter> | |
1066 | ||
1067 | <chapter id="filesystems"> | |
1068 | <title>Filesystem support</title> | |
1069 | <para> | |
8011b3c9 | 1070 | The NAND driver provides all necessary functions for a |
1da177e4 LT |
1071 | filesystem via the MTD interface. |
1072 | </para> | |
1073 | <para> | |
8011b3c9 | 1074 | Filesystems must be aware of the NAND peculiarities and |
1da177e4 LT |
1075 | restrictions. One major restrictions of NAND Flash is, that you cannot |
1076 | write as often as you want to a page. The consecutive writes to a page, | |
1077 | before erasing it again, are restricted to 1-3 writes, depending on the | |
1078 | manufacturers specifications. This applies similar to the spare area. | |
1079 | </para> | |
1080 | <para> | |
3ad2f3fb | 1081 | Therefore NAND aware filesystems must either write in page size chunks |
1da177e4 LT |
1082 | or hold a writebuffer to collect smaller writes until they sum up to |
1083 | pagesize. Available NAND aware filesystems: JFFS2, YAFFS. | |
1084 | </para> | |
1085 | <para> | |
1086 | The spare area usage to store filesystem data is controlled by | |
1087 | the spare area placement functionality which is described in one | |
1088 | of the earlier chapters. | |
1089 | </para> | |
1090 | </chapter> | |
1091 | <chapter id="tools"> | |
1092 | <title>Tools</title> | |
1093 | <para> | |
1094 | The MTD project provides a couple of helpful tools to handle NAND Flash. | |
1095 | <itemizedlist> | |
1096 | <listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem> | |
1097 | <listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem> | |
1098 | <listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem> | |
1099 | </itemizedlist> | |
1100 | </para> | |
1101 | <para> | |
1102 | These tools are aware of the NAND restrictions. Please use those tools | |
1103 | instead of complaining about errors which are caused by non NAND aware | |
1104 | access methods. | |
1105 | </para> | |
1106 | </chapter> | |
1107 | ||
1108 | <chapter id="defines"> | |
1109 | <title>Constants</title> | |
1110 | <para> | |
1111 | This chapter describes the constants which might be relevant for a driver developer. | |
1112 | </para> | |
70d6d9db | 1113 | <sect1 id="Chip_option_constants"> |
1da177e4 | 1114 | <title>Chip option constants</title> |
70d6d9db | 1115 | <sect2 id="Constants_for_chip_id_table"> |
1da177e4 LT |
1116 | <title>Constants for chip id table</title> |
1117 | <para> | |
1118 | These constants are defined in nand.h. They are ored together to describe | |
1119 | the chip functionality. | |
1120 | <programlisting> | |
1da177e4 LT |
1121 | /* Buswitdh is 16 bit */ |
1122 | #define NAND_BUSWIDTH_16 0x00000002 | |
1123 | /* Device supports partial programming without padding */ | |
1124 | #define NAND_NO_PADDING 0x00000004 | |
1125 | /* Chip has cache program function */ | |
1126 | #define NAND_CACHEPRG 0x00000008 | |
1127 | /* Chip has copy back function */ | |
1128 | #define NAND_COPYBACK 0x00000010 | |
1129 | /* AND Chip which has 4 banks and a confusing page / block | |
1130 | * assignment. See Renesas datasheet for further information */ | |
1131 | #define NAND_IS_AND 0x00000020 | |
1132 | /* Chip has a array of 4 pages which can be read without | |
1133 | * additional ready /busy waits */ | |
1134 | #define NAND_4PAGE_ARRAY 0x00000040 | |
1135 | </programlisting> | |
1136 | </para> | |
1137 | </sect2> | |
70d6d9db | 1138 | <sect2 id="Constants_for_runtime_options"> |
1da177e4 LT |
1139 | <title>Constants for runtime options</title> |
1140 | <para> | |
1141 | These constants are defined in nand.h. They are ored together to describe | |
1142 | the functionality. | |
1143 | <programlisting> | |
1da177e4 LT |
1144 | /* The hw ecc generator provides a syndrome instead a ecc value on read |
1145 | * This can only work if we have the ecc bytes directly behind the | |
1146 | * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */ | |
1147 | #define NAND_HWECC_SYNDROME 0x00020000 | |
1148 | </programlisting> | |
1149 | </para> | |
1150 | </sect2> | |
1151 | </sect1> | |
1152 | ||
70d6d9db | 1153 | <sect1 id="EEC_selection_constants"> |
1da177e4 LT |
1154 | <title>ECC selection constants</title> |
1155 | <para> | |
1156 | Use these constants to select the ECC algorithm. | |
1157 | <programlisting> | |
1158 | /* No ECC. Usage is not recommended ! */ | |
1159 | #define NAND_ECC_NONE 0 | |
1160 | /* Software ECC 3 byte ECC per 256 Byte data */ | |
1161 | #define NAND_ECC_SOFT 1 | |
1162 | /* Hardware ECC 3 byte ECC per 256 Byte data */ | |
1163 | #define NAND_ECC_HW3_256 2 | |
1164 | /* Hardware ECC 3 byte ECC per 512 Byte data */ | |
1165 | #define NAND_ECC_HW3_512 3 | |
1166 | /* Hardware ECC 6 byte ECC per 512 Byte data */ | |
1167 | #define NAND_ECC_HW6_512 4 | |
1168 | /* Hardware ECC 6 byte ECC per 512 Byte data */ | |
1169 | #define NAND_ECC_HW8_512 6 | |
1170 | </programlisting> | |
1171 | </para> | |
1172 | </sect1> | |
1173 | ||
70d6d9db | 1174 | <sect1 id="Hardware_control_related_constants"> |
1da177e4 LT |
1175 | <title>Hardware control related constants</title> |
1176 | <para> | |
1177 | These constants describe the requested hardware access function when | |
1178 | the boardspecific hardware control function is called | |
1179 | <programlisting> | |
1180 | /* Select the chip by setting nCE to low */ | |
1181 | #define NAND_CTL_SETNCE 1 | |
1182 | /* Deselect the chip by setting nCE to high */ | |
1183 | #define NAND_CTL_CLRNCE 2 | |
1184 | /* Select the command latch by setting CLE to high */ | |
1185 | #define NAND_CTL_SETCLE 3 | |
1186 | /* Deselect the command latch by setting CLE to low */ | |
1187 | #define NAND_CTL_CLRCLE 4 | |
1188 | /* Select the address latch by setting ALE to high */ | |
1189 | #define NAND_CTL_SETALE 5 | |
1190 | /* Deselect the address latch by setting ALE to low */ | |
1191 | #define NAND_CTL_CLRALE 6 | |
1192 | /* Set write protection by setting WP to high. Not used! */ | |
1193 | #define NAND_CTL_SETWP 7 | |
1194 | /* Clear write protection by setting WP to low. Not used! */ | |
1195 | #define NAND_CTL_CLRWP 8 | |
1196 | </programlisting> | |
1197 | </para> | |
1198 | </sect1> | |
1199 | ||
70d6d9db | 1200 | <sect1 id="Bad_block_table_constants"> |
1da177e4 LT |
1201 | <title>Bad block table related constants</title> |
1202 | <para> | |
1203 | These constants describe the options used for bad block | |
1204 | table descriptors. | |
1205 | <programlisting> | |
1206 | /* Options for the bad block table descriptors */ | |
1207 | ||
1208 | /* The number of bits used per block in the bbt on the device */ | |
1209 | #define NAND_BBT_NRBITS_MSK 0x0000000F | |
1210 | #define NAND_BBT_1BIT 0x00000001 | |
1211 | #define NAND_BBT_2BIT 0x00000002 | |
1212 | #define NAND_BBT_4BIT 0x00000004 | |
1213 | #define NAND_BBT_8BIT 0x00000008 | |
1214 | /* The bad block table is in the last good block of the device */ | |
1215 | #define NAND_BBT_LASTBLOCK 0x00000010 | |
1216 | /* The bbt is at the given page, else we must scan for the bbt */ | |
1217 | #define NAND_BBT_ABSPAGE 0x00000020 | |
1da177e4 LT |
1218 | /* bbt is stored per chip on multichip devices */ |
1219 | #define NAND_BBT_PERCHIP 0x00000080 | |
1220 | /* bbt has a version counter at offset veroffs */ | |
1221 | #define NAND_BBT_VERSION 0x00000100 | |
1222 | /* Create a bbt if none axists */ | |
1223 | #define NAND_BBT_CREATE 0x00000200 | |
8011b3c9 | 1224 | /* Write bbt if necessary */ |
1da177e4 LT |
1225 | #define NAND_BBT_WRITE 0x00001000 |
1226 | /* Read and write back block contents when writing bbt */ | |
1227 | #define NAND_BBT_SAVECONTENT 0x00002000 | |
1228 | </programlisting> | |
1229 | </para> | |
1230 | </sect1> | |
1231 | ||
1232 | </chapter> | |
1233 | ||
1234 | <chapter id="structs"> | |
1235 | <title>Structures</title> | |
1236 | <para> | |
1237 | This chapter contains the autogenerated documentation of the structures which are | |
1238 | used in the NAND driver and might be relevant for a driver developer. Each | |
1239 | struct member has a short description which is marked with an [XXX] identifier. | |
1240 | See the chapter "Documentation hints" for an explanation. | |
1241 | </para> | |
1242 | !Iinclude/linux/mtd/nand.h | |
1243 | </chapter> | |
1244 | ||
1245 | <chapter id="pubfunctions"> | |
1246 | <title>Public Functions Provided</title> | |
1247 | <para> | |
1248 | This chapter contains the autogenerated documentation of the NAND kernel API functions | |
1249 | which are exported. Each function has a short description which is marked with an [XXX] identifier. | |
1250 | See the chapter "Documentation hints" for an explanation. | |
1251 | </para> | |
1252 | !Edrivers/mtd/nand/nand_base.c | |
1253 | !Edrivers/mtd/nand/nand_bbt.c | |
1254 | !Edrivers/mtd/nand/nand_ecc.c | |
1255 | </chapter> | |
1256 | ||
1257 | <chapter id="intfunctions"> | |
1258 | <title>Internal Functions Provided</title> | |
1259 | <para> | |
1260 | This chapter contains the autogenerated documentation of the NAND driver internal functions. | |
1261 | Each function has a short description which is marked with an [XXX] identifier. | |
1262 | See the chapter "Documentation hints" for an explanation. | |
1263 | The functions marked with [DEFAULT] might be relevant for a board driver developer. | |
1264 | </para> | |
1265 | !Idrivers/mtd/nand/nand_base.c | |
1266 | !Idrivers/mtd/nand/nand_bbt.c | |
844d3b42 RD |
1267 | <!-- No internal functions for kernel-doc: |
1268 | X!Idrivers/mtd/nand/nand_ecc.c | |
1269 | --> | |
1da177e4 LT |
1270 | </chapter> |
1271 | ||
1272 | <chapter id="credits"> | |
1273 | <title>Credits</title> | |
1274 | <para> | |
1275 | The following people have contributed to the NAND driver: | |
1276 | <orderedlist> | |
1277 | <listitem><para>Steven J. Hill<email>sjhill@realitydiluted.com</email></para></listitem> | |
1278 | <listitem><para>David Woodhouse<email>dwmw2@infradead.org</email></para></listitem> | |
1279 | <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> | |
1280 | </orderedlist> | |
1281 | A lot of users have provided bugfixes, improvements and helping hands for testing. | |
1282 | Thanks a lot. | |
1283 | </para> | |
1284 | <para> | |
1285 | The following people have contributed to this document: | |
1286 | <orderedlist> | |
1287 | <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> | |
1288 | </orderedlist> | |
1289 | </para> | |
1290 | </chapter> | |
1291 | </book> |