From 0167f94974d447c3111bb28f242e0316ee7ebdfe Mon Sep 17 00:00:00 2001 From: armink Date: Wed, 22 Jul 2015 11:42:33 +0800 Subject: [PATCH] =?UTF-8?q?1=E3=80=81=E3=80=90=E5=A2=9E=E5=8A=A0=E3=80=91?= =?UTF-8?q?=E7=A7=BB=E6=A4=8D=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: armink --- README.md | 47 ++------- docs/zh/api.md | 197 ++-------------------------------- docs/zh/port.md | 261 ++++++++++++++++++++++++++++++++++++++++++++++ docs/zh/readme.md | 3 +- 4 files changed, 278 insertions(+), 230 deletions(-) create mode 100644 docs/zh/port.md diff --git a/README.md b/README.md index a5d508a..fa82502 100644 --- a/README.md +++ b/README.md @@ -18,24 +18,7 @@ EasyFlash是一款开源的轻量级嵌入式Flash存储器库，主要为MCU(Mi 非常适合应用在小型的不带文件系统的产品中，方便开发人员快速定位、查找系统发生崩溃或死机的原因。同时配合[EasyLogger](https://github.com/armink/EasyLogger)(我开源的超轻量级、高性能C日志库，它提供与EasyFlash的无缝接口)一起使用，轻松实现C日志的Flash存储功能。 -### 1.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裸机的Env demo| -|\demo\env\stm32f10x\rtt |stm32f10x基于[RT-Thread](http://www.rt-thread.org/)的Env demo| -|\demo\env\stm32f4xx |stm32f4xx基于[RT-Thread](http://www.rt-thread.org/)的Env demo| -|\demo\iap\ymodem+rtt.c |使用[RT-Thread](http://www.rt-thread.org/)+[Ymodem](https://github.com/RT-Thread/rt-thread/tree/master/components/utilities/ymodem)的IAP Demo| -|\demo\log\easylogger.c |基于[EasyLogger](https://github.com/armink/EasyLogger)的Log Demo| - -### 1.2、资源占用 +### 1.1、资源占用 ``` 最低要求： ROM: 6K bytes RAM: 0.5K bytes + (Env大小) @@ -44,7 +27,7 @@ Demo平台：STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes) 实际占用： ROM: 6K bytes RAM: 2.6K bytes ``` -### 1.3、支持平台 +### 1.2、支持平台 目前已移植硬件平台有 `stm32f10x`与 `stm32f4xx` 系列的片内Flash，这个也是笔者产品使用的平台。其余平台的移植难度不大，在项目的设计之初就有考虑针对所有平台的适配性问题（64位除外），所以对所有移植接口都有做预留。移植只需修改 `\easyflash\port\ef_port.c` 一个文件，实现里面的擦、写、读及打印功能即可。 @@ -78,9 +61,11 @@ Demo平台：STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes) ![easy_flash_log](http://git.oschina.net/Armink/EasyFlash/raw/master/docs/zh/images/LogDemo.gif) ## 3、文档 -具体内容参考`\docs\`下的文件。 + +具体内容参考`\docs\`下的文件。务必保证在 **阅读文档** 后再移植使用。 ## 4、许可 + 采用 MIT 开源协议，细节请阅读项目中的 LICENSE 文件内容。 --- @@ -101,23 +86,7 @@ The library encapsulates the IAP (In-Application Programming) feature common int It's very suitable for small without a file system products. The developer can easy to locate and query problem when system crashes or freezes. You can use [EasyLogger](https://github.com/armink/EasyLogger)( A super-lightweight, high-performance C log library which open source by me. It provides a seamless interface with EasyFlash) at the same time. So, it's so easy to store the logs to flash. -### 1.1 File structure - -|Source file |Description | -|:------------------------------ |:----- | -|\easyflash\src\ef_env.c |Env (normal mode) interface and implementation source code.| -|\easyflash\src\ef_env_wl.c |Env (wear leveling mode) interface and implementation source code.| -|\easyflash\src\ef_iap.c |IAP interface and implementation source code.| -|\easyflash\src\ef_log.c |Log interface and implementation source code.| -|\easyflash\src\ef_utils.c |EasyFlash utils. For example CRC32.| -|\easyflash\src\easyflash.c |Currently contains EasyFlash initialization function only. | -|\easyflash\port\ef_port.c |EasyFlash portable interface and configuration for different platforms.| -|\demo\env\stm32f10x\non_os |stm32f10x non-os demo.| -|\demo\env\stm32f10x\rtt |stm32f10x demo base on [RT-Thread](http://www.rt-thread.org/).| -|\demo\env\stm32f4xx |stm32f4xx demo base on [RT-Thread](http://www.rt-thread.org/).| -|\demo\iap\ymodem+rtt.c |Using [RT-Thread](http://www.rt-thread.org/)+[Ymodem](https://github.com/RT-Thread/rt-thread/tree/master/components/utilities/ymodem) IAP Demo| -|\demo\log\easylogger.c |base on [EasyLogger](https://github.com/armink/EasyLogger) Log Demo| -### 1.2 Resource consumption +### 1.1 Resource consumption ``` Minimum : ROM: 6K bytes RAM: 0.5K bytes + (Env size) @@ -126,7 +95,7 @@ Demo :STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes) Actual : ROM: 6K bytes RAM: 2.6K bytes ``` -### 1.3 Supported platforms +### 1.2 Supported platforms Hardware platform has been ported `stm32f10x` and `stm32f4xx` series of on-chip Flash. This is my product platform. Remaining platform porting difficulty is little. The porting just modify `\easyflash\port\ef_port.c` file. Implement erase, write, read, print feature. @@ -161,7 +130,7 @@ The following figure is the output log process through the console. The logs wil ## 3 Documents -All documents is in the `\docs\` folder. +All documents is in the `\docs\` folder. Please **read the documents** before port and use it. ## 4 License diff --git a/docs/zh/api.md b/docs/zh/api.md index fa0027c..65a8415 100644 --- a/docs/zh/api.md +++ b/docs/zh/api.md @@ -2,11 +2,11 @@ --- -所有支持的API接口都在 `\easyflash\inc\easyflash.h` 中声明。以下内容较多，建议使用 **CTRL+F** 搜索。 +所有支持的API接口都在`\easyflash\inc\easyflash.h`中声明。以下内容较多，建议使用 **CTRL+F** 搜索。 名词介绍： -**备份区** ：是EasyFlash定义的一个存放环境变量、已下载程序及日志的Flash区域，详细存储架构可以参考 `\easyflash\src\easyflash.c` 文件头位置的注释说明或本文中的备份区参数配置。 +**备份区** ：是EasyFlash定义的一个存放环境变量、已下载程序及日志的Flash区域，详细存储架构可以参考`\easyflash\src\easyflash.c`文件头位置的注释说明或本文中的备份区参数配置。 **环境变量表** ：负责存放所有的环境变量，该表在Flash及RAM中均存在，上电后需从Flash加载到RAM中，修改后，则需要保存其至Flash中。。 @@ -32,7 +32,7 @@ void ef_load_env(void) #### 1.2.2 打印环境变量 -通过在移植接口( `\easyflash\port\ef_port.c` )中定义的 `ef_print` 打印方法，来将Flash中的所有环境变量输出出来。 +通过在移植接口(`\easyflash\port\ef_port.c`)中定义的`ef_print`打印方法，来将Flash中的所有环境变量输出出来。 ```C void ef_print_env(void) @@ -212,196 +212,13 @@ EfErrCode ef_log_clean(void); size_t ef_log_get_used_size(void); ``` -## 2 移植接口 +## 2、配置 -### 2.1 移植初始化 +参照EasyFlash 移植说明（port.md）中的 `参数设置` 章节 -EasyFlash移植初始化。可以传递默认环境变量，初始化EasyFlash移植所需的资源等等。 - -```C -EfErrCode ef_port_init(ef_env const **default_env, size_t *default_env_size) -``` - -|参数 |描述| -|:----- |:----| -|default_env |默认的环境变量| -|default_env_size |默认环境变量的数量| - -### 2.2 读取Flash - -最小单位为4个字节 - -```C -EfErrCode ef_port_read(uint32_t addr, uint32_t *buf, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|addr |读取起始地址| -|buf |存放读取数据的缓冲区| -|size |读取数据的大小（字节）| - -### 2.3 擦除Flash - -```C -EfErrCode ef_port_erase(uint32_t addr, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|addr |擦除起始地址| -|size |擦除数据的大小（字节）| - -### 2.4 写入Flash - -最小单位为4个字节 - -```C -EfErrCode ef_port_write(uint32_t addr, const uint32_t *buf, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|addr |写入的起始地址| -|buf |源数据的缓冲区| -|size |写入数据的大小（字节）| - -### 2.5 对环境变量缓冲区加锁 - -```C -void ef_port_env_lock(void) -``` - -### 2.6 对环境变量缓冲区解锁 - -```C -void ef_port_env_unlock(void) -``` - -### 2.7 打印调试日志信息 - -在定义 `PRINT_DEBUG` 宏后，打印调试日志信息 - -```C -void ef_log_debug(const char *file, const long line, const char *format, ...) -``` - -|参数 |描述| -|:----- |:----| -|file |调用该方法的文件| -|line |调用该方法的行号| -|format |打印格式| -|... |不定参| - -### 2.8 打印普通日志信息 - -```C -void ef_log_info(const char *format, ...) -``` - -|参数 |描述| -|:----- |:----| -|format |打印格式| -|... |不定参| - -### 2.9 无格式打印信息 - -该方法输出无固定格式的打印信息，为 `ef_print_env` 方法所用。而 `ef_log_debug` 及 `ef_log_info` 可以输出带指定前缀及格式的打印日志信息。 - -```C -void ef_print(const char *format, ...) -``` - -|参数 |描述| -|:----- |:----| -|format |打印格式| -|... |不定参| - -## 3、配置 - -配置该库需要将`\easyflash\ef_cfg.h`文件拷贝至项目目录，修改项目中的`ef_cfg.h`文件，开启、关闭、修改对应的宏即可。 - -### 3.1 ENV功能 - -- 默认状态：开启 -- 操作方法：开启、关闭`EF_USING_ENV`宏即可 - -#### 3.1.1 磨损平衡/常规 模式 - -磨损平衡：由于flash在写操作之前需要擦除且使用寿命有限，所以需要设计合理的磨损平衡（写平衡）机制，来保证数据被安全的保存在未到擦写寿命的Flash区中。 - -- 默认状态：常规模式 -- 常规模式：关闭`FLASH_ENV_USING_WL_MODE` -- 磨损平衡模式：打开`EF_ENV_USING_WL_MODE` - -#### 3.1.2 掉电保护 - -掉电保护：Power Fail Safeguard，当此项设置为可用时，如果在环境变量保存过程中发生掉电，已保存在Flash中的环境变量将不会有丢失的危险。下次上电后，环境变量将会被自动还原至之前的状态。（注意：本保护是基于软件实现的保护功能，更加可靠的掉电保护功能需要通过硬件来实现） - -- 默认状态：关闭 -- 操作方法：开启、关闭`EF_ENV_USING_PFS_MODE`宏即可 - -### 3.2 IAP功能 - -- 默认状态：开启 -- 操作方法：开启、关闭`EF_USING_IAP`宏即可 - -### 3.3 Log功能 - -- 默认状态：开启 -- 操作方法：开启、关闭`EF_USING_LOG`宏即可 - -### 3.4 Flash最小擦除单位 - -- 操作方法：修改`EF_ERASE_MIN_SIZE`宏对应值即可 - -### 3.5 备份区 - -备份区共计包含3个区域，依次为：环境变量区、日志区及在线升级区。分区方式如下图所示 - -![backup_area_partiton](http://git.oschina.net/Armink/EasyFlash/raw/master/docs/zh/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、擦写平衡+掉电保护模式：系统区将会占用1个`EF_ERASE_MIN_SIZE`大小，数据区将会是擦写平衡模式下的数据区总容量的2倍。 - - 例如：`EF_ERASE_MIN_SIZE`是128K，`ENV_USER_SETTING_SIZE`是2K，那么你可以这样定义不同模式下的环境变量总容量： - - 1、常规模式：`1*EF_ERASE_MIN_SIZE`； - - 2、擦写平衡模式：`3*EF_ERASE_MIN_SIZE`（它将会有2个Flash扇区去存储环境变量，按照每个Flash扇区可被擦写10W次计算，那么当前配置至少可擦写20W次）; - - 3、掉电保护模式：`2*EF_ERASE_MIN_SIZE`; - - 4、擦写平衡+掉电保护模式：`5*EF_ERASE_MIN_SIZE`; - -#### 3.5.1 备份区起始地址 - -- 操作方法：修改`EF_START_ADDR`宏对应值即可 - -#### 3.5.2 用户设定环境变量大小 - -- 操作方法：修改`ENV_USER_SETTING_SIZE`宏对应值即可 - -#### 3.5.3 环境变量区总容量 - -- 操作方法：修改`ENV_AREA_SIZE`宏对应值即可 - -#### 3.5.4 日志区总容量 - -- 操作方法：修改`LOG_AREA_SIZE`宏对应值即可 - -### 3.6 调试日志 - -开启后，将会库运行时自动输出调试日志 - -- 默认状态：开启 -- 操作方法：开启、关闭`PRINT_DEBUG`宏即可 - -## 4、注意 +## 3、注意 - 写数据前务必记得先擦除 -- 环境变量设置完后，只有调用 `ef_save_env`才会保存在Flash中，否则开机会丢失修改的内容 +- 环境变量设置完后，只有调用`ef_save_env`才会保存在Flash中，否则开机会丢失修改的内容 - 不要在应用程序及Bootloader中执行擦除及拷贝自身的动作 - ENV及Log功能对Flash擦除和写入要求4个字节对齐，擦除的最小单位则需根据用户的平台来确定 diff --git a/docs/zh/port.md b/docs/zh/port.md new file mode 100644 index 0000000..a0c78b0 --- /dev/null +++ b/docs/zh/port.md @@ -0,0 +1,261 @@ +# EasyFlash 移植说明 + +--- + +## 1、下载源码 + +[点击此链接](https://github.com/armink/EasyFlash/archive/master.zip)即可直接下载位于Github上的源码。 + +> 建议：点击项目主页 https://github.com/armink/EasyFlash 右上角 **Watch & Star**，这样项目有更新时，会及时以邮件形式通知你。 + +如果Github下载太慢，也可以点击项目位于的国内仓库下载的链接([OSChina](https://git.oschina.net/Armink/EasyFlash/repository/archive?ref=master)|[Coding](https://coding.net/u/armink/p/EasyFlash/git/archive/master))。 + +## 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裸机的Env demo| +|\demo\env\stm32f10x\rtt |stm32f10x基于[RT-Thread](http://www.rt-thread.org/)的Env demo| +|\demo\env\stm32f4xx |stm32f4xx基于[RT-Thread](http://www.rt-thread.org/)的Env demo| +|\demo\iap\ymodem+rtt.c |使用[RT-Thread](http://www.rt-thread.org/)+[Ymodem](https://github.com/RT-Thread/rt-thread/tree/master/components/utilities/ymodem)的IAP Demo| +|\demo\log\easylogger.c |基于[EasyLogger](https://github.com/armink/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移植所需的资源等等。 + +```C +EfErrCode ef_port_init(ef_env const **default_env, size_t *default_env_size) +``` + +|参数 |描述| +|:----- |:----| +|default_env |默认的环境变量| +|default_env_size |默认环境变量的数量| + +### 4.2 读取Flash + +最小单位为4个字节 + +```C +EfErrCode ef_port_read(uint32_t addr, uint32_t *buf, size_t size) +``` + +|参数 |描述| +|:----- |:----| +|addr |读取起始地址| +|buf |存放读取数据的缓冲区| +|size |读取数据的大小（字节）| + +### 4.3 擦除Flash + +```C +EfErrCode ef_port_erase(uint32_t addr, size_t size) +``` + +|参数 |描述| +|:----- |:----| +|addr |擦除起始地址| +|size |擦除数据的大小（字节）| + +### 4.4 写入Flash + +最小单位为4个字节 + +```C +EfErrCode ef_port_write(uint32_t addr, const uint32_t *buf, size_t size) +``` + +|参数 |描述| +|:----- |:----| +|addr |写入的起始地址| +|buf |源数据的缓冲区| +|size |写入数据的大小（字节）| + +### 4.5 对环境变量缓冲区加锁 + +为了保证RAM缓冲区在并发执行的安全性，所以需要对其进行加锁（如果项目的使用场景不存在并发情况，则可以忽略）。有操作系统是可以使用获取信号量来加锁，裸机时可以通过关闭全局中断来加锁 + +```C +void ef_port_env_lock(void) +``` + +### 4.6 对环境变量缓冲区解锁 + +有操作系统是可以使用释放信号量来解锁，裸机时可以通过开启全局中断来解锁 + +```C +void ef_port_env_unlock(void) +``` + +### 4.7 打印调试日志信息 + +在定义`PRINT_DEBUG`宏后，打印调试日志信息 + +```C +void ef_log_debug(const char *file, const long line, const char *format, ...) +``` + +|参数 |描述| +|:----- |:----| +|file |调用该方法的文件| +|line |调用该方法的行号| +|format |打印格式| +|... |不定参| + +### 4.8 打印普通日志信息 + +```C +void ef_log_info(const char *format, ...) +``` + +|参数 |描述| +|:----- |:----| +|format |打印格式| +|... |不定参| + +### 4.9 无格式打印信息 + +该方法输出无固定格式的打印信息，为`ef_print_env`方法所用（如果不使用`ef_print_env`则可以忽略）。而`ef_log_debug`及`ef_log_info`可以输出带指定前缀及格式的打印日志信息。 + +```C +void ef_print(const char *format, ...) +``` + +|参数 |描述| +|:----- |:----| +|format |打印格式| +|... |不定参| + +## 5、设置参数 + +配置时需要修改项目中的`ef_cfg.h`文件，开启、关闭、修改对应的宏即可。 + +### 5.1 环境变量功能 + +- 默认状态：开启 +- 操作方法：开启、关闭`EF_USING_ENV`宏即可 + +#### 5.1.1 磨损平衡/常规 模式 + +磨损平衡：由于flash在写操作之前需要擦除且使用寿命有限，所以需要设计合理的磨损平衡（写平衡）机制，来保证数据被安全的保存在未到擦写寿命的Flash区中。 + +- 默认状态：常规模式 +- 常规模式：关闭`FLASH_ENV_USING_WL_MODE` +- 磨损平衡模式：打开`EF_ENV_USING_WL_MODE` + +#### 5.1.2 掉电保护 + +掉电保护：Power Fail Safeguard，当此项设置为可用时，如果在环境变量保存过程中发生掉电，已保存在Flash中的环境变量将不会有丢失的危险。下次上电后，环境变量将会被自动还原至之前的状态。（注意：本保护是基于软件实现的保护功能，更加可靠的掉电保护功能需要通过硬件来实现） + +- 默认状态：关闭 +- 操作方法：开启、关闭`EF_ENV_USING_PFS_MODE`宏即可 + +### 5.2 在线升级功能 + +- 默认状态：开启 +- 操作方法：开启、关闭`EF_USING_IAP`宏即可 + +### 5.3 日志功能 + +- 默认状态：开启 +- 操作方法：开启、关闭`EF_USING_LOG`宏即可 + +### 5.4 Flash最小擦除单位 + +- 操作方法：修改`EF_ERASE_MIN_SIZE`宏对应值即可 + +### 5.5 备份区 + +备份区共计包含3个区域，依次为：环境变量区、日志区及在线升级区。分区方式如下图所示 + +![backup_area_partiton](http://git.oschina.net/Armink/EasyFlash/raw/master/docs/zh/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、擦写平衡+掉电保护模式：系统区将会占用1个`EF_ERASE_MIN_SIZE`大小，数据区将会是擦写平衡模式下的数据区总容量的2倍。 + - 例如：`EF_ERASE_MIN_SIZE`是128K，`ENV_USER_SETTING_SIZE`是2K，那么你可以这样定义不同模式下的环境变量总容量： + - 1、常规模式：`1*EF_ERASE_MIN_SIZE`； + - 2、擦写平衡模式：`3*EF_ERASE_MIN_SIZE`（它将会有2个Flash扇区去存储环境变量，按照每个Flash扇区可被擦写10W次计算，那么当前配置至少可擦写20W次）; + - 3、掉电保护模式：`2*EF_ERASE_MIN_SIZE`; + - 4、擦写平衡+掉电保护模式：`5*EF_ERASE_MIN_SIZE`; + +#### 5.5.1 备份区起始地址 + +- 操作方法：修改`EF_START_ADDR`宏对应值即可 + +#### 5.5.2 用户设定环境变量大小 + +- 操作方法：修改`ENV_USER_SETTING_SIZE`宏对应值即可 + +> 注意：不使用环境变量功能时，可以不定义此宏。 + +#### 5.5.3 环境变量区总容量 + +- 操作方法：修改`ENV_AREA_SIZE`宏对应值即可 + +> 注意：不使用环境变量功能时，可以不定义此宏。 + +#### 5.5.4 日志区总容量 + +- 操作方法：修改`LOG_AREA_SIZE`宏对应值即可 + +> 注意：不使用日志功能时，可以不定义此宏。 + +### 5.6 调试日志 + +开启后，将会库运行时自动输出调试日志 + +- 默认状态：开启 +- 操作方法：开启、关闭`PRINT_DEBUG`宏即可 + +## 6、测试验证 + +如果`\demo`文件夹下有与项目Flash规格一致的Demo，则直接编译运行，观察测试结果即可。无需关注下面的步骤。 + +每次使用前，务必先执行`easyflash_init`方法对EasyFlash库及所使用的Flash进行初始化，保证初始化没问题后，再使用各功能的API方法。如果出现错误或断言，需根据提示信息检查移植配置及接口。 + +### 6.1 环境变量 + +查看`\demo\env`文件夹中例子的`readme.md`说明文档。测试时可以将`\demo\env\stm32f10x\non_os\app\src\app.c`中的`static void test_env(void)`复制到项目中，然后运行测试。 + +### 6.2 在线升级 + +查看`\demo\iap`文件夹中的`readme.md`说明文档。 + +### 6.3 日志 + +查看`\demo\log`文件夹中的`readme.md`说明文档。 + +> 注意：`easylogger.c`是使用[EasyLogger](https://github.com/armink/EasyLogger)与EasyFlash的无缝接口的例子，EasyLogger提供针对日志的很多常用功能封装，详细功能可以查看其介绍。使用这个例子时，务必记得将EasyLogger一并导入到项目中。 \ No newline at end of file diff --git a/docs/zh/readme.md b/docs/zh/readme.md index d01eeaf..167b423 100644 --- a/docs/zh/readme.md +++ b/docs/zh/readme.md @@ -1,3 +1,4 @@ |文件名 |描述| |:----- |:----| -|api.md |API 说明| \ No newline at end of file +|api.md |API 说明| +|port.md |移植说明| \ No newline at end of file