From 52cd7dae4b4cd6284f68f917a86ee61fbc74146b Mon Sep 17 00:00:00 2001 From: armink Date: Tue, 11 Aug 2015 16:13:05 +0800 Subject: [PATCH] =?UTF-8?q?1=E3=80=81=E3=80=90=E5=A2=9E=E5=8A=A0=E3=80=91?= =?UTF-8?q?=E6=A0=B8=E5=BF=83=E5=8A=9F=E8=83=BD=E7=A7=BB=E6=A4=8D=E8=AF=B4?= =?UTF-8?q?=E6=98=8E=E6=96=87=E6=A1=A3=EF=BC=8C=E4=BD=8D=E7=BD=AE=EF=BC=9A?= =?UTF-8?q?\docs\zh\port\kernel.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: armink --- docs/zh/port/kernel.md | 191 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 190 insertions(+), 1 deletion(-) diff --git a/docs/zh/port/kernel.md b/docs/zh/port/kernel.md index 56965e6..f4f5a92 100644 --- a/docs/zh/port/kernel.md +++ b/docs/zh/port/kernel.md @@ -1 +1,190 @@ -#即将发布... \ No newline at end of file +# 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_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`这些文件到项目的编译路径中； +- 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 缓冲区大小 + +缓冲区大小决定了日志一行最多输出多少字符，单位：byte。 + +- 操作方法：修改`ELOG_BUF_SIZE`宏对应值即可 + +### 4.4 行号最大长度 + +建议设置`5`较为合适，用户可以根据自己的文件行号最大值进行设置，例如最大行号为：`9999`，则可以设置行号最大长度为`4` + +- 操作方法：修改`ELOG_LINE_NUM_MAX_LEN`宏对应值即可 + +### 4.5 过滤标签最大长度 + +日志中标签内容及用户设置过滤标签的最大长度，单位：byte。 + +- 操作方法：修改`ELOG_FILTER_TAG_MAX_LEN`宏对应值即可 + +### 4.6 过滤关键词最大长度 + +用户可设置过滤关键字的最大长度，单位：byte。 + +- 操作方法：修改`ELOG_FILTER_KW_MAX_LEN`宏对应值即可 + +### 4.7 换行符 + +用户可以根据自己的使用场景自定义换行符，例如：`"\r\n"`，`"\n"` + +- 操作方法：修改`ELOG_NEWLINE_SIGN`宏对应值即可 + +## 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#L44-L56)） +```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