Documentation/driver-api/mtdnand.rst

2 MTD NAND Driver Programming Interface
10 The generic NAND driver supports almost all NAND and AG-AND based chips
15 board drivers or filesystem drivers suitable for NAND devices.
31 --------------------------
37 -  [MTD Interface]
43 -  [NAND Interface]
45    These functions are exported and provide the interface to the NAND
48 -  [GENERIC]
53 -  [DEFAULT]
58    via pointers in the NAND chip description structure. The board driver
61    NULL on entry to nand_scan() then the pointer is set to the default
65 -------------------------------
71 -  [INTERN]
73    These members are for NAND driver internal use only and must not be
77 -  [REPLACEABLE]
82    nand_scan(). If the function pointer is NULL on entry to
86 -  [BOARDSPECIFIC]
92 -  [OPTIONAL]
95    The generic NAND driver code does not use this information.
101 functions and fill out some really board dependent members in the nand
105 -------------
109 using kmalloc or you can allocate it statically. The NAND chip structure
131 -----------------
140         { .name = "Flash partition 1",
143         { .name = "Flash partition 2",
150 -------------------------
153 NAND chip(s). The access can be done by GPIO pins or by address lines.
183             case NAND_CTL_SETCLE: this->legacy.IO_ADDR_W |= CLE_ADRR_BIT;  break;
184             case NAND_CTL_CLRCLE: this->legacy.IO_ADDR_W &= ~CLE_ADRR_BIT; break;
185             case NAND_CTL_SETALE: this->legacy.IO_ADDR_W |= ALE_ADRR_BIT;  break;
186             case NAND_CTL_CLRALE: this->legacy.IO_ADDR_W &= ~ALE_ADRR_BIT; break;
192 ---------------------
194 If the hardware interface has the ready busy pin of the NAND chip
200 and the function pointer this->legacy.dev_ready is set to NULL.
203 -------------
222             printk ("Unable to allocate NAND MTD device structure.\n");
223             err = -ENOMEM;
232             printk("Ioremap to access NAND chip failed\n");
233             err = -EIO;
237         /* Set address of NAND IO lines */
238         this->legacy.IO_ADDR_R = baseaddr;
239         this->legacy.IO_ADDR_W = baseaddr;
241         this->hwcontrol = board_hwcontrol;
243         this->legacy.chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
245         this->legacy.dev_ready = board_dev_ready;
246         this->eccmode = NAND_ECC_SOFT;
250             err = -ENXIO;
268 -------------
297 This chapter describes the advanced functionality of the NAND driver.
302 ---------------------
304 The nand driver can control chip arrays. Therefore the board driver must
311 The nand driver concatenates the chips to one virtual chip and provides
341         this->legacy.IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK;
342         this->legacy.IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK;
345             this->legacy.IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
346             this->legacy.IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
350             this->legacy.IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
351             this->legacy.IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
358 --------------------
363 The nand driver supports three different types of hardware ECC.
365 -  NAND_ECC_HW3_256
369 -  NAND_ECC_HW3_512
373 -  NAND_ECC_HW6_512
377 -  NAND_ECC_HW8_512
386 -  enable_hwecc
393 -  calculate_ecc
397    NAND_HWECC_SYNDROME is set then the function is only called on
400 -  correct_data
404    corrected. If the error is not correctable return -1. If your
412 Many hardware ECC implementations provide Reed-Solomon codes and
413 calculate an error syndrome on read. The syndrome must be converted to a
414 standard Reed-Solomon syndrome before calling the error correction code
415 in the generic Reed-Solomon library.
420 is not longer possible. The nand driver code handles this layout and the
422 code. Provide a matching oob-layout in this case. See rts_from4.c and
424 use bad block tables on FLASH, because the ECC layout is interfering
429 -----------------------
431 Most NAND chips mark the bad blocks at a defined position in the spare
438 The nand driver supports various types of bad block tables.
440 -  Per device
445 -  Per chip
450 -  Fixed offset
455 -  Automatic placed
460 -  Mirrored tables
462    The bad block table is mirrored on the chip (device) to allow updates
467 descriptors depending on the chip information which was retrieved by
472 checking the bad block information on the flash chip itself.
474 Flash based tables
477 It may be desired or necessary to keep a bad block table in FLASH. For
478 AG-AND chips this is mandatory, as they have no factory marked bad
491 The simplest way to activate the FLASH based bad block table support is
493 nand chip structure before calling nand_scan(). For AG-AND chips is
494 this done by default. This activates the default FLASH based bad block
495 table functionality of the NAND driver. The default bad block table
498 -  Store bad block table per chip
500 -  Use 2 bits per block
502 -  Automatic placement at the end of the chip
504 -  Use mirrored tables with version numbers
506 -  Reserve 4 blocks at the end of the chip
523 -  Number of bits per block
527 -  Table per chip
533 -  Table location is absolute
542 -  Table location is automatically detected
554 -  Table creation
560 -  Table write support
566    If the write support is enabled then the table is updated on FLASH.
571 -  Table version control
582 -  Save block contents on write
591 -  Number of reserved blocks
601 --------------------------
603 The nand driver implements different possibilities for placement of
606 -  Placement defined by fs driver
608 -  Automatic placement
610 The default placement function is automatic placement. The nand driver
630 -  useecc
633    file include/mtd/mtd-abi.h contains constants to select ecc and
639 -  eccbytes
643 -  eccpos
648 -  oobfree
691 ----------------------------------------
736 0x08 - 0x0F   Autoplace 0 - 7
750 0x02-0x27   Autoplace 0 - 37
804 The NAND driver provides all necessary functions for a filesystem via
807 Filesystems must be aware of the NAND peculiarities and restrictions.
808 One major restrictions of NAND Flash is, that you cannot write as often
810 it again, are restricted to 1-3 writes, depending on the manufacturers
813 Therefore NAND aware filesystems must either write in page size chunks
815 pagesize. Available NAND aware filesystems: JFFS2, YAFFS.
824 The MTD project provides a couple of helpful tools to handle NAND Flash.
826 -  flasherase, flasheraseall: Erase and format FLASH partitions
828 -  nandwrite: write filesystem images to NAND FLASH
830 -  nanddump: dump the contents of a NAND FLASH partitions
832 These tools are aware of the NAND restrictions. Please use those tools
833 instead of complaining about errors which are caused by non NAND aware
843 ---------------------
848 These constants are defined in rawnand.h. They are OR-ed together to
870 These constants are defined in rawnand.h. They are OR-ed together to
873     /* The hw ecc generator provides a syndrome instead a ecc value on read
875      * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
880 -----------------------
899 ----------------------------------
923 ---------------------------------
930     /* The number of bits used per block in the bbt on the device */
938     /* The bbt is at the given page, else we must scan for the bbt */
940     /* bbt is stored per chip on multichip devices */
942     /* bbt has a version counter at offset veroffs */
944     /* Create a bbt if none axists */
946     /* Write bbt if necessary */
948     /* Read and write back block contents when writing bbt */
956 which are used in the NAND driver and might be relevant for a driver
961 .. kernel-doc:: include/linux/mtd/rawnand.h
967 This chapter contains the autogenerated documentation of the NAND kernel
972 .. kernel-doc:: drivers/mtd/nand/raw/nand_base.c
978 This chapter contains the autogenerated documentation of the NAND driver
984 .. kernel-doc:: drivers/mtd/nand/raw/nand_base.c
987 .. kernel-doc:: drivers/mtd/nand/raw/nand_bbt.c
993 The following people have contributed to the NAND driver: