# TFDB

**Repository Path**: RT-Thread-Mirror/TFDB

## Basic Information

- **Project Name**: TFDB
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 8
- **Forks**: 4
- **Created**: 2022-04-02
- **Last Updated**: 2026-10-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# TFDB

 Tiny Flash Database for MCU.

## TinyFlashDB设计前言

在单片机日常开发中，总会需要存储一些信息，这时就需要使用单片机FLASH存储的方案，目前单片机存储的方案有很多，比如：EASYFLASH、FLASHDB、OSAL_NV等等方案，他们程序都非常大，在存储不多的变量时不值得。而且很少有考虑到flash写入出错的情况。  
在实际产品中，嵌入式产品flash写入可能会受各种因素影响（电池供电、意外断电、气温等）从而并不是很稳定，一旦出现错误，会导致产品一系列问题。  

## TinyFlashDB设计理念

不同于其他很多的KV型数据库，TinyFlashDB每一个需要存储的变量都会分配一个单独的单片机flash扇区，变量长度不可变。  
所以TinyFlashDB仅适用于存储几个关键性变量（例如：IAP跳转标志、系统断电时间等等），不适合大规模数据存储（大规模数据存储可使用EASYFLASH等）。  
TinyFlashDB在设计时就考虑了写入错误的影响，追求力所能及的安全保障、资源占用方面尽可能的缩小（单块模式代码占用不到1kb）、尽可能的通用性（可以移植到51等8位机，无法逆序写入的stm32L4系列，某些flash加密的单片机和其他普通32位机上）。  

## TinyFlashDB使用示例

```c
const tfdb_index_t test_index = {
    .end_byte = 0x00,
    .flash_addr = 0x4000,
    .flash_size = 256,
    .value_length = 2,
};/* c99写法，如果编译器不支持，可自行改为c89写法 */
tfdb_addr_t addr = 0; /*addr cache*/

uint8_t test_buf[TFDB_ALIGNED_RW_BUFFER_SIZE(2,1)]; /*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\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);
    }
}
```

## TinyFlashDB API介绍

```c
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扇区时会去校验此信息。  

```c
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`成功，其他失败。

```c
TFDB_Err_Code tfdb_get_pre(const tfdb_index_t *index, uint8_t *rw_buffer, tfdb_addr_t *addr_cache, tfdb_addr_t *pre_addr_cache, void* value_to);
```

函数功能：从`index`指向的扇区中获取比当前最新数据更早的一条有效数据（即上一次保存的数据），flash头部数据校验出错不会重新初始化flash。

当前数据所在地址的前一个位置的数据校验失败时，会继续向前回退查找，直到找到一条有效数据，或者没有更早的数据（返回`TFDB_NO_PRE_DATA`）。

参数 `index`、`rw_buffer`、`value_to`：与`tfdb_get`相同。

参数 `addr_cache`：与`tfdb_get`相同。为`NULL`或0时会先自动获取最新数据的地址（此时`value_to`会先保存最新数据，找到上一次保存的数据后会被覆盖）。

参数 `pre_addr_cache`：可以是`NULL`，或者是地址缓存变量的指针。函数成功后，上一次保存的数据的地址会保存到该变量，可用于之后直接读取该条数据。

返回值：`TFDB_NO_ERR`成功，`TFDB_NO_PRE_DATA`没有更早的数据，其他失败。

```c
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 dual使用示例

tfdb dual api是基于`tfdb_set`和`tfdb_get`封装而成的。`tfdb dual`会调用`tfdb_set`和`tfdb_get`，并且在数据前部添加两个字节的seq，所以tfdb dual最长支持253字节的用户数据。`value_length`配置过大或flash块容量不足以存放对齐后的记录时，API调用会返回`TFDB_CFG_ERR`，各粒度与块容量对应的上限见设计原理章节。  
同时，tfdb dual api需要提供两个缓冲区，并且需要是增加两字节变量长度再重新计算的`aligned_value_size`。

```c
typedef struct _my_test_params_struct
{
    uint32_t    aa[2];
    uint8_t     bb[16];
} my_test_params_t;

my_test_params_t my_test_params = {
        1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18
};

tfdb_dual_index_t my_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_t my_test_tfdb_dual_cache = {0};

void my_test_tfdb_dual_func()
{
    uint32_t rw_buffer[TFDB_DUAL_ALIGNED_RW_BUFFER_SIZE(TFDB_DUAL_VALUE_LENGTH(sizeof(my_test_params_t)), 4)];
    uint32_t rw_buffer_bak[TFDB_DUAL_ALIGNED_RW_BUFFER_SIZE(TFDB_DUAL_VALUE_LENGTH(sizeof(my_test_params_t)), 4)];
    TFDB_Err_Code err;
    for(uint8_t i = 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_t i = 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));   /* 测试无地址缓存读取 */
    }
}

```

## TinyFlashDB dual API介绍

```c
typedef struct _tfdb_dual_index_struct
{
    tfdb_index_t indexes[2];
} tfdb_dual_index_t;

typedef struct _tfdb_dual_cache_struct
{
    tfdb_addr_t     addr_cache[2];
    uint16_t        seq[2];
} tfdb_dual_cache_t;
```

结构体功能：在TinyFlashDB dual中，API的操作都需要指定的参数`index`，该`index`结构体中存储了两个`tfdb_index_t`。

```c
TFDB_Err_Code tfdb_dual_get(const tfdb_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`成功，其他失败。  

```c
TFDB_Err_Code tfdb_dual_set(const tfdb_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`成功，其他失败。

```c
TFDB_Err_Code tfdb_dual_get_pre(const tfdb_dual_index_t *index, uint8_t *rw_buffer, uint8_t *rw_buffer_bak, tfdb_dual_cache_t *cache, tfdb_dual_cache_t *pre_cache, void *value_to);
```

函数功能：获取比当前最新数据更早的一条有效数据（即上一次保存的数据），作用与单块模式下的`tfdb_get_pre`相同。

dual模式下两次写入分别位于两个flash块中，所以上一次保存的数据通常在另一个flash块中，为该块中最新的记录。当该记录损坏时（例如写入时意外断电），会自动回退到当前数据所在flash块中的上一条有效记录，返回可以读取到的最新的较早数据。

参数 `index`：tfdb操作的index指针。

参数 `rw_buffer`、`rw_buffer_bak`：与`tfdb_dual_get`相同的写入和读取缓存。

参数 `cache`：不可以是`NULL`，必须是`tfdb_dual_cache_t`定义的缓存的指针。当`cache`未初始化时，会像`tfdb_dual_get`一样先读取两个flash块初始化`cache`，此时`value_to`会先保存最新数据，找到上一次保存的数据后会被覆盖。

参数 `pre_cache`：可以是`NULL`，或者是`tfdb_dual_cache_t`定义的缓存的指针。函数成功后，上一次保存的数据的地址和seq会被保存到对应flash块的表项中，其余表项清零，可用于之后直接读取该条数据。

参数 `value_to`：要保存数据内容的地址。

返回值：`TFDB_NO_ERR`成功，`TFDB_NO_PRE_DATA`没有更早的数据，其他失败。

## TinyFlashDB设计原理

观察上方代码，可以发现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`个字节：

```c
/* in tinyflashdb.c */
static uint16_t tfdb_aligned_size(const tfdb_index_t *index)
{
    uint16_t aligned_value_size;

    aligned_value_size = (uint16_t)(index->value_length + 2);/* data + verify + end_byte */

#if (TFDB_WRITE_UNIT_BYTES==2)
    /* aligned with TFDB_WRITE_UNIT_BYTES */
    aligned_value_size = (uint16_t)((aligned_value_size + 1) & ~(TFDB_WRITE_UNIT_BYTES - 1));
#elif (TFDB_WRITE_UNIT_BYTES==4)
    /* aligned with TFDB_WRITE_UNIT_BYTES */
    aligned_value_size = (uint16_t)((aligned_value_size + 3) & ~(TFDB_WRITE_UNIT_BYTES - 1));
#elif (TFDB_WRITE_UNIT_BYTES==8)
    /* aligned with TFDB_WRITE_UNIT_BYTES */
    aligned_value_size = (uint16_t)((aligned_value_size + 7) & ~(TFDB_WRITE_UNIT_BYTES - 1));
#endif

#if (TFDB_WRITE_UNIT_BYTES==8)
    if (aligned_value_size > index->flash_size - 8)
#else
    if (aligned_value_size > index->flash_size - 4)
#endif
    {
        /* the value can not be stored in this flash block. */
        return 0;
    }
    return aligned_value_size;
}
```

`aligned_value_size`按写入粒度对齐，按16位计算最大可达264，不会再溢出；`value_length`最大为255（受其自身的8位长度限制），dual模式最长支持253字节用户数据。同时flash块必须至少能容纳一条记录（头部4字节，8字节粒度为8字节，加`aligned_value_size`不能超过`flash_size`），否则`tfdb_set`、`tfdb_get`、`tfdb_get_pre`及对应的dual API都会返回`TFDB_CFG_ERR`。以常见的256字节块为例，容量上限为：  

|TFDB_WRITE_UNIT_BYTES|1|2|4|8|
-|-|-|-
|单块value_length上限|250|250|250|246|
|dual最长用户数据（字节）|248|248|248|244|  

|前value_length个字节|第value_length+1字节|第value_length+2字节|其他对齐字节|
-|-|-|-
|value_from数据内容|value_from的和校验|end_byte|end_byte|  

每次写入后都会再读取出来进行校验，如果校验不通过，就会继续在下一个地址继续尝试写入。直到达到最大写入次数（TFDB_WRITE_MAX_RETRY）或者头部校验错误。  

读取数据时也会计算和校验，不通过的话继续读取，直到返回校验通过的最新数据，或者读取失败。  

## TinyFlashDB dual设计原理

数据前部两字节seq的合法值由`TFDB_DUAL_SEQ_COUNT`决定：默认为3种（0x00ff->0x0ff0->0xff00），可配置为5种（0xff00->0xf0f0->0x0ff0->0x0f0f->0x00ff）。  
如此循环往复，通过读取两个block中最新变量的seq来判断哪个flash扇区中存储的是最新值。  
当最新值存储在第一扇区时，下次写入则会在第二扇区写入，反之亦然。  
5值循环将`tfdb_dual_get_pre`的判别窗口从3次写入扩大到5次写入，两块中需要更多条连续损坏记录才会出现判别歧义；两套值集互不兼容，且切换无法被程序检测——部分旧值在另一套循环中仍是合法值，不重新初始化直接切换会使库静默误判最新数据所在的扇区（返回旧数据），所以切换配置前必须擦除并重新初始化两个flash块。  
`tfdb_dual_get_pre`通过seq在循环中的前后关系，比较两个候选记录（另一扇区中最新的记录，和当前扇区中的上一条有效记录）哪个是上一次保存的数据，即使其中一条候选记录损坏，也能返回可以读取到的最新的较早数据。  

## TinyFlashDB移植和配置

### 移植使用只需要在tfdb_port.c中，编写完成三个接口函数，也要在tfdb_port.h中添加相应的头文件和根据不同芯片修改宏定义

```c
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中

```c
/* 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.
 * if it's over 1 byte, please be care of little endian or big endian. */
#define TFDB_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. */
#define TFDB_VALUE_AFTER_ERASE_SIZE         1

/* 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

/* the dual seq cycle value count, only support 3 or 5, must be an odd number.
 * 3: 0x00ff -> 0x0ff0 -> 0xff00
 * 5: 0xff00 -> 0xf0f0 -> 0x0ff0 -> 0x0f0f -> 0x00ff
 * @note the two value sets are not compatible with each other,
 * switching needs the dual flash blocks re-initialized. */
#define TFDB_DUAL_SEQ_COUNT                 3

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

## TFDB资源占用

在去除DEBUG和LOG打印信息后（两者定义为空），TFDB_WRITE_UNIT_BYTES=4、TFDB_DUAL_SEQ_COUNT=3配置下的tinyflashdb.c代码占用如下（芯片相关的tfdb_port接口实现不计算在内，由用户平台决定）：

### Cortex M4平台

arm-none-eabi-gcc 9.3.1，-O2 -mcpu=cortex-m4 -mthumb

```c
tfdb_check           0x3a
tfdb_init            0x42
tfdb_get             0x13a
tfdb_get_pre         0x86
tfdb_set             0x19a
tfdb_dual_get        0xc6
tfdb_dual_get_pre    0x2a4
tfdb_dual_set        0x10a
.text 合计           0x8a0（2208字节，单块模式约0x350）
```

### RISC-V平台

riscv32-wch-elf-gcc 15.2.0，-Os -march=rv32imac -mabi=ilp32

```c
tfdb_check           0x5c
tfdb_init            0x68
tfdb_get             0x140
tfdb_get_pre         0x88
tfdb_set             0x1b8
tfdb_dual_seq_valid  0x40
tfdb_dual_judge      0x66
tfdb_dual_get        0x11c
tfdb_dual_get_pre    0x2d0
tfdb_dual_set        0x138
.text 合计           0xa0e（2574字节，单块模式约0x3bc）
```

## Demo

裸机移植例程，RT-Thread可以参考使用：  
[STM32F429IGT6](https://github.com/smartmx/TFDB/tree/raw/Templates/STM32F429IGT6_TFDB)  
[CH583](https://github.com/smartmx/TFDB/tree/raw/Templates/CH583_TFDB)  

## [博客主页](https://blog.maxiang.vip/)

QQ交流群：562090553