diff --git a/docs/en/api.md b/docs/en/api.md deleted file mode 100644 index f65681d..0000000 --- a/docs/en/api.md +++ /dev/null @@ -1 +0,0 @@ -# Coming soon... \ No newline at end of file diff --git a/docs/en/images/EasyLoggerDemo.gif b/docs/en/images/EasyLoggerDemo.gif deleted file mode 100644 index dd28138..0000000 Binary files a/docs/en/images/EasyLoggerDemo.gif and /dev/null differ diff --git a/docs/en/images/LogDemo.gif b/docs/en/images/LogDemo.gif deleted file mode 100644 index b99b662..0000000 Binary files a/docs/en/images/LogDemo.gif and /dev/null differ diff --git a/docs/en/readme.md b/docs/en/readme.md deleted file mode 100644 index 916db5a..0000000 --- a/docs/en/readme.md +++ /dev/null @@ -1,3 +0,0 @@ -|File name |Description| -|:----- |:----| -|api.md |API description| \ No newline at end of file diff --git a/docs/readme.md b/docs/readme.md deleted file mode 100644 index da9229a..0000000 --- a/docs/readme.md +++ /dev/null @@ -1,4 +0,0 @@ -|File or folder name |Description| -|:----- |:----| -|en |English documents| -|zh |中文文档（简体）| \ No newline at end of file diff --git a/docs/zh/api/flash.md b/docs/zh/api/flash.md deleted file mode 100644 index e13d575..0000000 --- a/docs/zh/api/flash.md +++ /dev/null @@ -1,110 +0,0 @@ -# EasyLogger Flash 插件 API 说明 - ---- - -所有Flash插件功能的API接口都在[`\easylogger\plugins\flash\elog_flash.h`](https://github.com/armink/EasyLogger/blob/master/easylogger/plugins/flash/elog_flash.h)中声明。以下内容较多，可以使用 **CTRL+F** 搜索。 - -> 建议：点击项目主页 https://github.com/armink/EasyLogger 右上角 **Watch & Star**，这样项目有更新时，会及时以邮件形式通知你。 - -## 1、用户使用接口 - -### 1.1 初始化 - -初始化的EasyLogger的Flash插件，初始化后才可以使用下面的API。 - -> 注意：插件的初始化必须放在核心功能初始化之后。 - -``` -ElogErrCode elog_flash_init(void) -``` - -### 1.2 输出Flash中指定位置存储的日志 - -日志的输出方式取决用户的移植接口`elog_flash_port_putput`的实现，具体参考Flash插件移植说明（[`\docs\zh\port\flash.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/port/flash.md)）。首页Demo中是输出到控制台的方式。 - -``` -void elog_flash_output(size_t pos, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|pos |日志存储的位置索引（从0开始）| -|size |日志大小，单位：字节| - -### 1.3 输出Flash中存储的所有日志 - -``` -void elog_flash_output_all(void) -``` - -### 1.4 输出Flash中最近存储的日志 - -``` -void elog_flash_output_recent(size_t size) -``` - -|参数 |描述| -|:----- |:----| -|size |日志大小，单位：字节| - -### 1.5 往Flash中写入日志 - -此方法可以放到核心功能的日志输出移植接口`elog_port_output`中，实现所有日志自动保存至Flash中的功能。 - -``` -void elog_flash_write(const char *log, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|log |日志内容| -|size |日志大小，单位：字节| - -### 1.6 清空Flash中全部日志 - -> 注意：如果Flash插件开启缓冲模式，那么缓冲区的日志也将会被清空。 - -``` -void elog_flash_clean(void) -``` - -### 1.7 使能/失能Flash日志功能锁 - -默认为使能状态，当系统或MCU进入异常后，需要输出异常日志时，就必须失能Flash日志功能锁，来保证异常日志能够被正常输出。 - -``` -void elog_flash_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.8 将缓冲区中所有日志保存至Flash中 - -> 注意：只有Flash插件开启缓冲模式时，此功能才可以被使用。非缓冲模式下调用`elog_flash_write()`会立刻保存日志。 - -``` -void elog_flash_flush(void); -``` - -## 2、配置 - -参照EasyLogger Flash插件移植说明（[`\docs\zh\port\flash.md`](https://github.com/armink/EasyLogger/blob/master/docs/zh/port/flash.md)）中的 `设置参数` 章节 diff --git a/docs/zh/api/kernel.md b/docs/zh/api/kernel.md deleted file mode 100644 index da72829..0000000 --- a/docs/zh/api/kernel.md +++ /dev/null @@ -1,434 +0,0 @@ -# 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) -``` - -#### 1.3.1 输出基本日志 - -所有级别的日志输出方法如下，每种级别都有两种简化方式，用户可以自行选择。 - -```c -#define elog_assert(tag, ...) -#define elog_a(tag, ...) //简化方式1，每次需填写 LOG_TAG -#define log_a(...) //简化方式2，LOG_TAG 已经在文件顶部定义，使用前无需填写 LOG_TAG - -#define elog_error(tag, ...) -#define elog_e(tag, ...) -#define log_e(...) - -#define elog_warn(tag, ...) -#define elog_w(tag, ...) -#define log_w(...) - -#define elog_info(tag, ...) -#define elog_i(tag, ...) -#define log_i(...) - -#define elog_debug(tag, ...) -#define elog_d(tag, ...) -#define log_d(...) - -#define elog_verbose(tag, ...) -#define elog_v(tag, ...) -#define log_v(...) -``` - -|参数 |描述| -|:----- |:----| -|tag |日志标签| -|... |不定参格式，与`printf`入参一致，放入将要输出日志| - -**技巧一** ：对于每个源代码文件，可以在引用 `elog.h` 上方，根据模块的不同功能，定义不同的日志标签，如下所示，这样既可直接使用 `log_x` 这类无需输入标签的简化方式 API 。 - -```c -//WiFi 协议处理(位于 /wifi/proto.c 源代码文件) -#define LOG_TAG "wifi.proto" - -#include - -log_e("我是 wifi.proto 日志"); -``` - -```C -//WiFi 数据打包处理(位于 /wifi/package.c 源代码文件) -#define LOG_TAG "wifi.package" - -#include - -log_w("我是 wifi.package 日志"); -``` - -```C -//CAN 命令解析(位于 /can/disp.c 源代码文件) -#define LOG_TAG "can.disp" - -#include - -log_w("我是 can.disp 日志"); -``` - -**技巧二** ：为了实现按照模块、子模块作用域来限制日志输出级别的功能，可以按照下面的方式，在模块的头文件中定义以下宏定义： - -```C -/** - * Log default configuration for EasyLogger. - * NOTE: Must defined before including the - */ -#if !defined(LOG_TAG) - #define LOG_TAG "xx" -#endif -#undef LOG_LVL -#if defined(XX_LOG_LVL) - #define LOG_LVL XX_LOG_LVL -#endif -``` - -XX 是模块名称的缩写，该段内容务必定义在 `elog.h` 之前，否则失效；这样做的 **好处** 是，如果模块内的源文件没有定义 TAG ，则会自动引用该段内容中的定义的 TAG 。同时可以在 头文件中可以配置 `XX_LOG_LVL` ，这样只会输出比这个优先级高或相等级别的日志。当然 XX_LOG_LVL 这个宏也可以不定义，此时会输出全部级别的日志，定义为 ASSERT 级别，就只剩断言信息了。 -此时我们就能够实现 **源文件->子模块->模块->EasyLogger全局** 对于其中任何环节的日志配置及控制。调试时想要查看其中任何环节的日志，或者调整其中的某个环节日志级别，都会非常轻松，极大的提高了调试的灵活性及效率。 - -#### 1.3.2 输出 RAW 格式日志 - -``` -void elog_raw(const char *format, ...) -``` -|参数 |描述| -|:----- |:----| -|format |样式，类似`printf`首个入参| -|... |不定参| - -### 1.4 断言 - -#### 1.4.1 使用断言 - -EasyLogger自带的断言，可以直接用户软件，在断言表达式不成立后会输出断言信息并保持`while(1)`，或者执行断言钩子方法，钩子方法的设定参考 [`elog_assert_set_hook`](#114-设置断言钩子方法)。 - -``` -#define ELOG_ASSERT(EXPR) -#define assert(EXPR) //简化形式 -``` - -|参数 |描述| -|:----- |:----| -|EXPR |表达式| - -#### 1.4.2 设置断言钩子方法 - -默认断言钩子方法为空，设置断言钩子方法后。当断言`ELOG_ASSERT(EXPR)`中的条件不满足时，会自动执行断言钩子方法。断言钩子方法定义及使用可以参考上一章节的例子。 - -```c -void elog_assert_set_hook(void (*hook)(const char* expr, const char* func, size_t line)) -``` - -|参数 |描述| -|:----- |:----| -|hook |断言钩子方法| - -### 1.5 日志输出控制 - -#### 1.5.1 使能/失能日志输出 - -``` -void elog_set_output_enabled(bool enabled) -``` -|参数 |描述| -|:----- |:----| -|enabled |true: 使能，false: 失能| - -#### 1.5.2 获取日志使能状态 - -``` -bool elog_get_output_enabled(void) -``` - -#### 1.5.3 使能/失能日志输出锁 - -默认为使能状态，当系统或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_async_enabled(false); - /* 失能日志输出锁 */ - 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.6 日志格式及样式 - -#### 1.6.1 设置日志格式 - -每种级别可对应一种日志输出格式，日志的输出内容位置顺序固定，只可定义开启或关闭某子内容。可设置的日志子内容包括：级别、标签、时间、进程信息、线程信息、文件路径、行号、方法名。 - -> 注：默认为 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.6.2 使能/失能日志颜色 - -日志颜色功能是将各个级别日志按照颜色进行区分，默认颜色功能是关闭的。日志的颜色修改方法详见《EasyLogger 移植说明》中的 `设置参数` 章节。 - -``` -void elog_set_text_color_enabled(bool enabled) -``` - -|参数 |描述| -|:----- |:----| -|enabled |true: 使能，false: 失能| - -#### 1.6.3 查找日志级别 - -在日志中查找该日志的级别。查找成功则返回其日志级别，查找失败则返回 -1 。 - -> **注意** ：使用此功能时，请务必保证所有级别的设定的日志格式里均已开启输出日志级别功能，否则会断言错误。 - -``` -int8_t elog_find_lvl(const char *log) -``` - -|参数 |描述| -|:----- |:----| -|log |待查找的日志缓冲区| - -#### 1.6.4 查找日志标签 - -在日志中查找该日志的标签。查找成功则返回其日志标签及标签长度，查找失败则返回 NULL 。 - -> **注意** ：使用此功能时，首先请务必保证该级别对应的设定日志格式中，已开启输出日志标签功能，否则会断言错误。其次需保证设定日志标签中 **不能包含空格** ，否则会查询失败。 - -``` -const char *elog_find_tag(const char *log, uint8_t lvl, size_t *tag_len) -``` - -|参数 |描述| -|:----- |:----| -|log |待查找的日志缓冲区| -|lvl |待查找日志的级别| -|tag_len |查找到的标签长度| - -### 1.7 过滤日志 - -#### 1.7.1 设置过滤级别 - -默认过滤级别为5(详细)，用户可以任意设置。在设置高优先级后，低优先级的日志将不会输出。例如：设置当前过滤的优先级为3(警告)，则只会输出优先级别为警告、错误、断言的日志。 - -``` -void elog_set_filter_lvl(uint8_t level) -``` - -|参数 |描述| -|:----- |:----| -|level |级别| - -#### 1.7.2 设置过滤标签 - -默认过滤标签为空字符串(`""`)，即不过滤。当前输出日志的标签会与过滤标签做字符串匹配，日志的标签包含过滤标签，则该输出该日志。例如：设置过滤标签为WiFi，则系统中包含WiFi字样标签的（WiFi.Bsp、WiFi.Protocol、Setting.Wifi）日志都会被输出。 - ->注：RAW格式日志不支持标签过滤 - -``` -void elog_set_filter_tag(const char *tag) -``` - -|参数 |描述| -|:----- |:----| -|tag |标签| - -#### 1.7.3 设置过滤关键词 - -默认过滤关键词为空字符串("")，即不过滤。检索当前输出日志中是否包含该关键词，包含则允许输出。 - -> 注：对于配置较低的MCU建议不开启关键词过滤（默认为不过滤），增加关键字过滤将会在很大程度上减低日志的输出效率。实际上当需要实时查看日志时，过滤关键词功能交给上位机做会更轻松，所以后期的跨平台日志助手开发完成后，就无需该功能。 - -``` -void elog_set_filter_kw(const char *keyword) -``` - -|参数 |描述| -|:----- |:----| -|keyword |关键词| - -#### 1.7.4 设置过滤器 - -设置过滤器后，只输出符合过滤要求的日志。所有参数设置方法，可以参考上述3个章节。 - -``` -void elog_set_filter(uint8_t level, const char *tag, const char *keyword) -``` - -|参数 |描述| -|:----- |:----| -|level |级别| -|tag |标签| -|keyword |关键词| - -#### 1.7.3 按模块的级别过滤 - -这里指的**模块**代表一类具有相同标签属性的日志代码。有些时候需要在运行时动态的修改某一个模块的日志输出级别。 - -``` -void elog_set_filter_tag_lvl(const char *tag, uint8_t level); -``` - -|参数 |描述| -|:----- |:----| -|tag |日志的标签| -|level |设定的日志级别| - -参数 level 日志级别可取如下值： - -|**级别** |**名称** | -| --------------------- | ---------------- | -| 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 缓冲输出模式 - -#### 1.8.1 使能/失能缓冲输出模式 - -``` -void elog_buf_enabled(bool enabled) -``` -|参数 |描述| -|:----- |:----| -|enabled |true: 使能，false: 失能| - - -#### 1.8.2 将缓冲区中的日志全部输出 - -在缓冲输出模式下，执行此方法可以将缓冲区中的日志全部输出干净。 - -``` -void elog_flush(void) -``` - -### 1.9 异步输出模式 - -#### 1.9.1 使能/失能异步输出模式 - -``` -void elog_async_enabled(bool enabled) -``` -|参数 |描述| -|:----- |:----| -|enabled |true: 使能，false: 失能| - -#### 1.9.2 在异步输出模式下获取日志 - -在异步输出模式下，如果用户没有启动 pthread 库，此时需要启用额外线程来实现日志的异步输出功能。使用此方法即可获取到异步输出缓冲区中的指定长度的日志。如果设定日志长度小于日志缓冲区中已存在日志长度，将只会返回已存在日志长度。 - -```C -size_t elog_async_get_log(char *log, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|log |取出的日志内容| -|size |待取出的日志大小| - -#### 1.9.3 在异步输出模式下获取行日志（以换行符结尾） - -异步模式下获取行日志与 1.9.2 中的直接获取日志功能类似，只不过这里所获取到的日志内容，必须为 **行日志** （以换行符结尾）格式，为后续的日志按行分析功能提供便利。如果设定日志长度小于日志缓冲区中已存在日志长度，将只会返回日志缓冲区中行日志的长度。如果缓冲区中不存在行日志，将不能保证返回的日志格式是行日志。 - -```C -size_t elog_async_get_line_log(char *log, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|log |取出的行日志内容| -|size |待取出的行日志大小| - -## 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 deleted file mode 100644 index 0badd0c..0000000 --- a/docs/zh/api/readme.md +++ /dev/null @@ -1,4 +0,0 @@ -|文件名 |描述| -|:----- |:----| -|flash.md |flash插件API文档| -|kernel.md |核心功能API文档| \ No newline at end of file diff --git a/docs/zh/images/EasyLoggerDemo.gif b/docs/zh/images/EasyLoggerDemo.gif deleted file mode 100644 index dd28138..0000000 Binary files a/docs/zh/images/EasyLoggerDemo.gif and /dev/null differ diff --git a/docs/zh/images/LogDemo.gif b/docs/zh/images/LogDemo.gif deleted file mode 100644 index b99b662..0000000 Binary files a/docs/zh/images/LogDemo.gif and /dev/null differ diff --git a/docs/zh/images/TextColor.png b/docs/zh/images/TextColor.png deleted file mode 100644 index a321de5..0000000 Binary files a/docs/zh/images/TextColor.png and /dev/null differ diff --git a/docs/zh/port/flash.md b/docs/zh/port/flash.md deleted file mode 100644 index 7823917..0000000 --- a/docs/zh/port/flash.md +++ /dev/null @@ -1,116 +0,0 @@ -# EasyLogger Flash插件移植说明 - ---- - -## 1、准备工作 - -在使用Flash插件前，保证EasyLogger的核心功能已经在项目中移植成功（[移植文档点这里](https://github.com/armink/EasyLogger/blob/master/docs/zh/port/kernel.md)）。再确认已下载的源码中存在`\easylogger\plugins\flash`文件夹，该文件夹为Flash插件的所有源码。 - -## 2、导入项目 - -目前只有STM32F10x平台的RT-Thread系统Demo里面使用了Flash插件，如果你的项目与这个Demo平台一致，则可以先直接跳过2、3、4章节，按照第5章的要求设置参数，并运行、验证Demo。验证通过再按照下面的导入项目要求，将Demo中的移植文件直接导入到项目中即可。 - -- 1、打开`\easylogger\plugins\flash`文件夹，内部文件结构如下： - -|源文件 |描述 | -|:------------------------------ |:----- | -|elog_flash.c |Flash插件源码| -|elog_flash.h |Flash插件头文件| -|elog_flash_cfg.h |Flash插件配置头文件| -|elog_flash_port.c |Flash插件移植文件| - - -- 2、将`\easylogger\plugins\flash`下的所有文件拷贝到项目中； -- 3、添加`elog_flash.c`及`elog_flash_port.c`这些文件到项目的编译路径中； -- 4、添加插件所在文件夹到编译的头文件目录列表中； - -## 3、移植接口 - -### 3.1 移植初始化 - -Flash插件移植初始化。初始化Flash插件移植所需的资源等等。 - -```C -ElogErrCode elog_flash_port_init(void) -``` - -### 3.2 Flash中的日志被读取后的输出接口 - -将日志从Flash中读取后，调用`elog_flash_outout()`、`elog_flash_outout_all()`及`elog_flash_outout_recent()`进行输出展示时，将会调用此移植接口。可以在里面增加输出到终端、网络等功能。 - -```C -void elog_flash_port_output(const char *log, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|log |日志内容| -|size |日志大小| - -例子： -```c -void elog_flash_port_output(const char *log, size_t size) { - /* output to terminal */ - rt_kprintf("%.*s", size, log); -} - -``` -### 3.3 资源同步锁-加锁 - -对日志写入Flash操作进行加锁，保证日志在并发写入时的正确性。有操作系统时可以使用获取信号量来加锁，裸机时可以通过关闭全局中断来加锁。 - -```C -void elog_flash_port_lock(void) -``` - -### 3.4 资源同步锁-解锁 - -与加锁功能对应。 - -```C -void elog_flash_port_unlock(void) -``` -## 4、设置参数 - -配置时需要修改项目中的`elog_flash_cfg.h`文件，开启、关闭、修改对应的宏即可。 - -### 4.1 缓冲模式 - -开启后，需要写入Flash的日志会先存储至RAM缓冲区，当缓冲区满时，缓冲区中的所有日志将自动写入Flash。如果关闭，所有日志在输出时会立刻写入Flash。 - -- 默认状态：开启 -- 操作方法：开启、关闭`ELOG_FLASH_USING_BUF_MODE`宏即可 - -#### 4.1.1 缓冲区大小 - -当开启缓冲模式后，此配置才会生效，单位：byte。 - -- 操作方法：修改`ELOG_FLASH_BUF_SIZE`宏对应值即可 - -## 5、测试验证 - -每次使用前，务必核心功能都已经初始化完成，再调用`elog_flash_init()`方法对Flash插件进行初始化，保证初始化没问题后，再调用`elog_start()`方法启动EasyLogger，最后就可以使用Flash插件自带的API方法进行测试。如果使用的RT-Thread的Demo，则可以按照[这里的命令要求](https://github.com/armink/EasyLogger/tree/master/demo/os/rt-thread/stm32f10x#22-flash-log将日志保存到flash中)，接上finsh串口，输入finsh命令即可测试。 - -摘取自STM32平台下RT-Thread Demo中的初始化过程（[点击查看全部](https://github.com/armink/EasyLogger/blob/master/demo/os/rt-thread/stm32f10x/app/src/app_task.c)）： -```c -/* 初始化EasyFlash及EasyLogger */ -if ((easyflash_init() == EF_NO_ERR)&&(elog_init() == ELOG_NO_ERR)) { - /* 设置日志格式 */ - elog_set_fmt(ELOG_LVL_ASSERT, ELOG_FMT_ALL & ~ELOG_FMT_P_INFO); - 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_FMT_P_INFO)); - elog_set_fmt(ELOG_LVL_VERBOSE, ELOG_FMT_ALL & ~(ELOG_FMT_FUNC | ELOG_FMT_P_INFO)); - /* 设置EasyLogger的断言钩子方法 */ - elog_assert_set_hook(elog_user_assert_hook); - /* 初始化EasyLogger的Flash 插件 */ - elog_flash_init(); - /* 启动EasyLogger */ - elog_start(); - /* 设置RT-Thread提供的硬件异常钩子方法 */ - rt_hw_exception_install(exception_hook); - /* 设置RT-Thread断言钩子方法 */ - rt_assert_set_hook(rtt_user_assert_hook); -} -``` diff --git a/docs/zh/port/kernel.md b/docs/zh/port/kernel.md deleted file mode 100644 index 7cac8d1..0000000 --- a/docs/zh/port/kernel.md +++ /dev/null @@ -1,260 +0,0 @@ -# EasyLogger 核心功能移植说明 - ---- - -## 1、下载源码 - -[点击此链接](https://github.com/armink/EasyLogger/archive/master.zip)即可直接下载位于Github上的源码。软件版本号位于 `\easylogger\inc\elog.h` 的 `ELOG_SW_VERSION` 宏定义。当然你也可以选择使用Git工具直接克隆到本地。 - -> 建议：点击项目主页 https://github.com/armink/EasyLogger 右上角 **Watch & Star**，这样项目有更新时，会及时以邮件形式通知你。 - -如果Github下载太慢，也可以点击项目位于的国内仓库下载的链接([OSChina](https://git.oschina.net/Armink/EasyLogger/repository/archive?ref=master)|[Coding](https://coding.net/u/armink/p/EasyLogger/git/archive/master))。 - -## 2、导入项目 - -在导入到项目前，先打开[`\demo\`](https://github.com/armink/EasyLogger/tree/master/demo)文件夹，检查下有没有与项目平台一致的Demo。如果有则先直接跳过2、3、4章节，按照第5章的要求设置参数，并运行、验证Demo。验证通过再按照下面的导入项目要求，将Demo中的移植文件直接导入到项目中即可。 - -- 1、先解压下载好的源码包，文件的目录结构大致如下： - -|源文件 |描述 | -|:------------------------------ |:----- | -|\easylogger\src\elog.c |核心功能源码| -|\easylogger\src\elog_async.c |核心功能异步输出模式源码| -|\easylogger\src\elog_buf.c |核心功能缓冲输出模式源码| -|\easylogger\src\elog_utils.c |EasyLogger常用小工具| -|\easylogger\port\elog_port.c |不同平台下的EasyLogger移植接口| -|\easylogger\plugins\ |插件源码目录| -|\docs\zh\ |所有中文文档目录| -|\demo\non_os\stm32f10x\ |stm32f10x裸机的 demo| -|\demo\os\linux\ |linux平台 demo| -|\demo\os\windows\ |windows平台 demo| -|\demo\os\rt-thread\stm32f10x\ |stm32f10x基于[RT-Thread](http://www.rt-thread.org/)的demo（包含Flash插件demo）| - - -- 2、将`\easylogger\`（里面包含`inc`、`src`及`port`的那个）文件夹拷贝到项目中； -- 3、添加`\easylogger\src\elog.c`、`\easylogger\src\elog_utils.c`及`\easylogger\port\elog_port.c`这些文件到项目的编译路径中（elog_async.c 及 elog_buf.c 视情况选择性添加）； -- 4、添加`\easylogger\inc\`文件夹到编译的头文件目录列表中； - -## 3、移植接口 - -### 3.1 移植初始化 - -EasyLogger移植初始化。初始化EasyLogger移植所需的资源等等。 - -```C -ElogErrCode elog_port_init(void) -``` - -### 3.2 日志输出接口 - -日志最终输出的末端接口。可以在里面增加输出到终端、输出到文件、输出到Flash等方法。 - -```C -void elog_port_output(const char *log, size_t size) -``` - -|参数 |描述| -|:----- |:----| -|log |日志内容| -|size |日志大小| - -例子： -```c -void elog_port_output(const char *log, size_t size) { - /* output to terminal */ - printf("%.*s", size, log); - /* output to flash */ - elog_flash_write(log, size); -} -``` - -### 3.3 对日志输出加锁 - -对日志输出方法进行加锁，保证日志在并发输出时的正确性。有操作系统时可以使用获取信号量来加锁，裸机时可以通过关闭全局中断来加锁。 - -```C -void elog_port_output_lock(void) -``` - -### 3.4 对日志输出解锁 - -与日志输出加锁功能对应。 - -```C -void elog_port_output_unlock(void) -``` - -### 3.5 获取当前时间 - -返回当前时间，将会显示在日志中。 - -```C -const char *elog_port_get_time(void) -``` - -### 3.6 获取进程信息 - -返回进程信息，将会显示在日志中。（没有则可以返回 `""` ） - -```C -const char *elog_port_get_p_info(void) -``` - -### 3.7 获取线程信息 - -返回线程信息，将会显示在日志中。（没有则可以返回 `""`） - -```C -const char *elog_port_get_t_info(void) -``` - -## 4、设置参数 - -配置时需要修改项目中的`elog_cfg.h`文件，开启、关闭、修改对应的宏即可。 - -### 4.1 输出开关 - -开启后，日志才会被输出。如果关闭，所有日志输出代码都将会被替换为空。 - -- 操作方法：开启、关闭`ELOG_OUTPUT_ENABLE`宏即可 - -### 4.2 输出级别 - -此方法为静态设置输出级别。设置后，比当前输出级别低的日志输出代码将会被替换为空。 - -输出控制级别： `ELOG_OUTPUT_ENABLE（总开关） > ELOG_OUTPUT_LVL（静态） > elog_set_filter（动态）` - -- 操作方法：修改`ELOG_OUTPUT_LVL`宏对应值即可 - -可选的设置级别如下： -``` -/* output log's level */ -#define ELOG_LVL_ASSERT 0 -#define ELOG_LVL_ERROR 1 -#define ELOG_LVL_WARN 2 -#define ELOG_LVL_INFO 3 -#define ELOG_LVL_DEBUG 4 -#define ELOG_LVL_VERBOSE 5 -``` -### 4.3 断言开关 - -开启后，将会启动断言检查功能。如果关闭，所有断言检查代码都将会被替换为空。 - -- 操作方法：开启、关闭`ELOG_ASSERT_ENABLE`宏即可 - -### 4.4 每行日志的缓冲区大小 - -该配置决定了日志一行最多输出多少字符，单位：byte。 - -- 操作方法：修改`ELOG_LINE_BUF_SIZE`宏对应值即可 - -### 4.5 行号最大长度 - -建议设置`5`较为合适，用户可以根据自己的文件行号最大值进行设置，例如最大行号为：`9999`，则可以设置行号最大长度为`4` - -- 操作方法：修改`ELOG_LINE_NUM_MAX_LEN`宏对应值即可 - -### 4.6 过滤标签最大长度 - -日志中标签内容及用户设置过滤标签的最大长度，单位：byte。 - -- 操作方法：修改`ELOG_FILTER_TAG_MAX_LEN`宏对应值即可 - -### 4.7 过滤关键词最大长度 - -用户可设置过滤关键字的最大长度，单位：byte。 - -- 操作方法：修改`ELOG_FILTER_KW_MAX_LEN`宏对应值即可 - -### 4.8 标签 + 级别过滤器的最大数目 - -最大支持的动态日志级别过滤的模块（标签）数量，详见 ：`elog_set_filter_tag_lvl` - -- 操作方法：修改`ELOG_FILTER_TAG_LVL_MAX_NUM`宏对应值即可 - -### 4.9 换行符 - -用户可以根据自己的使用场景自定义换行符，例如：`"\r\n"`，`"\n"` - -- 操作方法：修改`ELOG_NEWLINE_SIGN`宏对应值即可 - -### 4.10 颜色 - -> **注意** ：启用颜色功能需先定义 `ELOG_COLOR_ENABLE` - -每个级别的日志均有默认颜色。如果想修改，请先查看在 `elog.c` 的头部定义的各种颜色及字体风格，这里以修改 `VERBOSE` 级别日志来举例： - -首先选择前景色为白色，再选择背景色为黑色，最后字体风格为粗体 - -那么最终的配置如下： - -``` -#define ELOG_COLOR_VERBOSE (F_WHITE B_BLACK S_BOLD) -``` - -- 操作方法：增加并修改`ELOG_COLOR_VERBOSE`宏对应值即可，其他级别日志颜色的修改以此类推 - -### 4.11 异步输出模式 - -开启异步输出模式后，将会提升用户应用程序的执行效率。应用程序在进行日志输出时，无需等待日志彻底输出完成，即可直接返回。 - -- 操作方法：开启、关闭`ELOG_ASYNC_OUTPUT_ENABLE`宏即可 - -#### 4.11.1 异步输出日志的最高级别 - -日志低于或等于该级别时，才会通过异步输出。高于该级别的日志都将按照默认的同步方式输出。这样的好处是，提升了较高级别的日志输出的实时性。 - -- 默认级别：`ELOG_LVL_ASSERT` ，不定义此宏，将会自动按照默认值设置 -- 操作方法：修改`ELOG_ASYNC_OUTPUT_LVL`宏对应值即可 - -#### 4.11.2 异步输出模式缓冲区大小 - -- 默认大小：`(ELOG_LINE_BUF_SIZE * 10)` ，不定义此宏，将会自动按照默认值设置 -- 操作方法：修改`ELOG_ASYNC_OUTPUT_BUF_SIZE`宏对应值即可 - -#### 4.11.3 异步按行输出日志 - -由于异步输出方式内部拥有缓冲区，所以直接输出缓冲区中积累的日志时，日志移植输出方法 (`elog_port_output`) 输出的日志将不会按照 **行日志** （以换行符结尾）的格式进行输出。这使得无法在移植输出方法中完成日志的分析处理。开启此功能后，将会最大限度保证移植输出方法每次输出的日志格式都为行日志。 - -- 操作方法：开启、关闭`ELOG_ASYNC_LINE_OUTPUT`宏即可 - -#### 4.11.4 启用 pthread 库 - -异步输出模式默认是使用 POSIX 的 pthread 库来实现，用户的平台如果支持 pthread ，则可以开启此宏。对于一些缺少 pthread 的支持平台，可以关闭此宏，参考 `elog_async.c` 中关于日志异步输出线程的实现方式，自己动手实现此功能。 - -- 操作方法：开启、关闭`ELOG_ASYNC_OUTPUT_USING_PTHREAD`宏即可 - -### 4.12 缓冲输出模式 - -开启缓冲输出模式后，如果缓冲区不满，用户线程在进行日志输出时，无需等待日志彻底输出完成，即可直接返回。但当日志缓冲区满以后，将会占用用户线程，自动将缓冲区中的日志全部输出干净。同时用户也可以在非日志输出线程，通过定时等机制使用 `void elog_flush(void)` 将缓冲区中的日志输出干净。 - -- 操作方法：开启、关闭`ELOG_BUFF_OUTPUT_ENABLE`宏即可 - -#### 4.12.1 缓冲输出模式缓冲区大小 - -- 默认大小：`(ELOG_LINE_BUF_SIZE * 10)` ，不定义此宏，将会自动按照默认值设置 -- 操作方法：修改`ELOG_BUF_OUTPUT_BUF_SIZE`宏对应值即可 - - -## 5、测试验证 - -如果`\demo\`文件夹下有与项目平台一致的Demo，则直接编译运行，观察测试结果即可。无需关注下面的步骤。 - -每次使用前，务必先执行`elog_init()`方法对EasyLogger库进行初始化，保证初始化没问题后，再设置输出格式、过滤级别、断言钩子等，最后记得调用`elog_start()`方法启动EasyLogger，否则EasyLogger将不会开始工作。启动后接上终端就即可日志的输出信息，可以参考并运行这里的[日志测试函数](https://github.com/armink/EasyLogger/blob/master/demo/os/windows/main.c#L76-L88)。如果出现错误或断言，需根据提示信息检查移植配置及接口。 - -下面为常见初始化方式（[点击查看源码](https://github.com/armink/EasyLogger/blob/master/demo/os/windows/main.c)） -```c -/* close printf buffer */ -setbuf(stdout, NULL); -/* initialize EasyLogger */ -elog_init(); -/* set EasyLogger log format */ -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); -/* start EasyLogger */ -elog_start(); -``` \ No newline at end of file diff --git a/docs/zh/port/readme.md b/docs/zh/port/readme.md deleted file mode 100644 index d17d525..0000000 --- a/docs/zh/port/readme.md +++ /dev/null @@ -1,4 +0,0 @@ -|文件名 |描述| -|:----- |:----| -|flash.md |flash插件移植文档| -|kernel.md |核心功能移植文档| \ No newline at end of file diff --git a/docs/zh/readme.md b/docs/zh/readme.md deleted file mode 100644 index 7a9d3cf..0000000 --- a/docs/zh/readme.md +++ /dev/null @@ -1,4 +0,0 @@ -|文件名 |描述| -|:----- |:----| -|api |API说明| -|port |移植说明| \ No newline at end of file