CmBacktrace 应用笔记
- CmBacktrace 应用笔记
- 本文的目的和结构
- 本文的目的和背景
- 本文的结构
- CmBacktrace 是什么
- 准备工作
- 准备 addr2line
- ENV配置
- 确认宏定义
- 开启C99
- 确定初始化参数
- 使用示例
- 常见问题
- 参考
- API列表
- cm_backtrace_init
- cm_backtrace_call_stack
- cm_backtrace_assert
- cm_backtrace_fault
- API列表
- 本文的目的和结构
CmBacktrace 应用笔记
本文的目的和结构
本文的目的和背景
对于从 C51 、MSP430 等简单单片机转而使用更加复杂的 ARM 新人来说，时不时出现的 "hard falut" 死机会让新人瞬间懵掉。定位错误的方法也往往是连接上仿真器，一步步 F10/F11 单步，定位到具体的错误代码，再去猜测、排除、推敲错误原因，这种过程十分痛苦，且花费的时间很长。 当然，也有部分开发者通过故障寄存器信息来定位故障原因及故障代码地址，虽然这样能解决一小部分问题，但是重复的、繁琐的分析过程也会耽误很多时间。而且对于一些复杂问题，只依靠代码地址是无法解决的，必须得还原错误现场的函数调用逻辑关系。虽然连接仿真器可以查看到的函数调用栈，但故障状态下是无法显示的，所以还是得一步步 F10/F11 单步去定位错误代码的位置。另外，很多产品真机调试时必须断开仿真器，这又使定位错误代码雪上加霜。
为了能让开发者更快的知道造成 hard falut 的原因，更快的定位到错误代码的位置，本应用笔记将一步步介绍 CmBacktrace 的相关知识和使用方法，让开发者能不费吹灰之力就找出代码中的问题所在。
本文的结构
本文首先介绍了 什么是 CmBacktrace，然后介绍了使用 CmBacktrace 要做的准备工作，接着介绍了 在RT-Thread中使用CmBacktrace的例子，最后总结了使用 CmBacktrace 时的常见问题。通过这些讲解，希望开发者能更快上手 CmBacktrace。
CmBacktrace 是什么
CmBacktrace （Cortex Microcontroller Backtrace）是一款针对 ARM Cortex-M 系列 MCU 的错误代码自动追踪、定位，错误原因自动分析的开源库。
主要特性如下：
支持的错误包括：
断言（assert）
故障（Hard Fault, Memory Management Fault, Bus Fault, Usage Fault, Debug Fault）
故障原因 自动诊断 ：可在故障发生时，自动分析出故障的原因，定位发生故障的代码位置，而无需再手动分析繁杂的故障寄存器；
输出错误现场的 函数调用栈（需配合 addr2line 工具进行精确定位），还原发生错误时的现场信息，定位问题代码位置、逻辑更加快捷、精准。也可以在正常状态下使用该库，获取当前的函数调用栈；
支持 裸机 及以下操作系统平台：
UCOS
FreeRTOS（需修改源码）
根据错误现场状态，输出对应的 线程栈 或 C 主栈；
故障诊断信息支持多国语言（目前：简体中文、英文）；
适配 Cortex-M0/M3/M4/M7 MCU；
支持 IAR、KEIL、GCC 编译器；
准备工作
准备 addr2line
在 https://github.com/armink/CmBacktrace/tree/master/tools/addr2line 页面中下载 addr2line（需要按照自己的系统版本下载），然后将下载下来的 addr2line 拷贝至 C:\Windows 下 ，这样就可以使用 addr2line 了。
ENV配置
RT-Thread 已经对 CmBacktrace 做了适配，直接在 ENV 使能 CmBacktrace 就可以使用了。
下面介绍如何在 ENV 中配置CmBacktrace：
- 打开 ENV，进入相应的 bsp 目录
- 输入 menuconfig
- 进入 RT-Thread online packages -> tools packages
- 使能 CmBacktrace
- 进入 CmBacktrace 配置界面
- 选择自己的 CPU 平台
- 选择打印的语言
- 选择版本，推荐使用最新版
确认宏定义
CmBacktrace 的运行需要知道存放代码的 SECTION 的开始地址和结束地址以及栈的 SECTION 的开始地址和结束地址。用户只需要查看 cmb_def.h 文件里默认定义的 CMB_CSTACK_BLOCK_NAME 和 CMB_CODE_SECTION_NAME 这两个宏是否正确即可。如不正确，用户需要根据分散加载文件和启动文件来确定这两个宏的值并在 cmb_cfg.h 里重新定义这两个宏。
这里以 rt1052 的 mdk 工程为例进行讲解如何在工程里找到这两个宏的值。首先找 CMB_CSTACK_BLOCK_NAME 的值，我们打开工程里的启动文件，可以在文件的开头看到这样一段代码
- AREA RESET, DATA, READONLY
- EXPORT __Vectors
- EXPORT __Vectors_End
- EXPORT __Vectors_Size
- IMPORT |Image$$ARM_LIB_STACK$$ZI$$Limit|
- __Vectors DCD |Image$$ARM_LIB_STACK$$ZI$$Limit|;Top of Stack
ImageARM_LIB_STACKARMLIBSTACKZILimit，所以 CMB_CSTACK_BLOCK_NAME 的值应该是 ImageARM_LIB_STACKZI。
CMB_CODE_SECTION_NAME 的值在分散加载文件里寻找，分散加载文件可以点击 MDK的 Options -> Linker 选项面板里的 Edit… 按纽打开
我们可以找到这样一段代码
- ER_IROM1 m_text_start m_text_size ; load address = execution address
- {
- *(RESET,+FIRST)
- *(InRoot$$Sections)
- .ANY (+RO)
- }
保存有 .ANY (+RO) 的 SECTION 名字就是我们要找的值，所以，CMB_CODE_SECTION_NAME 的值为 ER_IROM1。
开启C99
CmBacktrace 的使用需要 C99 的支持，使用 MDK 的开发者可以在 Options -> C/C++面板中勾选 C99 Mode选项。
使用IAR的开发者，可以在 Options -> C/C++ Compiler 中选择 C99。
使用 GCC 进行编译的用户，在编译配置中增加 -std=c99 即可 。
确定初始化参数
在使用 CmBacktrace 之前需要先调用下初始化函数，函数原型如下：
- void cm_backtrace_init(constchar*firmware_name,constchar*hardware_ver,constchar*software_ver)
CmBacktrace 的初始化函数需要 3 个参数，第一个参数是固件名字，第二个参数是硬件版本，第三个参数是软件版本。这三个参数会在发生 hard fault时打印出来，firmware_name需要填写生成的固件名称，错误填写会导致在使用 addr2line 时无法找到文件。hardware_ver和software_ver建议填写真实的软硬件版本号，方便后期调试和维护。在 cmb_port.c 文件中，我们可以看到 RT-Thread 已经将 rt_cm_backtrace_init 函数进行了自动初始化，默认的三个参数分别是rtthread,1.0,1.0，开发者需要按照实际情况进行更改。
使用示例
CmBacktrace 提供了一个测试函数，提供除零测试和执行非对齐访问的测试。当做完上面的准备工作后，开发者可以直接将工程编译，下载进板子里，进行测试，判断 CmBacktrace 是否正常工作。
CmBacktrace 导出到 finsh shell 中的测试函数命令为cmb_test，输入 cmb_test DIVBYZERO 就是进行除零测试，输入 cmb_test UNALIGNED 就是执行非对齐访问的测试。
我们看下运行完除零测试的结果
- msh />cmb_test DIVBYZERO
- thread pri status sp stack size max used left tick error
- ---------------------------------------------------------
- tshell 20 ready 0x000001000x0000100023%0x00000009000
- phy 30 suspend 0x0000006c0x0000020030%0x00000001000
- tcpip 10 suspend 0x000000b40x0000080017%0x00000014000
- etx 12 suspend 0x000000880x0000040013%0x00000010000
- erx 12 suspend 0x000000880x0000040013%0x00000010000
- mmcsd_de 22 suspend 0x000000900x0000040049%0x00000013000
- tidle 31 ready 0x000000540x0000010032%0x00000018000
- main 10 suspend 0x000000640x0000080035%0x00000012000
- Firmware name: rtthread-imxrt, hardware version:1.0, software version:1.0
- Fault on thread tshell
- =====Thread stack information =====
- addr:80002ad0 data:00000012
- addr:80002ad4 data:6002ae58
- addr:80002ad8 data:80001a40
- addr:80002adc data:6000b575
- addr:80002ae0 data:80001a40
- addr:80002ae4 data:80001a49
- addr:80002ae8 data:00000000
- addr:80002aec data:00000000
- addr:80002af0 data:00000000
- addr:80002af4 data:00000000
- addr:80002af8 data:00000000
- addr:80002afc data:00000000
- addr:80002b00 data:00000000
- addr:80002b04 data:00000000
- addr:80002b08 data:20000c7c
- addr:80002b0c data:00000012
- addr:80002b10 data:80001a40
- addr:80002b14 data:20000c7c
- addr:80002b18 data:00000001
- addr:80002b1c data: deadbeef
- addr:80002b20 data: deadbeef
- addr:80002b24 data: deadbeef
- addr:80002b28 data: deadbeef
- addr:80002b2c data:60019ffb
- addr:80002b30 data:00000001
- addr:80002b34 data:0000000d
- addr:80002b38 data:00000000
- addr:80002b3c data:60015a7b
- addr:80002b40 data:23232323
- ====================================
- ===================Registers information ====================
- R0 :0000000a R1 :00000000 R2 :0000004f R3 :80808000
- R12:01010101 LR :6000c5ad PC :6000c5c8 PSR:41000000
- ==============================================================
- Usage fault is caused byIndicates a divide by zero has taken place (can be set only if DIV_0_TRP isset)
- Show more call stack info by run: addr2line -e rtthread-imxrt.axf -a -f 6000c5c86000c5a96002ae546000b57160019ff760015a77
CmBacktrace 首先打印出了发生 hard falut 时的所有线程信息，接着打印了固件名字和软硬件版本号，再打印了错误是发生在 tshell 这个线程里面的（因为我们是在 tshell 这个线程里调用的除零测试函数），紧接着打印的是线程的栈信息和寄存器信息。最后两行信息是最重要的，倒数第二行介绍了发生故障的原因，是因为除零造成的。最后一行提示如果需要获取函数调用栈，需要在 addr2line 中运行 CmBacktrace 给出的参数。
在使用addr2line 之前我们要先确认保存了工程对象文件的文件夹位置。使用mdk的开发者，可以在 Options -> Output 面板中查看，设置对象文件的保存路径。
使用IAR的开发者，可以在 Options -> General Options 面板的Output选项中查看和设置。
我们将 run：后面的所有内容都复制下来，然后进入保存了工程生成的对象文件的文件夹，打开env，将刚刚复制的内容粘贴上去，按下回车，错误现场的函数调用栈就会输出出来，我们看下刚刚进行除零测试时的函数调用栈的信息
- > addr2line -e rtthread-imxrt.axf -a -f 6000c5c86000c5a96002ae546000b57160019ff760015a77
- 0x6000c5c8
- cmb_test
- D:\rt-thread\bsp\imxrt1052-evk/packages\CmBacktrace-v1.2.0\/cmb_port.c:87
- 0x6000c5a9
- cmb_test
- D:\rt-thread\bsp\imxrt1052-evk/packages\CmBacktrace-v1.2.0\/cmb_port.c:82
- 0x6002ae54
- FSymTab$$Base
- ??:?
- 0x6000b571
- msh_get_cmd
- D:\rt-thread\bsp\imxrt1052-evk/..\..\components\finsh\/msh.c:312
- 0x60019ff7
- msh_exec
- D:\rt-thread\bsp\imxrt1052-evk/..\..\components\finsh\/msh.c:335
- 0x60015a77
- finsh_thread_entry
- D:\rt-thread\bsp\imxrt1052-evk/..\..\components\finsh\/shell.c:613
我们可以看到，CmBacktrace 不仅仅定位出了是 cmb_port.c里第87行产生的问题，还打印出了函数调用逻辑关系，方便开发者进行 BUG 修复。
常见问题
- 使用前必须确认自己的 MCU 是 ARM Cortex-M0(+)/M3/M4/M7 架构，其他架构暂不支持。
- 使用前要确定 CMB_CSTACK_BLOCK_NAME 和 CMB_CODE_SECTION_NAME 两个宏的宏定义，如果定义错误，CmBacktrace会无法正确使用。
- 初始化时要输入正确的固件名称，不然使用 addr2line 时会提示找不到文件
- 当线程的栈被写穿时，CmBacktrace 无法正常使用。
参考
API列表
cm_backtrace_init
CmBacktrace 库初始化
函数原型:
- void cm_backtrace_init(constchar*firmware_name,constchar*hardware_ver,constchar*software_ver)
| 参数 | 描述 |
|---|---|
| firmware_name | 固件名称，需与编译器生成的固件名称对应 |
| hardware_ver | 固件对应的硬件版本号 |
| software_ver | 固件的软件版本号 |
函数返回：无
注意 ：以上入参将会在断言或故障时输出，主要起了追溯的作用
cm_backtrace_call_stack
获取函数调用栈
函数原型:
- size_t cm_backtrace_call_stack(uint32_t*buffer,size_t size,uint32_t sp)
| 参数 | 描述 |
|---|---|
| buffer | 存储函数调用栈的缓冲区 |
| size | 缓冲区大小 |
| sp | 待获取的堆栈指针 |
函数返回：函数调用栈实际深度
示例：
- /* 建立深度为 16 的函数调用栈缓冲区，深度大小不应该超过 CMB_CALL_STACK_MAX_DEPTH（默认16） */
- uint32_t call_stack[16]={0};
- size_t i, depth =0;
- /* 获取当前环境下的函数调用栈，每个元素将会以 32 位地址形式存储， depth 为函数调用栈实际深度 */
- depth = cm_backtrace_call_stack(call_stack,sizeof(call_stack), cmb_get_sp());
- /* 输出当前函数调用栈信息
- * 注意：查看函数名称及具体行号时，需要使用 addr2line 工具转换
- */
- for(i =0; i < depth; i++){
- printf("%08x ", call_stack[i]);
- }
cm_backtrace_assert
追踪断言错误信息
函数原型:
- void cm_backtrace_assert(uint32_t sp)
| 参数 | 描述 |
|---|---|
| sp | 断言环境时的堆栈指针 |
函数返回：无
注意 ：入参 SP 尽量在断言函数内部获取，而且尽可能靠近断言函数开始的位置。当在断言函数的子函数中（例如：在 RT-Thread 的断言钩子方法中）使用时，由于函数嵌套会存在寄存器入栈的操作，此时再获取 SP 将发生变化，就需要人为调整（加减固定的偏差值）入参值，所以作为新手 不建议在断言的子函数 中使用该函数。
cm_backtrace_fault
追踪故障错误信息
函数原型:
- void cm_backtrace_fault(uint32_t fault_handler_lr,uint32_t fault_handler_sp)
| 参数 | 描述 |
|---|---|
| fault_handler_lr | 故障处理函数环境下的 LR 寄存器值 |
| fault_handler_sp | 故障处理函数环境下的 SP 寄存器值 |
函数返回：无
该函数可以在故障处理函数（例如： HardFault_Handler）中调用。另外，库本身提供了 HardFault 处理的汇编文件（点击查看，需根据自己编译器进行选择），会在故障时自动调用 cm_backtrace_fault 方法。所以移植时，最简单的方式就是直接使用该汇编文件。