0001 =====================================
0002 MTD NAND Driver Programming Interface
0003 =====================================
0004
0005 :Author: Thomas Gleixner
0006
0007 Introduction
0008 ============
0009
0010 The generic NAND driver supports almost all NAND and AG-AND based chips
0011 and connects them to the Memory Technology Devices (MTD) subsystem of
0012 the Linux Kernel.
0013
0014 This documentation is provided for developers who want to implement
0015 board drivers or filesystem drivers suitable for NAND devices.
0016
0017 Known Bugs And Assumptions
0018 ==========================
0019
0020 None.
0021
0022 Documentation hints
0023 ===================
0024
0025 The function and structure docs are autogenerated. Each function and
0026 struct member has a short description which is marked with an [XXX]
0027 identifier. The following chapters explain the meaning of those
0028 identifiers.
0029
0030 Function identifiers [XXX]
0031 --------------------------
0032
0033 The functions are marked with [XXX] identifiers in the short comment.
0034 The identifiers explain the usage and scope of the functions. Following
0035 identifiers are used:
0036
0037 - [MTD Interface]
0038
0039 These functions provide the interface to the MTD kernel API. They are
0040 not replaceable and provide functionality which is complete hardware
0041 independent.
0042
0043 - [NAND Interface]
0044
0045 These functions are exported and provide the interface to the NAND
0046 kernel API.
0047
0048 - [GENERIC]
0049
0050 Generic functions are not replaceable and provide functionality which
0051 is complete hardware independent.
0052
0053 - [DEFAULT]
0054
0055 Default functions provide hardware related functionality which is
0056 suitable for most of the implementations. These functions can be
0057 replaced by the board driver if necessary. Those functions are called
0058 via pointers in the NAND chip description structure. The board driver
0059 can set the functions which should be replaced by board dependent
0060 functions before calling nand_scan(). If the function pointer is
0061 NULL on entry to nand_scan() then the pointer is set to the default
0062 function which is suitable for the detected chip type.
0063
0064 Struct member identifiers [XXX]
0065 -------------------------------
0066
0067 The struct members are marked with [XXX] identifiers in the comment. The
0068 identifiers explain the usage and scope of the members. Following
0069 identifiers are used:
0070
0071 - [INTERN]
0072
0073 These members are for NAND driver internal use only and must not be
0074 modified. Most of these values are calculated from the chip geometry
0075 information which is evaluated during nand_scan().
0076
0077 - [REPLACEABLE]
0078
0079 Replaceable members hold hardware related functions which can be
0080 provided by the board driver. The board driver can set the functions
0081 which should be replaced by board dependent functions before calling
0082 nand_scan(). If the function pointer is NULL on entry to
0083 nand_scan() then the pointer is set to the default function which is
0084 suitable for the detected chip type.
0085
0086 - [BOARDSPECIFIC]
0087
0088 Board specific members hold hardware related information which must
0089 be provided by the board driver. The board driver must set the
0090 function pointers and datafields before calling nand_scan().
0091
0092 - [OPTIONAL]
0093
0094 Optional members can hold information relevant for the board driver.
0095 The generic NAND driver code does not use this information.
0096
0097 Basic board driver
0098 ==================
0099
0100 For most boards it will be sufficient to provide just the basic
0101 functions and fill out some really board dependent members in the nand
0102 chip description structure.
0103
0104 Basic defines
0105 -------------
0106
0107 At least you have to provide a nand_chip structure and a storage for
0108 the ioremap'ed chip address. You can allocate the nand_chip structure
0109 using kmalloc or you can allocate it statically. The NAND chip structure
0110 embeds an mtd structure which will be registered to the MTD subsystem.
0111 You can extract a pointer to the mtd structure from a nand_chip pointer
0112 using the nand_to_mtd() helper.
0113
0114 Kmalloc based example
0115
0116 ::
0117
0118 static struct mtd_info *board_mtd;
0119 static void __iomem *baseaddr;
0120
0121
0122 Static example
0123
0124 ::
0125
0126 static struct nand_chip board_chip;
0127 static void __iomem *baseaddr;
0128
0129
0130 Partition defines
0131 -----------------
0132
0133 If you want to divide your device into partitions, then define a
0134 partitioning scheme suitable to your board.
0135
0136 ::
0137
0138 #define NUM_PARTITIONS 2
0139 static struct mtd_partition partition_info[] = {
0140 { .name = "Flash partition 1",
0141 .offset = 0,
0142 .size = 8 * 1024 * 1024 },
0143 { .name = "Flash partition 2",
0144 .offset = MTDPART_OFS_NEXT,
0145 .size = MTDPART_SIZ_FULL },
0146 };
0147
0148
0149 Hardware control function
0150 -------------------------
0151
0152 The hardware control function provides access to the control pins of the
0153 NAND chip(s). The access can be done by GPIO pins or by address lines.
0154 If you use address lines, make sure that the timing requirements are
0155 met.
0156
0157 *GPIO based example*
0158
0159 ::
0160
0161 static void board_hwcontrol(struct mtd_info *mtd, int cmd)
0162 {
0163 switch(cmd){
0164 case NAND_CTL_SETCLE: /* Set CLE pin high */ break;
0165 case NAND_CTL_CLRCLE: /* Set CLE pin low */ break;
0166 case NAND_CTL_SETALE: /* Set ALE pin high */ break;
0167 case NAND_CTL_CLRALE: /* Set ALE pin low */ break;
0168 case NAND_CTL_SETNCE: /* Set nCE pin low */ break;
0169 case NAND_CTL_CLRNCE: /* Set nCE pin high */ break;
0170 }
0171 }
0172
0173
0174 *Address lines based example.* It's assumed that the nCE pin is driven
0175 by a chip select decoder.
0176
0177 ::
0178
0179 static void board_hwcontrol(struct mtd_info *mtd, int cmd)
0180 {
0181 struct nand_chip *this = mtd_to_nand(mtd);
0182 switch(cmd){
0183 case NAND_CTL_SETCLE: this->legacy.IO_ADDR_W |= CLE_ADRR_BIT; break;
0184 case NAND_CTL_CLRCLE: this->legacy.IO_ADDR_W &= ~CLE_ADRR_BIT; break;
0185 case NAND_CTL_SETALE: this->legacy.IO_ADDR_W |= ALE_ADRR_BIT; break;
0186 case NAND_CTL_CLRALE: this->legacy.IO_ADDR_W &= ~ALE_ADRR_BIT; break;
0187 }
0188 }
0189
0190
0191 Device ready function
0192 ---------------------
0193
0194 If the hardware interface has the ready busy pin of the NAND chip
0195 connected to a GPIO or other accessible I/O pin, this function is used
0196 to read back the state of the pin. The function has no arguments and
0197 should return 0, if the device is busy (R/B pin is low) and 1, if the
0198 device is ready (R/B pin is high). If the hardware interface does not
0199 give access to the ready busy pin, then the function must not be defined
0200 and the function pointer this->legacy.dev_ready is set to NULL.
0201
0202 Init function
0203 -------------
0204
0205 The init function allocates memory and sets up all the board specific
0206 parameters and function pointers. When everything is set up nand_scan()
0207 is called. This function tries to detect and identify then chip. If a
0208 chip is found all the internal data fields are initialized accordingly.
0209 The structure(s) have to be zeroed out first and then filled with the
0210 necessary information about the device.
0211
0212 ::
0213
0214 static int __init board_init (void)
0215 {
0216 struct nand_chip *this;
0217 int err = 0;
0218
0219 /* Allocate memory for MTD device structure and private data */
0220 this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL);
0221 if (!this) {
0222 printk ("Unable to allocate NAND MTD device structure.\n");
0223 err = -ENOMEM;
0224 goto out;
0225 }
0226
0227 board_mtd = nand_to_mtd(this);
0228
0229 /* map physical address */
0230 baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024);
0231 if (!baseaddr) {
0232 printk("Ioremap to access NAND chip failed\n");
0233 err = -EIO;
0234 goto out_mtd;
0235 }
0236
0237 /* Set address of NAND IO lines */
0238 this->legacy.IO_ADDR_R = baseaddr;
0239 this->legacy.IO_ADDR_W = baseaddr;
0240 /* Reference hardware control function */
0241 this->hwcontrol = board_hwcontrol;
0242 /* Set command delay time, see datasheet for correct value */
0243 this->legacy.chip_delay = CHIP_DEPENDEND_COMMAND_DELAY;
0244 /* Assign the device ready function, if available */
0245 this->legacy.dev_ready = board_dev_ready;
0246 this->eccmode = NAND_ECC_SOFT;
0247
0248 /* Scan to find existence of the device */
0249 if (nand_scan (this, 1)) {
0250 err = -ENXIO;
0251 goto out_ior;
0252 }
0253
0254 add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS);
0255 goto out;
0256
0257 out_ior:
0258 iounmap(baseaddr);
0259 out_mtd:
0260 kfree (this);
0261 out:
0262 return err;
0263 }
0264 module_init(board_init);
0265
0266
0267 Exit function
0268 -------------
0269
0270 The exit function is only necessary if the driver is compiled as a
0271 module. It releases all resources which are held by the chip driver and
0272 unregisters the partitions in the MTD layer.
0273
0274 ::
0275
0276 #ifdef MODULE
0277 static void __exit board_cleanup (void)
0278 {
0279 /* Unregister device */
0280 WARN_ON(mtd_device_unregister(board_mtd));
0281 /* Release resources */
0282 nand_cleanup(mtd_to_nand(board_mtd));
0283
0284 /* unmap physical address */
0285 iounmap(baseaddr);
0286
0287 /* Free the MTD device structure */
0288 kfree (mtd_to_nand(board_mtd));
0289 }
0290 module_exit(board_cleanup);
0291 #endif
0292
0293
0294 Advanced board driver functions
0295 ===============================
0296
0297 This chapter describes the advanced functionality of the NAND driver.
0298 For a list of functions which can be overridden by the board driver see
0299 the documentation of the nand_chip structure.
0300
0301 Multiple chip control
0302 ---------------------
0303
0304 The nand driver can control chip arrays. Therefore the board driver must
0305 provide an own select_chip function. This function must (de)select the
0306 requested chip. The function pointer in the nand_chip structure must be
0307 set before calling nand_scan(). The maxchip parameter of nand_scan()
0308 defines the maximum number of chips to scan for. Make sure that the
0309 select_chip function can handle the requested number of chips.
0310
0311 The nand driver concatenates the chips to one virtual chip and provides
0312 this virtual chip to the MTD layer.
0313
0314 *Note: The driver can only handle linear chip arrays of equally sized
0315 chips. There is no support for parallel arrays which extend the
0316 buswidth.*
0317
0318 *GPIO based example*
0319
0320 ::
0321
0322 static void board_select_chip (struct mtd_info *mtd, int chip)
0323 {
0324 /* Deselect all chips, set all nCE pins high */
0325 GPIO(BOARD_NAND_NCE) |= 0xff;
0326 if (chip >= 0)
0327 GPIO(BOARD_NAND_NCE) &= ~ (1 << chip);
0328 }
0329
0330
0331 *Address lines based example.* Its assumed that the nCE pins are
0332 connected to an address decoder.
0333
0334 ::
0335
0336 static void board_select_chip (struct mtd_info *mtd, int chip)
0337 {
0338 struct nand_chip *this = mtd_to_nand(mtd);
0339
0340 /* Deselect all chips */
0341 this->legacy.IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK;
0342 this->legacy.IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK;
0343 switch (chip) {
0344 case 0:
0345 this->legacy.IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0;
0346 this->legacy.IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0;
0347 break;
0348 ....
0349 case n:
0350 this->legacy.IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn;
0351 this->legacy.IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn;
0352 break;
0353 }
0354 }
0355
0356
0357 Hardware ECC support
0358 --------------------
0359
0360 Functions and constants
0361 ~~~~~~~~~~~~~~~~~~~~~~~
0362
0363 The nand driver supports three different types of hardware ECC.
0364
0365 - NAND_ECC_HW3_256
0366
0367 Hardware ECC generator providing 3 bytes ECC per 256 byte.
0368
0369 - NAND_ECC_HW3_512
0370
0371 Hardware ECC generator providing 3 bytes ECC per 512 byte.
0372
0373 - NAND_ECC_HW6_512
0374
0375 Hardware ECC generator providing 6 bytes ECC per 512 byte.
0376
0377 - NAND_ECC_HW8_512
0378
0379 Hardware ECC generator providing 8 bytes ECC per 512 byte.
0380
0381 If your hardware generator has a different functionality add it at the
0382 appropriate place in nand_base.c
0383
0384 The board driver must provide following functions:
0385
0386 - enable_hwecc
0387
0388 This function is called before reading / writing to the chip. Reset
0389 or initialize the hardware generator in this function. The function
0390 is called with an argument which let you distinguish between read and
0391 write operations.
0392
0393 - calculate_ecc
0394
0395 This function is called after read / write from / to the chip.
0396 Transfer the ECC from the hardware to the buffer. If the option
0397 NAND_HWECC_SYNDROME is set then the function is only called on
0398 write. See below.
0399
0400 - correct_data
0401
0402 In case of an ECC error this function is called for error detection
0403 and correction. Return 1 respectively 2 in case the error can be
0404 corrected. If the error is not correctable return -1. If your
0405 hardware generator matches the default algorithm of the nand_ecc
0406 software generator then use the correction function provided by
0407 nand_ecc instead of implementing duplicated code.
0408
0409 Hardware ECC with syndrome calculation
0410 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0411
0412 Many hardware ECC implementations provide Reed-Solomon codes and
0413 calculate an error syndrome on read. The syndrome must be converted to a
0414 standard Reed-Solomon syndrome before calling the error correction code
0415 in the generic Reed-Solomon library.
0416
0417 The ECC bytes must be placed immediately after the data bytes in order
0418 to make the syndrome generator work. This is contrary to the usual
0419 layout used by software ECC. The separation of data and out of band area
0420 is not longer possible. The nand driver code handles this layout and the
0421 remaining free bytes in the oob area are managed by the autoplacement
0422 code. Provide a matching oob-layout in this case. See rts_from4.c and
0423 diskonchip.c for implementation reference. In those cases we must also
0424 use bad block tables on FLASH, because the ECC layout is interfering
0425 with the bad block marker positions. See bad block table support for
0426 details.
0427
0428 Bad block table support
0429 -----------------------
0430
0431 Most NAND chips mark the bad blocks at a defined position in the spare
0432 area. Those blocks must not be erased under any circumstances as the bad
0433 block information would be lost. It is possible to check the bad block
0434 mark each time when the blocks are accessed by reading the spare area of
0435 the first page in the block. This is time consuming so a bad block table
0436 is used.
0437
0438 The nand driver supports various types of bad block tables.
0439
0440 - Per device
0441
0442 The bad block table contains all bad block information of the device
0443 which can consist of multiple chips.
0444
0445 - Per chip
0446
0447 A bad block table is used per chip and contains the bad block
0448 information for this particular chip.
0449
0450 - Fixed offset
0451
0452 The bad block table is located at a fixed offset in the chip
0453 (device). This applies to various DiskOnChip devices.
0454
0455 - Automatic placed
0456
0457 The bad block table is automatically placed and detected either at
0458 the end or at the beginning of a chip (device)
0459
0460 - Mirrored tables
0461
0462 The bad block table is mirrored on the chip (device) to allow updates
0463 of the bad block table without data loss.
0464
0465 nand_scan() calls the function nand_default_bbt().
0466 nand_default_bbt() selects appropriate default bad block table
0467 descriptors depending on the chip information which was retrieved by
0468 nand_scan().
0469
0470 The standard policy is scanning the device for bad blocks and build a
0471 ram based bad block table which allows faster access than always
0472 checking the bad block information on the flash chip itself.
0473
0474 Flash based tables
0475 ~~~~~~~~~~~~~~~~~~
0476
0477 It may be desired or necessary to keep a bad block table in FLASH. For
0478 AG-AND chips this is mandatory, as they have no factory marked bad
0479 blocks. They have factory marked good blocks. The marker pattern is
0480 erased when the block is erased to be reused. So in case of powerloss
0481 before writing the pattern back to the chip this block would be lost and
0482 added to the bad blocks. Therefore we scan the chip(s) when we detect
0483 them the first time for good blocks and store this information in a bad
0484 block table before erasing any of the blocks.
0485
0486 The blocks in which the tables are stored are protected against
0487 accidental access by marking them bad in the memory bad block table. The
0488 bad block table management functions are allowed to circumvent this
0489 protection.
0490
0491 The simplest way to activate the FLASH based bad block table support is
0492 to set the option NAND_BBT_USE_FLASH in the bbt_option field of the
0493 nand chip structure before calling nand_scan(). For AG-AND chips is
0494 this done by default. This activates the default FLASH based bad block
0495 table functionality of the NAND driver. The default bad block table
0496 options are
0497
0498 - Store bad block table per chip
0499
0500 - Use 2 bits per block
0501
0502 - Automatic placement at the end of the chip
0503
0504 - Use mirrored tables with version numbers
0505
0506 - Reserve 4 blocks at the end of the chip
0507
0508 User defined tables
0509 ~~~~~~~~~~~~~~~~~~~
0510
0511 User defined tables are created by filling out a nand_bbt_descr
0512 structure and storing the pointer in the nand_chip structure member
0513 bbt_td before calling nand_scan(). If a mirror table is necessary a
0514 second structure must be created and a pointer to this structure must be
0515 stored in bbt_md inside the nand_chip structure. If the bbt_md member
0516 is set to NULL then only the main table is used and no scan for the
0517 mirrored table is performed.
0518
0519 The most important field in the nand_bbt_descr structure is the
0520 options field. The options define most of the table properties. Use the
0521 predefined constants from rawnand.h to define the options.
0522
0523 - Number of bits per block
0524
0525 The supported number of bits is 1, 2, 4, 8.
0526
0527 - Table per chip
0528
0529 Setting the constant NAND_BBT_PERCHIP selects that a bad block
0530 table is managed for each chip in a chip array. If this option is not
0531 set then a per device bad block table is used.
0532
0533 - Table location is absolute
0534
0535 Use the option constant NAND_BBT_ABSPAGE and define the absolute
0536 page number where the bad block table starts in the field pages. If
0537 you have selected bad block tables per chip and you have a multi chip
0538 array then the start page must be given for each chip in the chip
0539 array. Note: there is no scan for a table ident pattern performed, so
0540 the fields pattern, veroffs, offs, len can be left uninitialized
0541
0542 - Table location is automatically detected
0543
0544 The table can either be located in the first or the last good blocks
0545 of the chip (device). Set NAND_BBT_LASTBLOCK to place the bad block
0546 table at the end of the chip (device). The bad block tables are
0547 marked and identified by a pattern which is stored in the spare area
0548 of the first page in the block which holds the bad block table. Store
0549 a pointer to the pattern in the pattern field. Further the length of
0550 the pattern has to be stored in len and the offset in the spare area
0551 must be given in the offs member of the nand_bbt_descr structure.
0552 For mirrored bad block tables different patterns are mandatory.
0553
0554 - Table creation
0555
0556 Set the option NAND_BBT_CREATE to enable the table creation if no
0557 table can be found during the scan. Usually this is done only once if
0558 a new chip is found.
0559
0560 - Table write support
0561
0562 Set the option NAND_BBT_WRITE to enable the table write support.
0563 This allows the update of the bad block table(s) in case a block has
0564 to be marked bad due to wear. The MTD interface function
0565 block_markbad is calling the update function of the bad block table.
0566 If the write support is enabled then the table is updated on FLASH.
0567
0568 Note: Write support should only be enabled for mirrored tables with
0569 version control.
0570
0571 - Table version control
0572
0573 Set the option NAND_BBT_VERSION to enable the table version
0574 control. It's highly recommended to enable this for mirrored tables
0575 with write support. It makes sure that the risk of losing the bad
0576 block table information is reduced to the loss of the information
0577 about the one worn out block which should be marked bad. The version
0578 is stored in 4 consecutive bytes in the spare area of the device. The
0579 position of the version number is defined by the member veroffs in
0580 the bad block table descriptor.
0581
0582 - Save block contents on write
0583
0584 In case that the block which holds the bad block table does contain
0585 other useful information, set the option NAND_BBT_SAVECONTENT. When
0586 the bad block table is written then the whole block is read the bad
0587 block table is updated and the block is erased and everything is
0588 written back. If this option is not set only the bad block table is
0589 written and everything else in the block is ignored and erased.
0590
0591 - Number of reserved blocks
0592
0593 For automatic placement some blocks must be reserved for bad block
0594 table storage. The number of reserved blocks is defined in the
0595 maxblocks member of the bad block table description structure.
0596 Reserving 4 blocks for mirrored tables should be a reasonable number.
0597 This also limits the number of blocks which are scanned for the bad
0598 block table ident pattern.
0599
0600 Spare area (auto)placement
0601 --------------------------
0602
0603 The nand driver implements different possibilities for placement of
0604 filesystem data in the spare area,
0605
0606 - Placement defined by fs driver
0607
0608 - Automatic placement
0609
0610 The default placement function is automatic placement. The nand driver
0611 has built in default placement schemes for the various chiptypes. If due
0612 to hardware ECC functionality the default placement does not fit then
0613 the board driver can provide a own placement scheme.
0614
0615 File system drivers can provide a own placement scheme which is used
0616 instead of the default placement scheme.
0617
0618 Placement schemes are defined by a nand_oobinfo structure
0619
0620 ::
0621
0622 struct nand_oobinfo {
0623 int useecc;
0624 int eccbytes;
0625 int eccpos[24];
0626 int oobfree[8][2];
0627 };
0628
0629
0630 - useecc
0631
0632 The useecc member controls the ecc and placement function. The header
0633 file include/mtd/mtd-abi.h contains constants to select ecc and
0634 placement. MTD_NANDECC_OFF switches off the ecc complete. This is
0635 not recommended and available for testing and diagnosis only.
0636 MTD_NANDECC_PLACE selects caller defined placement,
0637 MTD_NANDECC_AUTOPLACE selects automatic placement.
0638
0639 - eccbytes
0640
0641 The eccbytes member defines the number of ecc bytes per page.
0642
0643 - eccpos
0644
0645 The eccpos array holds the byte offsets in the spare area where the
0646 ecc codes are placed.
0647
0648 - oobfree
0649
0650 The oobfree array defines the areas in the spare area which can be
0651 used for automatic placement. The information is given in the format
0652 {offset, size}. offset defines the start of the usable area, size the
0653 length in bytes. More than one area can be defined. The list is
0654 terminated by an {0, 0} entry.
0655
0656 Placement defined by fs driver
0657 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0658
0659 The calling function provides a pointer to a nand_oobinfo structure
0660 which defines the ecc placement. For writes the caller must provide a
0661 spare area buffer along with the data buffer. The spare area buffer size
0662 is (number of pages) \* (size of spare area). For reads the buffer size
0663 is (number of pages) \* ((size of spare area) + (number of ecc steps per
0664 page) \* sizeof (int)). The driver stores the result of the ecc check
0665 for each tuple in the spare buffer. The storage sequence is::
0666
0667 <spare data page 0><ecc result 0>...<ecc result n>
0668
0669 ...
0670
0671 <spare data page n><ecc result 0>...<ecc result n>
0672
0673 This is a legacy mode used by YAFFS1.
0674
0675 If the spare area buffer is NULL then only the ECC placement is done
0676 according to the given scheme in the nand_oobinfo structure.
0677
0678 Automatic placement
0679 ~~~~~~~~~~~~~~~~~~~
0680
0681 Automatic placement uses the built in defaults to place the ecc bytes in
0682 the spare area. If filesystem data have to be stored / read into the
0683 spare area then the calling function must provide a buffer. The buffer
0684 size per page is determined by the oobfree array in the nand_oobinfo
0685 structure.
0686
0687 If the spare area buffer is NULL then only the ECC placement is done
0688 according to the default builtin scheme.
0689
0690 Spare area autoplacement default schemes
0691 ----------------------------------------
0692
0693 256 byte pagesize
0694 ~~~~~~~~~~~~~~~~~
0695
0696 ======== ================== ===================================================
0697 Offset Content Comment
0698 ======== ================== ===================================================
0699 0x00 ECC byte 0 Error correction code byte 0
0700 0x01 ECC byte 1 Error correction code byte 1
0701 0x02 ECC byte 2 Error correction code byte 2
0702 0x03 Autoplace 0
0703 0x04 Autoplace 1
0704 0x05 Bad block marker If any bit in this byte is zero, then this
0705 block is bad. This applies only to the first
0706 page in a block. In the remaining pages this
0707 byte is reserved
0708 0x06 Autoplace 2
0709 0x07 Autoplace 3
0710 ======== ================== ===================================================
0711
0712 512 byte pagesize
0713 ~~~~~~~~~~~~~~~~~
0714
0715
0716 ============= ================== ==============================================
0717 Offset Content Comment
0718 ============= ================== ==============================================
0719 0x00 ECC byte 0 Error correction code byte 0 of the lower
0720 256 Byte data in this page
0721 0x01 ECC byte 1 Error correction code byte 1 of the lower
0722 256 Bytes of data in this page
0723 0x02 ECC byte 2 Error correction code byte 2 of the lower
0724 256 Bytes of data in this page
0725 0x03 ECC byte 3 Error correction code byte 0 of the upper
0726 256 Bytes of data in this page
0727 0x04 reserved reserved
0728 0x05 Bad block marker If any bit in this byte is zero, then this
0729 block is bad. This applies only to the first
0730 page in a block. In the remaining pages this
0731 byte is reserved
0732 0x06 ECC byte 4 Error correction code byte 1 of the upper
0733 256 Bytes of data in this page
0734 0x07 ECC byte 5 Error correction code byte 2 of the upper
0735 256 Bytes of data in this page
0736 0x08 - 0x0F Autoplace 0 - 7
0737 ============= ================== ==============================================
0738
0739 2048 byte pagesize
0740 ~~~~~~~~~~~~~~~~~~
0741
0742 =========== ================== ================================================
0743 Offset Content Comment
0744 =========== ================== ================================================
0745 0x00 Bad block marker If any bit in this byte is zero, then this block
0746 is bad. This applies only to the first page in a
0747 block. In the remaining pages this byte is
0748 reserved
0749 0x01 Reserved Reserved
0750 0x02-0x27 Autoplace 0 - 37
0751 0x28 ECC byte 0 Error correction code byte 0 of the first
0752 256 Byte data in this page
0753 0x29 ECC byte 1 Error correction code byte 1 of the first
0754 256 Bytes of data in this page
0755 0x2A ECC byte 2 Error correction code byte 2 of the first
0756 256 Bytes data in this page
0757 0x2B ECC byte 3 Error correction code byte 0 of the second
0758 256 Bytes of data in this page
0759 0x2C ECC byte 4 Error correction code byte 1 of the second
0760 256 Bytes of data in this page
0761 0x2D ECC byte 5 Error correction code byte 2 of the second
0762 256 Bytes of data in this page
0763 0x2E ECC byte 6 Error correction code byte 0 of the third
0764 256 Bytes of data in this page
0765 0x2F ECC byte 7 Error correction code byte 1 of the third
0766 256 Bytes of data in this page
0767 0x30 ECC byte 8 Error correction code byte 2 of the third
0768 256 Bytes of data in this page
0769 0x31 ECC byte 9 Error correction code byte 0 of the fourth
0770 256 Bytes of data in this page
0771 0x32 ECC byte 10 Error correction code byte 1 of the fourth
0772 256 Bytes of data in this page
0773 0x33 ECC byte 11 Error correction code byte 2 of the fourth
0774 256 Bytes of data in this page
0775 0x34 ECC byte 12 Error correction code byte 0 of the fifth
0776 256 Bytes of data in this page
0777 0x35 ECC byte 13 Error correction code byte 1 of the fifth
0778 256 Bytes of data in this page
0779 0x36 ECC byte 14 Error correction code byte 2 of the fifth
0780 256 Bytes of data in this page
0781 0x37 ECC byte 15 Error correction code byte 0 of the sixth
0782 256 Bytes of data in this page
0783 0x38 ECC byte 16 Error correction code byte 1 of the sixth
0784 256 Bytes of data in this page
0785 0x39 ECC byte 17 Error correction code byte 2 of the sixth
0786 256 Bytes of data in this page
0787 0x3A ECC byte 18 Error correction code byte 0 of the seventh
0788 256 Bytes of data in this page
0789 0x3B ECC byte 19 Error correction code byte 1 of the seventh
0790 256 Bytes of data in this page
0791 0x3C ECC byte 20 Error correction code byte 2 of the seventh
0792 256 Bytes of data in this page
0793 0x3D ECC byte 21 Error correction code byte 0 of the eighth
0794 256 Bytes of data in this page
0795 0x3E ECC byte 22 Error correction code byte 1 of the eighth
0796 256 Bytes of data in this page
0797 0x3F ECC byte 23 Error correction code byte 2 of the eighth
0798 256 Bytes of data in this page
0799 =========== ================== ================================================
0800
0801 Filesystem support
0802 ==================
0803
0804 The NAND driver provides all necessary functions for a filesystem via
0805 the MTD interface.
0806
0807 Filesystems must be aware of the NAND peculiarities and restrictions.
0808 One major restrictions of NAND Flash is, that you cannot write as often
0809 as you want to a page. The consecutive writes to a page, before erasing
0810 it again, are restricted to 1-3 writes, depending on the manufacturers
0811 specifications. This applies similar to the spare area.
0812
0813 Therefore NAND aware filesystems must either write in page size chunks
0814 or hold a writebuffer to collect smaller writes until they sum up to
0815 pagesize. Available NAND aware filesystems: JFFS2, YAFFS.
0816
0817 The spare area usage to store filesystem data is controlled by the spare
0818 area placement functionality which is described in one of the earlier
0819 chapters.
0820
0821 Tools
0822 =====
0823
0824 The MTD project provides a couple of helpful tools to handle NAND Flash.
0825
0826 - flasherase, flasheraseall: Erase and format FLASH partitions
0827
0828 - nandwrite: write filesystem images to NAND FLASH
0829
0830 - nanddump: dump the contents of a NAND FLASH partitions
0831
0832 These tools are aware of the NAND restrictions. Please use those tools
0833 instead of complaining about errors which are caused by non NAND aware
0834 access methods.
0835
0836 Constants
0837 =========
0838
0839 This chapter describes the constants which might be relevant for a
0840 driver developer.
0841
0842 Chip option constants
0843 ---------------------
0844
0845 Constants for chip id table
0846 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
0847
0848 These constants are defined in rawnand.h. They are OR-ed together to
0849 describe the chip functionality::
0850
0851 /* Buswitdh is 16 bit */
0852 #define NAND_BUSWIDTH_16 0x00000002
0853 /* Device supports partial programming without padding */
0854 #define NAND_NO_PADDING 0x00000004
0855 /* Chip has cache program function */
0856 #define NAND_CACHEPRG 0x00000008
0857 /* Chip has copy back function */
0858 #define NAND_COPYBACK 0x00000010
0859 /* AND Chip which has 4 banks and a confusing page / block
0860 * assignment. See Renesas datasheet for further information */
0861 #define NAND_IS_AND 0x00000020
0862 /* Chip has a array of 4 pages which can be read without
0863 * additional ready /busy waits */
0864 #define NAND_4PAGE_ARRAY 0x00000040
0865
0866
0867 Constants for runtime options
0868 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0869
0870 These constants are defined in rawnand.h. They are OR-ed together to
0871 describe the functionality::
0872
0873 /* The hw ecc generator provides a syndrome instead a ecc value on read
0874 * This can only work if we have the ecc bytes directly behind the
0875 * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */
0876 #define NAND_HWECC_SYNDROME 0x00020000
0877
0878
0879 ECC selection constants
0880 -----------------------
0881
0882 Use these constants to select the ECC algorithm::
0883
0884 /* No ECC. Usage is not recommended ! */
0885 #define NAND_ECC_NONE 0
0886 /* Software ECC 3 byte ECC per 256 Byte data */
0887 #define NAND_ECC_SOFT 1
0888 /* Hardware ECC 3 byte ECC per 256 Byte data */
0889 #define NAND_ECC_HW3_256 2
0890 /* Hardware ECC 3 byte ECC per 512 Byte data */
0891 #define NAND_ECC_HW3_512 3
0892 /* Hardware ECC 6 byte ECC per 512 Byte data */
0893 #define NAND_ECC_HW6_512 4
0894 /* Hardware ECC 8 byte ECC per 512 Byte data */
0895 #define NAND_ECC_HW8_512 6
0896
0897
0898 Hardware control related constants
0899 ----------------------------------
0900
0901 These constants describe the requested hardware access function when the
0902 boardspecific hardware control function is called::
0903
0904 /* Select the chip by setting nCE to low */
0905 #define NAND_CTL_SETNCE 1
0906 /* Deselect the chip by setting nCE to high */
0907 #define NAND_CTL_CLRNCE 2
0908 /* Select the command latch by setting CLE to high */
0909 #define NAND_CTL_SETCLE 3
0910 /* Deselect the command latch by setting CLE to low */
0911 #define NAND_CTL_CLRCLE 4
0912 /* Select the address latch by setting ALE to high */
0913 #define NAND_CTL_SETALE 5
0914 /* Deselect the address latch by setting ALE to low */
0915 #define NAND_CTL_CLRALE 6
0916 /* Set write protection by setting WP to high. Not used! */
0917 #define NAND_CTL_SETWP 7
0918 /* Clear write protection by setting WP to low. Not used! */
0919 #define NAND_CTL_CLRWP 8
0920
0921
0922 Bad block table related constants
0923 ---------------------------------
0924
0925 These constants describe the options used for bad block table
0926 descriptors::
0927
0928 /* Options for the bad block table descriptors */
0929
0930 /* The number of bits used per block in the bbt on the device */
0931 #define NAND_BBT_NRBITS_MSK 0x0000000F
0932 #define NAND_BBT_1BIT 0x00000001
0933 #define NAND_BBT_2BIT 0x00000002
0934 #define NAND_BBT_4BIT 0x00000004
0935 #define NAND_BBT_8BIT 0x00000008
0936 /* The bad block table is in the last good block of the device */
0937 #define NAND_BBT_LASTBLOCK 0x00000010
0938 /* The bbt is at the given page, else we must scan for the bbt */
0939 #define NAND_BBT_ABSPAGE 0x00000020
0940 /* bbt is stored per chip on multichip devices */
0941 #define NAND_BBT_PERCHIP 0x00000080
0942 /* bbt has a version counter at offset veroffs */
0943 #define NAND_BBT_VERSION 0x00000100
0944 /* Create a bbt if none axists */
0945 #define NAND_BBT_CREATE 0x00000200
0946 /* Write bbt if necessary */
0947 #define NAND_BBT_WRITE 0x00001000
0948 /* Read and write back block contents when writing bbt */
0949 #define NAND_BBT_SAVECONTENT 0x00002000
0950
0951
0952 Structures
0953 ==========
0954
0955 This chapter contains the autogenerated documentation of the structures
0956 which are used in the NAND driver and might be relevant for a driver
0957 developer. Each struct member has a short description which is marked
0958 with an [XXX] identifier. See the chapter "Documentation hints" for an
0959 explanation.
0960
0961 .. kernel-doc:: include/linux/mtd/rawnand.h
0962 :internal:
0963
0964 Public Functions Provided
0965 =========================
0966
0967 This chapter contains the autogenerated documentation of the NAND kernel
0968 API functions which are exported. Each function has a short description
0969 which is marked with an [XXX] identifier. See the chapter "Documentation
0970 hints" for an explanation.
0971
0972 .. kernel-doc:: drivers/mtd/nand/raw/nand_base.c
0973 :export:
0974
0975 Internal Functions Provided
0976 ===========================
0977
0978 This chapter contains the autogenerated documentation of the NAND driver
0979 internal functions. Each function has a short description which is
0980 marked with an [XXX] identifier. See the chapter "Documentation hints"
0981 for an explanation. The functions marked with [DEFAULT] might be
0982 relevant for a board driver developer.
0983
0984 .. kernel-doc:: drivers/mtd/nand/raw/nand_base.c
0985 :internal:
0986
0987 .. kernel-doc:: drivers/mtd/nand/raw/nand_bbt.c
0988 :internal:
0989
0990 Credits
0991 =======
0992
0993 The following people have contributed to the NAND driver:
0994
0995 1. Steven J. Hill\ sjhill@realitydiluted.com
0996
0997 2. David Woodhouse\ dwmw2@infradead.org
0998
0999 3. Thomas Gleixner\ tglx@linutronix.de
1000
1001 A lot of users have provided bugfixes, improvements and helping hands
1002 for testing. Thanks a lot.
1003
1004 The following people have contributed to this document:
1005
1006 1. Thomas Gleixner\ tglx@linutronix.de
