一步步介绍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 工具进行精确定位），还原发生错误时的现场信息，定位问题代码位置、逻辑更加快捷、精准。也可以在正常状态下使用该库，获取当前的函数调用栈；

支持 裸机 及以下操作系统平台：

RT-Thread

UCOS

FreeRTOS（需修改源码）

根据错误现场状态，输出对应的 线程栈 或 C 主栈；

故障诊断信息支持多国语言（目前：简体中文、英文）；

适配 Cortex-M0/M3/M4/M7 MCU；

支持 IAR、KEIL、GCC 编译器；

准备工作

准备 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 的值，我们打开工程里的启动文件，可以在文件的开头看到这样一段代码

ImageARM_LIB_STACKARM​L​​IB​S​​TACKZILimit，所以 CMB_CSTACK_BLOCK_NAME 的值应该是 ImageARM_LIB_STACKZI。

CMB_CODE_SECTION_NAME 的值在分散加载文件里寻找，分散加载文件可以点击 MDK的 Options -> Linker 选项面板里的 Edit… 按纽打开

我们可以找到这样一段代码

保存有 .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 之前需要先调用下初始化函数，函数原型如下：

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 就是执行非对齐访问的测试。

我们看下运行完除零测试的结果

CmBacktrace 首先打印出了发生 hard falut 时的所有线程信息，接着打印了固件名字和软硬件版本号，再打印了错误是发生在 tshell 这个线程里面的（因为我们是在 tshell 这个线程里调用的除零测试函数），紧接着打印的是线程的栈信息和寄存器信息。最后两行信息是最重要的，倒数第二行介绍了发生故障的原因，是因为除零造成的。最后一行提示如果需要获取函数调用栈，需要在 addr2line 中运行 CmBacktrace 给出的参数。

在使用addr2line 之前我们要先确认保存了工程对象文件的文件夹位置。使用mdk的开发者，可以在 Options -> Output 面板中查看，设置对象文件的保存路径。

使用IAR的开发者，可以在 Options -> General Options 面板的Output选项中查看和设置。

我们将 run：后面的所有内容都复制下来，然后进入保存了工程生成的对象文件的文件夹，打开env，将刚刚复制的内容粘贴上去，按下回车，错误现场的函数调用栈就会输出出来，我们看下刚刚进行除零测试时的函数调用栈的信息

我们可以看到，CmBacktrace 不仅仅定位出了是 cmb_port.c里第87行产生的问题，还打印出了函数调用逻辑关系，方便开发者进行 BUG 修复。

常见问题

使用前必须确认自己的 MCU 是 ARM Cortex-M0(+)/M3/M4/M7 架构，其他架构暂不支持。
使用前要确定 CMB_CSTACK_BLOCK_NAME 和 CMB_CODE_SECTION_NAME 两个宏的宏定义，如果定义错误，CmBacktrace会无法正确使用。
初始化时要输入正确的固件名称，不然使用 addr2line 时会提示找不到文件
当线程的栈被写穿时，CmBacktrace 无法正常使用。

原作者：RT-Thread应用笔记