The generic NAND driver supports almost all NAND and AG-AND based chips and connects them to the Memory Technology Devices (MTD) subsystem of the Linux Kernel.
This documentation is provided for developers who want to implement board drivers or filesystem drivers suitable for NAND devices.
The function and structure docs are autogenerated. Each function and struct member has a short description which is marked with an [XXX] identifier. The following chapters explain the meaning of those identifiers.
The functions are marked with [XXX] identifiers in the short comment. The identifiers explain the usage and scope of the functions. Following identifiers are used:
The struct members are marked with [XXX] identifiers in the comment. The identifiers explain the usage and scope of the members. Following identifiers are used:
For most boards it will be sufficient to provide just the basic functions and fill out some really board dependent members in the nand chip description structure.
At least you have to provide a nand_chip structure and a storage for the ioremap’ed chip address. You can allocate the nand_chip structure using kmalloc or you can allocate it statically. The NAND chip structure embeds an mtd structure which will be registered to the MTD subsystem. You can extract a pointer to the mtd structure from a nand_chip pointer using the nand_to_mtd() helper.
Kmalloc based example
static struct mtd_info *board_mtd; static void __iomem *baseaddr;
static struct nand_chip board_chip; static void __iomem *baseaddr;
If you want to divide your device into partitions, then define a partitioning scheme suitable to your board.
#define NUM_PARTITIONS 2 static struct mtd_partition partition_info[] = < < .name = "Flash partition 1", .offset = 0, .size = 8 * 1024 * 1024 >, < .name = "Flash partition 2", .offset = MTDPART_OFS_NEXT, .size = MTDPART_SIZ_FULL >, >;
The hardware control function provides access to the control pins of the NAND chip(s). The access can be done by GPIO pins or by address lines. If you use address lines, make sure that the timing requirements are met.
GPIO based example
static void board_hwcontrol(struct mtd_info *mtd, int cmd) < switch(cmd)< case NAND_CTL_SETCLE: /* Set CLE pin high */ break; case NAND_CTL_CLRCLE: /* Set CLE pin low */ break; case NAND_CTL_SETALE: /* Set ALE pin high */ break; case NAND_CTL_CLRALE: /* Set ALE pin low */ break; case NAND_CTL_SETNCE: /* Set nCE pin low */ break; case NAND_CTL_CLRNCE: /* Set nCE pin high */ break; >>
Address lines based example. It’s assumed that the nCE pin is driven by a chip select decoder.
static void board_hwcontrol(struct mtd_info *mtd, int cmd) < struct nand_chip *this = mtd_to_nand(mtd); switch(cmd)< case NAND_CTL_SETCLE: this->legacy.IO_ADDR_W |= CLE_ADRR_BIT; break; case NAND_CTL_CLRCLE: this->legacy.IO_ADDR_W &= ~CLE_ADRR_BIT; break; case NAND_CTL_SETALE: this->legacy.IO_ADDR_W |= ALE_ADRR_BIT; break; case NAND_CTL_CLRALE: this->legacy.IO_ADDR_W &= ~ALE_ADRR_BIT; break; > >
If the hardware interface has the ready busy pin of the NAND chip connected to a GPIO or other accessible I/O pin, this function is used to read back the state of the pin. The function has no arguments and should return 0, if the device is busy (R/B pin is low) and 1, if the device is ready (R/B pin is high). If the hardware interface does not give access to the ready busy pin, then the function must not be defined and the function pointer this->legacy.dev_ready is set to NULL.
The init function allocates memory and sets up all the board specific parameters and function pointers. When everything is set up nand_scan() is called. This function tries to detect and identify then chip. If a chip is found all the internal data fields are initialized accordingly. The structure(s) have to be zeroed out first and then filled with the necessary information about the device.
static int __init board_init (void) < struct nand_chip *this; int err = 0; /* Allocate memory for MTD device structure and private data */ this = kzalloc(sizeof(struct nand_chip), GFP_KERNEL); if (!this) < printk ("Unable to allocate NAND MTD device structure.\n"); err = -ENOMEM; goto out; >board_mtd = nand_to_mtd(this); /* map physical address */ baseaddr = ioremap(CHIP_PHYSICAL_ADDRESS, 1024); if (!baseaddr) < printk("Ioremap to access NAND chip failed\n"); err = -EIO; goto out_mtd; >/* Set address of NAND IO lines */ this->legacy.IO_ADDR_R = baseaddr; this->legacy.IO_ADDR_W = baseaddr; /* Reference hardware control function */ this->hwcontrol = board_hwcontrol; /* Set command delay time, see datasheet for correct value */ this->legacy.chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; /* Assign the device ready function, if available */ this->legacy.dev_ready = board_dev_ready; this->eccmode = NAND_ECC_SOFT; /* Scan to find existence of the device */ if (nand_scan (this, 1)) < err = -ENXIO; goto out_ior; >add_mtd_partitions(board_mtd, partition_info, NUM_PARTITIONS); goto out; out_ior: iounmap(baseaddr); out_mtd: kfree (this); out: return err; > module_init(board_init);
The exit function is only necessary if the driver is compiled as a module. It releases all resources which are held by the chip driver and unregisters the partitions in the MTD layer.
#ifdef MODULE static void __exit board_cleanup (void) < /* Unregister device */ WARN_ON(mtd_device_unregister(board_mtd)); /* Release resources */ nand_cleanup(mtd_to_nand(board_mtd)); /* unmap physical address */ iounmap(baseaddr); /* Free the MTD device structure */ kfree (mtd_to_nand(board_mtd)); >module_exit(board_cleanup); #endif
This chapter describes the advanced functionality of the NAND driver. For a list of functions which can be overridden by the board driver see the documentation of the nand_chip structure.
The nand driver can control chip arrays. Therefore the board driver must provide an own select_chip function. This function must (de)select the requested chip. The function pointer in the nand_chip structure must be set before calling nand_scan(). The maxchip parameter of nand_scan() defines the maximum number of chips to scan for. Make sure that the select_chip function can handle the requested number of chips.
The nand driver concatenates the chips to one virtual chip and provides this virtual chip to the MTD layer.
Note: The driver can only handle linear chip arrays of equally sized chips. There is no support for parallel arrays which extend the buswidth.
GPIO based example
static void board_select_chip (struct mtd_info *mtd, int chip) < /* Deselect all chips, set all nCE pins high */ GPIO(BOARD_NAND_NCE) |= 0xff; if (chip >= 0) GPIO(BOARD_NAND_NCE) &= ~ (1Address lines based example. Its assumed that the nCE pins are connected to an address decoder.
static void board_select_chip (struct mtd_info *mtd, int chip) < struct nand_chip *this = mtd_to_nand(mtd); /* Deselect all chips */ this->legacy.IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; this->legacy.IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; switch (chip) < case 0: this->legacy.IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; this->legacy.IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; break; . case n: this->legacy.IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; this->legacy.IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; break; > >
The nand driver supports three different types of hardware ECC.
If your hardware generator has a different functionality add it at the appropriate place in nand_base.c
The board driver must provide following functions:
Many hardware ECC implementations provide Reed-Solomon codes and calculate an error syndrome on read. The syndrome must be converted to a standard Reed-Solomon syndrome before calling the error correction code in the generic Reed-Solomon library.
The ECC bytes must be placed immediately after the data bytes in order to make the syndrome generator work. This is contrary to the usual layout used by software ECC. The separation of data and out of band area is not longer possible. The nand driver code handles this layout and the remaining free bytes in the oob area are managed by the autoplacement code. Provide a matching oob-layout in this case. See rts_from4.c and diskonchip.c for implementation reference. In those cases we must also use bad block tables on FLASH, because the ECC layout is interfering with the bad block marker positions. See bad block table support for details.
Most NAND chips mark the bad blocks at a defined position in the spare area. Those blocks must not be erased under any circumstances as the bad block information would be lost. It is possible to check the bad block mark each time when the blocks are accessed by reading the spare area of the first page in the block. This is time consuming so a bad block table is used.
The nand driver supports various types of bad block tables.
nand_scan() calls the function nand_default_bbt(). nand_default_bbt() selects appropriate default bad block table descriptors depending on the chip information which was retrieved by nand_scan().
The standard policy is scanning the device for bad blocks and build a ram based bad block table which allows faster access than always checking the bad block information on the flash chip itself.
It may be desired or necessary to keep a bad block table in FLASH. For AG-AND chips this is mandatory, as they have no factory marked bad blocks. They have factory marked good blocks. The marker pattern is erased when the block is erased to be reused. So in case of powerloss before writing the pattern back to the chip this block would be lost and added to the bad blocks. Therefore we scan the chip(s) when we detect them the first time for good blocks and store this information in a bad block table before erasing any of the blocks.
The blocks in which the tables are stored are protected against accidental access by marking them bad in the memory bad block table. The bad block table management functions are allowed to circumvent this protection.
The simplest way to activate the FLASH based bad block table support is to set the option NAND_BBT_USE_FLASH in the bbt_option field of the nand chip structure before calling nand_scan(). For AG-AND chips is this done by default. This activates the default FLASH based bad block table functionality of the NAND driver. The default bad block table options are
User defined tables are created by filling out a nand_bbt_descr structure and storing the pointer in the nand_chip structure member bbt_td before calling nand_scan(). If a mirror table is necessary a second structure must be created and a pointer to this structure must be stored in bbt_md inside the nand_chip structure. If the bbt_md member is set to NULL then only the main table is used and no scan for the mirrored table is performed.
The most important field in the nand_bbt_descr structure is the options field. The options define most of the table properties. Use the predefined constants from rawnand.h to define the options.
The nand driver implements different possibilities for placement of filesystem data in the spare area,
The default placement function is automatic placement. The nand driver has built in default placement schemes for the various chiptypes. If due to hardware ECC functionality the default placement does not fit then the board driver can provide a own placement scheme.
File system drivers can provide a own placement scheme which is used instead of the default placement scheme.
Placement schemes are defined by a nand_oobinfo structure
struct nand_oobinfo < int useecc; int eccbytes; int eccpos[24]; int oobfree[8][2]; >;
The calling function provides a pointer to a nand_oobinfo structure which defines the ecc placement. For writes the caller must provide a spare area buffer along with the data buffer. The spare area buffer size is (number of pages) * (size of spare area). For reads the buffer size is (number of pages) * ((size of spare area) + (number of ecc steps per page) * sizeof (int)). The driver stores the result of the ecc check for each tuple in the spare buffer. The storage sequence is:
This is a legacy mode used by YAFFS1.
If the spare area buffer is NULL then only the ECC placement is done according to the given scheme in the nand_oobinfo structure.
Automatic placement uses the built in defaults to place the ecc bytes in the spare area. If filesystem data have to be stored / read into the spare area then the calling function must provide a buffer. The buffer size per page is determined by the oobfree array in the nand_oobinfo structure.
If the spare area buffer is NULL then only the ECC placement is done according to the default builtin scheme.