大型量产固件的工程实践七嵌入式调试日志系统设计本文是《大型量产固件的工程实践》专栏第 7 篇。上一篇第 6 篇《嵌入式错误码体系设计》 下一篇第 7 篇实战《日志打印实现源码与使用范例》本文讲设计理念配套的完整实现见姊妹篇《07b日志打印实现源码与使用范例》。两篇命名与机制完全一致。一、调试日志的痛点嵌入式固件没有屏幕串口打印几乎是唯一的眼睛。但日志系统如果没设计好会变成新的麻烦调完了日志没删干净量产固件还在疯狂打印想只看网络模块的日志却被其他模块的日志刷屏打印太多把串口带宽占满反而拖慢系统。一套好的日志系统要解决三件事分级、分类、可开关。二、日志分级位掩码级别给日志分等级。这套设计里等级用位掩码1 n表示而不是顺序枚举——好处是可以组合一个整数就能表达允许多个级别。// 日志级别位掩码可组合#defineTRACE_LV_ERROR(10)/* 错误信息 */#defineTRACE_LV_WARN(11)/* 警告信息 */#defineTRACE_LV_INFO(12)/* 提示信息 */#defineTRACE_LV_STAT(13)/* 状态信息 */#defineTRACE_LV_PROC(14)/* 过程信息 */#defineTRACE_LV_INIT(15)/* 初始化过程信息 */#defineTRACE_LV_MASS(16)/* 可能大量输出的信息 */#defineTRACE_LV_PROF(17)/* 性能分析信息 */#defineTRACE_LV_CRITICAL(18)/* 关键信息 */为什么用位掩码级别过滤的典型判断是这个模块允许输出哪些级别用位掩码的话uint16_tallowTRACE_LV_ERROR|TRACE_LV_WARN;// 只允许错误 警告if(allowTRACE_LV_INFO){/* 该级别被允许 */}一个按位与就完成判断比比较大小的枚举更灵活——例如你可以给某个模块只开ERROR | STAT而另一个模块全开。三、日志分类按模块过滤光有级别还不够几十个模块的日志混在一起找问题像大海捞针。给日志加模块维度每个模块一个独立编号// 模块标识示例性划分实际按项目需求定义#defineTRACE_PART_DEFAULT(0)/* 未分类 */#defineTRACE_PART_SYS(1)/* 系统 */#defineTRACE_PART_IO(2)/* IO */#defineTRACE_PART_UART(3)/* 串口 */#defineTRACE_PART_I2C(4)/* I2C 总线 */#defineTRACE_PART_SPI(5)/* SPI 总线 */#defineTRACE_PART_GPIO(6)/* GPIO */#defineTRACE_PART_FLASH(7)/* 存储 */#defineTRACE_PART_DMA(8)/* DMA */#defineTRACE_PART_TIMER(9)/* 定时器 */#defineTRACE_PART_POWER(10)/* 电源 */#defineTRACE_PART_NETWORK(11)/* 网络 */#defineTRACE_PART_ANY(255)/* 任意模块 */过滤机制用一个数组每个模块一个元素元素值是该模块允许输出的级别掩码uint16_tpart_ctrl[32];// 32 个模块的级别过滤// 只关心网络模块网络开 ERROR|WARN|INFO其余模块静默for(inti0;i32;i)part_ctrl[i]0;part_ctrl[TRACE_PART_NETWORK]TRACE_LV_ERROR|TRACE_LV_WARN|TRACE_LV_INFO;收益排查网络断连问题时把其他模块静默网络日志一目了然。四、统一入口宏TRACE分级和分类最终收敛到一个统一入口宏。它把级别、模块、格式串都收进去并自动追加[函数名:行号]方便定位#defineTRACE(lv,part,fmt,...)\trace_print(lv,part,[%s:%d] fmt,__func__,__LINE__,##__VA_ARGS__)// 使用TRACE(TRACE_LV_INFO,TRACE_PART_I2C,id 0x%04X\r\n,i2c_read_id());TRACE(TRACE_LV_ERROR,TRACE_PART_SPI,read timeout, ret%d\r\n,ret);输出自动带上定位信息[INFO:I2C] [i2c_dev_init:20] id 0x1234 [ERROR:SPI] [spi_read:35] read timeout, ret-1000trace_print内部先做模块 × 级别过滤再格式化、再输出voidtrace_print(intlv,intpart,constchar*fmt,...){if((part0)||(part32))return;// 模块编号越界if(!(part_ctrl[part]lv))return;// 该模块该级别被过滤/* 格式化 写入缓冲 输出 */// ...}五、可开关运行时通道 编译期裁剪5.1 运行时通道开关全局控制日志输出到哪些通道用一个全局控制字的位来使能#defineTRACE_CTRL_UART0x02/* 串口通道 */#defineTRACE_CTRL_LINK0x01/* 网络通道 */#defineTRACE_CTRL_BUF0x20/* 记录到环形缓冲 */#defineTRACE_CTRL_EEPROM0x10/* 记录到 EEPROM */uint32_tglobal_ctrl;if(global_ctrlTRACE_CTRL_UART){/* 输出到串口 */}if(global_ctrlTRACE_CTRL_BUF){/* 写入环形缓冲 */}设计要点日志先写入环形缓冲2KB 级串口输出可控默认可关闭实时打印。这样高频日志不会直接刷串口拖慢系统需要时再一次性读出。5.2 编译期裁剪量产版本如需彻底零开销可以在编译期把 TRACE 宏裁成空语句#ifTRACE_ENABLED#defineTRACE(lv,part,fmt,...)trace_print(lv,part,[%s:%d] fmt,__func__,__LINE__,##__VA_ARGS__)#else#defineTRACE(lv,part,fmt,...)do{}while(0)// 空操作零开销#endif六、常见反模式6.1 没有开关日志写死// ❌ 没有开关量产固件还在疯狂打印printf(read: %d\r\n,val);// 到处都是裸 printf量产固件带着满屏printf出货串口带宽被占满性能也受影响。6.2 日志没有级别和模块全靠注释// ❌ 调试时临时加的打印靠记得删printf( debug: i%d \n,i);// 这种日志要么忘删要么删了又加回来6.3 日志与业务逻辑耦合// ❌ 日志函数里夹带业务逻辑#defineDEBUG_LOG(x){g_debug_flagx;printf(...);}// 改了业务状态日志宏必须纯打印绝不能影响业务状态——否则关掉日志就改变了程序行为这是极隐蔽的 bug。七、小结一套合格的调试日志系统四个要素要素作用实现分级控制详细程度位掩码TRACE_LV_*可组合分类按模块过滤TRACE_PART_*part_ctrl[]掩码可开关运行时/编译期裁剪global_ctrl通道位 TRACE_ENABLED宏可定位自动带位置TRACE宏拼入__func__/__LINE__把这四样做扎实日志就从临时调试手段升级成了可长期维护的观测工具。下一篇07b给出这套设计的完整可运行实现——分级过滤、三指针环形缓冲、多通道输出的全部源码与使用范例。本文仅介绍嵌入式调试日志系统的通用设计方法不涉及任何具体项目或产品的私有实现。
大型量产固件的工程实践七嵌入式调试日志系统设计本文是《大型量产固件的工程实践》专栏第 7 篇。上一篇第 6 篇《嵌入式错误码体系设计》 下一篇第 7 篇实战《日志打印实现源码与使用范例》本文讲设计理念配套的完整实现见姊妹篇《07b日志打印实现源码与使用范例》。两篇命名与机制完全一致。一、调试日志的痛点嵌入式固件没有屏幕串口打印几乎是唯一的眼睛。但日志系统如果没设计好会变成新的麻烦调完了日志没删干净量产固件还在疯狂打印想只看网络模块的日志却被其他模块的日志刷屏打印太多把串口带宽占满反而拖慢系统。一套好的日志系统要解决三件事分级、分类、可开关。二、日志分级位掩码级别给日志分等级。这套设计里等级用位掩码1 n表示而不是顺序枚举——好处是可以组合一个整数就能表达允许多个级别。// 日志级别位掩码可组合#defineTRACE_LV_ERROR(10)/* 错误信息 */#defineTRACE_LV_WARN(11)/* 警告信息 */#defineTRACE_LV_INFO(12)/* 提示信息 */#defineTRACE_LV_STAT(13)/* 状态信息 */#defineTRACE_LV_PROC(14)/* 过程信息 */#defineTRACE_LV_INIT(15)/* 初始化过程信息 */#defineTRACE_LV_MASS(16)/* 可能大量输出的信息 */#defineTRACE_LV_PROF(17)/* 性能分析信息 */#defineTRACE_LV_CRITICAL(18)/* 关键信息 */为什么用位掩码级别过滤的典型判断是这个模块允许输出哪些级别用位掩码的话uint16_tallowTRACE_LV_ERROR|TRACE_LV_WARN;// 只允许错误 警告if(allowTRACE_LV_INFO){/* 该级别被允许 */}一个按位与就完成判断比比较大小的枚举更灵活——例如你可以给某个模块只开ERROR | STAT而另一个模块全开。三、日志分类按模块过滤光有级别还不够几十个模块的日志混在一起找问题像大海捞针。给日志加模块维度每个模块一个独立编号// 模块标识示例性划分实际按项目需求定义#defineTRACE_PART_DEFAULT(0)/* 未分类 */#defineTRACE_PART_SYS(1)/* 系统 */#defineTRACE_PART_IO(2)/* IO */#defineTRACE_PART_UART(3)/* 串口 */#defineTRACE_PART_I2C(4)/* I2C 总线 */#defineTRACE_PART_SPI(5)/* SPI 总线 */#defineTRACE_PART_GPIO(6)/* GPIO */#defineTRACE_PART_FLASH(7)/* 存储 */#defineTRACE_PART_DMA(8)/* DMA */#defineTRACE_PART_TIMER(9)/* 定时器 */#defineTRACE_PART_POWER(10)/* 电源 */#defineTRACE_PART_NETWORK(11)/* 网络 */#defineTRACE_PART_ANY(255)/* 任意模块 */过滤机制用一个数组每个模块一个元素元素值是该模块允许输出的级别掩码uint16_tpart_ctrl[32];// 32 个模块的级别过滤// 只关心网络模块网络开 ERROR|WARN|INFO其余模块静默for(inti0;i32;i)part_ctrl[i]0;part_ctrl[TRACE_PART_NETWORK]TRACE_LV_ERROR|TRACE_LV_WARN|TRACE_LV_INFO;收益排查网络断连问题时把其他模块静默网络日志一目了然。四、统一入口宏TRACE分级和分类最终收敛到一个统一入口宏。它把级别、模块、格式串都收进去并自动追加[函数名:行号]方便定位#defineTRACE(lv,part,fmt,...)\trace_print(lv,part,[%s:%d] fmt,__func__,__LINE__,##__VA_ARGS__)// 使用TRACE(TRACE_LV_INFO,TRACE_PART_I2C,id 0x%04X\r\n,i2c_read_id());TRACE(TRACE_LV_ERROR,TRACE_PART_SPI,read timeout, ret%d\r\n,ret);输出自动带上定位信息[INFO:I2C] [i2c_dev_init:20] id 0x1234 [ERROR:SPI] [spi_read:35] read timeout, ret-1000trace_print内部先做模块 × 级别过滤再格式化、再输出voidtrace_print(intlv,intpart,constchar*fmt,...){if((part0)||(part32))return;// 模块编号越界if(!(part_ctrl[part]lv))return;// 该模块该级别被过滤/* 格式化 写入缓冲 输出 */// ...}五、可开关运行时通道 编译期裁剪5.1 运行时通道开关全局控制日志输出到哪些通道用一个全局控制字的位来使能#defineTRACE_CTRL_UART0x02/* 串口通道 */#defineTRACE_CTRL_LINK0x01/* 网络通道 */#defineTRACE_CTRL_BUF0x20/* 记录到环形缓冲 */#defineTRACE_CTRL_EEPROM0x10/* 记录到 EEPROM */uint32_tglobal_ctrl;if(global_ctrlTRACE_CTRL_UART){/* 输出到串口 */}if(global_ctrlTRACE_CTRL_BUF){/* 写入环形缓冲 */}设计要点日志先写入环形缓冲2KB 级串口输出可控默认可关闭实时打印。这样高频日志不会直接刷串口拖慢系统需要时再一次性读出。5.2 编译期裁剪量产版本如需彻底零开销可以在编译期把 TRACE 宏裁成空语句#ifTRACE_ENABLED#defineTRACE(lv,part,fmt,...)trace_print(lv,part,[%s:%d] fmt,__func__,__LINE__,##__VA_ARGS__)#else#defineTRACE(lv,part,fmt,...)do{}while(0)// 空操作零开销#endif六、常见反模式6.1 没有开关日志写死// ❌ 没有开关量产固件还在疯狂打印printf(read: %d\r\n,val);// 到处都是裸 printf量产固件带着满屏printf出货串口带宽被占满性能也受影响。6.2 日志没有级别和模块全靠注释// ❌ 调试时临时加的打印靠记得删printf( debug: i%d \n,i);// 这种日志要么忘删要么删了又加回来6.3 日志与业务逻辑耦合// ❌ 日志函数里夹带业务逻辑#defineDEBUG_LOG(x){g_debug_flagx;printf(...);}// 改了业务状态日志宏必须纯打印绝不能影响业务状态——否则关掉日志就改变了程序行为这是极隐蔽的 bug。七、小结一套合格的调试日志系统四个要素要素作用实现分级控制详细程度位掩码TRACE_LV_*可组合分类按模块过滤TRACE_PART_*part_ctrl[]掩码可开关运行时/编译期裁剪global_ctrl通道位 TRACE_ENABLED宏可定位自动带位置TRACE宏拼入__func__/__LINE__把这四样做扎实日志就从临时调试手段升级成了可长期维护的观测工具。下一篇07b给出这套设计的完整可运行实现——分级过滤、三指针环形缓冲、多通道输出的全部源码与使用范例。本文仅介绍嵌入式调试日志系统的通用设计方法不涉及任何具体项目或产品的私有实现。
