From b4a63b0dbb3b7974c80b478e624b9135efdb762d Mon Sep 17 00:00:00 2001 From: armink Date: Mon, 2 Mar 2015 16:01:40 +0800 Subject: [PATCH] =?UTF-8?q?1=E3=80=81=E3=80=90=E4=BF=AE=E6=94=B9=E3=80=91?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=E6=96=87=E6=A1=A3=E6=96=87=E4=BB=B6=E7=BC=96?= =?UTF-8?q?=E7=A0=81=E3=80=82?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: armink --- README.md | 64 ++++++------ docs/readme.md | 2 +- docs/zh/api.md | 242 +++++++++++++++++++++++----------------------- docs/zh/readme.md | 4 +- 4 files changed, 156 insertions(+), 156 deletions(-) diff --git a/README.md b/README.md index 9694a58..995d8cf 100644 --- a/README.md +++ b/README.md @@ -1,63 +1,63 @@ -# EasyFlash ʹ˵ +# EasyFlash 使用说明 --- -## 1 +## 1、介绍 -EasyFlashһԴǶʽFlash洢⣬ҪΪMCU(Micro Control Unit)ṩݡͨõϲӦýӿڣʹÿ߸ӸЧʵֻڵFlash洢ӦÿÿĿǰṩ **ʵù** +EasyFlash是一款开源的轻量级嵌入式Flash存储器库，主要为MCU(Micro Control Unit)提供便捷、通用的上层应用接口，使得开发者更加高效实现基于的Flash存储器常见应用开发。该库目前提供 **两大实用功能** ： - - **Env** ñʵֵ籣棬֧֡**дƽ**ģʽ赣ıȡĥƽ + - **Env** 让变量轻松实现掉电保存，支持“**写平衡**”模式，无需担心变量长度、磨损平衡等问题 - ʹ **ֵ(key-value)** ʽ洢FlashУU-Boot `` ʹ÷ʽU-Bootһ¡ - - **IAP** Ҳ¶ + 使用 **键值对(key-value)** 方式将变量存储到Flash中，类似U-Boot的 `环境变量` ，使用方式与U-Boot一致。 + - **IAP** 在线升级再也不是难事儿 - ÿװIAP(In-Application Programming)ܳõĽӿڣ֧CRC32У飬ͬʱ֧BootloaderApplication + 该库封装了IAP(In-Application Programming)功能常用的接口，支持CRC32校验，同时支持Bootloader及Application的升级。 -### 1.1ļṹ +### 1.1、文件结构 -|Դļ | | +|源文件 |描述 | |:------------------------------ |:----- | -|\flash\src\flash_env.c |EnvģʽزӿڼʵԴ| -|\flash\src\flash_env_wl.c |EnvĥƽģʽزӿڼʵԴ| -|\flash\src\flash_iap.c |IAP زӿڼʵԴ| -|\flash\src\flash_utils.c |EasyFlashСߣ磺CRC32| -|\flash\src\flash.c |ĿǰֻEasyFlashʼ| -|\flash\port\flash_port.c |ͬƽ̨µEasyFlashֲӿڼò| -|\demo\stm32f10x |stm32f10xƽ̨µdemo| +|\flash\src\flash_env.c |Env（常规模式）相关操作接口及实现源码| +|\flash\src\flash_env_wl.c |Env（磨损平衡模式）相关操作接口及实现源码| +|\flash\src\flash_iap.c |IAP 相关操作接口及实现源码| +|\flash\src\flash_utils.c |EasyFlash常用小工具，例如：CRC32| +|\flash\src\flash.c |目前只包含EasyFlash初始化方法| +|\flash\port\flash_port.c |不同平台下的EasyFlash移植接口及配置参数| +|\demo\stm32f10x |stm32f10x平台下的demo| -### 1.2Դռ +### 1.2、资源占用 ``` -Ҫ ROM: 6K bytes RAM: 0.5K bytes + (EnvС) +最低要求： ROM: 6K bytes RAM: 0.5K bytes + (Env大小) -Demoƽ̨STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes) -ʵռã ROM: 6K bytes RAM: 2.6K bytes +Demo平台：STM32F103RET6 + RT-Thread 1.2.2 + Env(2K bytes) +实际占用： ROM: 6K bytes RAM: 2.6K bytes ``` -### 1.3֧ƽ̨ +### 1.3、支持平台 -Ŀǰֲƽֻ̨ `STM32F10X` ϵеƬFlashҲDZ߲Ʒʹõƽ̨ƽֲ̨ѶȲĿ֮пƽ̨⣨64λ⣩ԶֲӿڶԤֲֻ޸ `\flash\port\flash_port.c` һļʵIJдӡܼɡ +目前已移植平台只有 `STM32F10X` 系列的片内Flash，这个也是笔者产品使用的平台。其余平台的移植难度不大，在项目的设计之初就有考虑针对所有平台的适配性问题（64位除外），所以对所有移植接口都有做预留。移植只需修改 `\flash\port\flash_port.c` 一个文件，实现里面的擦、写、读及打印功能即可。 -ӭ **fork and pull request**([Github](https://github.com/armink/EasyFlash)|[OSChina](http://git.oschina.net/armink/EasyFlash)|[Coding](https://coding.net/u/armink/p/EasyFlash/git)) Դijɹ벻˵ŬҲϣĿܹҽͿڣòƷĻóɹ +欢迎大家 **fork and pull request**([Github](https://github.com/armink/EasyFlash)|[OSChina](http://git.oschina.net/armink/EasyFlash)|[Coding](https://coding.net/u/armink/p/EasyFlash/git)) 。开源软件的成功离不开所有人的努力，也希望该项目能够帮助大家降低开发周期，让产品更早的获得成功。 -## 2 +## 2、流程 -### 2.1 +### 2.1、环境变量 -ͼΪ˹̨ͨûijýӿڣʾ˻ `"temp"` Ӵ棬޸ģɾĹ̡Щӿڶֱ֧Ӧòֱӵá +下图为人工通过控制台来调用环境变量的常用接口，演示了环境变量 `"temp"` 从创建到保存，再修改，最后删除的过程。这些接口都支持被应用层直接调用。 ![easy_flash_env](https://cloud.githubusercontent.com/assets/1734686/5886463/46ad7efa-a3db-11e4-8401-75c00a4c35ba.gif) -### 2.2 +### 2.2、在线升级 -ͼʾ̨ͨIAPḶ́ʹõǿԴIAPܽӿڣʾõǴ+YmodemЭķʽ㻹ҲʵͨCAN485̫ߣʵԶ¡ +下图演示了通过控制台来进行IAP升级软件的过程，使用的是库中自带的IAP功能接口，演示采用的是串口+Ymodem协议的方式。你还也可以实现通过CAN、485、以太网等总线，来实现远程网络更新。 ![easy_flash_iap](https://cloud.githubusercontent.com/assets/1734686/5886462/40f7d62c-a3db-11e4-866a-ba827c809370.gif) -## 3ĵ -ݲο`\docs\`µļ +## 3、文档 +具体内容参考`\docs\`下的文件。 -## 4Ȩ - GPL ԴЭ飬ϸĶĿе LICENSE ļݡ +## 4、版权 +采用 GPL 开源协议，细节请阅读项目中的 LICENSE 文件内容。 diff --git a/docs/readme.md b/docs/readme.md index 696a56f..da9229a 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,4 +1,4 @@ |File or folder name |Description| |:----- |:----| |en |English documents| -|zh |ĵ壩| \ No newline at end of file +|zh |中文文档（简体）| \ No newline at end of file diff --git a/docs/zh/api.md b/docs/zh/api.md index a627def..299b96f 100644 --- a/docs/zh/api.md +++ b/docs/zh/api.md @@ -1,139 +1,139 @@ -# EasyFlash API ˵ +# EasyFlash API 说明 --- -ֵ֧APIӿڶ `\flash\inc\flash.h` ݽ϶࣬ʹ **CTRL+F** +所有支持的API接口都在 `\flash\inc\flash.h` 中声明。以下内容较多，建议使用 **CTRL+F** 搜索。 -ʽܣ +名词介绍： -**** EasyFlashһŻسFlashϸ洢ܹԲο `\flash\src\flash.c` ļͷλõע˵ +**备份区** ：是EasyFlash定义的一个存放环境变量及已下载程序的Flash区域，详细存储架构可以参考 `\flash\src\flash.c` 文件头位置的注释说明。 -**** еĻñFlashRAMоڣϵFlashصRAMУ޸ĺҪFlashС +**环境变量表** ：负责存放所有的环境变量，该表在Flash及RAM中均存在，上电后需从Flash加载到RAM中，修改后，则需要保存其至Flash中。。 -## 1ûʹýӿ +## 1、用户使用接口 -### 1.1 ʼ +### 1.1 初始化 -ʼEasyFlashڳʼĹлʹ `\flash\port\flash_port.c` еûԶ +初始化EasyFlash。在初始化的过程中会使用 `\flash\port\flash_port.c` 中的用户自定义参数。 ```C FlashErrCode flash_init(void) ``` -### 1.2 +### 1.2 环境变量 -#### 1.2.1 ػ +#### 1.2.1 加载环境变量 -FlashелϵͳڴС +加载Flash中的所有环境变量到系统内存中。 ```C void flash_load_env(void) ``` -#### 1.2.2 ӡ +#### 1.2.2 打印环境变量 -ֲͨӿ( `\flash\port\flash_port.c` )ж `flash_print` ӡFlashел +通过在移植接口( `\flash\port\flash_port.c` )中定义的 `flash_print` 打印方法，来将Flash中的所有环境变量输出出来。 ```C void flash_print_env(void) ``` -#### 1.2.3 ȡ +#### 1.2.3 获取环境变量 -ͨȡӦֵע⣺˴ĻָѼصڴеĻ +通过环境变量的名字来获取其对应的值。（注意：此处的环境变量指代的已加载到内存中的环境变量） ```C char *flash_get_env(const char *key) ``` -| || +|参数 |描述| |:----- |:----| -|key || +|key |环境变量名称| -#### 1.2.4 û +#### 1.2.4 设置环境变量 -ʹô˷ʵֶԻӡ޸ļɾܡע⣺˴ĻָѼصڴеĻ +使用此方法可以实现对环境变量的增加、修改及删除功能。（注意：此处的环境变量指代的已加载到内存中的环境变量） -**** вڸƵĻʱִ +**增加** ：当环境变量表中不存在该名称的环境变量时，则会执行新增操作； -**޸** еĻڵǰдڣѸûֵ޸Ϊеֵ +**修改** ：入参中的环境变量名称在当前环境变量表中存在，则把该环境变量值修改为入参中的值； -**ɾ** еvalueΪʱɾӦĻ +**删除** ：当入参中的value为空时，则会删除入参名对应的环境变量。 ```C FlashErrCode flash_set_env(const char *key, const char *value) ``` -| || +|参数 |描述| |:----- |:----| -|key || -|value |ֵ| +|key |环境变量名称| +|value |环境变量值| -#### 1.2.5 滷 +#### 1.2.5 保存环境变量 -ڴеĻFlashС +保存内存中的环境变量表到Flash中。 ```C FlashErrCode flash_save_env(void) ``` -#### 1.2.6 ָ -ڴеĻָΪĬֵ +#### 1.2.6 恢复环境变量 +将内存中的环境变量表恢复为默认值。 ```C FlashErrCode flash_env_set_default(void) ``` -#### 1.2.7 ȡ +#### 1.2.7 获取环境变量分区的总容量 ```C uint32_t flash_get_env_total_size(void) ``` -#### 1.2.8 ȡǰʹûĴС +#### 1.2.8 获取当前已使用环境变量的大小 ```C uint32_t flash_get_env_used_size(void) ``` -### 1.3 +### 1.3 在线升级 -#### 1.3.1 еӦó +#### 1.3.1 擦除备份区中的应用程序 ```C FlashErrCode flash_erase_bak_app(size_t app_size) ``` -#### 1.3.2 ûӦó +#### 1.3.2 擦除用户的应用程序 -ע⣺벻ҪӦóеø÷ +注意：请不要在应用程序中调用该方法 ```C FlashErrCode flash_erase_user_app(uint32_t user_app_addr, size_t user_app_size) ``` -| || +|参数 |描述| |:----- |:----| -|user_app_addr |ûӦóڵַ| -|user_app_size |ûӦóС| +|user_app_addr |用户应用程序入口地址| +|user_app_size |用户应用程序大小| -#### 1.3.3 Bootloader +#### 1.3.3 擦除Bootloader -ע⣺벻ҪBootloaderеø÷ +注意：请不要在Bootloader中调用该方法 ```C FlashErrCode flash_erase_bl(uint32_t bl_addr, size_t bl_size) ``` -| || +|参数 |描述| |:----- |:----| -|bl_addr |Bootloaderڵַ| -|bl_size |BootloaderС| +|bl_addr |Bootloader入口地址| +|bl_size |Bootloader大小| -#### 1.3.4 дݵ +#### 1.3.4 写数据到备份区 -Ϊس򵽱ƵFlashд -ע⣺д֮ǰȷFlashѽв +为下载程序到备份区定制的Flash连续写方法。 +注意：写之前请先确认Flash已进行擦除。 ```C FlashErrCode flash_write_data_to_bak(uint8_t *data, @@ -142,166 +142,166 @@ FlashErrCode flash_write_data_to_bak(uint8_t *data, size_t total_size) ``` -| || +|参数 |描述| |:----- |:----| -|data |Ҫд뵽еݴ洢ַ| -|size |˴дݵĴСֽڣ| -|cur_size |֮ǰд뵽еݴСֽڣ| -|total_size |Ҫд뵽ܴСֽڣ| +|data |需要写入到备份区中的数据存储地址| +|size |此次写入数据的大小（字节）| +|cur_size |之前已写入到备份区中的数据大小（字节）| +|total_size |需要写入到备份区的数据总大小（字节）| -#### 1.3.5 ӱݿӦó +#### 1.3.5 从备份拷贝应用程序 -غõӦó򿽱ûӦóʼַ -ע⣺ -1ǰԭеӦóв -2ҪӦóеø÷ +将备份区已下载好的应用程序拷贝至用户应用程序起始地址。 +注意： +1、拷贝前必须对原有的应用程序进行擦除 +2、不要在应用程序中调用该方法 ```C FlashErrCode flash_copy_app_from_bak(uint32_t user_app_addr, size_t app_size) ``` -| || +|参数 |描述| |:----- |:----| -|user_app_addr |ûӦóڵַ| -|user_app_size |ûӦóС| +|user_app_addr |用户应用程序入口地址| +|user_app_size |用户应用程序大小| -#### 1.3.5 ӱݿBootloader +#### 1.3.5 从备份拷贝Bootloader -غõBootloaderBootloaderʼַ -ע⣺ -1ǰԭеBootloaderв -2ҪBootloaderеø÷ +将备份区已下载好的Bootloader拷贝至Bootloader起始地址。 +注意： +1、拷贝前必须对原有的Bootloader进行擦除 +2、不要在Bootloader中调用该方法 ```C FlashErrCode flash_copy_bl_from_bak(uint32_t bl_addr, size_t bl_size) ``` -| || +|参数 |描述| |:----- |:----| -|bl_addr |Bootloaderڵַ| -|bl_size |BootloaderС| +|bl_addr |Bootloader入口地址| +|bl_size |Bootloader大小| -## 2 ֲӿ +## 2 移植接口 -### 2.1 ȡFlash +### 2.1 读取Flash -СλΪ4ֽ +最小单位为4个字节 ```C FlashErrCode flash_read(uint32_t addr, uint32_t *buf, size_t size) ``` -| || +|参数 |描述| |:----- |:----| -|addr |ȡʼַ| -|buf |ŶȡݵĻ| -|size |ȡݵĴСֽڣ| +|addr |读取起始地址| +|buf |存放读取数据的缓冲区| +|size |读取数据的大小（字节）| -### 2.2 Flash +### 2.2 擦除Flash ```C FlashErrCode flash_erase(uint32_t addr, size_t size) ``` -| || +|参数 |描述| |:----- |:----| -|addr |ʼַ| -|size |ݵĴСֽڣ| +|addr |擦除起始地址| +|size |擦除数据的大小（字节）| -### 2.3 дFlash +### 2.3 写入Flash -СλΪ4ֽ +最小单位为4个字节 ```C FlashErrCode flash_write(uint32_t addr, const uint32_t *buf, size_t size) ``` -| || +|参数 |描述| |:----- |:----| -|addr |дʼַ| -|buf |ԴݵĻ| -|size |дݵĴСֽڣ| +|addr |写入的起始地址| +|buf |源数据的缓冲区| +|size |写入数据的大小（字节）| -### 2.4 䶯̬ڴ +### 2.4 分配动态内存 ```C void *flash_malloc(size_t size) ``` -| || +|参数 |描述| |:----- |:----| -|size |ڴС| +|size |需分配的内存大小| -### 2.5 ͷŶ̬ڴ +### 2.5 释放动态内存 ```C void flash_free(void *p) ``` -| || +|参数 |描述| |:----- |:----| -|p |ͷŵĶ̬ڴַ| +|p |需释放的动态内存地址| -### 2.6 ӡ־Ϣ +### 2.6 打印调试日志信息 -ڶ `FLASH_PRINT_DEBUG` 󣬴ӡ־Ϣ +在定义 `FLASH_PRINT_DEBUG` 宏后，打印调试日志信息 ```C void flash_log_debug(const char *file, const long line, const char *format, ...) ``` -| || +|参数 |描述| |:----- |:----| -|file |ø÷ļ| -|line |ø÷к| -|format |ӡʽ| -|... || +|file |调用该方法的文件| +|line |调用该方法的行号| +|format |打印格式| +|... |不定参| -### 2.7 ӡͨ־Ϣ +### 2.7 打印普通日志信息 ```C void flash_log_info(const char *format, ...) ``` -| || +|参数 |描述| |:----- |:----| -|format |ӡʽ| -|... || +|format |打印格式| +|... |不定参| -### 2.8 ޸ʽӡϢ +### 2.8 无格式打印信息 -÷޹̶ʽĴӡϢΪ `flash_print_env` á `flash_log_debug` `flash_log_info` ָǰ׺ʽĴӡ־Ϣ +该方法输出无固定格式的打印信息，为 `flash_print_env` 方法所用。而 `flash_log_debug` 及 `flash_log_info` 可以输出带指定前缀及格式的打印日志信息。 ```C void flash_print(const char *format, ...) ``` -| || +|参数 |描述| |:----- |:----| -|format |ӡʽ| -|... || +|format |打印格式| +|... |不定参| -## 3 +## 3、配置 -øÿҪ`\flash\flash.h`ļرնӦĺ꼴ɡ +配置该库需要打开`\flash\flash.h`文件，开启、关闭对应的宏即可。 -### 3.1 CRC32У +### 3.1 CRC32校验 -- Ĭ״̬ -- ر`FLASH_ENV_USING_CRC_CHECK`꼴 +- 默认状态：开启 +- 操作方法：开启、关闭`FLASH_ENV_USING_CRC_CHECK`宏即可 -### 3.2 ĥƽ/ ģʽ +### 3.2 磨损平衡/常规 模式 -- Ĭ״̬ģʽ -- ĥƽģʽ`FLASH_ENV_USING_WEAR_LEVELING_MODE`ر`FLASH_ENV_USING_NORMAL_MODE` -- ģʽ`FLASH_ENV_USING_NORMAL_MODE`ر`FLASH_ENV_USING_WEAR_LEVELING_MODE` -- ע⣺ֻѡһģʽģʽͬʱʹ +- 默认状态：常规模式 +- 磨损平衡模式：打开`FLASH_ENV_USING_WEAR_LEVELING_MODE`，关闭`FLASH_ENV_USING_NORMAL_MODE` +- 常规模式：打开`FLASH_ENV_USING_NORMAL_MODE`，关闭`FLASH_ENV_USING_WEAR_LEVELING_MODE` +- 注意：只能选择其中一种模式，两种模式不能同时使用 -## 4ע +## 4、注意 -- дǰؼǵȲ -- ֻе `flash_save_env`ŻᱣFlashУ򿪻ᶪʧ޸ĵ -- ҪӦóBootloaderִвĶ -- Flashȡд뷽СλΪ4ֽڣСλûƽ̨ȷ +- 写数据前务必记得先擦除 +- 环境变量设置完后，只有调用 `flash_save_env`才会保存在Flash中，否则开机会丢失修改的内容 +- 不要在应用程序及Bootloader中执行擦除及拷贝自身的动作 +- Flash读取和写入方法的最小单位为4个字节，擦除的最小单位则需根据用户的平台来确定 diff --git a/docs/zh/readme.md b/docs/zh/readme.md index 24aec5a..d01eeaf 100644 --- a/docs/zh/readme.md +++ b/docs/zh/readme.md @@ -1,3 +1,3 @@ -|ļ || +|文件名 |描述| |:----- |:----| -|api.md |API ˵| \ No newline at end of file +|api.md |API 说明| \ No newline at end of file