From 609f212f6a12e005d2395edd7b4192d2b051ae67 Mon Sep 17 00:00:00 2001 From: Mauro Carvalho Chehab Date: Sat, 13 May 2017 07:10:44 -0300 Subject: docs-rst: convert mtdnand book to ReST Use pandoc to convert documentation to ReST by calling Documentation/sphinx/tmplcvt script. The tables were manually adjusted to fit into 80 columns. Signed-off-by: Mauro Carvalho Chehab --- Documentation/DocBook/Makefile | 1 - Documentation/DocBook/mtdnand.tmpl | 1291 ------------------------------------ 2 files changed, 1292 deletions(-) delete mode 100644 Documentation/DocBook/mtdnand.tmpl (limited to 'Documentation/DocBook') diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 0a82f6253682..226e5e9fc801 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile @@ -8,7 +8,6 @@ DOCBOOKS := \ lsm.xml \ - mtdnand.xml \ sh.xml ifeq ($(DOCBOOKS),) diff --git a/Documentation/DocBook/mtdnand.tmpl b/Documentation/DocBook/mtdnand.tmpl deleted file mode 100644 index b442921bca54..000000000000 --- a/Documentation/DocBook/mtdnand.tmpl +++ /dev/null @@ -1,1291 +0,0 @@ - - - - - - MTD NAND Driver Programming Interface - - - - Thomas - Gleixner - -
- tglx@linutronix.de -
- - - - - - 2004 - Thomas Gleixner - - - - - This documentation is free software; you can redistribute - it and/or modify it under the terms of the GNU General Public - License version 2 as published by the Free Software Foundation. - - - - This program is distributed in the hope that it will be - useful, but WITHOUT ANY WARRANTY; without even the implied - warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. - See the GNU General Public License for more details. - - - - You should have received a copy of the GNU General Public - License along with this program; if not, write to the Free - Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, - MA 02111-1307 USA - - - - For more details see the file COPYING in the source - distribution of Linux. - - - - - - - - Introduction - - 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. - - - - - Known Bugs And Assumptions - - None. - - - - - Documentation hints - - 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. - - - Function identifiers [XXX] - - 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: - - - - [MTD Interface] - These functions provide the interface to the MTD kernel API. - They are not replaceable and provide functionality - which is complete hardware independent. - - - [NAND Interface] - These functions are exported and provide the interface to the NAND kernel API. - - - [GENERIC] - Generic functions are not replaceable and provide functionality - which is complete hardware independent. - - - [DEFAULT] - Default functions provide hardware related functionality which is suitable - for most of the implementations. These functions can be replaced by the - board driver if necessary. Those functions are called via pointers in the - NAND chip description structure. The board driver can set the functions which - should be replaced by board dependent functions before calling nand_scan(). - If the function pointer is NULL on entry to nand_scan() then the pointer - is set to the default function which is suitable for the detected chip type. - - - - - Struct member identifiers [XXX] - - 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: - - - - [INTERN] - These members are for NAND driver internal use only and must not be - modified. Most of these values are calculated from the chip geometry - information which is evaluated during nand_scan(). - - - [REPLACEABLE] - Replaceable members hold hardware related functions which can be - provided by the board driver. The board driver can set the functions which - should be replaced by board dependent functions before calling nand_scan(). - If the function pointer is NULL on entry to nand_scan() then the pointer - is set to the default function which is suitable for the detected chip type. - - - [BOARDSPECIFIC] - Board specific members hold hardware related information which must - be provided by the board driver. The board driver must set the function - pointers and datafields before calling nand_scan(). - - - [OPTIONAL] - Optional members can hold information relevant for the board driver. The - generic NAND driver code does not use this information. - - - - - - - Basic board driver - - 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. - - - Basic defines - - 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 example - - -static struct nand_chip board_chip; -static void __iomem *baseaddr; - - - - Partition defines - - 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 }, -}; - - - - Hardware control function - - 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->IO_ADDR_W |= CLE_ADRR_BIT; break; - case NAND_CTL_CLRCLE: this->IO_ADDR_W &= ~CLE_ADRR_BIT; break; - case NAND_CTL_SETALE: this->IO_ADDR_W |= ALE_ADRR_BIT; break; - case NAND_CTL_CLRALE: this->IO_ADDR_W &= ~ALE_ADRR_BIT; break; - } -} - - - - Device ready function - - 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->dev_ready is set to NULL. - - - - Init function - - 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->IO_ADDR_R = baseaddr; - this->IO_ADDR_W = baseaddr; - /* Reference hardware control function */ - this->hwcontrol = board_hwcontrol; - /* Set command delay time, see datasheet for correct value */ - this->chip_delay = CHIP_DEPENDEND_COMMAND_DELAY; - /* Assign the device ready function, if available */ - this->dev_ready = board_dev_ready; - this->eccmode = NAND_ECC_SOFT; - - /* Scan to find existence of the device */ - if (nand_scan (board_mtd, 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); - - - - Exit function - - 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) -{ - /* Release resources, unregister device */ - nand_release (board_mtd); - - /* unmap physical address */ - iounmap(baseaddr); - - /* Free the MTD device structure */ - kfree (mtd_to_nand(board_mtd)); -} -module_exit(board_cleanup); -#endif - - - - - - Advanced board driver functions - - 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. - - - Multiple chip control - - 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) &= ~ (1 << chip); -} - - - Address 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->IO_ADDR_R &= ~BOARD_NAND_ADDR_MASK; - this->IO_ADDR_W &= ~BOARD_NAND_ADDR_MASK; - switch (chip) { - case 0: - this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIP0; - this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIP0; - break; - .... - case n: - this->IO_ADDR_R |= BOARD_NAND_ADDR_CHIPn; - this->IO_ADDR_W |= BOARD_NAND_ADDR_CHIPn; - break; - } -} - - - - Hardware ECC support - - Functions and constants - - The nand driver supports three different types of - hardware ECC. - - NAND_ECC_HW3_256 - Hardware ECC generator providing 3 bytes ECC per - 256 byte. - - NAND_ECC_HW3_512 - Hardware ECC generator providing 3 bytes ECC per - 512 byte. - - NAND_ECC_HW6_512 - Hardware ECC generator providing 6 bytes ECC per - 512 byte. - - NAND_ECC_HW8_512 - Hardware ECC generator providing 6 bytes ECC per - 512 byte. - - - 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: - - enable_hwecc - This function is called before reading / writing to - the chip. Reset or initialize the hardware generator - in this function. The function is called with an - argument which let you distinguish between read - and write operations. - - calculate_ecc - This function is called after read / write from / to - the chip. Transfer the ECC from the hardware to - the buffer. If the option NAND_HWECC_SYNDROME is set - then the function is only called on write. See below. - - correct_data - In case of an ECC error this function is called for - error detection and correction. Return 1 respectively 2 - in case the error can be corrected. If the error is - not correctable return -1. If your hardware generator - matches the default algorithm of the nand_ecc software - generator then use the correction function provided - by nand_ecc instead of implementing duplicated code. - - - - - - Hardware ECC with syndrome calculation - - 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. - - - - - Bad block table support - - 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. - - Per device - The bad block table contains all bad block information - of the device which can consist of multiple chips. - - Per chip - A bad block table is used per chip and contains the - bad block information for this particular chip. - - Fixed offset - The bad block table is located at a fixed offset - in the chip (device). This applies to various - DiskOnChip devices. - - Automatic placed - The bad block table is automatically placed and - detected either at the end or at the beginning - of a chip (device) - - Mirrored tables - The bad block table is mirrored on the chip (device) to - allow updates of the bad block table without data loss. - - - - - 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. - - - Flash based tables - - 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 - - Store bad block table per chip - Use 2 bits per block - Automatic placement at the end of the chip - Use mirrored tables with version numbers - Reserve 4 blocks at the end of the chip - - - - - User defined tables - - 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 - nand.h to define the options. - - Number of bits per block - The supported number of bits is 1, 2, 4, 8. - Table per chip - Setting the constant NAND_BBT_PERCHIP selects that - a bad block table is managed for each chip in a chip array. - If this option is not set then a per device bad block table - is used. - Table location is absolute - Use the option constant NAND_BBT_ABSPAGE and - define the absolute page number where the bad block - table starts in the field pages. If you have selected bad block - tables per chip and you have a multi chip array then the start page - must be given for each chip in the chip array. Note: there is no scan - for a table ident pattern performed, so the fields - pattern, veroffs, offs, len can be left uninitialized - Table location is automatically detected - The table can either be located in the first or the last good - blocks of the chip (device). Set NAND_BBT_LASTBLOCK to place - the bad block table at the end of the chip (device). The - bad block tables are marked and identified by a pattern which - is stored in the spare area of the first page in the block which - holds the bad block table. Store a pointer to the pattern - in the pattern field. Further the length of the pattern has to be - stored in len and the offset in the spare area must be given - in the offs member of the nand_bbt_descr structure. For mirrored - bad block tables different patterns are mandatory. - Table creation - Set the option NAND_BBT_CREATE to enable the table creation - if no table can be found during the scan. Usually this is done only - once if a new chip is found. - Table write support - Set the option NAND_BBT_WRITE to enable the table write support. - This allows the update of the bad block table(s) in case a block has - to be marked bad due to wear. The MTD interface function block_markbad - is calling the update function of the bad block table. If the write - support is enabled then the table is updated on FLASH. - - Note: Write support should only be enabled for mirrored tables with - version control. - - Table version control - Set the option NAND_BBT_VERSION to enable the table version control. - It's highly recommended to enable this for mirrored tables with write - support. It makes sure that the risk of losing the bad block - table information is reduced to the loss of the information about the - one worn out block which should be marked bad. The version is stored in - 4 consecutive bytes in the spare area of the device. The position of - the version number is defined by the member veroffs in the bad block table - descriptor. - Save block contents on write - - In case that the block which holds the bad block table does contain - other useful information, set the option NAND_BBT_SAVECONTENT. When - the bad block table is written then the whole block is read the bad - block table is updated and the block is erased and everything is - written back. If this option is not set only the bad block table - is written and everything else in the block is ignored and erased. - - Number of reserved blocks - - For automatic placement some blocks must be reserved for - bad block table storage. The number of reserved blocks is defined - in the maxblocks member of the bad block table description structure. - Reserving 4 blocks for mirrored tables should be a reasonable number. - This also limits the number of blocks which are scanned for the bad - block table ident pattern. - - - - - - - Spare area (auto)placement - - The nand driver implements different possibilities for - placement of filesystem data in the spare area, - - Placement defined by fs driver - Automatic placement - - 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]; -}; - - - useecc - The useecc member controls the ecc and placement function. The header - file include/mtd/mtd-abi.h contains constants to select ecc and - placement. MTD_NANDECC_OFF switches off the ecc complete. This is - not recommended and available for testing and diagnosis only. - MTD_NANDECC_PLACE selects caller defined placement, MTD_NANDECC_AUTOPLACE - selects automatic placement. - - eccbytes - The eccbytes member defines the number of ecc bytes per page. - - eccpos - The eccpos array holds the byte offsets in the spare area where - the ecc codes are placed. - - oobfree - The oobfree array defines the areas in the spare area which can be - used for automatic placement. The information is given in the format - {offset, size}. offset defines the start of the usable area, size the - length in bytes. More than one area can be defined. The list is terminated - by an {0, 0} entry. - - - - - Placement defined by fs driver - - 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 - - - <spare data page 0><ecc result 0>...<ecc result n> - - - ... - - - <spare data page n><ecc result 0>...<ecc result n> - - - 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 - - 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. - - - - - Spare area autoplacement default schemes - - 256 byte pagesize - - -Offset -Content -Comment - - -0x00 -ECC byte 0 -Error correction code byte 0 - - -0x01 -ECC byte 1 -Error correction code byte 1 - - -0x02 -ECC byte 2 -Error correction code byte 2 - - -0x03 -Autoplace 0 - - - -0x04 -Autoplace 1 - - - -0x05 -Bad block marker -If any bit in this byte is zero, then this block is bad. -This applies only to the first page in a block. In the remaining -pages this byte is reserved - - -0x06 -Autoplace 2 - - - -0x07 -Autoplace 3 - - - - - - 512 byte pagesize - - -Offset -Content -Comment - - -0x00 -ECC byte 0 -Error correction code byte 0 of the lower 256 Byte data in -this page - - -0x01 -ECC byte 1 -Error correction code byte 1 of the lower 256 Bytes of data -in this page - - -0x02 -ECC byte 2 -Error correction code byte 2 of the lower 256 Bytes of data -in this page - - -0x03 -ECC byte 3 -Error correction code byte 0 of the upper 256 Bytes of data -in this page - - -0x04 -reserved -reserved - - -0x05 -Bad block marker -If any bit in this byte is zero, then this block is bad. -This applies only to the first page in a block. In the remaining -pages this byte is reserved - - -0x06 -ECC byte 4 -Error correction code byte 1 of the upper 256 Bytes of data -in this page - - -0x07 -ECC byte 5 -Error correction code byte 2 of the upper 256 Bytes of data -in this page - - -0x08 - 0x0F -Autoplace 0 - 7 - - - - - - 2048 byte pagesize - - -Offset -Content -Comment - - -0x00 -Bad block marker -If any bit in this byte is zero, then this block is bad. -This applies only to the first page in a block. In the remaining -pages this byte is reserved - - -0x01 -Reserved -Reserved - - -0x02-0x27 -Autoplace 0 - 37 - - - -0x28 -ECC byte 0 -Error correction code byte 0 of the first 256 Byte data in -this page - - -0x29 -ECC byte 1 -Error correction code byte 1 of the first 256 Bytes of data -in this page - - -0x2A -ECC byte 2 -Error correction code byte 2 of the first 256 Bytes data in -this page - - -0x2B -ECC byte 3 -Error correction code byte 0 of the second 256 Bytes of data -in this page - - -0x2C -ECC byte 4 -Error correction code byte 1 of the second 256 Bytes of data -in this page - - -0x2D -ECC byte 5 -Error correction code byte 2 of the second 256 Bytes of data -in this page - - -0x2E -ECC byte 6 -Error correction code byte 0 of the third 256 Bytes of data -in this page - - -0x2F -ECC byte 7 -Error correction code byte 1 of the third 256 Bytes of data -in this page - - -0x30 -ECC byte 8 -Error correction code byte 2 of the third 256 Bytes of data -in this page - - -0x31 -ECC byte 9 -Error correction code byte 0 of the fourth 256 Bytes of data -in this page - - -0x32 -ECC byte 10 -Error correction code byte 1 of the fourth 256 Bytes of data -in this page - - -0x33 -ECC byte 11 -Error correction code byte 2 of the fourth 256 Bytes of data -in this page - - -0x34 -ECC byte 12 -Error correction code byte 0 of the fifth 256 Bytes of data -in this page - - -0x35 -ECC byte 13 -Error correction code byte 1 of the fifth 256 Bytes of data -in this page - - -0x36 -ECC byte 14 -Error correction code byte 2 of the fifth 256 Bytes of data -in this page - - -0x37 -ECC byte 15 -Error correction code byte 0 of the sixt 256 Bytes of data -in this page - - -0x38 -ECC byte 16 -Error correction code byte 1 of the sixt 256 Bytes of data -in this page - - -0x39 -ECC byte 17 -Error correction code byte 2 of the sixt 256 Bytes of data -in this page - - -0x3A -ECC byte 18 -Error correction code byte 0 of the seventh 256 Bytes of -data in this page - - -0x3B -ECC byte 19 -Error correction code byte 1 of the seventh 256 Bytes of -data in this page - - -0x3C -ECC byte 20 -Error correction code byte 2 of the seventh 256 Bytes of -data in this page - - -0x3D -ECC byte 21 -Error correction code byte 0 of the eighth 256 Bytes of data -in this page - - -0x3E -ECC byte 22 -Error correction code byte 1 of the eighth 256 Bytes of data -in this page - - -0x3F -ECC byte 23 -Error correction code byte 2 of the eighth 256 Bytes of data -in this page - - - - - - - - Filesystem support - - The NAND driver provides all necessary functions for a - filesystem via the MTD interface. - - - Filesystems must be aware of the NAND peculiarities and - restrictions. One major restrictions of NAND Flash is, that you cannot - write as often as you want to a page. The consecutive writes to a page, - before erasing it again, are restricted to 1-3 writes, depending on the - manufacturers specifications. This applies similar to the spare area. - - - Therefore NAND aware filesystems must either write in page size chunks - or hold a writebuffer to collect smaller writes until they sum up to - pagesize. Available NAND aware filesystems: JFFS2, YAFFS. - - - The spare area usage to store filesystem data is controlled by - the spare area placement functionality which is described in one - of the earlier chapters. - - - - Tools - - The MTD project provides a couple of helpful tools to handle NAND Flash. - - flasherase, flasheraseall: Erase and format FLASH partitions - nandwrite: write filesystem images to NAND FLASH - nanddump: dump the contents of a NAND FLASH partitions - - - - These tools are aware of the NAND restrictions. Please use those tools - instead of complaining about errors which are caused by non NAND aware - access methods. - - - - - Constants - - This chapter describes the constants which might be relevant for a driver developer. - - - Chip option constants - - Constants for chip id table - - These constants are defined in nand.h. They are ored together to describe - the chip functionality. - -/* Buswitdh is 16 bit */ -#define NAND_BUSWIDTH_16 0x00000002 -/* Device supports partial programming without padding */ -#define NAND_NO_PADDING 0x00000004 -/* Chip has cache program function */ -#define NAND_CACHEPRG 0x00000008 -/* Chip has copy back function */ -#define NAND_COPYBACK 0x00000010 -/* AND Chip which has 4 banks and a confusing page / block - * assignment. See Renesas datasheet for further information */ -#define NAND_IS_AND 0x00000020 -/* Chip has a array of 4 pages which can be read without - * additional ready /busy waits */ -#define NAND_4PAGE_ARRAY 0x00000040 - - - - - Constants for runtime options - - These constants are defined in nand.h. They are ored together to describe - the functionality. - -/* The hw ecc generator provides a syndrome instead a ecc value on read - * This can only work if we have the ecc bytes directly behind the - * data bytes. Applies for DOC and AG-AND Renesas HW Reed Solomon generators */ -#define NAND_HWECC_SYNDROME 0x00020000 - - - - - - - ECC selection constants - - Use these constants to select the ECC algorithm. - -/* No ECC. Usage is not recommended ! */ -#define NAND_ECC_NONE 0 -/* Software ECC 3 byte ECC per 256 Byte data */ -#define NAND_ECC_SOFT 1 -/* Hardware ECC 3 byte ECC per 256 Byte data */ -#define NAND_ECC_HW3_256 2 -/* Hardware ECC 3 byte ECC per 512 Byte data */ -#define NAND_ECC_HW3_512 3 -/* Hardware ECC 6 byte ECC per 512 Byte data */ -#define NAND_ECC_HW6_512 4 -/* Hardware ECC 6 byte ECC per 512 Byte data */ -#define NAND_ECC_HW8_512 6 - - - - - - Hardware control related constants - - These constants describe the requested hardware access function when - the boardspecific hardware control function is called - -/* Select the chip by setting nCE to low */ -#define NAND_CTL_SETNCE 1 -/* Deselect the chip by setting nCE to high */ -#define NAND_CTL_CLRNCE 2 -/* Select the command latch by setting CLE to high */ -#define NAND_CTL_SETCLE 3 -/* Deselect the command latch by setting CLE to low */ -#define NAND_CTL_CLRCLE 4 -/* Select the address latch by setting ALE to high */ -#define NAND_CTL_SETALE 5 -/* Deselect the address latch by setting ALE to low */ -#define NAND_CTL_CLRALE 6 -/* Set write protection by setting WP to high. Not used! */ -#define NAND_CTL_SETWP 7 -/* Clear write protection by setting WP to low. Not used! */ -#define NAND_CTL_CLRWP 8 - - - - - - Bad block table related constants - - These constants describe the options used for bad block - table descriptors. - -/* Options for the bad block table descriptors */ - -/* The number of bits used per block in the bbt on the device */ -#define NAND_BBT_NRBITS_MSK 0x0000000F -#define NAND_BBT_1BIT 0x00000001 -#define NAND_BBT_2BIT 0x00000002 -#define NAND_BBT_4BIT 0x00000004 -#define NAND_BBT_8BIT 0x00000008 -/* The bad block table is in the last good block of the device */ -#define NAND_BBT_LASTBLOCK 0x00000010 -/* The bbt is at the given page, else we must scan for the bbt */ -#define NAND_BBT_ABSPAGE 0x00000020 -/* bbt is stored per chip on multichip devices */ -#define NAND_BBT_PERCHIP 0x00000080 -/* bbt has a version counter at offset veroffs */ -#define NAND_BBT_VERSION 0x00000100 -/* Create a bbt if none axists */ -#define NAND_BBT_CREATE 0x00000200 -/* Write bbt if necessary */ -#define NAND_BBT_WRITE 0x00001000 -/* Read and write back block contents when writing bbt */ -#define NAND_BBT_SAVECONTENT 0x00002000 - - - - - - - - Structures - - This chapter contains the autogenerated documentation of the structures which are - used in the NAND driver and might be relevant for a driver developer. Each - struct member has a short description which is marked with an [XXX] identifier. - See the chapter "Documentation hints" for an explanation. - -!Iinclude/linux/mtd/nand.h - - - - Public Functions Provided - - This chapter contains the autogenerated documentation of the NAND kernel API functions - which are exported. Each function has a short description which is marked with an [XXX] identifier. - See the chapter "Documentation hints" for an explanation. - -!Edrivers/mtd/nand/nand_base.c -!Edrivers/mtd/nand/nand_bbt.c -!Edrivers/mtd/nand/nand_ecc.c - - - - Internal Functions Provided - - This chapter contains the autogenerated documentation of the NAND driver internal functions. - Each function has a short description which is marked with an [XXX] identifier. - See the chapter "Documentation hints" for an explanation. - The functions marked with [DEFAULT] might be relevant for a board driver developer. - -!Idrivers/mtd/nand/nand_base.c -!Idrivers/mtd/nand/nand_bbt.c - - - - - Credits - - The following people have contributed to the NAND driver: - - Steven J. Hillsjhill@realitydiluted.com - David Woodhousedwmw2@infradead.org - Thomas Gleixnertglx@linutronix.de - - A lot of users have provided bugfixes, improvements and helping hands for testing. - Thanks a lot. - - - The following people have contributed to this document: - - Thomas Gleixnertglx@linutronix.de - - - - -- cgit v1.2.3