Contents of /alx-src/trunk/kernel26-alx/linux/Documentation/DocBook/mtdnand.tmpl
Parent Directory | Revision Log
Revision 628 -
(show annotations)
(download)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 44952 byte(s)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 44952 byte(s)
import linux sources based on 2.6.12-alx-r9: -using linux-2.6.12.6 -using 2.6.12-ck6 patch set -using fbsplash-0.9.2-r3 -using vesafb-tng-0.9-rc7 -using squashfs-2.2 -added cddvd-cmdfilter-drop.patch as ck dropped it -added via-epia-dri (cle266) patch -added zd1211-svn-32 wlan driver (http://zd1211.ath.cx/download/) -added debian patches to zd1211 for wep256 etc
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> |
83 | <sect1> |
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. |
94 | They are not replacable and provide functionality |
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> |
103 | Generic functions are not replacable and provide functionality |
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 |
110 | board driver if neccecary. Those functions are called via pointers in the |
111 | NAND chip description structure. The board driver can set the functions which |
112 | should be replaced by board dependend functions before calling nand_scan(). |
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> |
118 | <sect1> |
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 |
136 | should be replaced by board dependend functions before calling nand_scan(). |
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 |
159 | basic functions and fill out some really board dependend |
160 | members in the nand chip description structure. |
161 | See drivers/mtd/nand/skeleton for reference. |
162 | </para> |
163 | <sect1> |
164 | <title>Basic defines</title> |
165 | <para> |
166 | At least you have to provide a mtd structure and |
167 | a storage for the ioremap'ed chip address. |
168 | You can allocate the mtd structure using kmalloc |
169 | or you can allocate it statically. |
170 | In case of static allocation you have to allocate |
171 | a nand_chip structure too. |
172 | </para> |
173 | <para> |
174 | Kmalloc based example |
175 | </para> |
176 | <programlisting> |
177 | static struct mtd_info *board_mtd; |
178 | static unsigned long baseaddr; |
179 | </programlisting> |
180 | <para> |
181 | Static example |
182 | </para> |
183 | <programlisting> |
184 | static struct mtd_info board_mtd; |
185 | static struct nand_chip board_chip; |
186 | static unsigned long baseaddr; |
187 | </programlisting> |
188 | </sect1> |
189 | <sect1> |
190 | <title>Partition defines</title> |
191 | <para> |
192 | If you want to divide your device into parititions, then |
193 | enable the configuration switch CONFIG_MTD_PARITIONS and define |
194 | a paritioning scheme suitable to your board. |
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> |
208 | <sect1> |
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 | { |
240 | struct nand_chip *this = (struct nand_chip *) mtd->priv; |
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> |
250 | <sect1> |
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 |
254 | GPIO or other accesible I/O pin, this function is used to read back the state of the |
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> |
261 | <sect1> |
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. |
269 | The structure(s) have to be zeroed out first and then filled with the neccecary |
270 | information about the device. |
271 | </para> |
272 | <programlisting> |
273 | int __init board_init (void) |
274 | { |
275 | struct nand_chip *this; |
276 | int err = 0; |
277 | |
278 | /* Allocate memory for MTD device structure and private data */ |
279 | board_mtd = kmalloc (sizeof(struct mtd_info) + sizeof (struct nand_chip), GFP_KERNEL); |
280 | if (!board_mtd) { |
281 | printk ("Unable to allocate NAND MTD device structure.\n"); |
282 | err = -ENOMEM; |
283 | goto out; |
284 | } |
285 | |
286 | /* Initialize structures */ |
287 | memset ((char *) board_mtd, 0, sizeof(struct mtd_info) + sizeof(struct nand_chip)); |
288 | |
289 | /* map physical adress */ |
290 | baseaddr = (unsigned long)ioremap(CHIP_PHYSICAL_ADDRESS, 1024); |
291 | if(!baseaddr){ |
292 | printk("Ioremap to access NAND chip failed\n"); |
293 | err = -EIO; |
294 | goto out_mtd; |
295 | } |
296 | |
297 | /* Get pointer to private data */ |
298 | this = (struct nand_chip *) (); |
299 | /* Link the private data with the MTD structure */ |
300 | board_mtd->priv = this; |
301 | |
302 | /* Set address of NAND IO lines */ |
303 | this->IO_ADDR_R = baseaddr; |
304 | this->IO_ADDR_W = baseaddr; |
305 | /* Reference hardware control function */ |
306 | this->hwcontrol = board_hwcontrol; |
307 | /* Set command delay time, see datasheet for correct value */ |
308 | this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; |
309 | /* Assign the device ready function, if available */ |
310 | this->dev_ready = board_dev_ready; |
311 | this->eccmode = NAND_ECC_SOFT; |
312 | |
313 | /* Scan to find existance of the device */ |
314 | if (nand_scan (board_mtd, 1)) { |
315 | err = -ENXIO; |
316 | goto out_ior; |
317 | } |
318 | |
319 | add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS); |
320 | goto out; |
321 | |
322 | out_ior: |
323 | iounmap((void *)baseaddr); |
324 | out_mtd: |
325 | kfree (board_mtd); |
326 | out: |
327 | return err; |
328 | } |
329 | module_init(board_init); |
330 | </programlisting> |
331 | </sect1> |
332 | <sect1> |
333 | <title>Exit function</title> |
334 | <para> |
335 | The exit function is only neccecary if the driver is |
336 | compiled as a module. It releases all resources which |
337 | are held by the chip driver and unregisters the partitions |
338 | in the MTD layer. |
339 | </para> |
340 | <programlisting> |
341 | #ifdef MODULE |
342 | static void __exit board_cleanup (void) |
343 | { |
344 | /* Release resources, unregister device */ |
345 | nand_release (board_mtd); |
346 | |
347 | /* unmap physical adress */ |
348 | iounmap((void *)baseaddr); |
349 | |
350 | /* Free the MTD device structure */ |
351 | kfree (board_mtd); |
352 | } |
353 | module_exit(board_cleanup); |
354 | #endif |
355 | </programlisting> |
356 | </sect1> |
357 | </chapter> |
358 | |
359 | <chapter id="boarddriversadvanced"> |
360 | <title>Advanced board driver functions</title> |
361 | <para> |
362 | This chapter describes the advanced functionality of the NAND |
363 | driver. For a list of functions which can be overridden by the board |
364 | driver see the documentation of the nand_chip structure. |
365 | </para> |
366 | <sect1> |
367 | <title>Multiple chip control</title> |
368 | <para> |
369 | The nand driver can control chip arrays. Therefor the |
370 | board driver must provide an own select_chip function. This |
371 | function must (de)select the requested chip. |
372 | The function pointer in the nand_chip structure must |
373 | be set before calling nand_scan(). The maxchip parameter |
374 | of nand_scan() defines the maximum number of chips to |
375 | scan for. Make sure that the select_chip function can |
376 | handle the requested number of chips. |
377 | </para> |
378 | <para> |
379 | The nand driver concatenates the chips to one virtual |
380 | chip and provides this virtual chip to the MTD layer. |
381 | </para> |
382 | <para> |
383 | <emphasis>Note: The driver can only handle linear chip arrays |
384 | of equally sized chips. There is no support for |
385 | parallel arrays which extend the buswidth.</emphasis> |
386 | </para> |
387 | <para> |
388 | <emphasis>GPIO based example</emphasis> |
389 | </para> |
390 | <programlisting> |
391 | static void board_select_chip (struct mtd_info *mtd, int chip) |
392 | { |
393 | /* Deselect all chips, set all nCE pins high */ |
394 | GPIO(BOARD_NAND_NCE) |= 0xff; |
395 | if (chip >= 0) |
396 | GPIO(BOARD_NAND_NCE) &= ~ (1 << chip); |
397 | } |
398 | </programlisting> |
399 | <para> |
400 | <emphasis>Address lines based example.</emphasis> |
401 | Its assumed that the nCE pins are connected to an |
402 | address decoder. |
403 | </para> |
404 | <programlisting> |
405 | static void board_select_chip (struct mtd_info *mtd, int chip) |
406 | { |
407 | struct nand_chip *this = (struct nand_chip *) mtd->priv; |
408 | |
409 | /* Deselect all chips */ |
410 | this->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; |
411 | this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; |
412 | switch (chip) { |
413 | case 0: |
414 | this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; |
415 | this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; |
416 | break; |
417 | .... |
418 | case n: |
419 | this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; |
420 | this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; |
421 | break; |
422 | } |
423 | } |
424 | </programlisting> |
425 | </sect1> |
426 | <sect1> |
427 | <title>Hardware ECC support</title> |
428 | <sect2> |
429 | <title>Functions and constants</title> |
430 | <para> |
431 | The nand driver supports three different types of |
432 | hardware ECC. |
433 | <itemizedlist> |
434 | <listitem><para>NAND_ECC_HW3_256</para><para> |
435 | Hardware ECC generator providing 3 bytes ECC per |
436 | 256 byte. |
437 | </para> </listitem> |
438 | <listitem><para>NAND_ECC_HW3_512</para><para> |
439 | Hardware ECC generator providing 3 bytes ECC per |
440 | 512 byte. |
441 | </para> </listitem> |
442 | <listitem><para>NAND_ECC_HW6_512</para><para> |
443 | Hardware ECC generator providing 6 bytes ECC per |
444 | 512 byte. |
445 | </para> </listitem> |
446 | <listitem><para>NAND_ECC_HW8_512</para><para> |
447 | Hardware ECC generator providing 6 bytes ECC per |
448 | 512 byte. |
449 | </para> </listitem> |
450 | </itemizedlist> |
451 | If your hardware generator has a different functionality |
452 | add it at the appropriate place in nand_base.c |
453 | </para> |
454 | <para> |
455 | The board driver must provide following functions: |
456 | <itemizedlist> |
457 | <listitem><para>enable_hwecc</para><para> |
458 | This function is called before reading / writing to |
459 | the chip. Reset or initialize the hardware generator |
460 | in this function. The function is called with an |
461 | argument which let you distinguish between read |
462 | and write operations. |
463 | </para> </listitem> |
464 | <listitem><para>calculate_ecc</para><para> |
465 | This function is called after read / write from / to |
466 | the chip. Transfer the ECC from the hardware to |
467 | the buffer. If the option NAND_HWECC_SYNDROME is set |
468 | then the function is only called on write. See below. |
469 | </para> </listitem> |
470 | <listitem><para>correct_data</para><para> |
471 | In case of an ECC error this function is called for |
472 | error detection and correction. Return 1 respectively 2 |
473 | in case the error can be corrected. If the error is |
474 | not correctable return -1. If your hardware generator |
475 | matches the default algorithm of the nand_ecc software |
476 | generator then use the correction function provided |
477 | by nand_ecc instead of implementing duplicated code. |
478 | </para> </listitem> |
479 | </itemizedlist> |
480 | </para> |
481 | </sect2> |
482 | <sect2> |
483 | <title>Hardware ECC with syndrome calculation</title> |
484 | <para> |
485 | Many hardware ECC implementations provide Reed-Solomon |
486 | codes and calculate an error syndrome on read. The syndrome |
487 | must be converted to a standard Reed-Solomon syndrome |
488 | before calling the error correction code in the generic |
489 | Reed-Solomon library. |
490 | </para> |
491 | <para> |
492 | The ECC bytes must be placed immidiately after the data |
493 | bytes in order to make the syndrome generator work. This |
494 | is contrary to the usual layout used by software ECC. The |
495 | seperation of data and out of band area is not longer |
496 | possible. The nand driver code handles this layout and |
497 | the remaining free bytes in the oob area are managed by |
498 | the autoplacement code. Provide a matching oob-layout |
499 | in this case. See rts_from4.c and diskonchip.c for |
500 | implementation reference. In those cases we must also |
501 | use bad block tables on FLASH, because the ECC layout is |
502 | interferring with the bad block marker positions. |
503 | See bad block table support for details. |
504 | </para> |
505 | </sect2> |
506 | </sect1> |
507 | <sect1> |
508 | <title>Bad block table support</title> |
509 | <para> |
510 | Most NAND chips mark the bad blocks at a defined |
511 | position in the spare area. Those blocks must |
512 | not be erased under any circumstances as the bad |
513 | block information would be lost. |
514 | It is possible to check the bad block mark each |
515 | time when the blocks are accessed by reading the |
516 | spare area of the first page in the block. This |
517 | is time consuming so a bad block table is used. |
518 | </para> |
519 | <para> |
520 | The nand driver supports various types of bad block |
521 | tables. |
522 | <itemizedlist> |
523 | <listitem><para>Per device</para><para> |
524 | The bad block table contains all bad block information |
525 | of the device which can consist of multiple chips. |
526 | </para> </listitem> |
527 | <listitem><para>Per chip</para><para> |
528 | A bad block table is used per chip and contains the |
529 | bad block information for this particular chip. |
530 | </para> </listitem> |
531 | <listitem><para>Fixed offset</para><para> |
532 | The bad block table is located at a fixed offset |
533 | in the chip (device). This applies to various |
534 | DiskOnChip devices. |
535 | </para> </listitem> |
536 | <listitem><para>Automatic placed</para><para> |
537 | The bad block table is automatically placed and |
538 | detected either at the end or at the beginning |
539 | of a chip (device) |
540 | </para> </listitem> |
541 | <listitem><para>Mirrored tables</para><para> |
542 | The bad block table is mirrored on the chip (device) to |
543 | allow updates of the bad block table without data loss. |
544 | </para> </listitem> |
545 | </itemizedlist> |
546 | </para> |
547 | <para> |
548 | nand_scan() calls the function nand_default_bbt(). |
549 | nand_default_bbt() selects appropriate default |
550 | bad block table desriptors depending on the chip information |
551 | which was retrieved by nand_scan(). |
552 | </para> |
553 | <para> |
554 | The standard policy is scanning the device for bad |
555 | blocks and build a ram based bad block table which |
556 | allows faster access than always checking the |
557 | bad block information on the flash chip itself. |
558 | </para> |
559 | <sect2> |
560 | <title>Flash based tables</title> |
561 | <para> |
562 | It may be desired or neccecary to keep a bad block table in FLASH. |
563 | For AG-AND chips this is mandatory, as they have no factory marked |
564 | bad blocks. They have factory marked good blocks. The marker pattern |
565 | is erased when the block is erased to be reused. So in case of |
566 | powerloss before writing the pattern back to the chip this block |
567 | would be lost and added to the bad blocks. Therefor we scan the |
568 | chip(s) when we detect them the first time for good blocks and |
569 | store this information in a bad block table before erasing any |
570 | of the blocks. |
571 | </para> |
572 | <para> |
573 | The blocks in which the tables are stored are procteted against |
574 | accidental access by marking them bad in the memory bad block |
575 | table. The bad block table managment functions are allowed |
576 | to circumvernt this protection. |
577 | </para> |
578 | <para> |
579 | The simplest way to activate the FLASH based bad block table support |
580 | is to set the option NAND_USE_FLASH_BBT in the option field of |
581 | the nand chip structure before calling nand_scan(). For AG-AND |
582 | chips is this done by default. |
583 | This activates the default FLASH based bad block table functionality |
584 | of the NAND driver. The default bad block table options are |
585 | <itemizedlist> |
586 | <listitem><para>Store bad block table per chip</para></listitem> |
587 | <listitem><para>Use 2 bits per block</para></listitem> |
588 | <listitem><para>Automatic placement at the end of the chip</para></listitem> |
589 | <listitem><para>Use mirrored tables with version numbers</para></listitem> |
590 | <listitem><para>Reserve 4 blocks at the end of the chip</para></listitem> |
591 | </itemizedlist> |
592 | </para> |
593 | </sect2> |
594 | <sect2> |
595 | <title>User defined tables</title> |
596 | <para> |
597 | User defined tables are created by filling out a |
598 | nand_bbt_descr structure and storing the pointer in the |
599 | nand_chip structure member bbt_td before calling nand_scan(). |
600 | If a mirror table is neccecary a second structure must be |
601 | created and a pointer to this structure must be stored |
602 | in bbt_md inside the nand_chip structure. If the bbt_md |
603 | member is set to NULL then only the main table is used |
604 | and no scan for the mirrored table is performed. |
605 | </para> |
606 | <para> |
607 | The most important field in the nand_bbt_descr structure |
608 | is the options field. The options define most of the |
609 | table properties. Use the predefined constants from |
610 | nand.h to define the options. |
611 | <itemizedlist> |
612 | <listitem><para>Number of bits per block</para> |
613 | <para>The supported number of bits is 1, 2, 4, 8.</para></listitem> |
614 | <listitem><para>Table per chip</para> |
615 | <para>Setting the constant NAND_BBT_PERCHIP selects that |
616 | a bad block table is managed for each chip in a chip array. |
617 | If this option is not set then a per device bad block table |
618 | is used.</para></listitem> |
619 | <listitem><para>Table location is absolute</para> |
620 | <para>Use the option constant NAND_BBT_ABSPAGE and |
621 | define the absolute page number where the bad block |
622 | table starts in the field pages. If you have selected bad block |
623 | tables per chip and you have a multi chip array then the start page |
624 | must be given for each chip in the chip array. Note: there is no scan |
625 | for a table ident pattern performed, so the fields |
626 | pattern, veroffs, offs, len can be left uninitialized</para></listitem> |
627 | <listitem><para>Table location is automatically detected</para> |
628 | <para>The table can either be located in the first or the last good |
629 | blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place |
630 | the bad block table at the end of the chip (device). The |
631 | bad block tables are marked and identified by a pattern which |
632 | is stored in the spare area of the first page in the block which |
633 | holds the bad block table. Store a pointer to the pattern |
634 | in the pattern field. Further the length of the pattern has to be |
635 | stored in len and the offset in the spare area must be given |
636 | in the offs member of the nand_bbt_descr stucture. For mirrored |
637 | bad block tables different patterns are mandatory.</para></listitem> |
638 | <listitem><para>Table creation</para> |
639 | <para>Set the option NAND_BBT_CREATE to enable the table creation |
640 | if no table can be found during the scan. Usually this is done only |
641 | once if a new chip is found. </para></listitem> |
642 | <listitem><para>Table write support</para> |
643 | <para>Set the option NAND_BBT_WRITE to enable the table write support. |
644 | This allows the update of the bad block table(s) in case a block has |
645 | to be marked bad due to wear. The MTD interface function block_markbad |
646 | is calling the update function of the bad block table. If the write |
647 | support is enabled then the table is updated on FLASH.</para> |
648 | <para> |
649 | Note: Write support should only be enabled for mirrored tables with |
650 | version control. |
651 | </para></listitem> |
652 | <listitem><para>Table version control</para> |
653 | <para>Set the option NAND_BBT_VERSION to enable the table version control. |
654 | It's highly recommended to enable this for mirrored tables with write |
655 | support. It makes sure that the risk of loosing the bad block |
656 | table information is reduced to the loss of the information about the |
657 | one worn out block which should be marked bad. The version is stored in |
658 | 4 consecutive bytes in the spare area of the device. The position of |
659 | the version number is defined by the member veroffs in the bad block table |
660 | descriptor.</para></listitem> |
661 | <listitem><para>Save block contents on write</para> |
662 | <para> |
663 | In case that the block which holds the bad block table does contain |
664 | other useful information, set the option NAND_BBT_SAVECONTENT. When |
665 | the bad block table is written then the whole block is read the bad |
666 | block table is updated and the block is erased and everything is |
667 | written back. If this option is not set only the bad block table |
668 | is written and everything else in the block is ignored and erased. |
669 | </para></listitem> |
670 | <listitem><para>Number of reserved blocks</para> |
671 | <para> |
672 | For automatic placement some blocks must be reserved for |
673 | bad block table storage. The number of reserved blocks is defined |
674 | in the maxblocks member of the babd block table description structure. |
675 | Reserving 4 blocks for mirrored tables should be a reasonable number. |
676 | This also limits the number of blocks which are scanned for the bad |
677 | block table ident pattern. |
678 | </para></listitem> |
679 | </itemizedlist> |
680 | </para> |
681 | </sect2> |
682 | </sect1> |
683 | <sect1> |
684 | <title>Spare area (auto)placement</title> |
685 | <para> |
686 | The nand driver implements different possibilities for |
687 | placement of filesystem data in the spare area, |
688 | <itemizedlist> |
689 | <listitem><para>Placement defined by fs driver</para></listitem> |
690 | <listitem><para>Automatic placement</para></listitem> |
691 | </itemizedlist> |
692 | The default placement function is automatic placement. The |
693 | nand driver has built in default placement schemes for the |
694 | various chiptypes. If due to hardware ECC functionality the |
695 | default placement does not fit then the board driver can |
696 | provide a own placement scheme. |
697 | </para> |
698 | <para> |
699 | File system drivers can provide a own placement scheme which |
700 | is used instead of the default placement scheme. |
701 | </para> |
702 | <para> |
703 | Placement schemes are defined by a nand_oobinfo structure |
704 | <programlisting> |
705 | struct nand_oobinfo { |
706 | int useecc; |
707 | int eccbytes; |
708 | int eccpos[24]; |
709 | int oobfree[8][2]; |
710 | }; |
711 | </programlisting> |
712 | <itemizedlist> |
713 | <listitem><para>useecc</para><para> |
714 | The useecc member controls the ecc and placement function. The header |
715 | file include/mtd/mtd-abi.h contains constants to select ecc and |
716 | placement. MTD_NANDECC_OFF switches off the ecc complete. This is |
717 | not recommended and available for testing and diagnosis only. |
718 | MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE |
719 | selects automatic placement. |
720 | </para></listitem> |
721 | <listitem><para>eccbytes</para><para> |
722 | The eccbytes member defines the number of ecc bytes per page. |
723 | </para></listitem> |
724 | <listitem><para>eccpos</para><para> |
725 | The eccpos array holds the byte offsets in the spare area where |
726 | the ecc codes are placed. |
727 | </para></listitem> |
728 | <listitem><para>oobfree</para><para> |
729 | The oobfree array defines the areas in the spare area which can be |
730 | used for automatic placement. The information is given in the format |
731 | {offset, size}. offset defines the start of the usable area, size the |
732 | length in bytes. More than one area can be defined. The list is terminated |
733 | by an {0, 0} entry. |
734 | </para></listitem> |
735 | </itemizedlist> |
736 | </para> |
737 | <sect2> |
738 | <title>Placement defined by fs driver</title> |
739 | <para> |
740 | The calling function provides a pointer to a nand_oobinfo |
741 | structure which defines the ecc placement. For writes the |
742 | caller must provide a spare area buffer along with the |
743 | data buffer. The spare area buffer size is (number of pages) * |
744 | (size of spare area). For reads the buffer size is |
745 | (number of pages) * ((size of spare area) + (number of ecc |
746 | steps per page) * sizeof (int)). The driver stores the |
747 | result of the ecc check for each tuple in the spare buffer. |
748 | The storage sequence is |
749 | </para> |
750 | <para> |
751 | <spare data page 0><ecc result 0>...<ecc result n> |
752 | </para> |
753 | <para> |
754 | ... |
755 | </para> |
756 | <para> |
757 | <spare data page n><ecc result 0>...<ecc result n> |
758 | </para> |
759 | <para> |
760 | This is a legacy mode used by YAFFS1. |
761 | </para> |
762 | <para> |
763 | If the spare area buffer is NULL then only the ECC placement is |
764 | done according to the given scheme in the nand_oobinfo structure. |
765 | </para> |
766 | </sect2> |
767 | <sect2> |
768 | <title>Automatic placement</title> |
769 | <para> |
770 | Automatic placement uses the built in defaults to place the |
771 | ecc bytes in the spare area. If filesystem data have to be stored / |
772 | read into the spare area then the calling function must provide a |
773 | buffer. The buffer size per page is determined by the oobfree array in |
774 | the nand_oobinfo structure. |
775 | </para> |
776 | <para> |
777 | If the spare area buffer is NULL then only the ECC placement is |
778 | done according to the default builtin scheme. |
779 | </para> |
780 | </sect2> |
781 | <sect2> |
782 | <title>User space placement selection</title> |
783 | <para> |
784 | All non ecc functions like mtd->read and mtd->write use an internal |
785 | structure, which can be set by an ioctl. This structure is preset |
786 | to the autoplacement default. |
787 | <programlisting> |
788 | ioctl (fd, MEMSETOOBSEL, oobsel); |
789 | </programlisting> |
790 | oobsel is a pointer to a user supplied structure of type |
791 | nand_oobconfig. The contents of this structure must match the |
792 | criteria of the filesystem, which will be used. See an example in utils/nandwrite.c. |
793 | </para> |
794 | </sect2> |
795 | </sect1> |
796 | <sect1> |
797 | <title>Spare area autoplacement default schemes</title> |
798 | <sect2> |
799 | <title>256 byte pagesize</title> |
800 | <informaltable><tgroup cols="3"><tbody> |
801 | <row> |
802 | <entry>Offset</entry> |
803 | <entry>Content</entry> |
804 | <entry>Comment</entry> |
805 | </row> |
806 | <row> |
807 | <entry>0x00</entry> |
808 | <entry>ECC byte 0</entry> |
809 | <entry>Error correction code byte 0</entry> |
810 | </row> |
811 | <row> |
812 | <entry>0x01</entry> |
813 | <entry>ECC byte 1</entry> |
814 | <entry>Error correction code byte 1</entry> |
815 | </row> |
816 | <row> |
817 | <entry>0x02</entry> |
818 | <entry>ECC byte 2</entry> |
819 | <entry>Error correction code byte 2</entry> |
820 | </row> |
821 | <row> |
822 | <entry>0x03</entry> |
823 | <entry>Autoplace 0</entry> |
824 | <entry></entry> |
825 | </row> |
826 | <row> |
827 | <entry>0x04</entry> |
828 | <entry>Autoplace 1</entry> |
829 | <entry></entry> |
830 | </row> |
831 | <row> |
832 | <entry>0x05</entry> |
833 | <entry>Bad block marker</entry> |
834 | <entry>If any bit in this byte is zero, then this block is bad. |
835 | This applies only to the first page in a block. In the remaining |
836 | pages this byte is reserved</entry> |
837 | </row> |
838 | <row> |
839 | <entry>0x06</entry> |
840 | <entry>Autoplace 2</entry> |
841 | <entry></entry> |
842 | </row> |
843 | <row> |
844 | <entry>0x07</entry> |
845 | <entry>Autoplace 3</entry> |
846 | <entry></entry> |
847 | </row> |
848 | </tbody></tgroup></informaltable> |
849 | </sect2> |
850 | <sect2> |
851 | <title>512 byte pagesize</title> |
852 | <informaltable><tgroup cols="3"><tbody> |
853 | <row> |
854 | <entry>Offset</entry> |
855 | <entry>Content</entry> |
856 | <entry>Comment</entry> |
857 | </row> |
858 | <row> |
859 | <entry>0x00</entry> |
860 | <entry>ECC byte 0</entry> |
861 | <entry>Error correction code byte 0 of the lower 256 Byte data in |
862 | this page</entry> |
863 | </row> |
864 | <row> |
865 | <entry>0x01</entry> |
866 | <entry>ECC byte 1</entry> |
867 | <entry>Error correction code byte 1 of the lower 256 Bytes of data |
868 | in this page</entry> |
869 | </row> |
870 | <row> |
871 | <entry>0x02</entry> |
872 | <entry>ECC byte 2</entry> |
873 | <entry>Error correction code byte 2 of the lower 256 Bytes of data |
874 | in this page</entry> |
875 | </row> |
876 | <row> |
877 | <entry>0x03</entry> |
878 | <entry>ECC byte 3</entry> |
879 | <entry>Error correction code byte 0 of the upper 256 Bytes of data |
880 | in this page</entry> |
881 | </row> |
882 | <row> |
883 | <entry>0x04</entry> |
884 | <entry>reserved</entry> |
885 | <entry>reserved</entry> |
886 | </row> |
887 | <row> |
888 | <entry>0x05</entry> |
889 | <entry>Bad block marker</entry> |
890 | <entry>If any bit in this byte is zero, then this block is bad. |
891 | This applies only to the first page in a block. In the remaining |
892 | pages this byte is reserved</entry> |
893 | </row> |
894 | <row> |
895 | <entry>0x06</entry> |
896 | <entry>ECC byte 4</entry> |
897 | <entry>Error correction code byte 1 of the upper 256 Bytes of data |
898 | in this page</entry> |
899 | </row> |
900 | <row> |
901 | <entry>0x07</entry> |
902 | <entry>ECC byte 5</entry> |
903 | <entry>Error correction code byte 2 of the upper 256 Bytes of data |
904 | in this page</entry> |
905 | </row> |
906 | <row> |
907 | <entry>0x08 - 0x0F</entry> |
908 | <entry>Autoplace 0 - 7</entry> |
909 | <entry></entry> |
910 | </row> |
911 | </tbody></tgroup></informaltable> |
912 | </sect2> |
913 | <sect2> |
914 | <title>2048 byte pagesize</title> |
915 | <informaltable><tgroup cols="3"><tbody> |
916 | <row> |
917 | <entry>Offset</entry> |
918 | <entry>Content</entry> |
919 | <entry>Comment</entry> |
920 | </row> |
921 | <row> |
922 | <entry>0x00</entry> |
923 | <entry>Bad block marker</entry> |
924 | <entry>If any bit in this byte is zero, then this block is bad. |
925 | This applies only to the first page in a block. In the remaining |
926 | pages this byte is reserved</entry> |
927 | </row> |
928 | <row> |
929 | <entry>0x01</entry> |
930 | <entry>Reserved</entry> |
931 | <entry>Reserved</entry> |
932 | </row> |
933 | <row> |
934 | <entry>0x02-0x27</entry> |
935 | <entry>Autoplace 0 - 37</entry> |
936 | <entry></entry> |
937 | </row> |
938 | <row> |
939 | <entry>0x28</entry> |
940 | <entry>ECC byte 0</entry> |
941 | <entry>Error correction code byte 0 of the first 256 Byte data in |
942 | this page</entry> |
943 | </row> |
944 | <row> |
945 | <entry>0x29</entry> |
946 | <entry>ECC byte 1</entry> |
947 | <entry>Error correction code byte 1 of the first 256 Bytes of data |
948 | in this page</entry> |
949 | </row> |
950 | <row> |
951 | <entry>0x2A</entry> |
952 | <entry>ECC byte 2</entry> |
953 | <entry>Error correction code byte 2 of the first 256 Bytes data in |
954 | this page</entry> |
955 | </row> |
956 | <row> |
957 | <entry>0x2B</entry> |
958 | <entry>ECC byte 3</entry> |
959 | <entry>Error correction code byte 0 of the second 256 Bytes of data |
960 | in this page</entry> |
961 | </row> |
962 | <row> |
963 | <entry>0x2C</entry> |
964 | <entry>ECC byte 4</entry> |
965 | <entry>Error correction code byte 1 of the second 256 Bytes of data |
966 | in this page</entry> |
967 | </row> |
968 | <row> |
969 | <entry>0x2D</entry> |
970 | <entry>ECC byte 5</entry> |
971 | <entry>Error correction code byte 2 of the second 256 Bytes of data |
972 | in this page</entry> |
973 | </row> |
974 | <row> |
975 | <entry>0x2E</entry> |
976 | <entry>ECC byte 6</entry> |
977 | <entry>Error correction code byte 0 of the third 256 Bytes of data |
978 | in this page</entry> |
979 | </row> |
980 | <row> |
981 | <entry>0x2F</entry> |
982 | <entry>ECC byte 7</entry> |
983 | <entry>Error correction code byte 1 of the third 256 Bytes of data |
984 | in this page</entry> |
985 | </row> |
986 | <row> |
987 | <entry>0x30</entry> |
988 | <entry>ECC byte 8</entry> |
989 | <entry>Error correction code byte 2 of the third 256 Bytes of data |
990 | in this page</entry> |
991 | </row> |
992 | <row> |
993 | <entry>0x31</entry> |
994 | <entry>ECC byte 9</entry> |
995 | <entry>Error correction code byte 0 of the fourth 256 Bytes of data |
996 | in this page</entry> |
997 | </row> |
998 | <row> |
999 | <entry>0x32</entry> |
1000 | <entry>ECC byte 10</entry> |
1001 | <entry>Error correction code byte 1 of the fourth 256 Bytes of data |
1002 | in this page</entry> |
1003 | </row> |
1004 | <row> |
1005 | <entry>0x33</entry> |
1006 | <entry>ECC byte 11</entry> |
1007 | <entry>Error correction code byte 2 of the fourth 256 Bytes of data |
1008 | in this page</entry> |
1009 | </row> |
1010 | <row> |
1011 | <entry>0x34</entry> |
1012 | <entry>ECC byte 12</entry> |
1013 | <entry>Error correction code byte 0 of the fifth 256 Bytes of data |
1014 | in this page</entry> |
1015 | </row> |
1016 | <row> |
1017 | <entry>0x35</entry> |
1018 | <entry>ECC byte 13</entry> |
1019 | <entry>Error correction code byte 1 of the fifth 256 Bytes of data |
1020 | in this page</entry> |
1021 | </row> |
1022 | <row> |
1023 | <entry>0x36</entry> |
1024 | <entry>ECC byte 14</entry> |
1025 | <entry>Error correction code byte 2 of the fifth 256 Bytes of data |
1026 | in this page</entry> |
1027 | </row> |
1028 | <row> |
1029 | <entry>0x37</entry> |
1030 | <entry>ECC byte 15</entry> |
1031 | <entry>Error correction code byte 0 of the sixt 256 Bytes of data |
1032 | in this page</entry> |
1033 | </row> |
1034 | <row> |
1035 | <entry>0x38</entry> |
1036 | <entry>ECC byte 16</entry> |
1037 | <entry>Error correction code byte 1 of the sixt 256 Bytes of data |
1038 | in this page</entry> |
1039 | </row> |
1040 | <row> |
1041 | <entry>0x39</entry> |
1042 | <entry>ECC byte 17</entry> |
1043 | <entry>Error correction code byte 2 of the sixt 256 Bytes of data |
1044 | in this page</entry> |
1045 | </row> |
1046 | <row> |
1047 | <entry>0x3A</entry> |
1048 | <entry>ECC byte 18</entry> |
1049 | <entry>Error correction code byte 0 of the seventh 256 Bytes of |
1050 | data in this page</entry> |
1051 | </row> |
1052 | <row> |
1053 | <entry>0x3B</entry> |
1054 | <entry>ECC byte 19</entry> |
1055 | <entry>Error correction code byte 1 of the seventh 256 Bytes of |
1056 | data in this page</entry> |
1057 | </row> |
1058 | <row> |
1059 | <entry>0x3C</entry> |
1060 | <entry>ECC byte 20</entry> |
1061 | <entry>Error correction code byte 2 of the seventh 256 Bytes of |
1062 | data in this page</entry> |
1063 | </row> |
1064 | <row> |
1065 | <entry>0x3D</entry> |
1066 | <entry>ECC byte 21</entry> |
1067 | <entry>Error correction code byte 0 of the eigth 256 Bytes of data |
1068 | in this page</entry> |
1069 | </row> |
1070 | <row> |
1071 | <entry>0x3E</entry> |
1072 | <entry>ECC byte 22</entry> |
1073 | <entry>Error correction code byte 1 of the eigth 256 Bytes of data |
1074 | in this page</entry> |
1075 | </row> |
1076 | <row> |
1077 | <entry>0x3F</entry> |
1078 | <entry>ECC byte 23</entry> |
1079 | <entry>Error correction code byte 2 of the eigth 256 Bytes of data |
1080 | in this page</entry> |
1081 | </row> |
1082 | </tbody></tgroup></informaltable> |
1083 | </sect2> |
1084 | </sect1> |
1085 | </chapter> |
1086 | |
1087 | <chapter id="filesystems"> |
1088 | <title>Filesystem support</title> |
1089 | <para> |
1090 | The NAND driver provides all neccecary functions for a |
1091 | filesystem via the MTD interface. |
1092 | </para> |
1093 | <para> |
1094 | Filesystems must be aware of the NAND pecularities and |
1095 | restrictions. One major restrictions of NAND Flash is, that you cannot |
1096 | write as often as you want to a page. The consecutive writes to a page, |
1097 | before erasing it again, are restricted to 1-3 writes, depending on the |
1098 | manufacturers specifications. This applies similar to the spare area. |
1099 | </para> |
1100 | <para> |
1101 | Therefor NAND aware filesystems must either write in page size chunks |
1102 | or hold a writebuffer to collect smaller writes until they sum up to |
1103 | pagesize. Available NAND aware filesystems: JFFS2, YAFFS. |
1104 | </para> |
1105 | <para> |
1106 | The spare area usage to store filesystem data is controlled by |
1107 | the spare area placement functionality which is described in one |
1108 | of the earlier chapters. |
1109 | </para> |
1110 | </chapter> |
1111 | <chapter id="tools"> |
1112 | <title>Tools</title> |
1113 | <para> |
1114 | The MTD project provides a couple of helpful tools to handle NAND Flash. |
1115 | <itemizedlist> |
1116 | <listitem><para>flasherase, flasheraseall: Erase and format FLASH partitions</para></listitem> |
1117 | <listitem><para>nandwrite: write filesystem images to NAND FLASH</para></listitem> |
1118 | <listitem><para>nanddump: dump the contents of a NAND FLASH partitions</para></listitem> |
1119 | </itemizedlist> |
1120 | </para> |
1121 | <para> |
1122 | These tools are aware of the NAND restrictions. Please use those tools |
1123 | instead of complaining about errors which are caused by non NAND aware |
1124 | access methods. |
1125 | </para> |
1126 | </chapter> |
1127 | |
1128 | <chapter id="defines"> |
1129 | <title>Constants</title> |
1130 | <para> |
1131 | This chapter describes the constants which might be relevant for a driver developer. |
1132 | </para> |
1133 | <sect1> |
1134 | <title>Chip option constants</title> |
1135 | <sect2> |
1136 | <title>Constants for chip id table</title> |
1137 | <para> |
1138 | These constants are defined in nand.h. They are ored together to describe |
1139 | the chip functionality. |
1140 | <programlisting> |
1141 | /* Chip can not auto increment pages */ |
1142 | #define NAND_NO_AUTOINCR 0x00000001 |
1143 | /* Buswitdh is 16 bit */ |
1144 | #define NAND_BUSWIDTH_16 0x00000002 |
1145 | /* Device supports partial programming without padding */ |
1146 | #define NAND_NO_PADDING 0x00000004 |
1147 | /* Chip has cache program function */ |
1148 | #define NAND_CACHEPRG 0x00000008 |
1149 | /* Chip has copy back function */ |
1150 | #define NAND_COPYBACK 0x00000010 |
1151 | /* AND Chip which has 4 banks and a confusing page / block |
1152 | * assignment. See Renesas datasheet for further information */ |
1153 | #define NAND_IS_AND 0x00000020 |
1154 | /* Chip has a array of 4 pages which can be read without |
1155 | * additional ready /busy waits */ |
1156 | #define NAND_4PAGE_ARRAY 0x00000040 |
1157 | </programlisting> |
1158 | </para> |
1159 | </sect2> |
1160 | <sect2> |
1161 | <title>Constants for runtime options</title> |
1162 | <para> |
1163 | These constants are defined in nand.h. They are ored together to describe |
1164 | the functionality. |
1165 | <programlisting> |
1166 | /* Use a flash based bad block table. This option is parsed by the |
1167 | * default bad block table function (nand_default_bbt). */ |
1168 | #define NAND_USE_FLASH_BBT 0x00010000 |
1169 | /* The hw ecc generator provides a syndrome instead a ecc value on read |
1170 | * This can only work if we have the ecc bytes directly behind the |
1171 | * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */ |
1172 | #define NAND_HWECC_SYNDROME 0x00020000 |
1173 | </programlisting> |
1174 | </para> |
1175 | </sect2> |
1176 | </sect1> |
1177 | |
1178 | <sect1> |
1179 | <title>ECC selection constants</title> |
1180 | <para> |
1181 | Use these constants to select the ECC algorithm. |
1182 | <programlisting> |
1183 | /* No ECC. Usage is not recommended ! */ |
1184 | #define NAND_ECC_NONE 0 |
1185 | /* Software ECC 3 byte ECC per 256 Byte data */ |
1186 | #define NAND_ECC_SOFT 1 |
1187 | /* Hardware ECC 3 byte ECC per 256 Byte data */ |
1188 | #define NAND_ECC_HW3_256 2 |
1189 | /* Hardware ECC 3 byte ECC per 512 Byte data */ |
1190 | #define NAND_ECC_HW3_512 3 |
1191 | /* Hardware ECC 6 byte ECC per 512 Byte data */ |
1192 | #define NAND_ECC_HW6_512 4 |
1193 | /* Hardware ECC 6 byte ECC per 512 Byte data */ |
1194 | #define NAND_ECC_HW8_512 6 |
1195 | </programlisting> |
1196 | </para> |
1197 | </sect1> |
1198 | |
1199 | <sect1> |
1200 | <title>Hardware control related constants</title> |
1201 | <para> |
1202 | These constants describe the requested hardware access function when |
1203 | the boardspecific hardware control function is called |
1204 | <programlisting> |
1205 | /* Select the chip by setting nCE to low */ |
1206 | #define NAND_CTL_SETNCE 1 |
1207 | /* Deselect the chip by setting nCE to high */ |
1208 | #define NAND_CTL_CLRNCE 2 |
1209 | /* Select the command latch by setting CLE to high */ |
1210 | #define NAND_CTL_SETCLE 3 |
1211 | /* Deselect the command latch by setting CLE to low */ |
1212 | #define NAND_CTL_CLRCLE 4 |
1213 | /* Select the address latch by setting ALE to high */ |
1214 | #define NAND_CTL_SETALE 5 |
1215 | /* Deselect the address latch by setting ALE to low */ |
1216 | #define NAND_CTL_CLRALE 6 |
1217 | /* Set write protection by setting WP to high. Not used! */ |
1218 | #define NAND_CTL_SETWP 7 |
1219 | /* Clear write protection by setting WP to low. Not used! */ |
1220 | #define NAND_CTL_CLRWP 8 |
1221 | </programlisting> |
1222 | </para> |
1223 | </sect1> |
1224 | |
1225 | <sect1> |
1226 | <title>Bad block table related constants</title> |
1227 | <para> |
1228 | These constants describe the options used for bad block |
1229 | table descriptors. |
1230 | <programlisting> |
1231 | /* Options for the bad block table descriptors */ |
1232 | |
1233 | /* The number of bits used per block in the bbt on the device */ |
1234 | #define NAND_BBT_NRBITS_MSK 0x0000000F |
1235 | #define NAND_BBT_1BIT 0x00000001 |
1236 | #define NAND_BBT_2BIT 0x00000002 |
1237 | #define NAND_BBT_4BIT 0x00000004 |
1238 | #define NAND_BBT_8BIT 0x00000008 |
1239 | /* The bad block table is in the last good block of the device */ |
1240 | #define NAND_BBT_LASTBLOCK 0x00000010 |
1241 | /* The bbt is at the given page, else we must scan for the bbt */ |
1242 | #define NAND_BBT_ABSPAGE 0x00000020 |
1243 | /* The bbt is at the given page, else we must scan for the bbt */ |
1244 | #define NAND_BBT_SEARCH 0x00000040 |
1245 | /* bbt is stored per chip on multichip devices */ |
1246 | #define NAND_BBT_PERCHIP 0x00000080 |
1247 | /* bbt has a version counter at offset veroffs */ |
1248 | #define NAND_BBT_VERSION 0x00000100 |
1249 | /* Create a bbt if none axists */ |
1250 | #define NAND_BBT_CREATE 0x00000200 |
1251 | /* Search good / bad pattern through all pages of a block */ |
1252 | #define NAND_BBT_SCANALLPAGES 0x00000400 |
1253 | /* Scan block empty during good / bad block scan */ |
1254 | #define NAND_BBT_SCANEMPTY 0x00000800 |
1255 | /* Write bbt if neccecary */ |
1256 | #define NAND_BBT_WRITE 0x00001000 |
1257 | /* Read and write back block contents when writing bbt */ |
1258 | #define NAND_BBT_SAVECONTENT 0x00002000 |
1259 | </programlisting> |
1260 | </para> |
1261 | </sect1> |
1262 | |
1263 | </chapter> |
1264 | |
1265 | <chapter id="structs"> |
1266 | <title>Structures</title> |
1267 | <para> |
1268 | This chapter contains the autogenerated documentation of the structures which are |
1269 | used in the NAND driver and might be relevant for a driver developer. Each |
1270 | struct member has a short description which is marked with an [XXX] identifier. |
1271 | See the chapter "Documentation hints" for an explanation. |
1272 | </para> |
1273 | !Iinclude/linux/mtd/nand.h |
1274 | </chapter> |
1275 | |
1276 | <chapter id="pubfunctions"> |
1277 | <title>Public Functions Provided</title> |
1278 | <para> |
1279 | This chapter contains the autogenerated documentation of the NAND kernel API functions |
1280 | which are exported. Each function has a short description which is marked with an [XXX] identifier. |
1281 | See the chapter "Documentation hints" for an explanation. |
1282 | </para> |
1283 | !Edrivers/mtd/nand/nand_base.c |
1284 | !Edrivers/mtd/nand/nand_bbt.c |
1285 | !Edrivers/mtd/nand/nand_ecc.c |
1286 | </chapter> |
1287 | |
1288 | <chapter id="intfunctions"> |
1289 | <title>Internal Functions Provided</title> |
1290 | <para> |
1291 | This chapter contains the autogenerated documentation of the NAND driver internal functions. |
1292 | Each function has a short description which is marked with an [XXX] identifier. |
1293 | See the chapter "Documentation hints" for an explanation. |
1294 | The functions marked with [DEFAULT] might be relevant for a board driver developer. |
1295 | </para> |
1296 | !Idrivers/mtd/nand/nand_base.c |
1297 | !Idrivers/mtd/nand/nand_bbt.c |
1298 | !Idrivers/mtd/nand/nand_ecc.c |
1299 | </chapter> |
1300 | |
1301 | <chapter id="credits"> |
1302 | <title>Credits</title> |
1303 | <para> |
1304 | The following people have contributed to the NAND driver: |
1305 | <orderedlist> |
1306 | <listitem><para>Steven J. Hill<email>sjhill@realitydiluted.com</email></para></listitem> |
1307 | <listitem><para>David Woodhouse<email>dwmw2@infradead.org</email></para></listitem> |
1308 | <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> |
1309 | </orderedlist> |
1310 | A lot of users have provided bugfixes, improvements and helping hands for testing. |
1311 | Thanks a lot. |
1312 | </para> |
1313 | <para> |
1314 | The following people have contributed to this document: |
1315 | <orderedlist> |
1316 | <listitem><para>Thomas Gleixner<email>tglx@linutronix.de</email></para></listitem> |
1317 | </orderedlist> |
1318 | </para> |
1319 | </chapter> |
1320 | </book> |