nandps
Vitis Drivers API Documentation
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.