| nandps Vitis Drivers API Documentation

- Overview
- Data Structures
- APIs
- File List
- Examples

nandps Documentation

This file implements a driver for the NAND flash controller.Driver Initialization

The function call XNandPs_CfgInitialize() should be called by the application before any other function in the driver. The initialization function takes device specific data (like device id, instance id, and base address) and initializes the XNandPs instance with the device specific data.

Device Geometry

NAND flash device is memory device and it is segmented into areas called Logical Unit(s) (LUN) and further in to blocks and pages. A NAND flash device can have multiple LUN. LUN is sequential raw of multiple blocks of the same size. A block is the smallest erasable unit of data within the Flash array of a LUN. The size of each block is based on a power of 2. There is no restriction on the number of blocks within the LUN. A block contains a number of pages. A page is the smallest addressable unit for read and program operations. The arrangement of LUN, blocks, and pages is referred to by this module as the part's geometry.

The cells within the part can be programmed from a logic 1 to a logic 0 and not the other way around. To change a cell back to a logic 1, the entire block containing that cell must be erased. When a block is erased all bytes contain the value 0xFF. The number of times a block can be erased is finite. Eventually the block will wear out and will no longer be capable of erasure. As of this writing, the typical flash block can be erased 100,000 or more times.

The jobs done by this driver typically are:

- 8/16 bit operational mode
- Read, Write, and Erase operation
- Read, Write cache operation
- Read, Write Spare area operation
- HW Error Check and Correction (ECC)

Write Operation

The write call can be used to write a minimum of one byte and a maximum entire flash. If the address offset specified to write is out of flash or if the number of bytes specified from the offset exceed flash boundaries an error is reported back to the user. The write is blocking in nature in that the control is returned back to user only after the write operation is completed successfully or an error is reported.

Read Operation

The read call can be used to read a minimum of one byte and maximum of entire flash. If the address offset specified to read is out of flash or if the number of bytes specified from the offset exceed flash boundaries an error is reported back to the user. The read is blocking in nature in that the control is returned back to user only after the read operation is completed successfully or an error is reported.

Erase Operation

The erase operations are provided to erase a Block in the Flash memory. The erase call is blocking in nature in that the control is returned back to user only after the erase operation is completed successfully or an error is reported.

Page Cache Write Operation

The page cache write call is same as write call except that it uses cache commands to write. This enhances the performance. This operation can't be performed on OnDie ECC with internal ECC enabled. There is no way to disable internal ECC for OnDie ECC flash parts in current driver. This operation is tested with Spansion S34ML04G100TFI00 flash. We have to use this operation only on the flash parts which supports program page cache command.

Page Cache Read Operation

The page cache read call is same as read call except that it uses cache commands to read. This enhances the performance. The read cache random command is used since the HW ECC block doesn't support commands without address for starting ECC. This operation can't be performed on OnDie ECC with internal ECC enabled. There is no way to disable internal ECC for OnDie ECC flash parts in current driver. This operation is tested with Spansion S34ML04G100TFI00 flash. We have to use this operation only on the flash parts which supports read page cache command (random).

Write Spare Bytes Operation

This call writes to user specified buffer into spare bytes of a page.

Read Spare Bytes Operation

This call reads spare bytes of a page into user specified buffer.

Note

This driver is intended to be RTOS and processor independent. It works with physical addresses only. Any needs for dynamic memory management, threads, mutual exclusion, virtual memory, cache control, or HW write protection management must be satisfied by the layer above this driver.

    MODIFICATION HISTORY:

    Ver   Who    Date          Changes

    1.00a nm     12/10/2010  First release
            nm     29/09/2011  Added support for On-Die ECC NAND and Clean NAND
                             flash parts.
                             Added user spare buffer pointer to read/write
                             API's. Added new API's for reading and writing
                             spare buffer area.
                             Changes nand_cycles with ONFI timing mode 0.
                             Modified ONFI parameter page reading to read 3
                             mandatory pages.
    1.01a nm     28/02/2012  Added tcl file to generate xparameters.h.
                             Added support for 8Gb On-Die ECC NAND flash
                             parts (CR 648463).
                             Fixed 16-bit issue with ONFI commands like
                             read, write and read status command.
    1.02a nm     20/09/2012  Removed setting of set_cycles and set_opmode
                             register values as it is now done in FSBL using
                             the PCW generated files. CR#678949.
    1.03a nm     10/22/2012  Fixed CR# 683787,673348.
    1.04a nm     04/15/2013  Fixed CR# 704401. Removed warnings when compiled
                               with -Wall and -Wextra option in bsp.
                 04/25/2013  Implemented PR# 699544. Added page cache read
                       and program support. Added API's XNandPs_ReadCache
                       and XNandPs_WriteCache for page cache support.
                       Added XNandPs_Features structure to XNandPs instance
                       which contains features handled by driver.
                       Added function prototypes for Page cache read/write
                       and spare byte read/write API's.
    2.0   adk    12/10/13    Updated as per the New Tcl API's
    2.1   kpc    07/24/13    Fixed CR#808770. Update command register twice only
                             if flash device requires >= four address cycles.
    2.2   sb     01/31/2015  Use the address cycles defined in onfi parameter
                       page than hardcoding this value to 5 for read and
                       write operations.
          ms     03/17/17    Added readme.txt file in examples folder for doxygen
                             generation.
          ms     04/10/17    Modified Comment lines in examples to follow doxygen
                             rules.
    2.3   ms     04/18/17    Modified tcl file to add suffix U for all macros
                             definitions of nandps in xparameters.h
    2.4   nsk    06/20/18    Fixed BBT offset overflow in XNandPs_WriteBbt()
                       and XNandPs_ReadBbt().
    2.6     akm    09/03/20    Updated the Makefile to support parallel make execution.
    2.7   sg     03/18/21    Added validation check for parameter page.
    2.8  akm     07/06/23    Update the driver to support for system device-tree flow.
    2.9  sb      01/03/24    Add FlashBbt array in nandps structure for partial read/write operations
                             while reading and writing bbt in flash.
    2.10 akm     10/04/24    Retrieve the 'reg' property value from smcc node 'ranges'