Documentation/driver-api/mtdnand.rst

10 The generic NAND driver supports almost all NAND and AG-AND based chips
31 --------------------------
33 The functions are marked with [XXX] identifiers in the short comment.
34 The identifiers explain the usage and scope of the functions. Following
37 -  [MTD Interface]
39    These functions provide the interface to the MTD kernel API. They are
43 -  [NAND Interface]
45    These functions are exported and provide the interface to the NAND
48 -  [GENERIC]
50    Generic functions are not replaceable and provide functionality which
53 -  [DEFAULT]
55    Default functions provide hardware related functionality which is
56    suitable for most of the implementations. These functions can be
57    replaced by the board driver if necessary. Those functions are called
59    can set the functions which should be replaced by board dependent
60    functions before calling nand_scan(). If the function pointer is
65 -------------------------------
71 -  [INTERN]
77 -  [REPLACEABLE]
79    Replaceable members hold hardware related functions which can be
80    provided by the board driver. The board driver can set the functions
81    which should be replaced by board dependent functions before calling
86 -  [BOARDSPECIFIC]
92 -  [OPTIONAL]
101 functions and fill out some really board dependent members in the nand
105 -------------
131 -----------------
150 -------------------------
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 ---------------------
200 and the function pointer this->legacy.dev_ready is set to NULL.
203 -------------
209 The structure(s) have to be zeroed out first and then filled with the
223             err = -ENOMEM;
224             goto out;
233             err = -EIO;
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;
255         goto out;
261     out:
268 -------------
294 Advanced board driver functions
298 For a list of functions which can be overridden by the board driver see
302 ---------------------
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 --------------------
360 Functions and constants
365 -  NAND_ECC_HW3_256
369 -  NAND_ECC_HW3_512
373 -  NAND_ECC_HW6_512
377 -  NAND_ECC_HW8_512
384 The board driver must provide following functions:
386 -  enable_hwecc
393 -  calculate_ecc
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
414 standard Reed-Solomon syndrome before calling the error correction code
415 in the generic Reed-Solomon library.
419 layout used by software ECC. The separation of data and out of band area
422 code. Provide a matching oob-layout in this case. See rts_from4.c and
429 -----------------------
440 -  Per device
445 -  Per chip
450 -  Fixed offset
455 -  Automatic placed
460 -  Mirrored tables
478 AG-AND chips this is mandatory, as they have no factory marked bad
488 bad block table management functions are allowed to circumvent this
493 nand chip structure before calling nand_scan(). For AG-AND chips is
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
511 User defined tables are created by filling out a nand_bbt_descr
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
571 -  Table version control
577    about the one worn out block which should be marked bad. The version
582 -  Save block contents on write
591 -  Number of reserved blocks
601 --------------------------
606 -  Placement defined by fs driver
608 -  Automatic placement
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
810 it again, are restricted to 1-3 writes, depending on the manufacturers
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
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
875      * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
880 -----------------------
899 ----------------------------------
923 ---------------------------------
961 .. kernel-doc:: include/linux/mtd/rawnand.h
964 Public Functions Provided
968 API functions which are exported. Each function has a short description
972 .. kernel-doc:: drivers/mtd/nand/raw/nand_base.c
975 Internal Functions Provided
979 internal functions. Each function has a short description which is
981 for an explanation. The functions marked with [DEFAULT] might be
984 .. kernel-doc:: drivers/mtd/nand/raw/nand_base.c
987 .. kernel-doc:: drivers/mtd/nand/raw/nand_bbt.c