摘要:在單片機日常開發中，總會需要存儲一些信息，這時就需要使用單片機FLASH存儲的方案，目前單片機存儲的方案有很多如：EASYFLASH、FLASHDB、OSAL_NV等等方案，他們程序都非常大，在存儲不多的變量時不值得。而且現有方案的代碼中很少有考慮到flash寫入出錯的情況。

在實際產品中，嵌入式產品flash寫入可能會受各種因素影響(電池供電、意外斷電、氣溫等)從而并不是很穩定，一旦出現錯誤，會導致產品一系列問題。

一、TinyFlashDB設計理念

不同于其他很多的KV型數據庫，TinyFlashDB每一個需要存儲的變量都會分配一個單獨的單片機flash扇區，變量長度不可變。

TinyFlashDB在設計時就考慮了寫入錯誤的影響，追求力所能及的安全保障、資源占用方面盡可能的縮小（不到1kb代碼占用）、盡可能的通用性（可以移植到51等8位機，無法逆序寫入的stm32L4系列，某些flash加密的單片機和其他普通32位機上）。

二、TinyFlashDB使用示例

?

const?tfdb_index_t?test_index?=?{
????.end_byte?=?0x00,
????.flash_addr?=?0x4000,
????.flash_size?=?256,
????.value_length?=?2,

};
tfdb_addr_t?addr?=?0;?/*addr?cache*/

uint8_t?test_buf[4];?/*aligned_value_size*/

uint16_t?test_value;

void?main()
{
????TFDB_Err_Code?result;
????result?=?tfdb_set(&test_index,?test_buf,?&addr,?&test_value);
????if(result?==?TFDB_NO_ERR)
????{
????????printf("set?ok,?addr:%x
",?addr);
????}

????result?=?tfdb_get(&test_index,?test_buf,?&addr,?&test_value);
????if(result?==?TFDB_NO_ERR)
????{
????????printf("get?ok,?addr:%x,?value:%x
",?addr,?test_value);
????}
}

?

三、TinyFlashDB API介紹

?

typedef?struct?_tfdb_index_struct{
????tfdb_addr_t?????flash_addr;/*?the?start?address?of?the?flash?block?*/
????uint16_t????????flash_size;/*?the?size?of?the?flash?block?*/
????uint8_t?????????value_length;/*?the?length?of?value?that?saved?in?this?flash?block?*/
????uint8_t?????????end_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_Code?tfdb_get(const?tfdb_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_Code?tfdb_set(const?tfdb_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成功，其他失敗。

四、TinyFlashDB設計原理

觀察上方代碼，可以發現TinyFlashDB的操作都需要tfdb_index_t定義的index參數。

Flash初始化后頭部信息為4字節，所以只支持1、2、4、8字節操作的flash：頭部初始化時會讀取頭部，所以函數中rw_buffer指向的數據第一要求至少為4字節，如果最小寫入單位是8字節，則為第一要求最少為8字節。

數據存儲時，會根據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

?

每次寫入后都會再讀取出來進行校驗，如果校驗不通過，就會繼續在下一個地址寫入。指導達到最大寫入次數（TFDB_WRITE_MAX_RETRY）或者頭部校驗錯誤。

讀取數據時也會計算和校驗，不通過的話繼續讀取，直到返回校驗通過的最新數據，或者讀取失敗。

五、TinyFlashDB移植和配置

移植使用只需要在tfdb_port.c中，編寫完成三個接口函數，也要在tfdb_port.h中添加相應的頭文件和根據不同芯片修改宏定義

?

TFDB_Err_Code?tfdb_port_read(tfdb_addr_t?addr,?uint8_t?*buf,?size_t?size);

TFDB_Err_Code?tfdb_port_erase(tfdb_addr_t?addr,?size_t?size);

TFDB_Err_Code?tfdb_port_write(tfdb_addr_t?addr,?const?uint8_t?*buf,?size_t?size);

?

所有的配置項都在tfdb_port.h中

?

/*?use?string.h?or?self?functions?*/
#define?TFDB_USE_STRING_H???????????????1

#if?TFDB_USE_STRING_H
????#include?"string.h"
????#define?tfdb_memcpy?memcpy
????#define?tfdb_memcmp?memcmp
????#define?TFDB_MEMCMP_SAME?0
#else
????#define?tfdb_memcpy
????#define?tfdb_memcmp
????#define?TFDB_MEMCMP_SAME
#endif

#define?TFDB_DEBUG??????????????????????????printf

/*?The?data?value?in?flash?after?erased,?most?are?0xff,?some?flash?maybe?different.?*/
#define?TFDB_VALUE_AFTER_ERASE??????????????0xff

/*?the?flash?write?granularity,?unit:?byte
?*?only?support?1(stm32f4)/?2(CH559)/?4(stm32f1)/?8(stm32L4)?*/
#define?TFDB_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?*/
#define?TFDB_WRITE_MAX_RETRY????????????????32

/*?must?not?use?pointer?type.?Please?use?uint32_t,?uint16_t?or?uint8_t.?*/
typedef?uint32_t????tfdb_addr_t;

?

六、移植到STM32單片機

項目地址：https://github.com/smartmx/TFDB/tree/main

使用一下命令克隆Demo，裸機移植例程

?

git?clone?-b?raw?https://github.com/smartmx/TFDB.git

?

?