X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=doc%2FREADME.nand;h=ec461b2dc933b315a971607ee24a14e03a35e024;hb=8060209a9278593519f73ba763e67f7aa219a732;hp=a1a511c5339cbc8f9b6d71e1b13cf7e609fa9156;hpb=dfe161032d007e4901064ab36b58f054126b1f35;p=oweals%2Fu-boot.git diff --git a/doc/README.nand b/doc/README.nand index a1a511c533..ec461b2dc9 100644 --- a/doc/README.nand +++ b/doc/README.nand @@ -1,3 +1,4 @@ +# SPDX-License-Identifier: GPL-2.0+ NAND FLASH commands and notes See NOTE below!!! @@ -5,23 +6,6 @@ See NOTE below!!! # (C) Copyright 2003 # Dave Ellis, SIXNET, dge@sixnetio.com # -# See file CREDITS for list of people who contributed to this -# project. -# -# This program is free software; you can redistribute it and/or -# modify it under the terms of the GNU General Public License as -# published by the Free Software Foundation; either version 2 of -# the License, or (at your option) any later version. -# -# 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 Commands: @@ -105,26 +89,34 @@ Commands: Configuration Options: + CONFIG_SYS_NAND_U_BOOT_OFFS + NAND Offset from where SPL will read u-boot image. This is the starting + address of u-boot MTD partition in NAND. + CONFIG_CMD_NAND - Enables NAND support and commmands. + Enables NAND support and commands. CONFIG_CMD_NAND_TORTURE Enables the torture command (see description of this command below). - CONFIG_MTD_NAND_ECC_JFFS2 - Define this if you want the Error Correction Code information in - the out-of-band data to be formatted to match the JFFS2 file system. - CONFIG_MTD_NAND_ECC_YAFFS would be another useful choice for - someone to implement. - CONFIG_SYS_MAX_NAND_DEVICE The maximum number of NAND devices you want to support. + CONFIG_SYS_NAND_MAX_ECCPOS + If specified, overrides the maximum number of ECC bytes + supported. Useful for reducing image size, especially with SPL. + This must be at least 48 if nand_base.c is used. + + CONFIG_SYS_NAND_MAX_OOBFREE + If specified, overrides the maximum number of free OOB regions + supported. Useful for reducing image size, especially with SPL. + This must be at least 2 if nand_base.c is used. + CONFIG_SYS_NAND_MAX_CHIPS The maximum number of NAND chips per device to be supported. CONFIG_SYS_NAND_SELF_INIT - Traditionally, glue code in drivers/mtd/nand/nand.c has driven + Traditionally, glue code in drivers/mtd/nand/raw/nand.c has driven the initialization process -- it provides the mtd and nand structs, calls a board init function for a specific device, calls nand_scan(), and registers with mtd. @@ -133,7 +125,7 @@ Configuration Options: run code between nand_scan_ident() and nand_scan_tail(), or other deviations from the "normal" flow. - If a board defines CONFIG_SYS_NAND_SELF_INIT, drivers/mtd/nand/nand.c + If a board defines CONFIG_SYS_NAND_SELF_INIT, drivers/mtd/nand/raw/nand.c will make one call to board_nand_init(), with no arguments. That function is responsible for calling a driver init function for each NAND device on the board, that performs all initialization @@ -144,15 +136,8 @@ Configuration Options: Example of new init to be added to the end of an existing driver init: - /* - * devnum is the device number to be used in nand commands - * and in mtd->name. Must be less than - * CONFIG_SYS_NAND_MAX_DEVICE. - */ - mtd = &nand_info[devnum]; - /* chip is struct nand_chip, and is now provided by the driver. */ - mtd->priv = &chip; + mtd = nand_to_mtd(&chip); /* * Fill in appropriate values if this driver uses these fields, @@ -173,7 +158,11 @@ Configuration Options: if (nand_scan_tail(mtd)) error out - if (nand_register(devnum)) + /* + * devnum is the device number to be used in nand commands + * and in mtd->name. Must be less than CONFIG_SYS_MAX_NAND_DEVICE. + */ + if (nand_register(devnum, mtd)) error out In addition to providing more flexibility to the driver, it reduces @@ -185,17 +174,113 @@ Configuration Options: Please convert your driver even if you don't need the extra flexibility, so that one day we can eliminate the old mechanism. -NOTE: -===== -The current NAND implementation is based on what is in recent -Linux kernels. The old legacy implementation has been removed. + CONFIG_SYS_NAND_ONFI_DETECTION + Enables detection of ONFI compliant devices during probe. + And fetching device parameters flashed on device, by parsing + ONFI parameter page. + +Platform specific options +========================= + CONFIG_NAND_OMAP_GPMC + Enables omap_gpmc.c driver for OMAPx and AMxxxx platforms. + GPMC controller is used for parallel NAND flash devices, and can + do ECC calculation (not ECC error detection) for HAM1, BCH4, BCH8 + and BCH16 ECC algorithms. + + CONFIG_NAND_OMAP_ELM + Enables omap_elm.c driver for OMAPx and AMxxxx platforms. + ELM controller is used for ECC error detection (not ECC calculation) + of BCH4, BCH8 and BCH16 ECC algorithms. + Some legacy platforms like OMAP3xx do not have in-built ELM h/w engine, + thus such SoC platforms need to depend on software library for ECC error + detection. However ECC calculation on such plaforms would still be + done by GPMC controller. + + CONFIG_SPL_NAND_AM33XX_BCH + Enables SPL-NAND driver (am335x_spl_bch.c) which supports ELM based + hardware ECC correction. This is useful for platforms which have ELM + hardware engine and use NAND boot mode. + Some legacy platforms like OMAP3xx do not have in-built ELM h/w engine, + so those platforms should use CONFIG_SPL_NAND_SIMPLE for enabling + SPL-NAND driver with software ECC correction support. + + CONFIG_NAND_OMAP_ECCSCHEME + On OMAP platforms, this CONFIG specifies NAND ECC scheme. + It can take following values: + OMAP_ECC_HAM1_CODE_SW + 1-bit Hamming code using software lib. + (for legacy devices only) + OMAP_ECC_HAM1_CODE_HW + 1-bit Hamming code using GPMC hardware. + (for legacy devices only) + OMAP_ECC_BCH4_CODE_HW_DETECTION_SW + 4-bit BCH code (unsupported) + OMAP_ECC_BCH4_CODE_HW + 4-bit BCH code (unsupported) + OMAP_ECC_BCH8_CODE_HW_DETECTION_SW + 8-bit BCH code with + - ecc calculation using GPMC hardware engine, + - error detection using software library. + - requires CONFIG_BCH to enable software BCH library + (For legacy device which do not have ELM h/w engine) + OMAP_ECC_BCH8_CODE_HW + 8-bit BCH code with + - ecc calculation using GPMC hardware engine, + - error detection using ELM hardware engine. + OMAP_ECC_BCH16_CODE_HW + 16-bit BCH code with + - ecc calculation using GPMC hardware engine, + - error detection using ELM hardware engine. + + How to select ECC scheme on OMAP and AMxx platforms ? + ----------------------------------------------------- + Though higher ECC schemes have more capability to detect and correct + bit-flips, but still selection of ECC scheme is dependent on following + - hardware engines present in SoC. + Some legacy OMAP SoC do not have ELM h/w engine thus such + SoC cannot support BCHx_HW ECC schemes. + - size of OOB/Spare region + With higher ECC schemes, more OOB/Spare area is required to + store ECC. So choice of ECC scheme is limited by NAND oobsize. + + In general following expression can help: + NAND_OOBSIZE >= 2 + (NAND_PAGESIZE / 512) * ECC_BYTES + where + NAND_OOBSIZE = number of bytes available in + OOB/spare area per NAND page. + NAND_PAGESIZE = bytes in main-area of NAND page. + ECC_BYTES = number of ECC bytes generated to + protect 512 bytes of data, which is: + 3 for HAM1_xx ecc schemes + 7 for BCH4_xx ecc schemes + 14 for BCH8_xx ecc schemes + 26 for BCH16_xx ecc schemes + + example to check for BCH16 on 2K page NAND + NAND_PAGESIZE = 2048 + NAND_OOBSIZE = 64 + 2 + (2048 / 512) * 26 = 106 > NAND_OOBSIZE + Thus BCH16 cannot be supported on 2K page NAND. + + However, for 4K pagesize NAND + NAND_PAGESIZE = 4096 + NAND_OOBSIZE = 224 + ECC_BYTES = 26 + 2 + (4096 / 512) * 26 = 210 < NAND_OOBSIZE + Thus BCH16 can be supported on 4K page NAND. + + + CONFIG_NAND_OMAP_GPMC_PREFETCH + On OMAP platforms that use the GPMC controller + (CONFIG_NAND_OMAP_GPMC_PREFETCH), this options enables the code that + uses the prefetch mode to speed up read operations. -If you have board code which used CONFIG_NAND_LEGACY, you'll need -to convert to the current NAND interface for it to continue to work. +NOTE: +===== The Disk On Chip driver is currently broken and has been for some time. -There is a driver in drivers/mtd/nand, taken from Linux, that works with +There is a driver in drivers/mtd/nand/raw, taken from Linux, that works with the current NAND system but has not yet been adapted to the u-boot environment. @@ -216,7 +301,7 @@ Miscellaneous and testing commands: DANGEROUS!!! Factory set bad blocks will be lost. Use only to remove artificial bad blocks created with the "markbad" command. - "torture offset" + "torture offset [size]" Torture block to determine if it is still reliable. Enabled by the CONFIG_CMD_NAND_TORTURE configuration option. This command returns 0 if the block is still reliable, else 1. @@ -233,6 +318,10 @@ Miscellaneous and testing commands: automate actions following a nand->write() error. This would e.g. be required in order to program or update safely firmware to NAND, especially for the UBI part of such firmware. + Optionally, a second parameter size can be given to test multiple blocks with + one call. If size is not a multiple of the NAND's erase size, then the block + that contains offset + size will be tested in full. If used with size, this + command returns 0 if all tested blocks have been found reliable, else 1. NAND locking command (for chips with active LOCKPRE pin)