| nandpsu Vitis Drivers API Documentation

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

nandpsu Documentation

This file implements a driver to support Arasan NAND controller present in Zynq Ultrascale Mp. Driver Initialization

The function call XNandPsu_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 XNandPsu 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-bit operational mode
- Read, Write, and Erase operation

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.

Note
  Driver has been renamed to nandpsu after change in naming convention.

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.0   nm     05/06/2014  First release
      2.0   sb     01/12/2015  Removed Null checks for Buffer passed
                               as parameter to Read API's

    XNandPsu_Read()
    XNandPsu_ReadPage
                               Modified
    XNandPsu_SetFeature()
    XNandPsu_GetFeature()
                               and made them public.
                               Removed Failure Return for BCF Error check in
                               XNandPsu_ReadPage() and added BCH_Error counter
                               in the instance pointer structure.
                               Added XNandPsu_Prepare_Cmd API
                               Replaced
    XNandPsu_IntrStsEnable
    XNandPsu_IntrStsClear
    XNandPsu_IntrClear
    XNandPsu_SetProgramReg
                               with XNandPsu_WriteReg call
                               Modified xnandpsu.c file API's with above changes.
                               Corrected the program command for Set Feature API.
                               Modified
    XNandPsu_OnfiReadStatus
    XNandPsu_GetFeature
    XNandPsu_SetFeature
                               to add support for DDR mode.
                               Changed Convention for SLC/MLC
                               SLC –> HAMMING
                               MLC –> BCH
                               SlcMlc –> IsBCH
                               Added support for writing BBT signature and version
                               in page section by enabling XNANDPSU_BBT_NO_OOB.
                               Removed extra DMA mode initialization from
                               the XNandPsu_CfgInitialize API.
                               Modified
    XNandPsu_SetEccAddrSize
                               ECC address now is calculated based upon the
                               size of spare area
                               Modified Block Erase API, removed clearing of
                               packet register before erase.
                               Clearing Data Interface Register before
                               XNandPsu_OnfiReset call.
                               Modified XNandPsu_ChangeTimingMode API supporting
                               SDR and NVDDR interface for timing modes 0 to 5.
                               Modified Bbt Signature and Version Offset value for
                               Oob and No-Oob region.
      1.0   kpc    17/06/2015  Increased the timeout for complete event to avoid
                               timeout errors for erase operation on slower devices.
      1.1   mi     09/16/16 Removed compilation warnings with extra compiler flags.
      1.1   nsk    11/07/16    Change memcpy to Xil_MemCpy, CR#960462
      1.2   nsk    01/19/17    Fix for the failure of reading nand first redundant
                               parameter page. CR#966603
            ms     02/12/17    Fix for the compilation warning in _g.c file.
            ms     03/17/17    Added readme.txt file in examples folder for doxygen
                               generation.
            ms     04/10/17    Modified Comment lines in nandpsu_example.c to
                               follow doxygen rules.
      1.2   nsk    08/08/17    Added support to import example in SDK
      1.4   nsk    04/10/18    Added ICCARM compiler support. CR#997552.
      1.5   mus    11/08/18    Updated BBT signature array size  in
                               XNandPsu_BbtDesc structure to fix the compilation
                               warnings.
    1.6   sd     06/02/20    Added Clock support

      1.6   sd     20/03/20    Added compilation flag
      1.8   sg     03/18/21    Added validation check for parameter page.
      1.9   akm    07/15/21    Initialize NandInstPtr with Data Interface & Timing mode info.
      1.10  akm    10/20/21    Fix gcc warnings.
      1.10  akm    12/21/21    Validate input parameters before use.
      1.10  akm    01/05/22    Remove assert checks form static and internal APIs.
      1.11  akm    03/31/22    Fix unused parameter warning.
      1.11  akm    03/31/22    Fix misleading-indentation warning.
      1.12  akm    06/27/23    Update the driver to support for system device-tree flow.
      1.13  akm    02/13/24    Ensure buffer cache sync.
      1.13  akm    02/13/24    Avoid loop counter reset.
      1.13  akm    02/13/24    Always wrap page to device size.