HCC-Embedded. Embedded Flash File System Flash Translation Layer Developer Guide

Transcription

1 EFFS FTL - API Guide HCC-Embedded Embedded Flash File System Flash Translation Layer Developer Guide Version 101 All rights reserved This document and the associated software are the sole property of HCC-Embedded Kft Reproduction or duplication by any means of any portion of this document without the prior written consent of HCC-Embedded Kft is expressly forbidden HCC-Embedded Kft reserves the right to make changes to this document and to the related software at any time and without notice The information in this document has been carefully checked for its accuracy; however, HCC-Embedded Kft makes no warranty relating to the correctness of this document HCC-Embedded Kft 1 wwwhcc-embeddedcom

2 0 Overview 3 1 Files 4 2 Upper Layer Functions 5 UL_INIT 5 UL_FORMAT 6 UL_GETMAXSECTOR 7 UL_OPEN 8 UL_CLOSE 9 UL_READ 10 UL_WRITE 11 3 Lower Layer Functions 12 LL_INIT 12 LL_ERASE 13 LL_WRITE 14 LL_WRITEDOUBLE 15 LL_READ 16 4 System definitions 17 ULAYER_SETS 17 MAX_BLOCK 17 MAX_PAGE_PER_BLOCK 17 MAX_DATA_SIZE 17 MAX_SPARE_SIZE* 17 MAX_FREE_BLOCK* 17 MAX_LOG_BLOCK* 17 MAX_RESERVED_BLOCK* HCC-Embedded Kft 2 wwwhcc-embeddedcom

3 EFFS FTL - API Guide 0 Overview This document is a developers guide as to how to use EFFS-FTL EFFS-FTL is a highly efficient Flash Translation Layer designed for use with most standard types of NAND flash with all standard configuarations EFFS-FTL has two interfaces: Upper Layer interface: these are the API functions provided to an application (typically a file system) which will use the FTL Lower Layer Interface: these are a set of functions provided by the target system for basic access to the NAND flash devices Sample code is provided for this HCC-Embedded Kft 3 wwwhcc-embeddedcom

4 1 Files The following are the source files provided with the system: ulayerc - upper layer and functionality of FTL ulayerh - header for upper layer fil_badc - bad block handling module fil_badh - header for bad block handling fil_wearc - wear leveling module fil_wearh - header for wear leveling llayerc - low level layer for PC simulation llayerh - header for low level mdebugh - header for debug info prgmacroc - test routines prgmacroh - header for test routines k9f2816x0c_16bitc - low level layer for a sample target device Two sets of these files are provided SRC_NRM and SRC_EXT SRC_NRM is the standard system for use on systems with up to erasable blocks with a maximum of 128 pages per block SRC_EXT is an extended version of SRC_NRM which allows the use of multiple normal systems to extend the number of blocks which may be used HCC-Embedded Kft 4 wwwhcc-embeddedcom

5 EFFS FTL - API Guide 2 Upper Layer Functions Ulayer functions are the interface of FTL layer to the user application typically a file system ul_init This function must be called to initialize the flash translation layer If this function has an error, then this is a fatal error, in this case maybe the low level format function needs to be called (ul_format) int ul_init(void) None Return value 0 if successful other Example: void main() { if (ul_init()) { /* do some fatal error handling */ /* FTL cannot be used */ /* here FTL is useable */ HCC-Embedded Kft 5 wwwhcc-embeddedcom

6 ul_format This function must be called at once after manufacturing the device The function does a low level format of the FTL, all data is destroyed after this function is called int ul_format(void) None Return value 0 if successful other Example: if (ul_format()) { /* fatal error, device is not useable */ /* low level format is completed, so FTL can be used */ HCC-Embedded Kft 6 wwwhcc-embeddedcom

7 EFFS FTL - API Guide ul_getmaxsector This function retrieves the maximum accessible sector number Because of bad block handling and wear leveling and some other functionality of FTL this number is a dynamic number and calculated after ul_format or ul_init calls The disk size can be calculated by multiplying this number with MAX_DATA_SIZE unsigned long ul_getmaxsector(void) None Return value value number of sectors in FTL Example: unsigned long GetDiskSize() { return ul_getmaxsector()*max_data_size; HCC-Embedded Kft 7 wwwhcc-embeddedcom

8 ul_open This function is used to open a communication channel for reading or writing For mode parameter pass UL_READ for reading, UL_WRITE for writing int ul_open( Argument sector secnum mode unsigned long sector, unsigned long secnum, unsigned char mode ); start sector for operation sector number of the operation UL_READ or UL_WRITE Return value 0 if successful other Example: int read10sectors(long sectorstart, char *buffer ) { long cou; if (ul_open(sectorstart, 10,UL_READ)) return 1; for (cou=0; cou<10; cou++) { if (ul_read(buffer)) return 1; buffer+=max_data_size; if (ul_close()) return 1; return 0; HCC-Embedded Kft 8 wwwhcc-embeddedcom

9 EFFS FTL - API Guide ul_close This function is used to close the communication channel int ul_close(void) None Return value 0 if successful other Example: int read10sectors(long sectorstart, char *buffer ) { long cou; if (ul_open(sectorstart, 10,UL_READ)) return 1; for (cou=0; cou<10; cou++) { if (ul_read(buffer)) return 1; buffer+=max_data_size; if (ul_close()) return 1; return 0; HCC-Embedded Kft 9 wwwhcc-embeddedcom

10 ul_read Reads 1 sector from flash The number of ul_read commands must be the same value as number of sectors was passed in ul_open command It reads MAX_DATA_SIZE number of bytes as 1 sector int ul_read(unsigned char *data) Argument data pointer where to store data Return value 0 if successful other Example: int read10sectors(long sectorstart, char *buffer ) { long cou; if (ul_open(sectorstart, 10,UL_READ)) return 1; for (cou=0; cou<10; cou++) { if (ul_read(buffer)) return 1; buffer+=max_data_size; if (ul_close()) return 1; return 0; HCC-Embedded Kft 10 wwwhcc-embeddedcom

11 EFFS FTL - API Guide ul_write Writes 1 sector into flash The number of ul_write commands must be the same value as number of sectors was passed in ul_open command It writes MAX_DATA_SIZE number of bytes as 1 sector int ul_write(unsigned char *data) Argument data pointer where to get data for writing Return value 0 if successful other Example: int write10sectors(long sectorstart, char *buffer ) { long cou; if (ul_open(sectorstart, 10,UL_READ)) return 1; for (cou=0; cou<10; cou++) { if (ul_write(buffer)) return 1; buffer+=max_data_size; if (ul_close()) return 1; return 0; HCC-Embedded Kft 11 wwwhcc-embeddedcom

12 3 Lower Layer Functions Llayer functions (low level) are called from higher level functions to communicate directly with the physical hardware device (or simulated device) These functions must be implemented according to the required functionality ll_init This function is called for initiate low level functions or devices unsigned char ll_init(void); None Return value LL_OK LL_ERROR if successful HCC-Embedded Kft 12 wwwhcc-embeddedcom

13 EFFS FTL - API Guide ll_erase This function is called for erasing a physical block in the device unsigned char ll_erase(t_ba pba); Argument pba physical block address Return value LL_OK LL_ERROR if successful HCC-Embedded Kft 13 wwwhcc-embeddedcom

14 ll_write This function is called for writing a page of a physical block in the device unsigned char ll_write(t_ba pba,t_po ppo, unsigned char *buffer) Argument pba ppo buffer physical block address physical page offset buffer points to data (data + spare area) Return value LL_OK LL_ERROR if successful HCC-Embedded Kft 14 wwwhcc-embeddedcom

15 EFFS FTL - API Guide ll_writedouble This function is called for writing a page of a physical block in the device There are two buffer parameter, where the 1 st one is the 1 st half of the data, the 2 nd buffer is the 2 nd half of the data and contains spare area as well unsigned char ll_write(t_ba pba,t_po ppo, unsigned char *buffer0, unsigned char *buffer1); Argument pba ppo buffer0 buffer physical block address physical page offset buffer points to data (1 st half of data) buffer points to data (2 nd half of data + spare area) Return value LL_OK LL_ERROR if successful HCC-Embedded Kft 15 wwwhcc-embeddedcom

16 ll_read This function is called for reading a page from a physical block in the device unsigned char ll_read(t_ba pba,t_po ppo, unsigned char *buffer) Argument pba ppo buffer physical block address physical page offset storing buffer points to data (data + spare area) Return value LL_OK LL_ERASED LL_ERROR if successful if page is an erased (all data and spare area is 0xff) HCC-Embedded Kft 16 wwwhcc-embeddedcom

17 EFFS FTL - API Guide 4 System definitions There are two different system of FTL contained in the SRC_NRM and SRC_EXT directories Only one of them can be used for a single implementation The difference between them is SRC_EXT can be used for multiple sets of SRC_NRM by multiplying the maximum number of block in the system SRC_NRM can handle a maximum number of blocks with maximum 128 pages in each block SRC_EXT can multiply this as many times as many device is in the system Contact HCC for more detailed information All the system definitions are in ulayerh and are described below: ULAYER_SETS Used only in SRC_EXT, this is the multiplier of the ulayer MAX_BLOCK Maximum number of physical blocks in the system MAX_PAGE_PER_BLOCK Number of pages per block MAX_DATA_SIZE Data size on one page Typically it is 512 or 2048 bytes MAX_SPARE_SIZE* This is a fixed structure; its size is 16 bytes MAX_FREE_BLOCK* Number of free blocks in the system MAX_LOG_BLOCK* Number of logged blocks in the system HCC-Embedded Kft 17 wwwhcc-embeddedcom

18 MAX_RESERVED_BLOCK* Number of reserved blocks in the system * These values have complex implications for the system They should only be changed after consulting HCC-Embedded HCC-Embedded Kft 18 wwwhcc-embeddedcom