InJre

easyflash 教程

可以看easyflash下的docs文档，万一你们手头没有文档呢。这里我就直接黏贴了。

API 说明文档： docs/zh/api.md
通用移植文档： docs/zh/port.md

EasyFlash API 说明

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

名词介绍：

备份区 ：是EasyFlash定义的一个存放环境变量、已下载程序及日志的Flash区域，详细存储架构可以参考\easyflash\src\easyflash.c文件头位置的注释说明或移植文档中关于备份区参数配置。

环境变量表 ：负责存放所有的环境变量，该表在Flash及RAM中均存在，上电后需从Flash加载到RAM中，修改后，则需要保存其至Flash中。。

1、用户使用接口

1.1 初始化

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

EfErrCode easyflash_init(void)

1.2 环境变量

1.2.1 加载环境变量

加载Flash中的所有环境变量到系统内存中。

void ef_load_env(void)

1.2.2 打印环境变量

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

void ef_print_env(void)

1.2.3 获取环境变量

通过环境变量的名字来获取其对应的值。（注意：此处的环境变量指代的已加载到内存中的环境变量）

char *ef_get_env(const char *key)

参数	描述
key	环境变量名称

1.2.4 设置环境变量

使用此方法可以实现对环境变量的增加、修改及删除功能。（注意：此处的环境变量指代的已加载到内存中的环境变量）

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

EfErrCode ef_set_env(const char *key, const char *value)

参数	描述
key	环境变量名称
value	环境变量值

1.2.5 保存环境变量

保存内存中的环境变量表到Flash中。

EfErrCode ef_save_env(void)

1.2.6 重置环境变量

将内存中的环境变量表重置为默认值。

EfErrCode ef_env_set_default(void)

1.2.7 获取当前环境变量写入到Flash的字节大小

size_t ef_get_env_write_bytes(void)

1.2.8 设置并保存环境变量

设置环境变量成功后立刻保存。设置功能参考ef_set_env方法。

EfErrCode ef_set_and_save_env(const char *key, const char *value)

参数	描述
key	环境变量名称
value	环境变量值

1.3 在线升级

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

EfErrCode ef_erase_bak_app(size_t app_size)

1.3.2 擦除用户的应用程序

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

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 方法进行擦除，除此之外的其余功能，两个方法均一致。

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

EfErrCode ef_erase_spec_user_app(uint32_t user_app_addr, size_t app_size,
        EfErrCode (*app_erase)(uint32_t addr, size_t size));

参数	描述
user_app_addr	用户应用程序入口地址
user_app_size	用户应用程序大小
app_erase	用户指定应用程序擦写方法

1.3.4 擦除Bootloader

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

EfErrCode ef_erase_bl(uint32_t bl_addr, size_t bl_size)

参数	描述
bl_addr	Bootloader入口地址
bl_size	Bootloader大小

1.3.5 写数据到备份区

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

EfErrCode ef_write_data_to_bak(uint8_t *data,
                               size_t size,
                               size_t *cur_size,
                               size_t total_size)

参数	描述
data	需要写入到备份区中的数据存储地址
size	此次写入数据的大小（字节）
cur_size	之前已写入到备份区中的数据大小（字节）
total_size	需要写入到备份区的数据总大小（字节）

1.3.6 从备份拷贝应用程序

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

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 方法进行写操作，除此之外的其余功能，两个方法均一致。

EfErrCode ef_copy_spec_app_from_bak(uint32_t user_app_addr, size_t app_size,
        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中调用该方法

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中读取已存在的日志

EfErrCode ef_log_read(size_t index, uint32_t *log, size_t size);

参数	描述
index	日志读取的索引顺序
log	存储待读取日志的缓冲区
size	读取日志的大小

1.4.2 往Flash中保存日志

EfErrCode ef_log_write(const uint32_t *log, size_t size);

参数	描述
log	存储待保存的日志
size	待保存日志的大小

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

EfErrCode ef_log_clean(void);

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

size_t ef_log_get_used_size(void);

2、配置

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

3、注意

写数据前务必记得先擦除
环境变量设置完后，只有调用ef_save_env才会保存在Flash中，否则开机会丢失修改的内容
不要在应用程序及Bootloader中执行擦除及拷贝自身的动作
ENV及Log功能对Flash擦除和写入要求4个字节对齐，擦除的最小单位则需根据用户的平台来确定

EasyFlash 移植说明

1、下载源码

点击此链接即可直接下载位于Github上的源码。

建议：点击项目主页 https://github.com/armink/EasyFlash 右上角 Watch & Star，这样项目有更新时，会及时以邮件形式通知你。

如果Github下载太慢，也可以点击项目位于的国内仓库下载的链接(OSChina|Coding)。

2、导入项目

在导入到项目前，先打开\demo\文件夹，检查下有没有与项目Flash规格一致的Demo。如果有则先直接跳过2、3、4章节，按照第5章的要求设置参数，并运行、验证Demo。验证通过再按照下面的导入项目要求，将Demo中的移植文件直接导入到项目中即可。

1、先解压下载好的源码包，文件的目录结构大致如下：

源文件	描述
\easyflash\src\ef_env.c	Env（常规模式）相关操作接口及实现源码
\easyflash\src\ef_env_wl.c	Env（磨损平衡模式）相关操作接口及实现源码
\easyflash\src\ef_iap.c	IAP 相关操作接口及实现源码
\easyflash\src\ef_log.c	Log 相关操作接口及实现源码
\easyflash\src\ef_utils.c	EasyFlash常用小工具，例如：CRC32
\easyflash\src\easyflash.c	目前只包含EasyFlash初始化方法
\easyflash\port\ef_port.c	不同平台下的EasyFlash移植接口
\demo\env\stm32f10x\non_os	stm32f10x裸机片内Flash的Env demo
\demo\env\stm32f10x\non_os_spi_flash	stm32f10x裸机SPI Flash的Env demo
\demo\env\stm32f10x\rtt	stm32f10x基于RT-Thread的片内Flash Env demo
\demo\env\stm32f4xx	stm32f4xx基于RT-Thread的片内Flash Env demo
\demo\iap\ymodem+rtt.c	使用RT-Thread+Ymodem的IAP Demo
\demo\log\easylogger.c	基于EasyLogger的Log Demo

2、将\easyflash\（里面包含inc、src及port的那个）文件夹拷贝到项目中；
3、添加\easyflash\src\easyflash.c、\easyflash\src\ef_utils.c及\easyflash\port\ef_port.c这些文件到项目的编译路径中；
4、根据项目需求，选择性添加\easyflash\src\中的其他源码文件到项目的编译路径中；
5、添加\easyflash\inc\文件夹到编译的头文件目录列表中；

3、Flash规格

在移植时务必先要了解项目的Flash规格，这里需要了解是规格是 最小擦除单位 及 内部存储结构 ，各个厂家的Flash规格都有差异，同一厂家不同系列的规格也有差异。例如：stm32f10x系列中的大容量MCU自带Flash的页大小均为2K，而中小容量的页大小均为1K。在stm32f4xx系列中，每个页大小不是像stm32f10x那样平均分配，最大的有128K，最小的有16K。

注意：务必保证熟悉Flash规格后，再继续下章节。

4、移植接口

4.1 移植初始化

EasyFlash移植初始化。可以传递默认环境变量，初始化EasyFlash移植所需的资源等等。

EfErrCode ef_port_init(ef_env const **default_env, size_t *default_env_size)

参数	描述
default_env	默认的环境变量
default_env_size	默认环境变量的数量

4.2 读取Flash

最小单位为4个字节。

EfErrCode ef_port_read(uint32_t addr, uint32_t *buf, size_t size)

参数	描述
addr	读取起始地址
buf	存放读取数据的缓冲区
size	读取数据的大小（字节）

4.3 擦除Flash

EfErrCode ef_port_erase(uint32_t addr, size_t size)

参数	描述
addr	擦除起始地址
size	擦除数据的大小（字节）

4.4 写入Flash

最小单位为4个字节。

EfErrCode ef_port_write(uint32_t addr, const uint32_t *buf, size_t size)

参数	描述
addr	写入的起始地址
buf	源数据的缓冲区
size	写入数据的大小（字节）

4.5 对环境变量缓冲区加锁

为了保证RAM缓冲区在并发执行的安全性，所以需要对其进行加锁（如果项目的使用场景不存在并发情况，则可以忽略）。有操作系统时可以使用获取信号量来加锁，裸机时可以通过关闭全局中断来加锁。

void ef_port_env_lock(void)

4.6 对环境变量缓冲区解锁

有操作系统是可以使用释放信号量来解锁，裸机时可以通过开启全局中断来解锁。

void ef_port_env_unlock(void)

4.7 打印调试日志信息

在定义PRINT_DEBUG宏后，打印调试日志信息。

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

参数	描述
file	调用该方法的文件
line	调用该方法的行号
format	打印格式
…	不定参

4.8 打印普通日志信息

void ef_log_info(const char *format, ...)

参数	描述
format	打印格式
…	不定参

4.9 无格式打印信息

该方法输出无固定格式的打印信息，为ef_print_env方法所用（如果不使用ef_print_env则可以忽略）。而ef_log_debug及ef_log_info可以输出带指定前缀及格式的打印日志信息。

void ef_print(const char *format, ...)

参数	描述
format	打印格式
…	不定参

5、设置参数

配置时需要修改项目中的ef_cfg.h文件，开启、关闭、修改对应的宏即可。

5.1 环境变量功能

默认状态：开启
操作方法：开启、关闭EF_USING_ENV宏即可

5.1.1 磨损平衡/常规模式

磨损平衡：由于flash在写操作之前需要擦除且使用寿命有限，所以需要设计合理的磨损平衡（写平衡）机制，来保证数据被安全的保存在未到擦写寿命的Flash区中。

默认状态：常规模式
常规模式：关闭EF_ENV_USING_WL_MODE
磨损平衡模式：打开EF_ENV_USING_WL_MODE

5.1.2 掉电保护

掉电保护：Power Fail Safeguard，当此项设置为可用时，如果在环境变量保存过程中发生掉电，已保存在Flash中的环境变量将不会有丢失的危险。下次上电后，环境变量将会被自动还原至之前的状态。（注意：本保护是基于软件实现的保护功能，更加可靠的掉电保护功能需要通过硬件来实现）

默认状态：关闭
操作方法：开启、关闭EF_ENV_USING_PFS_MODE宏即可

5.1.3 自动更新（增量更新）

可以对 ENV 设置版本号（参照 5.1.4）。当 ENV 初始化时，如果检测到产品存储的版本号与设定版本号不一致，会自动追加默认环境变量集合中新增的环境变量。

该功能非常适用于经常升级的产品中，当产品功能变更时，有可能会新增环境变量，此时只需要增大当前设定的 ENV 版本号，下次固件升级后，新增的环境变量将会自动追加上去。

默认状态：关闭
操作方法：开启、关闭EF_ENV_AUTO_UPDATE宏即可

5.1.4 环境变量版本号

该配置依赖于 5.1.3 配置。设置的环境变量版本号为整形数值，可以从 0 开始。如果在默认环境变量表中增加了环境变量，此时需要对该配置进行修改（通常加 1 ）。

操作方法：修改EF_ENV_VER_NUM宏对应值即可

5.2 在线升级功能

默认状态：开启
操作方法：开启、关闭EF_USING_IAP宏即可

5.3 日志功能

默认状态：开启
操作方法：开启、关闭EF_USING_LOG宏即可

5.4 Flash最小擦除单位

操作方法：修改EF_ERASE_MIN_SIZE宏对应值即可

5.5 备份区

备份区共计包含3个区域，依次为：环境变量区、日志区及在线升级区。分区方式如下图所示

[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-27eI29Fp-1576720849511)(http://git.oschina.net/Armink/EasyFlash/raw/master/docs/zh/images/BackupAreaPartition.j)]

在配置时需要注意以下几点：

1、所有的区域必须按照EF_ERASE_MIN_SIZE对齐；
2、由于EasyFlash对所有的环境变量都会使用RAM缓存，但是在更多时候用户使用的环境变量大小会比EF_ERASE_MIN_SIZE小，所以需要再定义ENV_USER_SETTING_SIZE来指定用户设定的环境变量大小。
3、环境变量区总容量在不同的模式下会有差异
- 1、常规模式：没有差异；
- 2、擦写平衡模式：系统区将会占用1个EF_ERASE_MIN_SIZE大小，数据区至少等使用2个以上Flash扇区；
- 3、掉电保护模式：环境变量区将会被备份，所以总容量是常规模式的2倍；
- 4、擦写平衡+掉电保护模式：所需容量将会是擦写平衡模式下总容量的2倍。
- 例如：EF_ERASE_MIN_SIZE是128K，ENV_USER_SETTING_SIZE是2K，那么你可以这样定义不同模式下的环境变量总容量：
- 1、常规模式：1*EF_ERASE_MIN_SIZE；
- 2、擦写平衡模式：3*EF_ERASE_MIN_SIZE（它将会有3个Flash扇区去存储环境变量，1个系统区，2个数据区，按照每个Flash扇区可被擦写10W次计算，那么当前配置至少可擦写20W次）;
- 3、掉电保护模式：2*EF_ERASE_MIN_SIZE;
- 4、擦写平衡+掉电保护模式：6*EF_ERASE_MIN_SIZE;

5.5.1 备份区起始地址

操作方法：修改EF_START_ADDR宏对应值即可

5.5.2 用户设定环境变量大小

操作方法：修改ENV_USER_SETTING_SIZE宏对应值即可

注意：不使用环境变量功能时，可以不定义此宏。

5.5.3 环境变量区总容量

操作方法：修改ENV_AREA_SIZE宏对应值即可