Tiny Flash Database for MCU.
在单片机日常开发中，总会需要存储一些信息，这时就需要使用单片机FLASH存储的方案，目前单片机存储的方案有很多，比如：EASYFLASH、FLASHDB、OSAL_NV等等方案，他们程序都非常大，在存储不多的变量时不值得。而且很少有考虑到flash写入出错的情况。
在实际产品中，嵌入式产品flash写入可能会受各种因素影响（电池供电、意外断电、气温等）从而并不是很稳定，一旦出现错误，会导致产品一系列问题。
不同于其他很多的KV型数据库，TinyFlashDB每一个需要存储的变量都会分配一个单独的单片机flash扇区，变量长度不可变。
所以TinyFlashDB仅适用于存储几个关键性变量（例如：IAP跳转标志、系统断电时间等等），不适合大规模数据存储（大规模数据存储可使用EASYFLASH等）。
TinyFlashDB在设计时就考虑了写入错误的影响，追求力所能及的安全保障、资源占用方面尽可能的缩小（不到1kb代码占用）、尽可能的通用性（可以移植到51等8位机，无法逆序写入的stm32L4系列，某些flash加密的单片机和其他普通32位机上）。
consttfdb_index_ttest_index= {
.end_byte=0x00,
.flash_addr=0x4000,
.flash_size=256,
.value_length=2,
};/* c99写法，如果编译器不支持，可自行改为c89写法 */tfdb_addr_taddr=0; /*addr cache*/uint8_ttest_buf[TFDB_ALIGNED_RW_BUFFER_SIZE(2,1)]; /*aligned_value_size*/uint16_ttest_value;
voidmain()
{
TFDB_Err_Coderesult;
result=tfdb_set(&test_index, test_buf, &addr, &test_value);
if(result==TFDB_NO_ERR)
{
printf("set ok, addr:%x\n", addr);
}
addr=0; /* reset addr cache, to see tfdb_get. */result=tfdb_get(&test_index, test_buf, &addr, &test_value);
if(result==TFDB_NO_ERR)
{
printf("get ok, addr:%x, value:%x\n", addr, test_value);
}
}typedefstruct_tfdb_index_struct{
tfdb_addr_tflash_addr;/* the start address of the flash block */uint16_tflash_size;/* the size of the flash block */uint8_tvalue_length;/* the length of value that saved in this flash block */uint8_tend_byte; /* must different to TFDB_VALUE_AFTER_ERASE *//* 0x00 is recommended for end_byte, because almost all flash is 0xff after erase. */
}tfdb_index_t;结构体功能：在TinyFlashDB中，API的操作都需要指定的参数index，该index结构体中存储了flash的地址，flash的大小，存储的变量的长度，结束标志位。 在读取flash扇区时会去校验此信息。
TFDB_Err_Codetfdb_get(consttfdb_index_t*index, uint8_t*rw_buffer, tfdb_addr_t*addr_cache, void*value_to);函数功能：从index指向的扇区中获取一个index中指定变量长度的变量，flash头部数据校验出错不会重新初始化flash。
参数 index：tfdb操作的index指针。
参数 rw_buffer：写入和读取的缓存，所有flash的操作最后都会将整理后的数据拷贝到该buffer中，再调用tfdb_port_write或者tfdb_port_read进行读取写入。当芯片对于写入的数据区缓存有特殊要求（例如4字节对齐，256字节对齐等），可以通过该参数将符合要求的变量指针传递给函数使用。至少为4字节长度。
参数 addr_cache：可以是NULL，或者是地址缓存变量的指针，当addr_cache不为NULL，并且也不为0时，则认为addr_cache已经初始化成功，不再校验flash头部，直接从该addr_cache的地址读取数据。
参数 value_to：要存储数据内容的地址。
返回值：TFDB_NO_ERR成功，其他失败。
TFDB_Err_Codetfdb_set(consttfdb_index_t*index, uint8_t*rw_buffer, tfdb_addr_t*addr_cache, void*value_from);函数功能：在index指向的扇区中写入一个index中指定变量长度的变量，flash头部数据校验出错重新初始化flash。
参数 index：tfdb操作的index指针。
参数 rw_buffer：写入和读取的缓存，所有flash的操作最后都会将整理后的数据拷贝到该buffer中，再调用tfdb_port_write或者tfdb_port_read进行读取写入。当芯片对于写入的数据区缓存有特殊要求（例如4字节对齐，256字节对齐等），可以通过该参数将符合要求的变量指针传递给函数使用。至少为4字节长度。
参数 addr_cache：可以是NULL，或者是地址缓存变量的指针，当addr_cache不为NULL，并且也不为0时，则认为addr_cache已经初始化成功，不再校验flash头部，直接从该addr_cache的地址读取数据。
参数 value_from：要存储的数据内容。
返回值：TFDB_NO_ERR成功，其他失败。
tfdb dual api是基于tfdb_set和tfdb_get封装而成的。tfdb dual会调用tfdb_set和tfdb_get，并且在数据前部添加两个字节的seq，所以在tfdb dual中，最长支持的存储变量长度为253字节。
同时，tfdb dual api需要提供两个缓冲区，并且需要是增加两字节变量长度再重新计算的aligned_value_size。
typedefstruct_my_test_params_struct
{
uint32_taa[2];
uint8_tbb[16];
} my_test_params_t;
my_test_params_tmy_test_params= {
1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18
};
tfdb_dual_index_tmy_test_tfdb_dual= {
.indexes[0] = {
.end_byte=0x00,
.flash_addr=0x08077000,
.flash_size=256,
.value_length=TFDB_DUAL_VALUE_LENGTH(sizeof(my_test_params_t)),
},
.indexes[1] = {
.end_byte=0x00,
.flash_addr=0x08077100,
.flash_size=256,
.value_length=TFDB_DUAL_VALUE_LENGTH(sizeof(my_test_params_t)),
},
};
tfdb_dual_cache_tmy_test_tfdb_dual_cache= {0};
voidmy_test_tfdb_dual_func()
{
uint32_trw_buffer[TFDB_DUAL_ALIGNED_RW_BUFFER_SIZE(TFDB_DUAL_VALUE_LENGTH(sizeof(my_test_params_t)), 4)];
uint32_trw_buffer_bak[TFDB_DUAL_ALIGNED_RW_BUFFER_SIZE(TFDB_DUAL_VALUE_LENGTH(sizeof(my_test_params_t)), 4)];
TFDB_Err_Codeerr;
for(uint8_ti=0; i<36; i++)
{
err=tfdb_dual_get(&my_test_tfdb_dual, (uint8_t*)rw_buffer, (uint8_t*)rw_buffer_bak, &my_test_tfdb_dual_cache, &my_test_params);
if(err==TFDB_NO_ERR)
{
printf("read ok\ncache seq1:0x%04x, seq2:0x%04x\naddr1:0x%08x, addr2:0x%08x\n", my_test_tfdb_dual_cache.seq[0], my_test_tfdb_dual_cache.seq[1], my_test_tfdb_dual_cache.addr_cache[0], my_test_tfdb_dual_cache.addr_cache[1]);
}
else
{
printf("read err:%d\n", err);
}
my_test_params.aa[0]++;
my_test_params.aa[1]++;
for(uint8_ti=0; i<16; i++)
{
my_test_params.bb[i]++;
}
memset(&my_test_tfdb_dual_cache, 0, sizeof(my_test_tfdb_dual_cache)); /* 测试无地址缓存写入 */err=tfdb_dual_set(&my_test_tfdb_dual, (uint8_t*)rw_buffer, (uint8_t*)rw_buffer_bak, &my_test_tfdb_dual_cache, &my_test_params);
if(err==TFDB_NO_ERR)
{
printf("write ok\ncache seq1:0x%04x, seq2:0x%04x\naddr1:0x%08x, addr2:0x%08x\n", my_test_tfdb_dual_cache.seq[0], my_test_tfdb_dual_cache.seq[1], my_test_tfdb_dual_cache.addr_cache[0], my_test_tfdb_dual_cache.addr_cache[1]);
}
else
{
printf("write err:%d\n", err);
}
memset(&my_test_tfdb_dual_cache, 0, sizeof(my_test_tfdb_dual_cache)); /* 测试无地址缓存读取 */
}
}typedefstruct_tfdb_dual_index_struct
{
tfdb_index_tindexes[2];
} tfdb_dual_index_t;
typedefstruct_tfdb_dual_cache_struct
{
tfdb_addr_taddr_cache[2];
uint16_tseq[2];
} tfdb_dual_cache_t;结构体功能：在TinyFlashDB dual中，API的操作都需要指定的参数index，该index结构体中存储了两个tfdb_index_t。
TFDB_Err_Codetfdb_dual_get(consttfdb_dual_index_t*index, uint8_t*rw_buffer, uint8_t*rw_buffer_bak, tfdb_dual_cache_t*cache, void*value_to);函数功能：从index指向的扇区中获取一个index中指定变量长度的变量，flash头部数据校验出错不会重新初始化flash。
参数 index：tfdb操作的index指针。
参数 rw_buffer：写入和读取的缓存，所有flash的操作最后都会将整理后的数据拷贝到该buffer中，再调用tfdb_port_write或者tfdb_port_read进行读取写入。当芯片对于写入的数据区缓存有特殊要求（例如4字节对齐，256字节对齐等），可以通过该参数将符合要求的变量指针传递给函数使用。至少为4字节长度。
参数 rw_buffer_bak：写入和读取的缓存，所有flash的操作最后都会将整理后的数据拷贝到该buffer中，再调用tfdb_port_write或者tfdb_port_read进行读取写入。当芯片对于写入的数据区缓存有特殊要求（例如4字节对齐，256字节对齐等），可以通过该参数将符合要求的变量指针传递给函数使用。至少为4字节长度。
参数 cache：不可以是NULL，必须是tfdb_dual_cache_t定义的缓存的指针，当cache中数据合法时，则认为cache已经初始化成功，直接从该cache的flash块和地址读取数据。
参数 value_to：要存储数据内容的地址。
返回值：TFDB_NO_ERR成功，其他失败。
TFDB_Err_Codetfdb_dual_set(consttfdb_dual_index_t*index, uint8_t*rw_buffer, uint8_t*rw_buffer_bak, tfdb_dual_cache_t*cache, void*value_from);函数功能：在index指向的扇区中写入一个index中指定变量长度的变量，flash头部数据校验出错重新初始化flash。
参数 index：tfdb操作的index指针。
参数 rw_buffer：写入和读取的缓存，所有flash的操作最后都会将整理后的数据拷贝到该buffer中，再调用tfdb_port_write或者tfdb_port_read进行读取写入。当芯片对于写入的数据区缓存有特殊要求（例如4字节对齐，256字节对齐等），可以通过该参数将符合要求的变量指针传递给函数使用。至少为4字节长度。
参数 rw_buffer_bak：写入和读取的缓存，所有flash的操作最后都会将整理后的数据拷贝到该buffer中，再调用tfdb_port_write或者tfdb_port_read进行读取写入。当芯片对于写入的数据区缓存有特殊要求（例如4字节对齐，256字节对齐等），可以通过该参数将符合要求的变量指针传递给函数使用。至少为4字节长度。
参数 cache：不可以是NULL，必须是tfdb_dual_cache_t定义的缓存的指针，当cache中数据合法时，则认为cache已经初始化成功，直接从该cache的flash块和地址读取数据。
参数 value_from：要存储的数据内容。
返回值：TFDB_NO_ERR成功，其他失败。
观察上方代码，可以发现TinyFlashDB的操作都需要tfdb_index_t定义的index参数。
Flash初始化后头部信息为4字节，所以只支持1、2、4、8字节操作的flash：
头部初始化时会读取头部，所以函数中rw_buffer指向的数据第一要求至少为4字节，如果最小写入单位是8字节，则为第一要求最少为8字节。
| 第一字节 | 第二字节 | 第三字节 | 第四字节和其他对齐字节 |
|---|---|---|---|
| flash_size高8位字节 | flash_size低8位字节 | value_length | end_byte |
数据存储时，会根据flash支持的字节操作进行对齐，所以函数中rw_buffer指向的数据第二要求至少为下面函数中计算得出的aligned_value_size个字节：
aligned_value_size=index->value_length+2;/* data + verify + end_byte */#if (TFDB_WRITE_UNIT_BYTES==2)
/* aligned with TFDB_WRITE_UNIT_BYTES */aligned_value_size= ((aligned_value_size+1) &0xfe);
#elif (TFDB_WRITE_UNIT_BYTES==4)
/* aligned with TFDB_WRITE_UNIT_BYTES */aligned_value_size= ((aligned_value_size+3) &0xfc);
#elif (TFDB_WRITE_UNIT_BYTES==8)
/* aligned with TFDB_WRITE_UNIT_BYTES */aligned_value_size= ((aligned_value_size+7) &0xf8);
#endif| 前value_length个字节 | 第value_length+1字节 | 第value_length+2字节 | 其他对齐字节 |
|---|---|---|---|
| value_from数据内容 | value_from的和校验 | end_byte | end_byte |
每次写入后都会再读取出来进行校验，如果校验不通过，就会继续在下一个地址继续尝试写入。直到达到最大写入次数（TFDB_WRITE_MAX_RETRY）或者头部校验错误。
读取数据时也会计算和校验，不通过的话继续读取，直到返回校验通过的最新数据，或者读取失败。
数据前部两字节seq只有3种合法值，0x00ff->0x0ff0->0xff00。
如此循环往复，通过读取两个block中最新变量的seq来判断哪个flash扇区中存储的是最新值。
当最新值存储在第一扇区时，下次写入则会在第二扇区写入，反之亦然。
TFDB_Err_Codetfdb_port_read(tfdb_addr_taddr, uint8_t*buf, size_tsize);
TFDB_Err_Codetfdb_port_erase(tfdb_addr_taddr, size_tsize);
TFDB_Err_Codetfdb_port_write(tfdb_addr_taddr, constuint8_t*buf, size_tsize);/* use string.h or self functions */#defineTFDB_USE_STRING_H 1
#ifTFDB_USE_STRING_H#include"string.h"#definetfdb_memcpy memcpy
#definetfdb_memcmp memcmp
#defineTFDB_MEMCMP_SAME 0
#else#definetfdb_memcpy#definetfdb_memcmp#defineTFDB_MEMCMP_SAME#endif#defineTFDB_DEBUG printf
/* The data value in flash after erased, most are 0xff, some flash maybe different. * if it's over 1 byte, please be care of little endian or big endian. */#defineTFDB_VALUE_AFTER_ERASE 0xff
/* The size of TFDB_VALUE_AFTER_ERASE, only support 1 / 2 / 4. * This value must not bigger than TFDB_WRITE_UNIT_BYTES. */#defineTFDB_VALUE_AFTER_ERASE_SIZE 1
/* the flash write granularity, unit: byte * only support 1(stm32f4)/ 2(CH559)/ 4(stm32f1)/ 8(stm32L4) */#defineTFDB_WRITE_UNIT_BYTES 8 /* @note you must define it for a value *//* @note the max retry times when flash is error ,set 0 will disable retry count */#defineTFDB_WRITE_MAX_RETRY 32
/* must not use pointer type. Please use uint32_t, uint16_t or uint8_t. */typedefuint32_ttfdb_addr_t;在去除DEBUG打印信息后，资源占用如下：
keil -o2编译优化选项
Code (inc. data) RODataRWDataZIDataDebugObjectName15400002621tfdb_port.o68200004595tinyflashdb.ogcc -os编译优化选项
.text.tfdb_port_read0x00000000000039b40x1a ./Drivers/TFDB/tfdb_port.o0x00000000000039b4tfdb_port_read
.text.tfdb_port_erase0x00000000000039ce0x46 ./Drivers/TFDB/tfdb_port.o0x00000000000039cetfdb_port_erase
.text.tfdb_port_write0x0000000000003a140x5c ./Drivers/TFDB/tfdb_port.o0x0000000000003a14tfdb_port_write
.text.tfdb_check0x0000000000003a700x56 ./Drivers/TFDB/tinyflashdb.o0x0000000000003a70tfdb_check
.text.tfdb_init0x0000000000003ac60x56 ./Drivers/TFDB/tinyflashdb.o0x0000000000003ac6tfdb_init
.text.tfdb_set0x0000000000003b1c0x186 ./Drivers/TFDB/tinyflashdb.o0x0000000000003b1ctfdb_set
.text.tfdb_get0x0000000000003ca20x11c ./Drivers/TFDB/tinyflashdb.o0x0000000000003ca2tfdb_get裸机移植例程，RT-Thread可以参考使用：
STM32F429IGT6
CH583
QQ交流群：562090553