EasyLogger/docs/zh/port/kernel.md

EasyLogger 核心功能移植说明

---

1、下载源码

点击此链接即可直接下载位于Github上的源码。软件版本号位于 \easylogger\inc\elog.h 的 ELOG_SW_VERSION 宏定义。当然你也可以选择使用Git工具直接克隆到本地。

建议：点击项目主页 https://github.com/armink/EasyLogger 右上角 Watch & Star，这样项目有更新时，会及时以邮件形式通知你。

如果Github下载太慢，也可以点击项目位于的国内仓库下载的链接(OSChina|Coding)。

2、导入项目

在导入到项目前，先打开\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的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移植所需的资源等等。

ElogErrCode elog_port_init(void)

3.2 日志输出接口

日志最终输出的末端接口。可以在里面增加输出到终端、输出到文件、输出到Flash等方法。

void elog_port_output(const char *log, size_t size)

参数	描述
log	日志内容
size	日志大小

例子：

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 对日志输出加锁

对日志输出方法进行加锁，保证日志在并发输出时的正确性。有操作系统时可以使用获取信号量来加锁，裸机时可以通过关闭全局中断来加锁。

void elog_port_output_lock(void)

3.4 对日志输出解锁

与日志输出加锁功能对应。

void elog_port_output_unlock(void)

3.5 获取当前时间

返回当前时间，将会显示在日志中。

const char *elog_port_get_time(void)

3.6 获取进程信息

返回进程信息，将会显示在日志中。（没有则可以返回 "" ）

const char *elog_port_get_p_info(void)

3.7 获取线程信息

返回线程信息，将会显示在日志中。（没有则可以返回 ""）

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将不会开始工作。启动后接上终端就即可日志的输出信息，可以参考并运行这里的日志测试函数。如果出现错误或断言，需根据提示信息检查移植配置及接口。

下面为常见初始化方式（点击查看源码）

/* 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();