diff --git a/README.md b/README.md index 09c7111..588d847 100644 --- a/README.md +++ b/README.md @@ -22,11 +22,13 @@ ## 1.2 插件 -- 1. Flash Log：使用[EasyFlash](https://github.com/armink/EasyFlash)库提供的无缝接口，可以把日志直接存储在Flash中。 +- 1、Flash：使用[EasyFlash](https://github.com/armink/EasyFlash)库提供的Flash操作接口，可以把日志直接存储在Flash中。 +- 2、File（正在开发）：支持文件转档、软件运行时动态加载配置文件等与文件日志输出相关功能。 +- 3、敬请期待…… ## 1.3 Star & Fork -后续我还会提供更多插件。也非常欢迎大家设计、开发更多实用插件和功能，一起来完善EasyLogger **([Github](https://github.com/armink/EasyLogger)|[OSChina](http://git.oschina.net/armink/EasyLogger)|[Coding](https://coding.net/u/armink/p/EasyLogger/git))** ，同时把它推广给更多有需要的朋友。 +后续我还会提供更多插件。也非常欢迎大家设计、开发更多实用插件和功能，一起来完善EasyLogger **([Github](https://github.com/armink/EasyLogger)|[OSChina](http://git.oschina.net/armink/EasyLogger)|[Coding](https://coding.net/u/armink/p/EasyLogger/git))** 。如果觉得这个开源项目很赞，可以点击[项目主页](https://github.com/armink/EasyLogger) 右上角的**Star**，同时把它推荐给更多有需要的朋友。 # 2. 使用 @@ -55,19 +57,7 @@ EasyLogger拥有过滤方式、输出格式、输出开关这些属性。 ### 2.3 输出过滤 -#### 2.3.1 过滤级别 - -默认过滤级别为5(详细)，用户可以任意设置。在设置高优先级后，低优先级的日志将不会输出。例如：设置当前过滤的优先级为3(警告)，则只会输出优先级别为警告、错误、断言的日志。 - -#### 2.3.2 过滤标签 - -默认过滤标签为空字符串("")，即不过滤。当前输出日志的标签会与过滤标签做字符串匹配，日志的标签包含过滤标签，则该输出该日志。例如：设置过滤标签为WiFi，则系统中包含WiFi字样标签的（WiFi.BSP、WiFi.Protocol、Setting.WiFi）日志都会被输出。 - -#### 2.3.3 过滤关键词 - -默认过滤关键词为空字符串("")，即不过滤。检索当前输出日志中是否包含该关键词，包含则允许输出。 - -> 注：对于配置较低的MCU建议不开启关键词过滤（默认为不过滤），增加关键字过滤将会在很大程度上减低日志的输出效率。实际上过滤关键词功能交给上位机做会更轻松，所以后期的跨平台日志助手开发完成后，就无需该功能。 +支持按照**级别、标签及关键词**进行过滤。日志内容较多时，使用过滤功能可以更快定位日志，保证日志的可读性。更多的过滤功能设置方法及细节请阅读[`\docs\zh\api\kernel.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/api/kernel.md)文档 ### 2.4 输出格式 @@ -88,9 +78,9 @@ EasyLogger拥有过滤方式、输出格式、输出开关这些属性。 下图为在终端中输入命令来控制日志的输出及过滤器的设置，更加直观的展示了EasyLogger核心功能。 -- Demo路径：`demo` -- API文档：`docs\zh\api.md` -- 移植文档：即将发布…… +- Demo路径：[`\demo\os\rt-thread\stm32f10x\`](https://github.com/armink/EasyLogger/tree/master/demo/os/rt-thread/stm32f10x) +- API文档：[`\docs\zh\api\kernel.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/api/kernel.md) +- 移植文档：[`\docs\zh\port\kernel.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/port/kernel.md) ![easylogger](http://git.oschina.net/Armink/EasyLogger/raw/master/docs/zh/images/EasyLoggerDemo.gif) @@ -98,21 +88,25 @@ EasyLogger拥有过滤方式、输出格式、输出开关这些属性。 下图过程为通过控制台输出日志，并将输出的日志存储到Flash中。重启再读取上次保存的日志，最后清空Flash日志。 -- Demo路径：`demo\os\rt-thread\stm32f10x` -- API文档：`docs\zh\api.md` -- 移植文档：即将发布…… +- Demo路径：[`\demo\os\rt-thread\stm32f10x\`](https://github.com/armink/EasyLogger/tree/master/demo/os/rt-thread/stm32f10x) +- API文档：[`\docs\zh\api\flash.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/api/flash.md) +- 移植文档：[`\docs\zh\port\flash.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/port/flash.md) ![FlashLog](http://git.oschina.net/Armink/EasyLogger/raw/master/docs/zh/images/LogDemo.gif) -# 3. 后期 +# 3. 文档 + +具体内容参考[`\docs\zh\`](https://github.com/armink/EasyLogger/tree/master/docs/zh)下的文件。务必保证在 **阅读文档** 后再移植使用。 + +# 4. 后期 - 1、~~Flash存储：在[EasyFlash](https://github.com/armink/EasyFlash)中增加日志存储、读取功能，让EasyLogger与其无缝对接。使日志可以更加容易的存储在 **非文件系统** 中，~~并具有历史日检索的功能； -- 2、文件转档：文件系统下支持文件按容量转档，按时间区分； -- 3、异步输出：目前日志输出与用户代码之间是同步的方式，这种方式虽然软件简单，也不存在日志覆盖的问题。但在输出速度较低的平台下，会由于增加日志功能，而降低软件运行速度。所以后期会增加 **异步输出** 方式，关键字过滤也可以放到异步输出中去； -- 4、配置文件：文件系统下的配置文件； -- 5、日志助手：开发跨平台的日志助手，兼容Linux、Windows、Mac系统，打开助手即可查看、过滤（支持正则表达式）、排序、保存日志等，计划使用[NW.js](http://www.oschina.net/p/nwjs)框架； +- 2、配置文件：文件系统下的配置文件； +- 3、文件转档：文件系统下支持文件按容量转档，按时间区分； +- 4、日志助手：开发跨平台的日志助手，兼容Linux、Windows、Mac系统，打开助手即可查看、过滤（支持正则表达式）、排序、保存日志等。前端：[HTML5](https://zh.wikipedia.org/wiki/HTML5) + [Bootstrap](https://github.com/twbs/bootstrap) + [AngularJS](https://angularjs.org/) + [NW.js](http://www.oschina.net/p/nwjs)，后端：[Rust](https://github.com/rust-lang/rust) + [iron](https://github.com/iron/iron) + [rust-websocket](https://github.com/cyderize/rust-websocket) + [serial-rs](https://github.com/dcuddeback/serial-rs)； +- 5、异步输出：目前日志输出与用户代码之间是同步的方式，这种方式虽然软件简单，也不存在日志覆盖的问题。但在输出速度较低的平台下，会由于增加日志功能，而降低软件运行速度。所以后期会增加 **异步输出** 方式，关键字过滤也可以放到异步输出中去； - 6、Arduino：增加Arduino lib，并提供其Demo； -# 4. 许可 +# 5. 许可 MIT Copyright (c) armink.ztl@gmail.com diff --git a/docs/zh/api.md b/docs/zh/api/flash.md similarity index 100% rename from docs/zh/api.md rename to docs/zh/api/flash.md diff --git a/docs/zh/api/kernel.md b/docs/zh/api/kernel.md new file mode 100644 index 0000000..4077575 --- /dev/null +++ b/docs/zh/api/kernel.md @@ -0,0 +1,250 @@ +# EasyLogger 核心功能 API 说明 + +--- + +所有核心功能API接口都在[`\easylogger\inc\elog.h`](https://github.com/armink/EasyLogger/blob/master/easylogger/inc/elog.h)中声明。以下内容较多，可以使用 **CTRL+F** 搜索。 + +> 建议：点击项目主页 https://github.com/armink/EasyLogger 右上角 **Watch & Star**，这样项目有更新时，会及时以邮件形式通知你。 + +## 1、用户使用接口 + +### 1.1 初始化 + +初始化的EasyLogger的核心功能，初始化后才可以使用下面的API。 + +``` +ElogErrCode elog_init(void) +``` + +### 1.2 启动 + +**注意**：在初始化完成后，必须调用启动方法，日志才会被输出。 + +``` +void elog_start(void) +``` + +### 1.3 按级别输出日志 + +所有日志的级别关系大小如下： + +``` +级别 标识 描述 +0 [A] 断言(Assert) +1 [E] 错误(Error) +2 [W] 警告(Warn) +3 [I] 信息(Info) +4 [D] 调试(Debug) +5 [V] 详细(Verbose) +``` + +所有级别的日志输出方法如下，每种级别都有一种简写方式，用户可以自行选择。 + +```c +#define elog_assert(tag, ...) +#define elog_a(tag, ...) //简写 + +#define elog_error(tag, ...) +#define elog_e(tag, ...) + +#define elog_warn(tag, ...) +#define elog_w(tag, ...) + +#define elog_info(tag, ...) +#define elog_i(tag, ...) + +#define elog_debug(tag, ...) +#define elog_d(tag, ...) + +#define elog_verbose(tag, ...) +#define elog_v(tag, ...) +``` + +|参数 |描述| +|:----- |:----| +|tag |日志标签| +|... |不定参格式，与`printf`入参一致，放入将要输出日志| + +**建议**：对于每个文件或者每个模块，可以对重新覆盖定义上述日志输出宏定义，如下所示。这样的优点就是降低代码书写量，统一日志书写格式，代码可以做到尽可能少的依赖某个日志库，同时把部分复用代码无需修改日志输出方法，可直接拷贝至其他模块或者其他项目，提高软件的可重用性。 + +```c +//WiFi协议处理 +#define log_d(...) elog_d("wifi.proto", __VA_ARGS__) +#define log_w(...) elog_w("wifi.proto", __VA_ARGS__) +#define log_e(...) elog_e("wifi.proto", __VA_ARGS__) + +//WiFi数据打包处理 +#define log_d(...) elog_d("wifi.package", __VA_ARGS__) + +//CAN命令解析 +#define log_d(...) elog_d("can.disp", __VA_ARGS__) +#define log_e(...) elog_e("can.disp", __VA_ARGS__) + +``` +### 1.4 断言 + +EasyLogger自带的断言，可以直接用户软件，在断言表达式不成立后会输出断言信息并保持`while(1)`，或者执行断言钩子方法，钩子方法的设定参考 [`elog_assert_set_hook`](#114-设置断言钩子方法)。 + +``` +#define ELOG_ASSERT(EXPR) +``` + +|参数 |描述| +|:----- |:----| +|EXPR |表达式| + +### 1.5 使能/失能日志输出 + +``` +void elog_set_output_enabled(bool enabled) +``` +|参数 |描述| +|:----- |:----| +|enabled |true: 使能，false: 失能| + +### 1.6 获取日志使能状态 + +``` +bool elog_get_output_enabled(void) +``` + +### 1.7 设置日志格式 + +每种级别可对应一种日志输出格式，日志的输出内容位置顺序固定，只可定义开启或关闭某子内容。可设置的日志子内容包括：级别、标签、时间、进程信息、线程信息、文件路径、行号、方法名。 + +> 注：默认为 RAW格式 + +``` +void elog_set_fmt(uint8_t level, size_t set) +``` + +|参数 |描述| +|:----- |:----| +|level |级别| +|set |格式集合| + +例子： + +```c +/* 断言：输出所有内容 */ +elog_set_fmt(ELOG_LVL_ASSERT, ELOG_FMT_ALL); +/* 错误：输出级别、标签和时间 */ +elog_set_fmt(ELOG_LVL_ERROR, ELOG_FMT_LVL | ELOG_FMT_TAG | ELOG_FMT_TIME); +/* 警告：输出级别、标签和时间 */ +elog_set_fmt(ELOG_LVL_WARN, ELOG_FMT_LVL | ELOG_FMT_TAG | ELOG_FMT_TIME); +/* 信息：输出级别、标签和时间 */ +elog_set_fmt(ELOG_LVL_INFO, ELOG_FMT_LVL | ELOG_FMT_TAG | ELOG_FMT_TIME); +/* 调试：输出除了方法名之外的所有内容 */ +elog_set_fmt(ELOG_LVL_DEBUG, ELOG_FMT_ALL & ~ELOG_FMT_FUNC); +/* 详细：输出除了方法名之外的所有内容 */ +elog_set_fmt(ELOG_LVL_VERBOSE, ELOG_FMT_ALL & ~ELOG_FMT_FUNC); +``` + +### 1.8 设置过滤级别 + +默认过滤级别为5(详细)，用户可以任意设置。在设置高优先级后，低优先级的日志将不会输出。例如：设置当前过滤的优先级为3(警告)，则只会输出优先级别为警告、错误、断言的日志。 + +``` +void elog_set_filter_lvl(uint8_t level) +``` + +|参数 |描述| +|:----- |:----| +|level |级别| + +### 1.9 设置过滤标签 + +默认过滤标签为空字符串(`""`)，即不过滤。当前输出日志的标签会与过滤标签做字符串匹配，日志的标签包含过滤标签，则该输出该日志。例如：设置过滤标签为WiFi，则系统中包含WiFi字样标签的（WiFi.Bsp、WiFi.Protocol、Setting.Wifi）日志都会被输出。 + +>注：RAW格式日志不支持标签过滤 + +``` +void elog_set_filter_tag(const char *tag) +``` + +|参数 |描述| +|:----- |:----| +|tag |标签| + +### 1.10 设置过滤关键词 + +默认过滤关键词为空字符串("")，即不过滤。检索当前输出日志中是否包含该关键词，包含则允许输出。 + +> 注：对于配置较低的MCU建议不开启关键词过滤（默认为不过滤），增加关键字过滤将会在很大程度上减低日志的输出效率。实际上当需要实时查看日志时，过滤关键词功能交给上位机做会更轻松，所以后期的跨平台日志助手开发完成后，就无需该功能。 + +``` +void elog_set_filter_kw(const char *keyword) +``` + +|参数 |描述| +|:----- |:----| +|keyword |关键词| + +### 1.11 设置过滤器 + +设置过滤器后，只输出符合过滤要求的日志。所有参数设置方法，可以参考上述3个章节。 + +``` +void elog_set_filter(uint8_t level, const char *tag, const char *keyword) +``` + +|参数 |描述| +|:----- |:----| +|level |级别| +|tag |标签| +|keyword |关键词| + +### 1.12 输出RAW格式日志 + +``` +void elog_raw(const char *format, ...) +``` +|参数 |描述| +|:----- |:----| +|format |样式，类似`printf`首个入参| +|... |不定参| + +### 1.13 使能/失能日志输出锁 + +默认为失能状态，当系统或MCU进入异常后，需要输出异常日志时，就必须失能日志输出锁，来保证异常日志能够被正常输出。 + +``` +void elog_output_lock_enabled(bool enabled) +``` + +|参数 |描述| +|:----- |:----| +|enabled |true: 使能，false: 失能| + +例子： + +```c +/* EasyLogger断言钩子方法 */ +static void elog_user_assert_hook(const char* ex, const char* func, size_t line) { + /* 失能日志输出锁 */ + elog_output_lock_enabled(false); + /* 失能EasyLogger的Flash插件自带同步锁（Flash插件自带方法） */ + elog_flash_lock_enabled(false); + /* 输出断言信息 */ + elog_a("elog", "(%s) has assert failed at %s:%ld.\n", ex, func, line); + /* 将缓冲区中所有日志保存至Flash（Flash插件自带方法） */ + elog_flash_flush(); + while(1); +} +``` + +### 1.14 设置断言钩子方法 + +默认断言钩子方法为空，设置断言钩子方法后。当断言`ELOG_ASSERT(EXPR)`中的条件不满足时，会自动执行断言钩子方法。断言钩子方法定义及使用可以参考上一章节的例子。 + +```c +void elog_assert_set_hook(void (*hook)(const char* expr, const char* func, size_t line)) +``` + +|参数 |描述| +|:----- |:----| +|hook |断言钩子方法| + +## 2、配置 + +参照EasyLogger 移植说明（[`\docs\zh\port\kernel.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/port/kernel.md)）中的 `设置参数` 章节 diff --git a/docs/zh/api/readme.md b/docs/zh/api/readme.md new file mode 100644 index 0000000..0badd0c --- /dev/null +++ b/docs/zh/api/readme.md @@ -0,0 +1,4 @@ +|文件名 |描述| +|:----- |:----| +|flash.md |flash插件API文档| +|kernel.md |核心功能API文档| \ No newline at end of file diff --git a/docs/zh/port/flash.md b/docs/zh/port/flash.md new file mode 100644 index 0000000..56965e6 --- /dev/null +++ b/docs/zh/port/flash.md @@ -0,0 +1 @@ +#即将发布... \ No newline at end of file diff --git a/docs/zh/port/kernel.md b/docs/zh/port/kernel.md new file mode 100644 index 0000000..56965e6 --- /dev/null +++ b/docs/zh/port/kernel.md @@ -0,0 +1 @@ +#即将发布... \ No newline at end of file diff --git a/docs/zh/port/readme.md b/docs/zh/port/readme.md new file mode 100644 index 0000000..d17d525 --- /dev/null +++ b/docs/zh/port/readme.md @@ -0,0 +1,4 @@ +|文件名 |描述| +|:----- |:----| +|flash.md |flash插件移植文档| +|kernel.md |核心功能移植文档| \ No newline at end of file diff --git a/docs/zh/readme.md b/docs/zh/readme.md index d01eeaf..7a9d3cf 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 |API说明| +|port |移植说明| \ No newline at end of file