第5期 | EasyFlash，让 Flash 成为小型 KV 数据库

嵌入式开源项目精选专栏

本专栏由Mculover666创建，主要内容为寻找嵌入式领域内的优质开源项目，一是帮助开发者使用开源项目实现更多的功能，二是通过这些开源项目，学习大佬的代码及背后的实现思想，提升自己的代码水平，和其它专栏相比，本专栏的优势在于：

不会单纯的介绍分享项目，还会包含作者亲自实践的过程分享，甚至还会有对它背后的设计思想解读。

目前本专栏包含的开源项目有：

如果您自己编写或者发现的开源项目不错，欢迎留言或者私信投稿到本专栏，分享获得双倍的快乐！

1. EasyFlash

本期给大家带来的开源项目是 EasyFlash，可以让 Flash 成为小型 KV 数据库（Key-Value），作者armink，目前收获 975 个 star，遵循 MIT 开源许可协议。

EasyFlash是一款开源的轻量级嵌入式Flash存储器库，非常适合智能家居、可穿戴、工控、医疗、物联网等需要断电存储功能的产品，资源占用极低，并且支持各种 MCU 片上存储器。

目前 EasyFlash 支持以下功能：

• ENV：快速保存产品参数，支持 写平衡（磨损平衡） 及掉电保护功能；
• IAP：在线升级；
• LOG：无需文件系统，日志可直接存储在Flash上；

项目地址：https://github.com/armink/EasyFlash

2. 移植EasyFlash

2.1. 移植思路

在移植过程中主要参考两个资料：项目的readme文档和demo工程。

对于这些开源项目，其实移植起来也就两步：

• ① 添加源码到裸机工程中；
• ② 实现需要的接口即可（擦、写、读、打印）；

2.2. 准备裸机工程

本文中我使用的是小熊派IoT开发套件，主控芯片为STM32L431RCT6：板载Flash型号为W25Q64JV，大小64Mbit，与STM32的QSPI接口相连：

移植之前需要准备一份裸机工程，我使用STM32CubeMX生成，需要初始化以下配置：

• 配置一个串口用于打印信息
• printf重定向
• 配置SPI Flash通信接口（SPI或QSPI）
• 移植SFUD开源库（方便操作Flash）

SFUD移植过程请参考上一期文章：

2.3. 添加EasyFlash到工程中

② 在keil中添加 SFUD 组件的源码文件：

• src\easyflash.c：（必选）包含EasyFlash初始化方法；
• src\ef_utils.c：（必选）EasyFlash常用小工具；
• port\ef_port.c：（必选）EasyFlash移植接口；
• src\ef_env.c：Env（常规模式）相关操作接口及实现源码；

其它两个IAP和LOG相关的源码暂且不用添加。

③ 将easyflash/inc头文件路径添加到keil中：

2.4. 实现EasyFlash移植接口

EasyFlash的移植接口都已经写好了，在ef_port.c文件中，只需要在函数体中添加代码即可。

① 默认环境变量集合

产品上需要的默认环境变量集中定义在这里，当 flash 第一次初始化时会将默认的环境变量写入，采用 void * 类型，所以支持任意类型：

/* default environment variables set for user */
static const ef_env default_env_set[] = {
 {"wifi_ssid","FAST_88A6", 0}, //字符串大小设置为0，会自动检测
 {"wifi_passwd","12345678", 0},
};

② EasyFlash初始化接口

在该接口中会传递默认环境变量，初始化EasyFlash移植所需的资源（比如SFUD库的初始化）：

EfErrCode ef_port_init(ef_env const **default_env, size_t *default_env_size) {
    EfErrCode result = EF_NO_ERR;

    *default_env = default_env_set;
    *default_env_size = sizeof(default_env_set) / sizeof(default_env_set[0]);
 
 //SFUD库初始化
 sfud_init();

    return result;
}

③ 读取Flash接口

使用SFUD开源库提供的API实现该接口：

EfErrCode ef_port_read(uint32_t addr, uint32_t *buf, size_t size) {
    EfErrCode result = EF_NO_ERR;

 //获取SFUD Flash设备对象
    const sfud_flash *flash = sfud_get_device_table() + SFUD_W25Q64_DEVICE_INDEX;

 //使用SFUD开源库提供的API实现Flash读取
    sfud_read(flash, addr, size, (uint8_t *)buf);

    return result;
}

④ 擦除Flash接口

使用SFUD开源库提供的API实现该接口：

EfErrCode ef_port_erase(uint32_t addr, size_t size) {
    EfErrCode result = EF_NO_ERR;
    sfud_err sfud_result = SFUD_SUCCESS;
 
 //获取SFUD Flash设备对象
    const sfud_flash *flash = sfud_get_device_table() + SFUD_W25Q64_DEVICE_INDEX;
    
    /* make sure the start address is a multiple of FLASH_ERASE_MIN_SIZE */
    EF_ASSERT(addr % EF_ERASE_MIN_SIZE == 0);
    
 //使用SFUD提供的API实现Flash擦除
    sfud_result = sfud_erase(flash, addr, size);

    if(sfud_result != SFUD_SUCCESS) {
        result = EF_ERASE_ERR;
    }

    return result;
}

⑤ 写入Flash接口

使用SFUD开源库提供的API实现该接口：

EfErrCode ef_port_write(uint32_t addr, const uint32_t *buf, size_t size) {
    EfErrCode result = EF_NO_ERR;
    sfud_err sfud_result = SFUD_SUCCESS;
 
 //获取SFUD Flash设备对象
    const sfud_flash *flash = sfud_get_device_table() + SFUD_W25Q64_DEVICE_INDEX;

 //使用SFUD开源库提供的API实现
    sfud_result = sfud_write(flash, addr, size, (const uint8_t *)buf);

    if(sfud_result != SFUD_SUCCESS) {
        result = EF_WRITE_ERR;
    }

    return result;
}

⑥ 对环境变量缓冲区加锁/解锁

裸机时可以使用关闭/打开全局中断来上锁/解锁：

/**
 * lock the ENV ram cache
 */
void ef_port_env_lock(void) {
    
 //关闭全局中断
   __disable_irq();
}

/**
 * unlock the ENV ram cache
 */
void ef_port_env_unlock(void) {
    
 //打开全局中断
 __enable_irq();
    
}

⑦ EasyFlash打印数据和日志接口

在该文件最顶部开辟一块打印数据缓冲区：

//easyflash打印数据缓冲区
static char log_buf[128];

然后实现输出无固定格式的打印信息接口：

void ef_print(const char *format, ...) {
    va_list args;

    /* args point to the first variable parameter */
    va_start(args, format);

    /* 实现数据输出 */
 vsprintf(log_buf, format, args);
    printf("%s", log_buf);
    
    va_end(args);
}

然后使用该函数去实现调试信息日志打印接口：

void ef_log_debug(const char *file, const long line, const char *format, ...) {

#ifdef PRINT_DEBUG

    va_list args;

    /* args point to the first variable parameter */
    va_start(args, format);

    /* You can add your code under here. */
   ef_print("[Flash](%s:%ld) ", file, line);
    /* must use vprintf to print */
    vsprintf(log_buf, format, args);
    ef_print("%s", log_buf);
    printf("\r");
    
    va_end(args);

#endif

}

最后实现普通日志信息打印接口：

void ef_log_info(const char *format, ...) {
    va_list args;

    /* args point to the first variable parameter */
    va_start(args, format);

    /* You can add your code under here. */
 ef_print("[Flash]");
    /* must use vprintf to print */
    vsprintf(log_buf, format, args);
    ef_print("%s", log_buf);
    printf("\r");
    
    va_end(args);
}

2.5. 配置EasyFlash

EasyFlash的核心功能配置文件在ef_cfg.h，修改说明如下。

① 环境变量功能相关

② Flash擦除粒度和写入粒度③ 备份区相关④ 调试日志是否开启至此，EasyFlash移植、配置完成，接下来就可以愉快的使用了！

3. 使用EasyFlash

使用时包含头文件：

#include <easyflash.h>

3.1. 初始化EasyFlash

EfErrCode easyflash_init(void);

该 API 会初始化的EasyFlash的各个组件，初始化后才可以使用别的API，第一次初始化的时候，会自动调用 ef_env_set_default 将定义的默认环境变量保存到Flash。

在main函数中初始化EasyFlash：

/* USER CODE BEGIN 2 */
//初始化EasyFlash
ret = easyflash_init();
if(ret != EF_NO_ERR)
{
 printf("EasyFlash init fail, EfErrCode = %d.r\n", ret);
}

/* USER CODE END 2 */

3.2. 环境变量操作API

在 V4.0 以后，环境变量在 EasyFlash 底层都是按照二进制数据格式进行存储，即 blob 格式 ，这样上层支持传入任意类型。

① 获取 blob 类型环境变量

size_t ef_get_env_blob(const char *key, void *value_buf, size_t buf_len, size_t *save_value_len);

其中参数的意义如下：

• key：环境变量名称
• value_buf：存放环境变量的缓冲区
• buf_len：该缓冲区的大小
• save_value_len：返回该环境变量实际存储在 flash 中的大小
• 返回值：成功存放至缓冲区中的数据长度

② 设置 blob 类型环境变量

使用该API可以对环境变量完成如下操作：

• 增加 ：当环境变量表中不存在该名称的环境变量时，则会执行新增操作；
• 修改 ：入参中的环境变量名称在当前环境变量表中存在，则把该环境变量值修改为入参中的值；
• 删除：当入参中的value为NULL时，则会删除入参名对应的环境变量。

EfErrCode ef_set_env_blob(const char *key, const void *value_buf, size_t buf_len);

其中参数的意义如下：

• key：环境变量名称
• value_buf：环境变量值缓冲区
• buf_len：缓冲区长度，即值的长度

3.3. 测试读取默认环境变量

在main.c中编写一个EasyFlash测试函数：

void test_env(void)
{
 char wifi_ssid[20] = {0};
 char wifi_passwd[20] = {0};
 size_t len = 0;
 
 /* 读取默认环境变量值 */
 //环境变量长度未知，先获取 Flash 上存储的实际长度 */
 ef_get_env_blob("wifi_ssid", NULL, 0, &len);
 //获取环境变量
 ef_get_env_blob("wifi_ssid", wifi_ssid, len, NULL);
 //打印获取的环境变量值
 printf("wifi_ssid env is:%s\r\n", wifi_ssid);
 
 //环境变量长度未知，先获取 Flash 上存储的实际长度 */
 ef_get_env_blob("wifi_passwd", NULL, 0, &len);
 //获取环境变量
 ef_get_env_blob("wifi_passwd", wifi_passwd, len, NULL);
 //打印获取的环境变量值
 printf("wifi_passwd env is:%s\r\n", wifi_passwd);
 
 /* 将环境变量值改变 */
 ef_set_env_blob("wifi_ssid", "SSID_TEST", 9);
 ef_set_env_blob("wifi_passwd", "66666666", 8);

}

在main函数的初始化代码之后调用该函数，编译下载之后，在串口终端中可以看到读取结果：此时环境变量已经被修改，直接复位开发板，可以看到读取出的新值：

3.4. Easyflash和letter-shell的结合

EasyFlash在测试阶段需要不断的设置环境变量、读取环境变量、开发板重新上电，这个特点刚好可以应用letter-shell，直接将两个常用函数导出为命令，在串口命令行测试。

letter-shell的移植过程请参考第2期：

移植之后将读取环境变量的API封装，导出到命令列表中：

/* USER CODE BEGIN 4 */
int getenv(const char *key)
{
 size_t len = 0;
 char buf[20] = {0};
 
 //获取长度
 ef_get_env_blob(key, NULL, 0, &len);
 
 if(len == 0)
 {
  //环境变量不存在
  printf("evn %s is not exist\r\n", key);
  
  return -1;
 }
 else if(len < 20)
 {
  //环境变量值超长
  printf("buf size is not enough, len is %d\r\n", len);
  
  return -1;
 
 }
 else
 {
  //获取环境变量值
  ef_get_env_blob(key, buf, len, NULL);
  printf("read env %s, value is:%s\r\n", key, buf);
  
  return 0;
 }
}

SHELL_EXPORT_CMD(SHELL_CMD_PERMISSION(0)|SHELL_CMD_TYPE(SHELL_TYPE_CMD_FUNC), getenv, getenv, getenv);
/* USER CODE END 4 */

编译下载之后，在串口终端中查看串口输出：

然后进行读取环境变量测试：测试成功，同理，修改环境变量的API也可以进行封装，导出到命令列表中进行测试。

4. 设计思想解读

对于EasyFlash的全新版本设计，作者armink在仓库中写了一份文档，解铃还须系铃人，笔者的技术水平有限，直接放上作者的文档链接，欢迎感兴趣的读者阅读。

• EasyFlash V4.0 ENV 功能设计与实现（请阅读今天的第二篇文章）

5. 项目工程源码获取和问题交流

目前我将EasyFlash源码、我移植到小熊派STM32L431RCT6开发板的工程源码上传到了QQ群里（包含好几份HAL库，QQ相对速度快点），可以在QQ群里下载，有问题也可以在群里交流，当然也欢迎大家分享出来自己移植的工程到QQ群里：放上QQ群二维码：

接收更多精彩文章及资源推送，欢迎订阅我的微信公众号：『mculover666』。