Merge pull request #24 from outely/master

【增加】添加删除环境变量接口
【更新】修改ef_set_env()可存储空字符串

docs/zh/api.md

@@ -55,10 +55,9 @@ char *ef_get_env(const char *key)
 使用此方法可以实现对环境变量的增加、修改及删除功能。（注意：此处的环境变量指代的已加载到内存中的环境变量）
 
 - **增加** ：当环境变量表中不存在该名称的环境变量时，则会执行新增操作；
-
 - **修改** ：入参中的环境变量名称在当前环境变量表中存在，则把该环境变量值修改为入参中的值；
+- **删除**：当入参中的value为NULL时，则会删除入参名对应的环境变量。 
 
-- **删除** ：当入参中的value为空时，则会删除入参名对应的环境变量。
 
 ```C
 EfErrCode ef_set_env(const char *key, const char *value)
@@ -69,7 +68,19 @@ EfErrCode ef_set_env(const char *key, const char *value)
 |key                                     |环境变量名称|
 |value                                   |环境变量值|
 
-#### 1.2.5 保存环境变量
+#### 1.2.5 删除环境变量
+
+使用此方法可以实现对环境变量的删除功能。（注意：此处的环境变量指代的已加载到内存中的环境变量）
+
+```c
+EfErrCode ef_del_env(const char *key)
+```
+
+| 参数 | 描述         |
+| :--- | :----------- |
+| key  | 环境变量名称 |
+
+#### 1.2.6 保存环境变量
 
 保存内存中的环境变量表到Flash中。
 
@@ -77,20 +88,20 @@ EfErrCode ef_set_env(const char *key, const char *value)
 EfErrCode ef_save_env(void)
 ```
 
-#### 1.2.6 重置环境变量
+#### 1.2.7 重置环境变量
 将内存中的环境变量表重置为默认值。
 
 ```C
 EfErrCode ef_env_set_default(void)
 ```
 
-#### 1.2.7 获取当前环境变量写入到Flash的字节大小
+#### 1.2.8 获取当前环境变量写入到Flash的字节大小
 
 ```C
 size_t ef_get_env_write_bytes(void)
 ```
 
-#### 1.2.8 设置并保存环境变量
+#### 1.2.9 设置并保存环境变量
 
 设置环境变量成功后立刻保存。设置功能参考`ef_set_env`方法。
 
@@ -103,6 +114,18 @@ 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)
+```
+
+| 参数 | 描述         |
+| :--- | :----------- |
+| key  | 环境变量名称 |
+
 ### 1.3 在线升级
 
 #### 1.3.1 擦除备份区中的应用程序

easyflash/inc/easyflash.h

@@ -40,19 +40,19 @@ extern "C" {
 #endif
 
 #if defined(EF_USING_ENV) && (!defined(ENV_USER_SETTING_SIZE) || !defined(ENV_AREA_SIZE))
-    #error "Please configure user setting ENV size or ENV area size (in ef_cfg.h)"
+#error "Please configure user setting ENV size or ENV area size (in ef_cfg.h)"
 #endif
 
 #if defined(EF_USING_LOG) && !defined(LOG_AREA_SIZE)
-    #error "Please configure log area size (in ef_cfg.h)"
+#error "Please configure log area size (in ef_cfg.h)"
 #endif
 
 #if !defined(EF_START_ADDR)
-    #error "Please configure backup area start address (in ef_cfg.h)"
+#error "Please configure backup area start address (in ef_cfg.h)"
 #endif
 
 #if !defined(EF_ERASE_MIN_SIZE)
-    #error "Please configure minimum size of flash erasure (in ef_cfg.h)"
+#error "Please configure minimum size of flash erasure (in ef_cfg.h)"
 #endif
 
 /* EasyFlash debug print function. Must be implement by user. */
@@ -78,10 +78,10 @@ if (!(EXPR))                                                                  \
 /* EasyFlash software version number */
 #define EF_SW_VERSION                  "3.1.0"
 
-typedef struct _ef_env{
+typedef struct _ef_env {
     char *key;
     char *value;
-}ef_env, *ef_env_t;
+} ef_env, *ef_env_t;
 
 /* EasyFlash error code */
 typedef enum {
@@ -100,7 +100,7 @@ typedef enum {
     EF_SECTOR_EMPTY,
     EF_SECTOR_USING,
     EF_SECTOR_FULL,
-}EfSecrorStatus;
+} EfSecrorStatus;
 
 /* easyflash.c */
 EfErrCode easyflash_init(void);
@@ -111,10 +111,12 @@ EfErrCode ef_load_env(void);
 void ef_print_env(void);
 char *ef_get_env(const char *key);
 EfErrCode ef_set_env(const char *key, const char *value);
+EfErrCode ef_del_env(const char *key);
 EfErrCode ef_save_env(void);
 EfErrCode ef_env_set_default(void);
 size_t ef_get_env_write_bytes(void);
 EfErrCode ef_set_and_save_env(const char *key, const char *value);
+EfErrCode ef_del_and_save_env(const char *key);
 #endif
 
 #ifdef EF_USING_IAP
@@ -122,13 +124,13 @@ EfErrCode ef_set_and_save_env(const char *key, const char *value);
 EfErrCode ef_erase_bak_app(size_t app_size);
 EfErrCode ef_erase_user_app(uint32_t user_app_addr, size_t user_app_size);
 EfErrCode ef_erase_spec_user_app(uint32_t user_app_addr, size_t app_size,
-        EfErrCode (*app_erase)(uint32_t addr, size_t size));
+                                 EfErrCode (*app_erase)(uint32_t addr, size_t size));
 EfErrCode ef_erase_bl(uint32_t bl_addr, size_t bl_size);
 EfErrCode ef_write_data_to_bak(uint8_t *data, size_t size, size_t *cur_size,
-        size_t total_size);
+                               size_t total_size);
 EfErrCode ef_copy_app_from_bak(uint32_t user_app_addr, size_t app_size);
 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));
+                                    EfErrCode (*app_write)(uint32_t addr, const uint32_t *buf, size_t size));
 EfErrCode ef_copy_bl_from_bak(uint32_t bl_addr, size_t bl_size);
 uint32_t ef_get_bak_app_start_addr(void);
 #endif

easyflash/src/ef_env.c

@@ -130,16 +130,16 @@ EfErrCode ef_env_init(ef_env const *default_env, size_t default_env_size) {
     if (ENV_USER_SETTING_SIZE % EF_ERASE_MIN_SIZE == 0) {
         EF_ASSERT(ENV_USER_SETTING_SIZE == ENV_AREA_SIZE);
     } else {
-        EF_ASSERT((ENV_USER_SETTING_SIZE/EF_ERASE_MIN_SIZE + 1)*EF_ERASE_MIN_SIZE == ENV_AREA_SIZE);
+        EF_ASSERT((ENV_USER_SETTING_SIZE / EF_ERASE_MIN_SIZE + 1)*EF_ERASE_MIN_SIZE == ENV_AREA_SIZE);
     }
 #else
     /* total_size must be aligned with erase_min_size */
     if (ENV_USER_SETTING_SIZE % EF_ERASE_MIN_SIZE == 0) {
         /* it has double area when used power fail safeguard mode */
-        EF_ASSERT(2*ENV_USER_SETTING_SIZE == ENV_AREA_SIZE);
+        EF_ASSERT(2 * ENV_USER_SETTING_SIZE == ENV_AREA_SIZE);
     } else {
         /* it has double area when used power fail safeguard mode */
-        EF_ASSERT(2*(ENV_USER_SETTING_SIZE/EF_ERASE_MIN_SIZE + 1)*EF_ERASE_MIN_SIZE == ENV_AREA_SIZE);
+        EF_ASSERT(2 * (ENV_USER_SETTING_SIZE / EF_ERASE_MIN_SIZE + 1)*EF_ERASE_MIN_SIZE == ENV_AREA_SIZE);
     }
 #endif
 
@@ -170,7 +170,7 @@ EfErrCode ef_env_init(ef_env const *default_env, size_t default_env_size) {
  *
  * @return result
  */
-EfErrCode ef_env_set_default(void){
+EfErrCode ef_env_set_default(void) {
     extern EfErrCode ef_env_ver_num_set_default(void);
 
     EfErrCode result = EF_NO_ERR;
@@ -433,7 +433,7 @@ static EfErrCode create_env(const char *key, const char *value) {
  *
  * @return result
  */
-static EfErrCode del_env(const char *key){
+static EfErrCode del_env(const char *key) {
     EfErrCode result = EF_NO_ERR;
     char *del_env = NULL;
     size_t del_env_length, remain_env_length;
@@ -466,7 +466,7 @@ static EfErrCode del_env(const char *key){
     }
     /* calculate remain ENV length */
     remain_env_length = get_env_data_size()
-            - (((uint32_t) del_env + del_env_length) - ((uint32_t) env_cache + ENV_PARAM_BYTE_SIZE));
+                        - (((uint32_t) del_env + del_env_length) - ((uint32_t) env_cache + ENV_PARAM_BYTE_SIZE));
     /* remain ENV move forward */
     memcpy(del_env, del_env + del_env_length, remain_env_length);
     /* reset ENV end address */
@@ -478,7 +478,7 @@ static EfErrCode del_env(const char *key){
 }
 
 /**
- * Set an ENV. If it value is empty, delete it.
+ * Set an ENV.If it value is NULL, delete it.
  * If not find it in ENV table, then create it.
  *
  * @param key ENV name
@@ -490,7 +490,7 @@ EfErrCode ef_set_env(const char *key, const char *value) {
     EfErrCode result = EF_NO_ERR;
     char *old_env, *old_value;
 
-    if(!init_ok) {
+    if (!init_ok) {
         EF_INFO("ENV isn't initialize OK.\n");
         return EF_ENV_INIT_FAILED;
     }
@@ -498,8 +498,8 @@ EfErrCode ef_set_env(const char *key, const char *value) {
     /* lock the ENV cache */
     ef_port_env_lock();
 
-    /* if ENV value is empty, delete it */
-    if ((value == NULL) || *value == '\0') {
+    /* if ENV value is NULL, delete it */
+    if (value == NULL) {
         result = del_env(key);
     } else {
         old_env = find_env(key);
@@ -519,6 +519,33 @@ EfErrCode ef_set_env(const char *key, const char *value) {
             result = create_env(key, value);
         }
     }
+
+    /* unlock the ENV cache */
+    ef_port_env_unlock();
+
+    return result;
+}
+
+/**
+ * Del an ENV.
+ *
+ * @param key ENV name
+ *
+ * @return result
+ */
+EfErrCode ef_del_env(const char *key) {
+    EfErrCode result = EF_NO_ERR;
+
+    if (!init_ok) {
+        EF_INFO("ENV isn't initialize OK.\n");
+        return EF_ENV_INIT_FAILED;
+    }
+
+    /* lock the ENV cache */
+    ef_port_env_lock();
+
+    result = del_env(key);
+
     /* unlock the ENV cache */
     ef_port_env_unlock();
 
@@ -535,7 +562,7 @@ EfErrCode ef_set_env(const char *key, const char *value) {
 char *ef_get_env(const char *key) {
     char *env = NULL, *value = NULL;
 
-    if(!init_ok) {
+    if (!init_ok) {
         EF_INFO("ENV isn't initialize OK.\n");
         return NULL;
     }
@@ -559,12 +586,12 @@ char *ef_get_env(const char *key) {
  */
 void ef_print_env(void) {
     uint32_t *env_cache_data_addr = env_cache + ENV_PARAM_WORD_SIZE,
-            *env_cache_end_addr =
-            (uint32_t *) (env_cache + ENV_PARAM_WORD_SIZE + get_env_data_size() / 4);
+              *env_cache_end_addr =
+                  (uint32_t *) (env_cache + ENV_PARAM_WORD_SIZE + get_env_data_size() / 4);
     uint8_t j;
     char c;
 
-    if(!init_ok) {
+    if (!init_ok) {
         EF_INFO("ENV isn't initialize OK.\n");
         return;
     }
@@ -586,7 +613,7 @@ void ef_print_env(void) {
 #else
     ef_print("\nmode: power fail safeguard\n");
     ef_print("size: %ld/%ld bytes, write bytes %ld/%ld.\n", get_env_user_used_size(),
-            ENV_USER_SETTING_SIZE, ef_get_env_write_bytes(), ENV_AREA_SIZE);
+             ENV_USER_SETTING_SIZE, ef_get_env_write_bytes(), ENV_AREA_SIZE);
     ef_print("saved count: %ld\n", env_cache[ENV_PARAM_INDEX_SAVED_COUNT]);
 #endif
 
@@ -620,7 +647,7 @@ EfErrCode ef_load_env(void) {
         ef_port_read(get_env_data_addr(), env_cache_bak, get_env_data_size());
         /* read ENV CRC code from flash */
         ef_port_read(get_env_system_addr() + ENV_PARAM_INDEX_DATA_CRC * 4,
-                &env_cache[ENV_PARAM_INDEX_DATA_CRC] , 4);
+                     &env_cache[ENV_PARAM_INDEX_DATA_CRC] , 4);
         /* if ENV CRC32 check is fault, set default for it */
         if (!env_crc_is_ok()) {
             EF_INFO("Warning: ENV CRC check failed. Set it to default.\n");
@@ -633,7 +660,7 @@ EfErrCode ef_load_env(void) {
 EfErrCode ef_load_env(void) {
     EfErrCode result = EF_NO_ERR;
     uint32_t area0_start_address = env_start_addr, area1_start_address = env_start_addr
-            + ENV_AREA_SIZE / 2;
+                                   + ENV_AREA_SIZE / 2;
     uint32_t area0_end_addr, area1_end_addr, area0_crc, area1_crc, area0_saved_count, area1_saved_count;
     bool area0_is_valid = true, area1_is_valid = true;
     /* read ENV area end address from flash */
@@ -675,11 +702,11 @@ EfErrCode ef_load_env(void) {
     if (area0_is_valid && area1_is_valid) {
         /* read ENV area saved count from flash */
         ef_port_read(area0_start_address + ENV_PARAM_INDEX_SAVED_COUNT * 4,
-                &area0_saved_count, 4);
+                     &area0_saved_count, 4);
         ef_port_read(area1_start_address + ENV_PARAM_INDEX_SAVED_COUNT * 4,
-                &area1_saved_count, 4);
+                     &area1_saved_count, 4);
         /* the bigger saved count area is valid */
-        if ((area0_saved_count > area1_saved_count)||((area0_saved_count == 0)&&(area1_saved_count == 0xFFFFFFFF))) {
+        if ((area0_saved_count > area1_saved_count) || ((area0_saved_count == 0) && (area1_saved_count == 0xFFFFFFFF))) {
             area1_is_valid = false;
         } else {
             area0_is_valid = false;
@@ -828,6 +855,25 @@ EfErrCode ef_set_and_save_env(const char *key, const char *value) {
     return result;
 }
 
+/**
+ * Del and save an ENV. If del ENV is success then will save it.
+ *
+ * @param key ENV name
+ *
+ * @return result
+ */
+EfErrCode ef_del_and_save_env(const char *key) {
+    EfErrCode result = EF_NO_ERR;
+
+    result = ef_del_env(key);
+
+    if (result == EF_NO_ERR) {
+        result = ef_save_env();
+    }
+
+    return result;
+}
+
 #ifdef EF_ENV_AUTO_UPDATE
 /**
  * Auto update ENV to latest default when current EF_ENV_VER is changed.

easyflash/src/ef_env_wl.c

@@ -173,7 +173,7 @@ EfErrCode ef_env_init(ef_env const *default_env, size_t default_env_size) {
  *
  * @return result
  */
-EfErrCode ef_env_set_default(void){
+EfErrCode ef_env_set_default(void) {
     EfErrCode result = EF_NO_ERR;
     size_t i;
 
@@ -293,7 +293,7 @@ static size_t get_env_detail_size(void) {
  *
  * @return size
  */
-    /* must be initialized */
+/* must be initialized */
 static size_t get_env_user_used_size(void) {
     if (get_env_detail_end_addr() > get_cur_using_data_addr()) {
         return get_env_detail_end_addr() - get_cur_using_data_addr();
@@ -482,7 +482,7 @@ static EfErrCode del_env(const char *key) {
     }
     /* calculate remain ENV length */
     remain_env_length = get_env_detail_size()
-            - (((uint32_t) del_env + del_env_length) - ((uint32_t) env_cache + ENV_PARAM_PART_BYTE_SIZE));
+                        - (((uint32_t) del_env + del_env_length) - ((uint32_t) env_cache + ENV_PARAM_PART_BYTE_SIZE));
     /* remain ENV move forward */
     memcpy(del_env, del_env + del_env_length, remain_env_length);
     /* reset ENV end address */
@@ -494,7 +494,7 @@ static EfErrCode del_env(const char *key) {
 }
 
 /**
- * Set an ENV. If it value is empty, delete it.
+ * Set an ENV.If it value is NULL, delete it.
  * If not find it in ENV table, then create it.
  *
  * @param key ENV name
@@ -506,7 +506,7 @@ EfErrCode ef_set_env(const char *key, const char *value) {
     EfErrCode result = EF_NO_ERR;
     char *old_env, *old_value;
 
-    if(!init_ok) {
+    if (!init_ok) {
         EF_INFO("ENV isn't initialize OK.\n");
         return EF_ENV_INIT_FAILED;
     }
@@ -514,8 +514,8 @@ EfErrCode ef_set_env(const char *key, const char *value) {
     /* lock the ENV cache */
     ef_port_env_lock();
 
-    /* if ENV value is empty, delete it */
-    if ((value == NULL) || (*value == '\0')) {
+    /* if ENV value is NULL, delete it */
+    if (value == NULL) {
         result = del_env(key);
     } else {
         old_env = find_env(key);
@@ -541,6 +541,32 @@ EfErrCode ef_set_env(const char *key, const char *value) {
     return result;
 }
 
+/**
+ * Del an ENV.
+ *
+ * @param key ENV name
+ *
+ * @return result
+ */
+EfErrCode ef_del_env(const char *key) {
+    EfErrCode result = EF_NO_ERR;
+
+    if (!init_ok) {
+        EF_INFO("ENV isn't initialize OK.\n");
+        return EF_ENV_INIT_FAILED;
+    }
+
+    /* lock the ENV cache */
+    ef_port_env_lock();
+
+    result = del_env(key);
+
+    /* unlock the ENV cache */
+    ef_port_env_unlock();
+
+    return result;
+}
+
 /**
  * Get an ENV value by key name.
  *
@@ -551,7 +577,7 @@ EfErrCode ef_set_env(const char *key, const char *value) {
 char *ef_get_env(const char *key) {
     char *env = NULL, *value = NULL;
 
-    if(!init_ok) {
+    if (!init_ok) {
         EF_INFO("ENV isn't initialize OK.\n");
         return NULL;
     }
@@ -575,11 +601,11 @@ char *ef_get_env(const char *key) {
  */
 void ef_print_env(void) {
     uint32_t *env_cache_detail_addr = env_cache + ENV_PARAM_PART_WORD_SIZE, *env_cache_end_addr =
-            (uint32_t *) (env_cache + ENV_PARAM_PART_WORD_SIZE + get_env_detail_size() / 4);
+                                          (uint32_t *) (env_cache + ENV_PARAM_PART_WORD_SIZE + get_env_detail_size() / 4);
     uint8_t j;
     char c;
 
-    if(!init_ok) {
+    if (!init_ok) {
         EF_INFO("ENV isn't initialize OK.\n");
         return;
     }
@@ -598,11 +624,11 @@ void ef_print_env(void) {
 #ifndef EF_ENV_USING_PFS_MODE
     ef_print("\nmode: wear leveling\n");
     ef_print("size: %ld/%ld bytes, write bytes %ld/%ld.\n", get_env_user_used_size(), ENV_USER_SETTING_SIZE,
-            ef_get_env_write_bytes(), ENV_AREA_SIZE);
+             ef_get_env_write_bytes(), ENV_AREA_SIZE);
 #else
     ef_print("\nmode: wear leveling and power fail safeguard\n");
     ef_print("size: %ld/%ld bytes, write bytes %ld/%ld.\n", get_env_user_used_size(), ENV_USER_SETTING_SIZE,
-            ef_get_env_write_bytes(), ENV_AREA_SIZE / 2);
+             ef_get_env_write_bytes(), ENV_AREA_SIZE / 2);
     ef_print("saved count: %ld\n", env_cache[ENV_PARAM_PART_INDEX_SAVED_COUNT]);
 #endif
 
@@ -657,7 +683,7 @@ EfErrCode ef_load_env(void) {
             ef_port_read(get_env_detail_addr(), env_cache_bak, get_env_detail_size());
             /* read ENV CRC code from flash */
             ef_port_read(get_cur_using_data_addr() + ENV_PARAM_PART_INDEX_DATA_CRC * 4,
-                    &env_cache[ENV_PARAM_PART_INDEX_DATA_CRC], 4);
+                         &env_cache[ENV_PARAM_PART_INDEX_DATA_CRC], 4);
             /* if ENV CRC32 check is fault, set default for it */
             if (!env_crc_is_ok()) {
                 EF_INFO("Warning: ENV CRC check failed. Set it to default.\n");
@@ -739,11 +765,11 @@ EfErrCode ef_load_env(void) {
     if (area0_is_valid && area1_is_valid) {
         /* read ENV area saved count from flash */
         ef_port_read(area0_cur_using_addr + ENV_PARAM_PART_INDEX_SAVED_COUNT * 4,
-                &area0_saved_count, 4);
+                     &area0_saved_count, 4);
         ef_port_read(area1_cur_using_addr + ENV_PARAM_PART_INDEX_SAVED_COUNT * 4,
-                &area1_saved_count, 4);
+                     &area1_saved_count, 4);
         /* the bigger saved count area is valid */
-        if ((area0_saved_count > area1_saved_count)||((area0_saved_count == 0)&&(area1_saved_count == 0xFFFFFFFF))) {
+        if ((area0_saved_count > area1_saved_count) || ((area0_saved_count == 0) && (area1_saved_count == 0xFFFFFFFF))) {
             area1_is_valid = false;
         } else {
             area0_is_valid = false;
@@ -801,7 +827,7 @@ EfErrCode ef_save_env(void) {
     /* change the ENV detail end address to next save area address */
     set_env_detail_end_addr(get_cur_using_data_addr() + env_used_size);
     /* area0 or area1 */
-    if(get_cur_using_data_addr() < get_env_start_addr() + ENV_AREA_SIZE / 2) {
+    if (get_cur_using_data_addr() < get_env_start_addr() + ENV_AREA_SIZE / 2) {
         data_sec_end_addr = get_env_start_addr() + ENV_AREA_SIZE / 2 - 4;
     } else {
         data_sec_end_addr = get_env_start_addr() + ENV_AREA_SIZE - 4;
@@ -943,7 +969,7 @@ static EfErrCode save_cur_using_data_addr(uint32_t cur_data_addr) {
     EfErrCode result = EF_NO_ERR;
     uint32_t cur_system_sec_addr;
 
-    if (cur_data_addr < get_env_start_addr() + ENV_AREA_SIZE / 2){
+    if (cur_data_addr < get_env_start_addr() + ENV_AREA_SIZE / 2) {
         /* current using system section is in ENV area0 */
         cur_system_sec_addr = get_env_start_addr();
     } else {
@@ -989,6 +1015,25 @@ EfErrCode ef_set_and_save_env(const char *key, const char *value) {
     return result;
 }
 
+/**
+ * Del and save an ENV. If del ENV is success then will save it.
+ *
+ * @param key ENV name
+ *
+ * @return result
+ */
+EfErrCode ef_del_and_save_env(const char *key) {
+    EfErrCode result = EF_NO_ERR;
+
+    result = ef_del_env(key);
+
+    if (result == EF_NO_ERR) {
+        result = ef_save_env();
+    }
+
+    return result;
+}
+
 #ifdef EF_ENV_AUTO_UPDATE
 /**
  * Auto update ENV to latest default when current EF_ENV_VER is changed.