API

Flash-DBSim system provides two kinds of interfaces for developers: Public API Interfaces and Internal API Interfaces. Public API Interfaces are used for flash-based researches, and Internal API Interfaces are for secondary development and functional extension.

Basic Types
RV Return value type of Flash-DBSim system. If the function completed successfully, the return value will be RV_OK.
BLOCK_ID Physical block ID.
PAGE_ID Physical page ID.
LBA Logical block address.
ID_MODULE The module ID of Flash-DBSim system.
IDM_VFD, IDM_FTL The VFD/FTL module ID of Flash-DBSim system.
VFD_ID The ID of VFD Modules in Flash-DBSim system. All IDs of VFD modules in Flash-DBSim system are shown below:
FTL_ID The ID of FTL Modules in Flash-DBSim system. All IDs of FTL modules in Flash-DBSim system are shown below:
VFD_INFO  The configuration information of VFD module.
All fields in VFD_INFO are:
  • id: The ID of VFD module.
  • blockCount: The number of blocks in virtual flash device.
  • pageSize.size1: The size of data area per page, in byte.
  • pageSize.size2: The size of spare area per page, in byte.
  • pageCountPerBlock: The number of pages in every block.
  • eraseLimitation: The erase limitation of each block.
  • readTime.randomTime: The time of random read operation (MAX).
  • readTime.serialTime: The time of serial read operation (MIN).
  • programTime: The time of page program operation.
  • eraseTime: The time of block erase operation.
FTL_INFO  The configuration information of FTL module.
All fields in FTL_INFO are:
  • id: The ID of FTL module.。
  • mapListSize: The size of LBA-PBA map list.
  • wearLevelingThreshold: The threshold for wear-leveling.

Attention: Not all fields in VFD_INFO/FTL_INFO are necessary. Some VFD/FTL modules just use a part of them. See "Module" page for more information.

Public API Interfaces

Developers use Flash-DBSim system by calling the public API interfaces. All public API interfaces in Flash-DBSim are shown below:

  1. f_initialize
  2. f_release


  3. f_alloc_page
  4. f_release_page
  5. f_read_page
  6. f_write_page


  7. f_get_read_count 
  8. f_get_write_count 
  9. f_get_erase_count 
  10. f_get_read_count_total 
  11. f_get_write_count_total 
  12. f_get_erase_count_total 
  13. f_get_read_latency_total 
  14. f_get_write_latency_total 
  15. f_get_erase_latency_total 
f_initialize
Description: Initialize all data, modules in Flash-DBSim system.
RV f_initialize(
  const VFD_INFO& vfdInfo,
  const FTL_INFO& ftlInfo
);
Return Value: RV
Parameters:
vfdInfo The information of VFD module to be used in Flash-DBSim system.
ftlInfo The information of FTL module to be used in Flash-DBSim system.
Example: See also f_release
f_release
Description: Release all data, memory, modules in Flash-DBSim system.
RV f_release();
Return Value: RV
Parameters: (None)
Example: VFD_INFO vfdInfo;  /* information of VFD module */
FTL_INFO ftlInfo;  /* information of FTL module */

/* set 'vfdInfo' and 'ftlInfo' */
vfdInfo.id = ID_NAND_DEVICE_03;
vfdInfo.blockCount = 1024;
vfdInfo.pageCountPerBlock = 64;
vfdInfo.pageSize.size1 = 2048;
vfdInfo.pageSize.size2 = 0;
vfdInfo.eraseLimitation = 100000;
vfdInfo.readTime.randomTime = 25;
vfdInfo.readTime.serialTime = 0;
vfdInfo.programTime = 200;
vfdInfo.eraseTime = 1500;

ftlInfo.id = ID_FTL_01;
ftlInfo.mapListSize = 65536;
ftlInfo.wearLevelingThreshold = 4;

RV rv = f_initialize(vfdInfo, ftlInfo);
if (rv != RV_OK) {
    printf("initialize failed!\n");
    return;
}

/* calling other Public API Interfaces of Flash-DBSim system */

f_release();
f_alloc_page
Description: Request to allocate free pages.
int f_alloc_page(
  int count,
  LBA * lbas
);
Return Value: int, the number of allocated pages.
Parameters:
count The number of free pages need to be allocated.
lbas Save LBAs of allocated pages.
Example: See also f_release_page
f_release_page
Description: Release specified page.
RV f_release_page(
  LBA lba
);
Return Value: RV
Parameters:
lba The LBA of page to be released.
Example: LBA lba[10] = {-1};
int size = f_alloc_page(10, lba);  /* request to allocate 10 pages */

......

for (int i = 0; i < 10; i++)
    f_release_page(lba);  /* release all pages allocated above */
f_read_page
Description: Read data from specified page.
RV f_read_page(
  LBA lba,
  BYTE * buffer,
  int offset,
  size_t size
);
Return Value: RV
Parameters:
lba The LBA of page to be read.
buffer Save data read from page.
offset offset
size size
Example: BYTE buffer[4096];
RV rv = f_read_page(lba, buffer, 0, 4096);
f_write_page
Description: Write data to specified page.
RV f_write_page(
  LBA lba,
  const BYTE * buffer,
  int offset,
  size_t size
);
Return Value: RV
Parameters:
lba The LBA of page to be written.
buffer buffer.
offset offset
size size
Example: BYTE buffer[4096] = {0xFF};
RV rv = f_write_page(lba, buffer, 0, 4096);
f_get_read_count 
Description: Get the read count of specified page.
int f_get_read_count(
  BLOCK_ID blockID,
  PAGE_ID pageID
);
Return Value: The read count of specified page.
Parameters:
blockID The block ID of page.
pageID The page ID of page.
Example: int count = f_get_read_count(14, 63);
f_get_write_count 
Description: Get the write count of specified page.
int f_get_write_count(
  BLOCK_ID blockID,
  PAGE_ID pageID
);
Return Value: The write count of specified page.
Parameters:
blockID The block ID of page.
pageID The page ID of page.
Example: int count = f_get_write_count(14, 63);
f_get_erase_count 
Description: Get the erase count of speicifed block.
int f_get_erase_count(
  BLOCK_ID blockID
);
Return Value: The erase count of specified block.
Parameters:
blockID The block ID of specified block.
Example: int count = f_get_erase_count(14);
f_get_read_count_total 
Description: Get the total read count of all pages.
int f_get_read_count_total();
Return Value: The total read count of all pages.
Parameters: (None)
Example: int count = f_get_read_count_total();
f_get_write_count_total 
Description: Get the total write count of all pages.
int f_get_write_count_total();
Return Value: The total write count of all pages.
Parameters: (None)
Example: int count = f_get_write_count_total();
f_get_erase_count_total 
Description: Get the total erase count of all blocks.
int f_get_erase_count_total();
Return Value: The total erase count of all blocks.
Parameters: (None)
Example: int count = f_get_erase_count_total();
f_get_read_latency_total 
Description: Get the total read latency of all pages.
int f_get_read_latency_total();
Return Value: The total read latency of all pages.
Parameters: (None)
Example: int count = f_get_read_latency_total();
f_get_write_latency_total 
Description: Get the total write latency of all pages.
int f_get_write_latency_total();
Return Value: The total write latency of all pages.
Parameters: (None)
Example: int count = f_get_write_latency_total();
f_get_erase_latency_total 
Description: Get the total erase latency of all blocks.
int f_get_erase_latency_total();
Return Value: The total erase latency of all blocks.
Parameters: (None)
Example: int count = f_get_erase_latency_total();

Internal API Interfaces

Flash-DBSim system is combined by many modules (See also "Flash-DBSim Architecture"), and each of them communicates other modules by Internal API Interfaces defined by Flash-DBSim system.

Though Flash-DBSim system contains some VFD/FTL modules already, because them have been designed for specified algorithms, so new VFD/FTL module will be developed by users for the implementation of their own algorithms. For more information about secondary development of Flash-DBSim system, see also "How to Develop New Flash-DBSim Modules" section in "How to Use". All internal API interfaces in Flash-DBSim are shown below:

VFD Module

  1. IVFD_MODULE
  2. IVFD_COUNTER 
  3. IVFD_LATENCY 
IVFD_MODULE
Description: The main interface of all VFD modules.
Functions:
GetModuleInfo Get the configuration information of VFD module (See also VFD_INFO).
GetFlashType Get the type of virtual flash device of VFD module. (See also FLASH_TYPE).
Initialize Initialize VFD module.
Release Release VFD module.
EraseBlock Erase the specified block.
ReadPage Read data from the specified page.
WritePage Write data to the specified page.
IVFD_COUNTER 
Description: The counter interface of VFD modules. All modules with read/write/erase counters must be inherited from this interface.
Functions:
GetReadCount Get the read count of the specified page.
GetWriteCount Get the write count of the specified page.
GetEraseCount Get the erase count of the specified block.
GetReadCountTotal Get the total read count of all pages.
GetWriteCountTotal Get the total write count of all pages.
GetEraseCountTotal Get the total erase count of all blocks.
ResetReadCount Reset the read counters of all pages to 0.
ResetWriteCount Reset the write counters of all pages to 0.
ResetEraseCount Reset the erase counters of all blocks to 0.
ResetCount Reset all counters of all blocks/pages to 0.
IVFD_LATENCY 
Description: The latency interface of VFD modules. All modules with features of read/write/erase latencies must be inherited from this interface.
Functions:
GetReadLatencyTotal Get the total read latency timer of all pages.
GetWriteLatencyTotal Get the total write latency timer of all pages.
GetEraseLatencyTotal Get the total erase latency timer of all blocks.
ResetReadLatencyTotal Reset the read latency timer of all pages to 0.
ResetWriteLatencyTotal Reset the write latency timer of all pages to 0.
ResetEraseLatencyTotal Reset the erase latency timer of all blocks to 0.
ResetLatencyTotal Reset all latency timers of all pages/blocks to 0.

FTL Modules

  1. IFTL_MODULE
IFTL_MODULE
Description: Tha main interfaces of all FTL Modules.
Functions:
GetModuleInfo Get the configuration information of FTL module (See also FTL_INFO)
Initialize Initialize FTL module.
Release Release FTL module.
AllocPage Request to allocate a number of free pages.
ReleasePage Release the specified page.
ReadPage Read data from specified page.
WritePage Write data to specified page.