提交 b408d57f 编写于 作者: A armink

【更新】首页说明文档、API 文档及移植文档。

Signed-off-by: Narmink <armink.ztl@gmail.com>
上级 91f49605
......@@ -4,9 +4,9 @@
## 1、介绍([English](#1-introduction))
[EasyFlash](https://github.com/armink/EasyFlash)是一款开源的轻量级嵌入式Flash存储器库,主要为MCU(Micro Control Unit)提供便捷、通用的上层应用接口,使得开发者更加高效实现基于的Flash存储器常见应用开发。该库目前提供 **三大实用功能**
[EasyFlash](https://github.com/armink/EasyFlash)是一款开源的轻量级嵌入式Flash存储器库,方便开发者更加轻松的实现基于Flash存储器的常见应用开发。非常适合智能家居、可穿戴、工控、医疗等需要断电存储功能的产品,资源占用极低,支持各种 MCU 片上存储器。该库主要包括 **三大实用功能**
- **Env** 快速保存产品参数,支持 **写平衡(磨损平衡)****掉电保护** 模式
- **ENV** 快速保存产品参数,支持 **写平衡(磨损平衡)****掉电保护** 功能
EasyFlash不仅能够实现对产品的 **设定参数****运行日志** 等信息的掉电保存功能,还封装了简洁的 **增加、删除、修改及查询** 方法, 降低了开发者对产品参数的处理难度,也保证了产品在后期升级时拥有更好的扩展性。让Flash变为NoSQL(非关系型数据库)模型的小型键值(Key-Value)存储数据库。
......@@ -18,16 +18,28 @@ EasyFlash不仅能够实现对产品的 **设定参数** 或 **运行日志**
非常适合应用在小型的不带文件系统的产品中,方便开发人员快速定位、查找系统发生崩溃或死机的原因。同时配合[EasyLogger](https://github.com/armink/EasyLogger)(我开源的超轻量级、高性能C日志库,它提供与EasyFlash的无缝接口)一起使用,轻松实现C日志的Flash存储功能。
### 1.1、资源占用
### 1.1、V4.0 NG 模式
```
最低要求: ROM: 6K bytes RAM: 0.5K bytes + (Env大小)
自 2019 年春节后,EasyFlash 经过 4 年多的迭代,结合众多开发者的需求及建议,终于发布了 V4.0 版本,该版本中的 ENV 功能被命名为 **NG** (Next Generation) 模式,这是一个完全重构的新版本,具有以下新特性:
- 更小的资源占用,内存占用 **几乎为 0** ;(V4.0 以前版本会使用额外的 RAM 空间进行缓存)
- ENV 的值类型支持 **任意类型** 、任意长度,相当于直接 memcpy 变量至 flash ;(V4.0 之前只支持存储字符串)
- ENV 操作效率比以前的模式高,充分利用剩余空闲区域,擦除次数及操作时间显著降低;
- **原生支持** 磨损平衡、掉电保护功能 (V4.0 之前需要占用额外的 Flash 扇区);
- ENV 支持 **增量升级** ,固件升级后 ENV 也支持升级;
- 支持大数据存储模式,**长度无限制**,数据可在多个 Flash 扇区上顺序存储(V4.1 即将支持);
- 支持 **数据加密** ,提升存储的安全性(V4.2 即将支持);
- 支持 **数据压缩** ,减低 Flash 占用(V4.3 即将支持);
V4.0 设计及内部原理,V4.0 迁移指南等更多内容请阅读文档章节
Demo平台:STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes)
实际占用: ROM: 6K bytes RAM: 2.6K bytes
### 1.2、资源占用
```
最低要求: ROM: 6K bytes RAM: 0.1K bytes
```
### 1.2、支持平台
### 1.3、支持平台
目前已移植硬件平台有 `stm32f10x``stm32f4xx` 系列的片内Flash,SPI Flash,这些也是笔者产品使用的平台。其余平台的移植难度不大,在项目的设计之初就有考虑针对所有平台的适配性问题(64位除外),所以对所有移植接口都有做预留。移植只需修改 [`\easyflash\port\ef_port.c`](https://github.com/armink/EasyFlash/blob/master/easyflash/port/ef_port.c) 一个文件,实现里面的擦、写、读及打印功能即可。
......@@ -35,36 +47,47 @@ Demo平台:STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes)
## 2、流程
### 2.1、Env:环境变量(KV数据库)
### 2.1、ENV:环境变量(KV数据库)
下图为通过控制台(终端)来调用环境变量的常用接口,演示了以下过程,这些接口都支持被应用层直接调用。
- 1、创建“温度”的环境变量,名为 `temp`,并且赋值为 `123`
- 2、保存“温度”到Flash中并重启;
- 2、保存“温度”到Flash中并重启(V4.0 版本的每个操作完自动保存,无需额外保存)
- 3、检查“温度”是否被成功保存;
- 4、修改“温度”值为 `456` 并保存、重启;
- 5、检查“温度”是否被成功修改;
- 6、删除“温度”的环境变量。
![easy_flash_env](https://raw.githubusercontent.com/armink/EasyFlash/master/docs/zh/images/EnvDemo.gif)
![easy_flash_env](/docs/zh/images/EnvDemo.gif)
### 2.2、IAP:在线升级
下图演示了通过控制台来进行IAP升级软件的过程,使用的是库中自带的IAP功能接口,演示采用的是串口+Ymodem协议的方式。你还也可以实现通过CAN、485、以太网等总线,来实现远程网络更新。
![easy_flash_iap](https://raw.githubusercontent.com/armink/EasyFlash/master/docs/zh/images/IapDemo.gif)
![easy_flash_iap](/docs/zh/images/IapDemo.gif)
### 2.3、Log:日志存储
下图过程为通过控制台输出日志,并将输出的日志存储到Flash中。重启再读取上次保存的日志,最后清空Flash日志。
![easy_flash_log](https://raw.githubusercontent.com/armink/EasyFlash/master/docs/zh/images/LogDemo.gif)
![easy_flash_log](/docs/zh/images/LogDemo.gif)
## 3、文档
具体内容参考[`\docs\zh\`](https://github.com/armink/EasyFlash/tree/master/docs/zh)下的文件。务必保证在 **阅读文档** 后再移植使用。
- API 文档:[`\docs\zh\api.md`](/docs/zh/api.md)
- 移植文档:[`\docs\zh\port.md`](/docs/zh/port.md)
- V4.0 迁移指南:[`\docs\zh\v4_migrate.md`](/docs/zh/v4_migrate.md)
- V4.0 设计及实现细节:[`\docs\zh\design.md`](/docs/zh/design.md)
## 4、许可
务必保证在 **阅读文档** 后再移植使用。
## 4、支持
![support](/docs/zh/images/wechat_support.png)
如果 EasyFlash 解决了你的问题,不妨请我 **喝杯咖啡**~
## 5、许可
采用 MIT 开源协议,细节请阅读项目中的 LICENSE 文件内容。
......@@ -89,10 +112,7 @@ It's very suitable for small without a file system products. The developer can e
### 1.1 Resource consumption
```
Minimum : ROM: 6K bytes RAM: 0.5K bytes + (Env size)
Demo :STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes)
Actual : ROM: 6K bytes RAM: 2.6K bytes
Minimum : ROM: 6K bytes RAM: 0.2K bytes
```
### 1.2 Supported platforms
......@@ -114,19 +134,19 @@ The figure below shows an ENV's common interface be called by the console (termi
- 5.Check the temperature has changed successfully;
- 6.Delete temperature environment variable.
![easy_flash_env](https://raw.githubusercontent.com/armink/EasyFlash/master/docs/en/images/EnvDemo.gif)
![easy_flash_env](/docs/en/images/EnvDemo.gif)
### 2.2 IAP
The figure below shows the process of upgrading software through the console by IAP. It use this library comes with IAP function interface. It uses a serial port + Ymodem protocol mode. You can also be achieved through CAN, 485, Ethernet bus to online upgrade.
![easy_flash_iap](https://raw.githubusercontent.com/armink/EasyFlash/master/docs/en/images/IapDemo.gif)
![easy_flash_iap](/docs/en/images/IapDemo.gif)
### 2.3 Log
The following figure is the output of the log process through the console. The logs are saved to flash at real time. Then the board is rebooted and the logs back are read back from flash. At last logs will be erased.
![easy_flash_log](https://raw.githubusercontent.com/armink/EasyFlash/master/docs/en/images/LogDemo.gif)
![easy_flash_log](/docs/en/images/LogDemo.gif)
## 3 Documents
......
......@@ -6,9 +6,7 @@
名词介绍:
**备份区** :是EasyFlash定义的一个存放环境变量、已下载程序及日志的Flash区域,详细存储架构可以参考[`\easyflash\src\easyflash.c`](https://github.com/armink/EasyFlash/blob/master/easyflash/src/easyflash.c#L29-L58)文件头位置的注释说明或[移植文档中关于备份区参数配置](https://github.com/armink/EasyFlash/blob/master/docs/zh/port.md#55-备份区)
**环境变量表** :负责存放所有的环境变量,该表在Flash及RAM中均存在,上电后需从Flash加载到RAM中,修改后,则需要保存其至Flash中。。
- **备份区** :是EasyFlash定义的一个存放环境变量、已下载程序及日志的Flash区域,详细存储架构可以参考[`\easyflash\src\easyflash.c`](https://github.com/armink/EasyFlash/blob/master/easyflash/src/easyflash.c#L29-L58)文件头位置的注释说明或[移植文档中关于备份区参数配置](https://github.com/armink/EasyFlash/blob/master/docs/zh/port.md#55-备份区)
## 1、用户使用接口
......@@ -22,25 +20,43 @@ EfErrCode easyflash_init(void)
### 1.2 环境变量
#### 1.2.1 加载环境变量
在 V4.0 以后,环境变量在 EasyFlash 底层都是按照二进制数据格式进行存储,即 blob 格式,这样上层支持传入任意类型。而在 V4.0 之前底层使用的是字符串格式进行存储,字符串格式的环境变量也可以转换为 blob 格式,所以 V4.0 能做到完全兼容以前的 API 。
#### 1.2.1 获取环境变量
通过环境变量的名字来获取其对应的值。支持两种接口
加载Flash中的所有环境变量到系统内存中。
##### 1.2.1.1 获取 blob 类型环境变量
```C
void ef_load_env(void)
size_t ef_get_env_blob(const char *key, void *value_buf, size_t buf_len, size_t *value_len)
```
#### 1.2.2 打印环境变量
|参数 |描述|
|:----- |:----|
|key |环境变量名称|
|value_buf |存放环境变量的缓冲区|
|buf_len |该缓冲区的大小|
|value_len |返回该环境变量实际存储的大小|
|返回 |成功存放至缓冲区中的数据长度|
通过在移植接口([`\easyflash\port\ef_port.c`](https://github.com/armink/EasyFlash/blob/master/easyflash/port/ef_port.c))中定义的`ef_print`打印方法,来将Flash中的所有环境变量输出出来。
示例:
```C
void ef_print_env(void)
char value[32];
size_t len;
/* 如果环境变量长度未知,可以先获取 Flash 上存储的实际长度,将通过 len 返回 */
ef_get_env_blob("key", NULL, 0, &len);
/* 如果长度已知,使用 value 缓冲区,存放读取回来的环境变量值数据,并将实际长度返回 */
len = ef_get_env_blob("key", value, sizeof(value) , NULL);
```
#### 1.2.3 获取环境变量
##### 1.2.1.2 获取字符串类型环境变量
**注意**
通过环境变量的名字来获取其对应的值。(注意:此处的环境变量指代的已加载到内存中的环境变量)
- 该函数不推荐继续使用,可以使用上面的函数替代;
- 该函数不支持可重入,返回的值位于函数内部缓冲区,出于安全考虑,请加锁保护。
```C
char *ef_get_env(const char *key)
......@@ -49,15 +65,31 @@ char *ef_get_env(const char *key)
|参数 |描述|
|:----- |:----|
|key |环境变量名称|
|返回 |环境变量值|
#### 1.2.4 设置环境变量
使用此方法可以实现对环境变量的增加、修改及删除功能。(注意:此处的环境变量指代的已加载到内存中的环境变量)
#### 1.2.2 设置环境变量
使用此方法可以实现对环境变量的增加、修改及删除功能。
- **增加** :当环境变量表中不存在该名称的环境变量时,则会执行新增操作;
- **修改** :入参中的环境变量名称在当前环境变量表中存在,则把该环境变量值修改为入参中的值;
- **删除**:当入参中的value为NULL时,则会删除入参名对应的环境变量。
##### 1.2.1.1 设置 blob 类型环境变量
```C
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 设置字符串类型环境变量
```C
EfErrCode ef_set_env(const char *key, const char *value)
......@@ -68,9 +100,9 @@ EfErrCode ef_set_env(const char *key, const char *value)
|key |环境变量名称|
|value |环境变量值|
#### 1.2.5 删除环境变量
#### 1.2.3 删除环境变量
使用此方法可以实现对环境变量的删除功能。(注意:此处的环境变量指代的已加载到内存中的环境变量)
使用此方法可以实现对环境变量的删除功能。
```c
EfErrCode ef_del_env(const char *key)
......@@ -80,51 +112,22 @@ EfErrCode ef_del_env(const char *key)
| :--- | :----------- |
| key | 环境变量名称 |
#### 1.2.6 保存环境变量
保存内存中的环境变量表到Flash中。
```C
EfErrCode ef_save_env(void)
```
#### 1.2.7 重置环境变量
#### 1.2.4 重置环境变量
将内存中的环境变量表重置为默认值。
```C
EfErrCode ef_env_set_default(void)
```
#### 1.2.8 获取当前环境变量写入到Flash的字节大小
```C
size_t ef_get_env_write_bytes(void)
```
#### 1.2.9 设置并保存环境变量
#### 1.2.5 打印环境变量
设置环境变量成功后立刻保存。设置功能参考`ef_set_env`方法
通过在移植接口([`\easyflash\port\ef_port.c`](https://github.com/armink/EasyFlash/blob/master/easyflash/port/ef_port.c))中定义的`ef_print`打印方法,来将Flash中的所有环境变量输出出来
```C
EfErrCode ef_set_and_save_env(const char *key, const char *value)
```
|参数 |描述|
|:----- |:----|
|key |环境变量名称|
|value |环境变量值|
#### 1.2.10 删除并保存环境变量
删除环境变量成功后立刻保存。删除功能参考`ef_del_env`方法。
```c
EfErrCode ef_del_and_save_env(const char *key)
void ef_print_env(void)
```
| 参数 | 描述 |
| :--- | :----------- |
| key | 环境变量名称 |
### 1.3 在线升级
......@@ -287,6 +290,5 @@ size_t ef_log_get_used_size(void);
## 3、注意
- 写数据前务必记得先擦除
- 环境变量设置完后,只有调用`ef_save_env`才会保存在Flash中,否则开机会丢失修改的内容
- 不要在应用程序及Bootloader中执行擦除及拷贝自身的动作
- ENV及Log功能对Flash擦除和写入要求4个字节对齐,擦除的最小单位则需根据用户的平台来确定
- Log功能对Flash擦除和写入要求4个字节对齐,擦除的最小单位则需根据用户的平台来确定
马上就来……
\ No newline at end of file
......@@ -4,7 +4,7 @@
## 1、下载源码
[点击此链接](https://github.com/armink/EasyFlash/archive/master.zip)即可直接下载位于Github上的源码。
[点击此链接](https://github.com/armink/EasyFlash/archive/master.zip)即可直接下载位于Github上的最新源码。
> 建议:点击项目主页 https://github.com/armink/EasyFlash 右上角 **Watch & Star**,这样项目有更新时,会及时以邮件形式通知你。
......@@ -19,7 +19,6 @@
|源文件 |描述 |
|:------------------------------ |:----- |
|\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|
......@@ -40,9 +39,16 @@
## 3、Flash规格
在移植时务必先要了解项目的Flash规格,这里需要了解是规格是 **最小擦除单位** 及 **内部存储结构** ,各个厂家的Flash规格都有差异,同一厂家不同系列的规格也有差异。例如:stm32f10x系列中的大容量MCU自带Flash的页大小均为2K,而中小容量的页大小均为1K。在stm32f4xx系列中,每个页大小不是像stm32f10x那样平均分配,最大的有128K,最小的有16K。
在移植时务必先要了解项目的Flash规格,这里需要了解是规格是 **擦除粒度(擦除最小单元)** 、**写入粒度**及 **内部存储结构** ,各个厂家的Flash规格都有差异,同一厂家不同系列的规格也有差异。以下是一些常见 Flash 的规格
> 注意:务必保证熟悉Flash规格后,再继续下章节。
| Flash 类型 | 写入粒度 | 擦除粒度 | 内部存储结构 |
| ---------------------- | -------- | ------------ | ------------------------- |
| STM32F1 片内 Flash | 4bytes | 1K/2K | 均匀分布 |
| STM32F2/F4 片内 Flash | 1byte | 16K/64K/128K | 最大的有128K,最小的有16K |
| STM32L4 片内 Flash | 8bytes | 4K | 均匀分布 |
| Nor Flash(SPI-Flash) | 1bit | 4K | 均匀分布 |
> **注意** :务必保证熟悉Flash规格后,再继续下章节。
## 4、移植接口
......@@ -69,7 +75,7 @@ EfErrCode ef_port_read(uint32_t addr, uint32_t *buf, size_t size)
|参数 |描述|
|:----- |:----|
|addr |读取起始地址|
|addr |读取起始地址(4字节对齐)|
|buf |存放读取数据的缓冲区|
|size |读取数据的大小(字节)|
......@@ -94,7 +100,7 @@ EfErrCode ef_port_write(uint32_t addr, const uint32_t *buf, size_t size)
|参数 |描述|
|:----- |:----|
|addr |写入的起始地址|
|addr |写入的起始地址(4字节对齐)|
|buf |源数据的缓冲区|
|size |写入数据的大小(字节)|
......@@ -162,33 +168,18 @@ void ef_print(const char *format, ...)
- 默认状态:开启
- 操作方法:开启、关闭`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 自动更新(增量更新)
#### 5.1.1 自动更新(增量更新)
可以对 ENV 设置版本号(参照 5.1.4)。当 ENV 初始化时,如果检测到产品存储的版本号与设定版本号不一致,会自动追加默认环境变量集合中新增的环境变量。
可以对 ENV 设置版本号(参照 5.1.2)。当 ENV 初始化时,如果检测到产品存储的版本号与设定版本号不一致,会自动追加默认环境变量集合中新增的环境变量。
该功能非常适用于经常升级的产品中,当产品功能变更时,有可能会新增环境变量,此时只需要增大当前设定的 ENV 版本号,下次固件升级后,新增的环境变量将会自动追加上去。
- 默认状态:关闭
- 操作方法:开启、关闭`EF_ENV_AUTO_UPDATE`宏即可
#### 5.1.4 环境变量版本号
#### 5.1.2 环境变量版本号
该配置依赖于 5.1.3 配置。设置的环境变量版本号为整形数值,可以从 0 开始。如果在默认环境变量表中增加了环境变量,此时需要对该配置进行修改(通常加 1 )。
该配置依赖于 5.1.1 配置。设置的环境变量版本号为整形数值,可以从 0 开始。如果在默认环境变量表中增加了环境变量,此时需要对该配置进行修改(通常加 1 )。
- 操作方法:修改`EF_ENV_VER_NUM`宏对应值即可
......@@ -202,48 +193,38 @@ void ef_print(const char *format, ...)
- 默认状态:开启
- 操作方法:开启、关闭`EF_USING_LOG`宏即可
### 5.4 Flash最小擦除单位
### 5.4 Flash 擦除粒度(最小擦除单位)
- 操作方法:修改`EF_ERASE_MIN_SIZE`宏对应值即可,单位:byte
- 操作方法:修改`EF_ERASE_MIN_SIZE`宏对应值即可
### 5.5 Flash 写入粒度
- 操作方法:修改`EF_WRITE_GRAN`宏对应值即可,单位:bit,仅支持:1/8/32/64
### 5.5 备份区
备份区共计包含3个区域,依次为:环境变量区、日志区及在线升级区。分区方式如下图所示
![backup_area_partiton](http://git.oschina.net/Armink/EasyFlash/raw/master/docs/zh/images/BackupAreaPartition.jpg)
![backup_area_partiton](/images/BackupAreaPartition.jpg)
在配置时需要注意以下几点:
- 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`;
- 2、从 V4.0 开始 ENV 的模式命名为 NG 模式,V4.0 之前的称之为 LEGACY 遗留模式;
- 遗留模式已经被废弃,不再建议继续使用;
- 如果需要继续使用遗留模式,请 EasyFlash 的 V3.X 版本。
#### 5.5.1 备份区起始地址
- 操作方法:修改`EF_START_ADDR`宏对应值即可
#### 5.5.2 用户设定环境变量大小
- 操作方法:修改`ENV_USER_SETTING_SIZE`宏对应值即可
> 注意:不使用环境变量功能时,可以不定义此宏。
#### 5.5.3 环境变量区总容量
#### 5.5.2 环境变量区总容量
- 操作方法:修改`ENV_AREA_SIZE`宏对应值即可
> 注意:不使用环境变量功能时,可以不定义此宏。
#### 5.5.4 日志区总容量
#### 5.5.3 日志区总容量
- 操作方法:修改`LOG_AREA_SIZE`宏对应值即可
......
马上就来……
\ No newline at end of file
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册