Tuesday, February 23, 2010

The main job to implement NAND driver for UFFS is setup "struct uffs_StorageAttrSt" and provide functions in "struct uffs_FlashOpsSt" .

Setup "struct StorageAttrSt":This is the data structure to describe the basic attributes of you NAND flash, tell UFFS which ECC option your driver will use and how the tag and ECC will be layout to page spare area.

uffs_StorageAttrSt::block_status_offsThere is one byte on page spare area used for indicating block status (bad/good block). The position of the status byte is NAND vendor specific. For example, SAMSUNG NAND flash with small page size (512) usually use the 5th bytes of spare as status byte, so you should set ::block_status_offs = 4 (0 based offset).

uffs_StorageAttrSt::ecc_optChoose ECC options for your driver:

UFFS_ECC_NONE - do not use ECC ( not recommended )

UFFS_ECC_SOFT - UFFS will take care of ECC calculation and correction.

UFFS_ECC_HW_AUTO - Your NAND controller will generate ECC code AND write the ECC codes to page spare area (and you can't stop that !) when you write data to page data area. This will cause partial programming on spare area as UFFS need to write tag to spare later.

For most modem MCUs with build-in NAND controller, your should choose UFFS_ECC_HW, otherwise choose UFFS_ECC_SOFT. Some very rare NAND controller will write ECC right after encode, in this case, choose UFFS_ECC_HW_AUTO.

uffs_StorageAttrSt::layout_optTell UFFS do the layout for you or you driver will do the layout. In most case, you should choose letting UFFS do the layout (UFFS_LAYOUT_UFFS). In very rare case you might want to do the layout in your driver (UFFS_LAYOUT_FLASH).

If UFFS_LAYOUT_UFFS is chosen, your driver must provide 'ReadPageSpare' and 'WritePageSpare' functions in "struct uffs_FlashOpsSt". (will discuss this later)

if UFFS_LAYOUT_FLASH is chosen, your driver must provide 'ReadPageSpareWithLayout' and 'WritePageSpareWithLayout' functions in "struct uffs_FlashOpsSt".

uffs_StorageAttrSt::ecc_layout, uffs_StorageAttrSt::data_layoutTell UFFS how to layout the ECC and Tag data on page spare area.

In most case, you should set ecc_layout and data_layout to NULL and UFFS will create the layout array for you.

However, if you have to use UFFS_ECC_HW_AUTO for ecc_opt (because of the rare hardware controller) or you want to create your own spare layout to be compatible with other software, you need to provide the layout array.

The layout array is unsigned char array, start from offset, followed by size, terminated by [0xFF, 0x00].

dev: uffs_Deviceblock, page: block and page number to be read. The page number is relative number (to the block).data: buffer for the read datalen: the size of data to be readecc: if your driver use hardware to calculate ECC (ecc_opt = UFF_ECC_HW), your driver should copy the calcuated ECC to ecc. For other ecc_opt (UFFS_ECC_NONE, UFFS_ECC_SOFT or UFFS_ECC_HW_AUTO), ecc is not used.

dev: uffs_Deviceblock, page: block and page number to be read. The page number is relative number (to the block).spare: buffer for the read dataofs: reading offset from the start of spare area.len: the data amount to be read

dev: uffs_Deviceblock, page: block and page number to be wrote data: data bufferofs: programing offset from the start of spare arealen: size of dataeod: U_FALSE if this function is called after 'WritePageData', otherwise U_TRUE

UFFS_FLASH_BAD_BLK should be returned if a bad block is found.

Note1: When programing a full page (data area + spare area), UFFS call WritePageData() followed by WritePageSpare(eod = U_TRUE). In this case, START command sent in WritePageData() and PROGRAM command sent in WritePageSpare(), this avoid partial program.

Note2: When programming page spare area only, UFFS call WritePageSpare(eod = U_FALSE). In this case, START and PROGRAM command issued within WritePageSpare() function.

Thanks to the people who tried/adopted UFFS in their projects, it's YOU made this release :)

Version 1.3 is an important version in the way to UFFS2, the new features and structure changes in v1.3 made a clean and flexible code base. It's recommended for all UFFS users to update to this new release.