【完善】文档细节。

Signed-off-by: armink <[email protected]>

docs/zh/api/kernel.md

@@ -338,31 +338,39 @@ void elog_set_filter(uint8_t level, const char *tag, const char *keyword)
 |tag                                     |标签|
 |keyword                                 |关键词|
 
-#### 1.7.3 设置过滤关键词等级
+#### 1.7.3 按模块的级别过滤
 
-> 注：对于配置较低的MCU建议不开启关键词过滤（默认为不过滤），增加关键字过滤等级将会在很大程度上减低日志的输出效率。实际上当需要实时查看日志时，过滤关键词功能交给上位机做会更轻松，所以后期的跨平台日志助手开发完成后，就无需该功能。
+这里指的**模块**代表一类具有相同标签属性的日志代码。有些时候需要在运行时动态的修改某一个模块的日志输出级别。
 
 ```
 void elog_set_filter_tag_lvl(const char *tag, uint8_t level);
 ```
 
 |参数                                    |描述|
 |:-----                                  |:----|
-|tag                                     |标签|
-|level                                   |级别|
+|tag                                     |日志的标签|
+|level                                   |设定的日志级别|
 
 参数 level 日志级别可取如下值：
-```
-级别 标识 描述
-0    [A]  断言(Assert)
-1    [E]  错误(Error)
-2    [W]  警告(Warn)
-3    [I]  信息(Info)
-4    [D]  调试(Debug)
-5    [V]  详细(Verbose)
-0    [A]  静默停止输出
-5    [V]  全部
-```
+
+|**级别**             |**名称**            |
+| --------------------- | ---------------- |
+| ELOG_LVL_ASSERT        | 断言             |
+| ELOG_LVL_ERROR         | 错误             |
+| ELOG_LVL_WARNING       | 警告             |
+| ELOG_LVL_INFO          | 信息             |
+| ELOG_LVL_DEBUG | 调试             |
+| ELOG_LVL_VERBOSE | 详细 |
+| ELOG_FILTER_LVL_SILENT | 静默（停止输出） |
+| ELOG_FILTER_LVL_ALL    | 全部             |
+
+函数调用如下所示：
+
+| 功能        | 函数调用            |
+| ---------------- | ------------------------------ |
+| 关闭 `wifi` 模块全部日志  | `elog_set_filter_tag_lvl("wifi", ELOG_FILTER_LVL_SILENT);` |
+| 开启 `wifi` 模块全部日志       | `elog_set_filter_tag_lvl("wifi", ELOG_FILTER_LVL_ALL);` |
+| 设置 `wifi` 模块日志级别为警告 | `elog_set_filter_tag_lvl("wifi", ELOG_LVL_WARNING);` |
 
 ### 1.8 缓冲输出模式
 

docs/zh/port/kernel.md

@@ -113,7 +113,7 @@ const char *elog_port_get_t_info(void)
 配置时需要修改项目中的`elog_cfg.h`文件，开启、关闭、修改对应的宏即可。
 
 ### 4.1 输出开关
-    
+
 开启后，日志才会被输出。如果关闭，所有日志输出代码都将会被替换为空。
 
 - 操作方法：开启、关闭`ELOG_OUTPUT_ENABLE`宏即可
@@ -166,13 +166,19 @@ const char *elog_port_get_t_info(void)
 
 - 操作方法：修改`ELOG_FILTER_KW_MAX_LEN`宏对应值即可
 
-### 4.8 换行符
+### 4.8  标签 + 级别过滤器的最大数目
+
+最大支持的动态日志级别过滤的模块（标签）数量，详见 ：`elog_set_filter_tag_lvl`
+
+- 操作方法：修改`ELOG_FILTER_TAG_LVL_MAX_NUM`宏对应值即可
+
+### 4.9 换行符
 
 用户可以根据自己的使用场景自定义换行符，例如：`"\r\n"`，`"\n"`
 
 - 操作方法：修改`ELOG_NEWLINE_SIGN`宏对应值即可
 
-### 4.9 颜色
+### 4.10 颜色
 
 > **注意** ：启用颜色功能需先定义 `ELOG_COLOR_ENABLE`
 
@@ -188,53 +194,47 @@ const char *elog_port_get_t_info(void)
 
 - 操作方法：增加并修改`ELOG_COLOR_VERBOSE`宏对应值即可，其他级别日志颜色的修改以此类推
 
-### 4.10 异步输出模式
+### 4.11 异步输出模式
 
 开启异步输出模式后，将会提升用户应用程序的执行效率。应用程序在进行日志输出时，无需等待日志彻底输出完成，即可直接返回。
 
 - 操作方法：开启、关闭`ELOG_ASYNC_OUTPUT_ENABLE`宏即可
 
-#### 4.10.1 异步输出日志的最高级别
+#### 4.11.1 异步输出日志的最高级别
 
 日志低于或等于该级别时，才会通过异步输出。高于该级别的日志都将按照默认的同步方式输出。这样的好处是，提升了较高级别的日志输出的实时性。
 
 - 默认级别：`ELOG_LVL_ASSERT` ，不定义此宏，将会自动按照默认值设置
 - 操作方法：修改`ELOG_ASYNC_OUTPUT_LVL`宏对应值即可
 
-#### 4.10.2 异步输出模式缓冲区大小
+#### 4.11.2 异步输出模式缓冲区大小
 
 - 默认大小：`(ELOG_LINE_BUF_SIZE * 10)` ，不定义此宏，将会自动按照默认值设置
 - 操作方法：修改`ELOG_ASYNC_OUTPUT_BUF_SIZE`宏对应值即可
 
-#### 4.10.3 异步按行输出日志
+#### 4.11.3 异步按行输出日志
 
 由于异步输出方式内部拥有缓冲区，所以直接输出缓冲区中积累的日志时，日志移植输出方法 (`elog_port_output`) 输出的日志将不会按照 **行日志** （以换行符结尾）的格式进行输出。这使得无法在移植输出方法中完成日志的分析处理。开启此功能后，将会最大限度保证移植输出方法每次输出的日志格式都为行日志。
 
 - 操作方法：开启、关闭`ELOG_ASYNC_LINE_OUTPUT`宏即可
 
-#### 4.10.4 启用 pthread 库
+#### 4.11.4 启用 pthread 库
 
 异步输出模式默认是使用 POSIX 的 pthread 库来实现，用户的平台如果支持 pthread ，则可以开启此宏。对于一些缺少 pthread 的支持平台，可以关闭此宏，参考 `elog_async.c` 中关于日志异步输出线程的实现方式，自己动手实现此功能。
 
 - 操作方法：开启、关闭`ELOG_ASYNC_OUTPUT_USING_PTHREAD`宏即可
 
-### 4.11 缓冲输出模式
+### 4.12 缓冲输出模式
 
 开启缓冲输出模式后，如果缓冲区不满，用户线程在进行日志输出时，无需等待日志彻底输出完成，即可直接返回。但当日志缓冲区满以后，将会占用用户线程，自动将缓冲区中的日志全部输出干净。同时用户也可以在非日志输出线程，通过定时等机制使用 `void elog_flush(void)` 将缓冲区中的日志输出干净。
 
 - 操作方法：开启、关闭`ELOG_BUFF_OUTPUT_ENABLE`宏即可
 
-#### 4.11.1 缓冲输出模式缓冲区大小
+#### 4.12.1 缓冲输出模式缓冲区大小
 
 - 默认大小：`(ELOG_LINE_BUF_SIZE * 10)` ，不定义此宏，将会自动按照默认值设置
 - 操作方法：修改`ELOG_BUF_OUTPUT_BUF_SIZE`宏对应值即可
 
-### 4.6 过滤标签等级最大数目
-
-日志中标签内容及用户设置过滤标签等级的最大数目
-
-- 操作方法：修改`ELOG_FILTER_TAG_LVL_MAX_NUM`宏对应值即可
-
 
 ## 5、测试验证
 

easylogger/inc/elog.h

@@ -47,8 +47,8 @@ extern "C" {
 #define ELOG_LVL_VERBOSE                     5
 
 /* the output silent level and all level for filter setting */
-#define LOG_FILTER_LVL_SILENT                      0
-#define LOG_FILTER_LVL_ALL                         5
+#define ELOG_FILTER_LVL_SILENT               ELOG_LVL_ASSERT
+#define ELOG_FILTER_LVL_ALL                  ELOG_LVL_VERBOSE
 
 /* output log's level total number */
 #define ELOG_LVL_TOTAL_NUM                   6
@@ -151,7 +151,7 @@ typedef struct {
     uint8_t level;
     char tag[ELOG_FILTER_TAG_MAX_LEN + 1];
     char keyword[ELOG_FILTER_KW_MAX_LEN + 1];
-    ElogTagLvlFilter tag_lvl_filter[ELOG_FILTER_TAG_LVL_MAX_NUM];
+    ElogTagLvlFilter tag_lvl[ELOG_FILTER_TAG_LVL_MAX_NUM];
 } ElogFilter, *ElogFilter_t;
 
 /* easy logger */

easylogger/src/elog.c

@@ -57,6 +57,11 @@
     #error "Please configure output newline sign (in elog_cfg.h)"
 #endif
 
+/* output filter's tag level max num */
+#ifndef ELOG_FILTER_TAG_LVL_MAX_NUM
+#define ELOG_FILTER_TAG_LVL_MAX_NUM          4
+#endif
+
 #ifdef ELOG_COLOR_ENABLE
 /**
  * CSI(Control Sequence Introducer/Initiator) sign
@@ -340,17 +345,29 @@ static void elog_set_filter_tag_lvl_default()
     uint8_t i = 0;
 
     for (i =0; i< ELOG_FILTER_TAG_LVL_MAX_NUM; i++){
-        memset(elog.filter.tag_lvl_filter[i].tag, '\0', ELOG_FILTER_TAG_MAX_LEN + 1);
-        elog.filter.tag_lvl_filter[i].level = LOG_FILTER_LVL_SILENT;
-        elog.filter.tag_lvl_filter[i].tag_use_flag = false;
+        memset(elog.filter.tag_lvl[i].tag, '\0', ELOG_FILTER_TAG_MAX_LEN + 1);
+        elog.filter.tag_lvl[i].level = ELOG_FILTER_LVL_SILENT;
+        elog.filter.tag_lvl[i].tag_use_flag = false;
     }
 }
 
 /**
- * set log filter's tag level
+ * Set the filter's level by different tag.
+ * The log on this tag which level is less than it will stop output.
+ *
+ * example:
+ *     // the example tag log enter silent mode
+ *     elog_set_filter_tag_lvl("example", ELOG_FILTER_LVL_SILENT);
+ *     // the example tag log which level is less than INFO level will stop output
+ *     elog_set_filter_tag_lvl("example", ELOG_LVL_INFO);
+ *     // remove example tag's level filter, all level log will resume output
+ *     elog_set_filter_tag_lvl("example", ELOG_FILTER_LVL_ALL);
+ *
+ * @param tag log tag
+ * @param level The filter level. When the level is ELOG_FILTER_LVL_SILENT, the log enter silent mode.
+ *        When the level is ELOG_FILTER_LVL_ALL, it will remove this tag's level filer.
+ *        Then all level log will resume output.
  *
- * @param tag tag
- * @param level level
  */
 void elog_set_filter_tag_lvl(const char *tag, uint8_t level)
 {
@@ -365,30 +382,30 @@ void elog_set_filter_tag_lvl(const char *tag, uint8_t level)
     elog_port_output_lock();
     /* find the tag in arr */
     for (i =0; i< ELOG_FILTER_TAG_LVL_MAX_NUM; i++){
-        if (elog.filter.tag_lvl_filter[i].tag_use_flag == true &&
-            !strncmp(tag, elog.filter.tag_lvl_filter[i].tag,ELOG_FILTER_TAG_MAX_LEN)){
+        if (elog.filter.tag_lvl[i].tag_use_flag == true &&
+            !strncmp(tag, elog.filter.tag_lvl[i].tag,ELOG_FILTER_TAG_MAX_LEN)){
             break;
         }
     }
 
     if (i < ELOG_FILTER_TAG_LVL_MAX_NUM){
         /* find OK */
-        if (level == LOG_FILTER_LVL_ALL){
+        if (level == ELOG_FILTER_LVL_ALL){
             /* remove current tag's level filter when input level is the lowest level */
-             elog.filter.tag_lvl_filter[i].tag_use_flag = false;
-             memset(elog.filter.tag_lvl_filter[i].tag, '\0', ELOG_FILTER_TAG_MAX_LEN + 1);
-             elog.filter.tag_lvl_filter[i].level = LOG_FILTER_LVL_SILENT;
+             elog.filter.tag_lvl[i].tag_use_flag = false;
+             memset(elog.filter.tag_lvl[i].tag, '\0', ELOG_FILTER_TAG_MAX_LEN + 1);
+             elog.filter.tag_lvl[i].level = ELOG_FILTER_LVL_SILENT;
         } else{
-            elog.filter.tag_lvl_filter[i].level = level;
+            elog.filter.tag_lvl[i].level = level;
         }
     } else{
-        /* only add the new tag's level filer when level is not LOG_FILTER_LVL_ALL */
-        if (level != LOG_FILTER_LVL_ALL){
+        /* only add the new tag's level filer when level is not ELOG_FILTER_LVL_ALL */
+        if (level != ELOG_FILTER_LVL_ALL){
             for (i =0; i< ELOG_FILTER_TAG_LVL_MAX_NUM; i++){
-                if (elog.filter.tag_lvl_filter[i].tag_use_flag == false){
-                    strncpy(elog.filter.tag_lvl_filter[i].tag, tag, ELOG_FILTER_TAG_MAX_LEN);
-                    elog.filter.tag_lvl_filter[i].level = level;
-                    elog.filter.tag_lvl_filter[i].tag_use_flag = true;
+                if (elog.filter.tag_lvl[i].tag_use_flag == false){
+                    strncpy(elog.filter.tag_lvl[i].tag, tag, ELOG_FILTER_TAG_MAX_LEN);
+                    elog.filter.tag_lvl[i].level = level;
+                    elog.filter.tag_lvl[i].tag_use_flag = true;
                     break;
                 }
             }
@@ -409,7 +426,7 @@ uint8_t elog_get_filter_tag_lvl(const char *tag)
 {
     ELOG_ASSERT(tag != ((void *)0));
     uint8_t i = 0;
-    uint8_t level = LOG_FILTER_LVL_ALL;
+    uint8_t level = ELOG_FILTER_LVL_ALL;
 
     if (!elog.init_ok) {
         return level;
@@ -418,9 +435,9 @@ uint8_t elog_get_filter_tag_lvl(const char *tag)
     elog_port_output_lock();
     /* find the tag in arr */
     for (i =0; i< ELOG_FILTER_TAG_LVL_MAX_NUM; i++){
-        if (elog.filter.tag_lvl_filter[i].tag_use_flag == true &&
-            !strncmp(tag, elog.filter.tag_lvl_filter[i].tag,ELOG_FILTER_TAG_MAX_LEN)){
-            level = elog.filter.tag_lvl_filter[i].level;
+        if (elog.filter.tag_lvl[i].tag_use_flag == true &&
+            !strncmp(tag, elog.filter.tag_lvl[i].tag,ELOG_FILTER_TAG_MAX_LEN)){
+            level = elog.filter.tag_lvl[i].level;
             break;
         }
     }