## 14 NAND Flash Commands

Compared to NOR or SPI flash, NAND devices are inexpensive and high density. Today’s NAND chips, and multi-chip modules, commonly hold multiple GigaBytes of data.

NAND chips consist of a number of “erase blocks” of a given size (such as 128 KBytes), each of which is divided into a number of pages (of perhaps 512 or 2048 bytes each). Each page of a NAND flash has an “out of band” (OOB) area to hold Error Correcting Code (ECC) and other metadata, usually 16 bytes of OOB for every 512 bytes of page data.

One key characteristic of NAND flash is that its error rate is higher than that of NOR flash. In normal operation, that ECC is used to correct and detect errors. However, NAND blocks can also wear out and become unusable; those blocks are then marked "bad". NAND chips are even shipped from the manufacturer with a few bad blocks. The highest density chips use a technology (MLC) that wears out more quickly, so ECC support is increasingly important as a way to detect blocks that have begun to fail, and help to preserve data integrity with techniques such as wear leveling.

Software is used to manage the ECC. Some controllers don’t support ECC directly; in those cases, software ECC is used. Other controllers speed up the ECC calculations with hardware. Single-bit error correction hardware is routine. Controllers geared for newer MLC chips may correct 4 or more errors for every 512 bytes of data.

You will need to make sure that any data you write using OpenOCD includes the apppropriate kind of ECC. For example, that may mean passing the `oob_softecc` flag when writing NAND data, or ensuring that the correct hardware ECC mode is used.

The basic steps for using NAND devices include:

1. Declare via the command `nand device`
   Do this in a board-specific configuration file, passing parameters as needed by the controller.
2. Configure each device using `nand probe`.
   Do this only after the associated target is set up, such as in its reset-init script or in procures defined to access that device.
3. Operate on the flash via `nand subcommand`
   Often commands to manipulate the flash are typed by a human, or run via a script in some automated way. Common task include writing a boot loader, operating system, or other data needed to initialize or de-brick a board.

NOTE: At the time this text was written, the largest NAND flash fully supported by OpenOCD is 2 GiBytes (16 GiBits). This is because the variables used to hold offsets and lengths are only 32 bits wide. (Larger chips may work in some cases, unless an offset or length is larger than 0xffffffff, the largest 32-bit unsigned integer.) Some larger devices will work, since they are actually multi-chip modules with two smaller chips and individual chipselect lines.

### 14.1 NAND Configuration Commands

NAND chips must be declared in configuration scripts, plus some additional configuration that’s done after OpenOCD has initialized.

Config Command: nand device name driver target [configparams...]

  Declares a NAND device, which can be read and written to after it has been configured through `nand probe`. In OpenOCD, devices are single chips; this is unlike some operating systems, which may manage multiple chips as if they were a single (larger) device. In some cases, configuring a device will activate extra commands; see the controller-specific documentation.

  NOTE: This command is not available after OpenOCD initialization has completed. Use it in board specific configuration files, not interactively.

  - name ... may be used to reference the NAND bank in most other NAND commands. A number is also available.
  - driver ... identifies the NAND controller driver associated with the NAND device being declared. See NAND Driver List.
  - target ... names the target used when issuing commands to the NAND controller.
  - configparams ... controllers may support, or require, additional parameters. See the controller-specific documentation for more information.

Command: nand list

  Prints a summary of each device declared using `nand device`, numbered from zero. Note that un-probed devices show no details.

      > nand list
      #0: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
              blocksize: 131072, blocks: 8192
      #1: NAND 1GiB 3,3V 8-bit (Micron) pagesize: 2048, buswidth: 8,
              blocksize: 131072, blocks: 8192
      >

Command: nand probe num

  Probes the specified device to determine key characteristics like its page and block sizes, and how many blocks it has. The num parameter is the value shown by `nand list`. You must (successfully) probe a device before you can use it with most other NAND commands.

### 14.2 Erasing, Reading, Writing to NAND Flash

Command: nand dump num filename offset length [oob_option]

  Reads binary data from the NAND device and writes it to the file, starting at the specified offset. The num parameter is the value shown by `nand list`.

  Use a complete path name for filename, so you don’t depend on the directory used to start the OpenOCD server.

  The offset and length must be exact multiples of the device’s page size. They describe a data region; the OOB data associated with each such page may also be accessed.

  NOTE: At the time this text was written, no error correction was done on the data that’s read, unless raw access was disabled and the underlying NAND controller driver had a `read_page` method which handled that error correction.

  By default, only page data is saved to the specified file. Use an oob_option parameter to save OOB data:

  - no oob_* parameter
    Output file holds only page data; OOB is discarded.
  - `oob_raw`
    Output file interleaves page data and OOB data; the file will be longer than "length" by the size of the spare areas associated with each data page. Note that this kind of "raw" access is different from what’s implied by `nand raw_access`, which just controls whether a hardware-aware access method is used.
  - `oob_only`
    Output file has only raw OOB data, and will be smaller than "length" since it will contain only the spare areas associated with each data page.

Command: nand erase num [offset length]

  Erases blocks on the specified NAND device, starting at the specified offset and continuing for length bytes. Both of those values must be exact multiples of the device’s block size, and the region they specify must fit entirely in the chip. If those parameters are not specified, the whole NAND chip will be erased. The num parameter is the value shown by `nand list`.

  NOTE: This command will try to erase bad blocks, when told to do so, which will probably invalidate the manufacturer’s bad block marker. For the remainder of the current server session, `nand info` will still report that the block “is” bad.

Command: nand write num filename offset [option...]

  Writes binary data from the file into the specified NAND device, starting at the specified offset. Those pages should already have been erased; you can’t change zero bits to one bits. The num parameter is the value shown by `nand list`.

  Use a complete path name for filename, so you don’t depend on the directory used to start the OpenOCD server.

  The offset must be an exact multiple of the device’s page size. All data in the file will be written, assuming it doesn’t run past the end of the device. Only full pages are written, and any extra space in the last page will be filled with 0xff bytes. (That includes OOB data, if that’s being written.)

  NOTE: At the time this text was written, bad blocks are ignored. That is, this routine will not skip bad blocks, but will instead try to write them. This can cause problems.

  Provide at most one option parameter. With some NAND drivers, the meanings of these parameters may change if `nand raw_access` was used to disable hardware ECC.

  - no oob_* parameter
    File has only page data, which is written. If raw acccess is in use, the OOB area will not be written. Otherwise, if the underlying NAND controller driver has a `write_page` routine, that routine may write the OOB with hardware-computed ECC data.
  - `oob_only`
    File has only raw OOB data, which is written to the OOB area. Each page’s data area stays untouched. This can be a dangerous option, since it can invalidate the ECC data. You may need to force raw access to use this mode.
  - `oob_raw`
    File interleaves data and OOB data, both of which are written If raw access is enabled, the data is written first, then the un-altered OOB. Otherwise, if the underlying NAND controller driver has a `write_page` routine, that routine may modify the OOB before it’s written, to include hardware-computed ECC data.
  - `oob_softecc`
    File has only page data, which is written. The OOB area is filled with 0xff, except for a standard 1-bit software ECC code stored in conventional locations. You might need to force raw access to use this mode, to prevent the underlying driver from applying hardware ECC.
  - `oob_softecc_kw`
    File has only page data, which is written. The OOB area is filled with 0xff, except for a 4-bit software ECC specific to the boot ROM in Marvell Kirkwood SoCs. You might need to force raw access to use this mode, to prevent the underlying driver from applying hardware ECC.

Command: nand verify num filename offset [option...]

  Verify the binary data in the file has been programmed to the specified NAND device, starting at the specified offset. The num parameter is the value shown by `nand list`.

  Use a complete path name for filename, so you don’t depend on the directory used to start the OpenOCD server.

  The offset must be an exact multiple of the device’s page size. All data in the file will be read and compared to the contents of the flash, assuming it doesn’t run past the end of the device. As with `nand write`, only full pages are verified, so any extra space in the last page will be filled with 0xff bytes.

  The same options accepted by `nand write`, and the file will be processed similarly to produce the buffers that can be compared against the contents produced from `nand dump`.

  NOTE: This will not work when the underlying NAND controller driver’s `write_page` routine must update the OOB with a hardward-computed ECC before the data is written. This limitation may be removed in a future release.

### 14.3 Other NAND commands

Command: nand check_bad_blocks num [offset length]

  Checks for manufacturer bad block markers on the specified NAND device. If no parameters are provided, checks the whole device; otherwise, starts at the specified offset and continues for length bytes. Both of those values must be exact multiples of the device’s block size, and the region they specify must fit entirely in the chip. The num parameter is the value shown by `nand list`.

  NOTE: Before using this command you should force raw access with `nand raw_access enable` to ensure that the underlying driver will not try to apply hardware ECC.

Command: nand info num

  The num parameter is the value shown by `nand list`. This prints the one-line summary from "nand list", plus for devices which have been probed this also prints any known status for each block.

Command: nand raw_access num (`enable`|`disable`)

  Sets or clears an flag affecting how page I/O is done. The num parameter is the value shown by `nand list`.

  This flag is cleared (disabled) by default, but changing that value won’t affect all NAND devices. The key factor is whether the underlying driver provides `read_page` or `write_page` methods. If it doesn’t provide those methods, the setting of this flag is irrelevant; all access is effectively “raw”.

  When those methods exist, they are normally used when reading data (`nand dump` or reading bad block markers) or writing it (`nand write`). However, enabling raw access (setting the flag) prevents use of those methods, bypassing hardware ECC logic. This can be a dangerous option, since writing blocks with the wrong ECC data can cause them to be marked as bad.

### 14.4 NAND Driver List

As noted above, the `nand device` command allows driver-specific options and behaviors. Some controllers also activate controller-specific commands.

NAND Driver: at91sam9

  This driver handles the NAND controllers found on AT91SAM9 family chips from Atmel. It takes two extra parameters: address of the NAND chip; address of the ECC controller.

      nand device $NANDFLASH at91sam9 $CHIPNAME 0x40000000 0xfffffe800

  AT91SAM9 chips support single-bit ECC hardware. The `write_page` and `read_page` methods are used to utilize the ECC hardware unless they are disabled by using the `nand raw_access` command. There are four additional commands that are needed to fully configure the AT91SAM9 NAND controller. Two are optional; most boards use the same wiring for ALE/CLE:

  Command: at91sam9 cle num addr_line

    Configure the address line used for latching commands. The num parameter is the value shown by `nand list`.

  Command: at91sam9 ale num addr_line

    Configure the address line used for latching addresses. The num parameter is the value shown by `nand list`.

  For the next two commands, it is assumed that the pins have already been properly configured for input or output.

  Command: at91sam9 rdy_busy num pio_base_addr pin

    Configure the RDY/nBUSY input from the NAND device. The num parameter is the value shown by `nand list`. pio_base_addr is the base address of the PIO controller and pin is the pin number.

  Command: at91sam9 ce num pio_base_addr pin

    Configure the chip enable input to the NAND device. The num parameter is the value shown by `nand list`. pio_base_addr is the base address of the PIO controller and pin is the pin number.

NAND Driver: davinci

  This driver handles the NAND controllers found on DaVinci family chips from Texas Instruments. It takes three extra parameters: address of the NAND chip; hardware ECC mode to use (`hwecc1`, `hwecc4`, `hwecc4_infix`); address of the AEMIF controller on this processor.

      nand device davinci dm355.arm 0x02000000 hwecc4 0x01e10000

  All DaVinci processors support the single-bit ECC hardware, and newer ones also support the four-bit ECC hardware. The `write_page` and `read_page` methods are used to implement those ECC modes, unless they are disabled using the `nand raw_access` command.

NAND Driver: lpc3180

  These controllers require an extra `nand device` parameter: the clock rate used by the controller.

  Command: lpc3180 select num [mlc|slc]

    Configures use of the MLC or SLC controller mode. MLC implies use of hardware ECC. The num parameter is the value shown by `nand list`.

  At this writing, this driver includes `write_page` and `read_page` methods. Using `nand raw_access` to disable those methods will prevent use of hardware ECC in the MLC controller mode, but won’t change SLC behavior.

NAND Driver: mx3

  This driver handles the NAND controller in i.MX31. The mxc driver should work for this chip aswell.

NAND Driver: mxc

  This driver handles the NAND controller found in Freescale i.MX chips. It has support for v1 (i.MX27 and i.MX31) and v2 (i.MX35). The driver takes 3 extra arguments, chip (`mx27`, `mx31`, `mx35`), ecc (`noecc`, `hwecc`) and optionally if bad block information should be swapped between main area and spare area (`biswap`), defaults to off.

      nand device mx35.nand mxc imx35.cpu mx35 hwecc biswap

  Command: mxc biswap bank_num [enable|disable]

    Turns on/off bad block information swaping from main area, without parameter query status.

NAND Driver: orion

  These controllers require an extra `nand device` parameter: the address of the controller.

      nand device orion 0xd8000000

  These controllers don’t define any specialized commands. At this writing, their drivers don’t include `write_page` or `read_page` methods, so `nand raw_access` won’t change any behavior.

NAND Driver: s3c2410
NAND Driver: s3c2412
NAND Driver: s3c2440
NAND Driver: s3c2443
NAND Driver: s3c6400

  These S3C family controllers don’t have any special `nand device` options, and don’t define any specialized commands. At this writing, their drivers don’t include `write_page` or `read_page` methods, so `nand raw_access` won’t change any behavior.