EasyFlash API 说明


所有支持的API接口都在\easyflash\inc\easyflash.h中声明。以下内容较多,建议使用 CTRL+F 搜索。

名词介绍:

1、用户使用接口

1.1 初始化

初始化的EasyFlash的各个组件,初始化后才可以使用下面的API。

针对环境变量组件,如果 flash 第一次初始化,会自动调用 ef_env_set_default ,恢复移植文件中定义的默认环境变量(详见移植文档),之后每次启动会自动检查 flash 中的环境变量状态,flash 出现严重损坏时也会恢复环境变量至默认。如果开启增量升级功能,还会做增量升级的检查,版本号不一致时执行增量升级。

  1. EfErrCode easyflash_init(void)

1.2 环境变量

在 V4.0 以后,环境变量在 EasyFlash 底层都是按照二进制数据格式进行存储,即 blob 格式 ,这样上层支持传入任意类型。而在 V4.0 之前底层使用的是字符串格式进行存储,字符串格式的环境变量也可以转换为 blob 格式,所以 V4.0 能做到完全兼容以前的 API ,例如:ef_get_env/ef_set_env ,这些 API 只能 给字符串 ENV 使用。

另外字符串 ENV 也有长度的限制,默认 EF_STR_ENV_VALUE_MAX_SIZE 配置为 128 字节,超过长度的可能无法使用 ef_get_env 获取,只能使用 ef_get_env_blob 获取。

1.2.1 获取环境变量

通过环境变量的名字来获取其对应的值。支持两种接口

1.2.1.1 获取 blob 类型环境变量
  1. 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 中的大小
返回 成功存放至缓冲区中的数据长度

示例:

  1. char value[32];
  2. size_t len;
  3. /* 如果环境变量长度未知,可以先获取 Flash 上存储的实际长度,将通过 len 返回 */
  4. ef_get_env_blob("key", NULL, 0, &len);
  5. /* 如果长度已知,使用 value 缓冲区,存放读取回来的环境变量值数据,并将实际长度返回 */
  6. len = ef_get_env_blob("key", value, sizeof(value) , NULL);
1.2.1.2 获取字符串类型环境变量

注意

  • 该函数已废弃,不推荐继续使用,可以使用上面的函数替代;
  • 该函数不允许连续使用,使用时需使用 strdup 包裹,确保每次返回回来的字符串内存空间独立;
  • 该函数不支持可重入,返回的值位于函数内部缓冲区,出于安全考虑,请加锁保护。
  1. char *ef_get_env(const char *key)
参数 描述
key 环境变量名称
返回 环境变量值

1.2.2 设置环境变量

使用此方法可以实现对环境变量的增加、修改及删除功能。

  • 增加 :当环境变量表中不存在该名称的环境变量时,则会执行新增操作;
  • 修改 :入参中的环境变量名称在当前环境变量表中存在,则把该环境变量值修改为入参中的值;
  • 删除:当入参中的value为NULL时,则会删除入参名对应的环境变量。
1.2.1.1 设置 blob 类型环境变量
  1. EfErrCode ef_set_env_blob(const char *key, const void *value_buf, size_t buf_len)
参数 描述
key 环境变量名称
value_buf 环境变量值缓冲区
buf_len 缓冲区长度,即值的长度
1.2.1.2 设置字符串类型环境变量
  1. EfErrCode ef_set_env(const char *key, const char *value)
参数 描述
key 环境变量名称
value 环境变量值

1.2.3 删除环境变量

使用此方法可以实现对环境变量的删除功能。

  1. EfErrCode ef_del_env(const char *key)
参数 描述
key 环境变量名称

1.2.4 重置环境变量

将内存中的环境变量表重置为默认值。关于默认环境变量的设定方法可以参考移植文档。

  1. EfErrCode ef_env_set_default(void)

1.2.5 打印环境变量

通过在移植接口(\easyflash\port\ef_port.c)中定义的ef_print打印方法,来将Flash中的所有环境变量输出出来。

  1. void ef_print_env(void)

1.3 在线升级

1.3.1 擦除备份区中的应用程序

  1. EfErrCode ef_erase_bak_app(size_t app_size)

1.3.2 擦除用户的应用程序

注意:请不要在应用程序中调用该方法

  1. EfErrCode ef_erase_user_app(uint32_t user_app_addr, size_t user_app_size)
参数 描述
user_app_addr 用户应用程序入口地址
user_app_size 用户应用程序大小

1.3.3 通过用户指定的擦除方法来擦除应用程序

当用户的应用程序与备份区 不在同一个 Flash 时,则需要用户额外指定擦除应用程序的方法。而 ef_erase_user_app 会使用移植文件中的 ef_port_erase 方法进行擦除,除此之外的其余功能,两个方法均一致。

注意:请不要在应用程序中调用该方法

  1. EfErrCode ef_erase_spec_user_app(uint32_t user_app_addr, size_t app_size,
  2. EfErrCode (*app_erase)(uint32_t addr, size_t size));
参数 描述
user_app_addr 用户应用程序入口地址
user_app_size 用户应用程序大小
app_erase 用户指定应用程序擦写方法

1.3.4 擦除Bootloader

注意:请不要在Bootloader中调用该方法

  1. EfErrCode ef_erase_bl(uint32_t bl_addr, size_t bl_size)
参数 描述
bl_addr Bootloader入口地址
bl_size Bootloader大小

1.3.5 写数据到备份区

为下载程序到备份区定制的Flash连续写方法。注意:写之前请先确认Flash已进行擦除。

  1. EfErrCode ef_write_data_to_bak(uint8_t *data,
  2. size_t size,
  3. size_t *cur_size,
  4. size_t total_size)
参数 描述
data 需要写入到备份区中的数据存储地址
size 此次写入数据的大小(字节)
cur_size 之前已写入到备份区中的数据大小(字节)
total_size 需要写入到备份区的数据总大小(字节)

1.3.6 从备份拷贝应用程序

将备份区已下载好的应用程序拷贝至用户应用程序起始地址。注意:1、拷贝前必须对原有的应用程序进行擦除2、不要在应用程序中调用该方法

  1. EfErrCode ef_copy_app_from_bak(uint32_t user_app_addr, size_t app_size)
参数 描述
user_app_addr 用户应用程序入口地址
user_app_size 用户应用程序大小

1.3.7 通过用户指定的写操作方法来拷贝应用程序

当用户的应用程序与备份区 不在同一个 Flash 时,则需要用户额外指定写应用程序的方法。而 ef_copy_app_from_bak 会使用移植文件中的 ef_port_write 方法进行写操作,除此之外的其余功能,两个方法均一致。

  1. EfErrCode ef_copy_spec_app_from_bak(uint32_t user_app_addr, size_t app_size,
  2. EfErrCode (*app_write)(uint32_t addr, const uint32_t *buf, size_t size))
参数 描述
user_app_addr 用户应用程序入口地址
user_app_size 用户应用程序大小
app_write 用户指定应用程序写操作方法

1.3.8 从备份拷贝Bootloader

将备份区已下载好的Bootloader拷贝至Bootloader起始地址。注意:1、拷贝前必须对原有的Bootloader进行擦除2、不要在Bootloader中调用该方法

  1. EfErrCode ef_copy_bl_from_bak(uint32_t bl_addr, size_t bl_size)
参数 描述
bl_addr Bootloader入口地址
bl_size Bootloader大小

1.4 日志存储

1.4.1 从Flash中读取已存在的日志

  1. EfErrCode ef_log_read(size_t index, uint32_t *log, size_t size);
参数 描述
index 日志读取的索引顺序
log 存储待读取日志的缓冲区
size 读取日志的大小

1.4.2 往Flash中保存日志

  1. EfErrCode ef_log_write(const uint32_t *log, size_t size);
参数 描述
log 存储待保存的日志
size 待保存日志的大小

1.4.3 清空存储在Flash中全部日志

  1. EfErrCode ef_log_clean(void);

1.4.4 获取已存储在Flash中的日志大小

  1. size_t ef_log_get_used_size(void);

2、配置

参照EasyFlash 移植说明(\docs\zh\port.md)中的 设置参数 章节

3、注意

  • 写数据前务必记得先擦除
  • 不要在应用程序及Bootloader中执行擦除及拷贝自身的动作
  • Log功能对Flash擦除和写入要求4个字节对齐,擦除的最小单位则需根据用户的平台来确定