CmBacktrace库详解-以Cortex-M3/M4+FreeRTOS为例

1.为什么写这篇文章

        相信很多做FreeRTOS开发的同学在查找偶现的死机问题时，都希望能有一个像Linux core dump一样的机制，能够将死机现场的寄存器信息和调用栈保存起来，但原生的FreeRTOS并没有提供类似机制。朱天龙老师的CmBacktrace库则是提供了一种针对ARM Cortex-M系列MCU的死机现场和断言触发现场信息保存的方法。

        CmBacktrace源码在Github和gitee上均可下载，这里贴一下不需要梯子的gitee仓库地址：CmBacktrace: ARM Cortex-M 系列 MCU 错误追踪库，有需要的同学可以自行前往下载。

        源码内的README中对库的移植和使用有非常详细的说明，网络上也有很多描述CmBacktrace使用方法的帖子，但是网上却很难找到CmBacktrace实现机制。因此，本帖不对该库的移植和使用的相关内容做过多介绍，而是主要以FreeRTOS+Cortex-M3/M4为例，分析一下CmBacktrace的错误现场信息保存的实现机制（断言现场打印的信息是错误现场的子集，所以这里只分析错误现场打印）。写这篇文章的另一个重要原因就是，我本人暂时还没在网上找到cortex-M3/M4调用栈回溯原理分析的帖子，所以在这里补充一下。当然，由于本人能力所限，分析可能存在一定的错误和遗漏，欢迎大家在评论区指出。

2.死机现场

        我们先来看一下CmBacktrace打印的死机现场。

        在我写这篇文章的时候，手上并没有相关的硬件环境，所以在这里借用一下源码内提供的demo的现场：

        我们可以看到，现场总共保存了六类信息：

• a.故障软件版本信息
• b.发生死机问题的线程名称
• c.栈内信息
• d.寄存器信息
• e.死机原因
• f.调用栈信息

        前五类信息的打印机制非常简单，在这里只做简答介绍，重点介绍的是调用栈的回溯。

3.a-e类信息打印机制的简单介绍

a.故障软件版本信息

        初始化时传入

 b.发生死机问题的线程名称

        这个是操作系统相关的，直接调用相应操作系统的接口。如果是FreeRTOS，那么就是调用的就是vTaskName函数。

 

 c.栈内信息

        这里需要注意一下，cortex-M3/M4有两个栈指针：msp和psp，当无操作系统时，使用的是msp。如果有操作系统，psp就作为应用线程栈指针，msp则是作为中断和异常栈（包括部分内核）指针。打印时逐字打印整个栈空间的内容。这里如何判断栈的起始地址和栈大小放在调用栈回溯里介绍。

d.寄存器信息

        对这里不熟悉的同学简单的去翻一下《ARM Cortex-M3与Cortex-M4权威指南》4.2.2这一节的内容就可以了。

 e.死机原因

cortex-M3/M4的错误异常有以下几种：

• MemManage错误
• 总线错误
• 使用错误
• HardFault

        除hardFault之外的错误是可配置错误异常，而所有的错误默认都会触发HardFault，所以如果要进入三个可配置错误的异常而不是进入HardFault，那么这三个异常的优先级就需要比HardFault高。对这块感兴趣的同学可以自行去翻阅《ARM Cortex-M3与Cortex-M4权威指南》12章的内容，也是一些寄存器的配置和接口的调用配置，这里也就不展开讲了。这里的打印信息其实也是根据各错误状态信息寄存器的内容和预先定义的字符串输出的，大家结合一下源码和寄存器各位的描述就可以知道了。

4.调用栈回溯

        这里按照从顶层到底层的顺序，跟踪整个代码实现过程，这样对整个过程的介绍会更加清晰且容易理解。在这个过程中也会介绍一些相关的扩展知识，因为这里的代码脱离了这些知识是无法理解的。

1.cm_backtrace_fault的调用

        首先看下，CmBacktrace的最顶层函数cm_backtrace_fault是怎么被调用的（使用者其实可以在任何想要打印现场信息的地方调用这个函数）：

        这是一段汇编代码，他的意思其实就是在HardFault错误处理函数中，以lr的值作为第一个参数，sp的值作为第二个参数调用cm_backtrace_fault。

ps1.这里扩展第一个知识点：arm cortex函数调用时参数的传递

ATPCS(Arm-Thumb Procedure Call Standard)规定子程序使用R0-R3传参，当参数大于4个时，剩余参数使用栈来传递。

2.cm_backtrace_fault函数分析

        这里只关注调用栈打印相关的部分，其他部分其实就是实现了其他现场信息的打印，前面已有做简单介绍。

void cm_backtrace_fault(uint32_t fault_handler_lr, uint32_t fault_handler_sp) {
    uint32_t stack_pointer = fault_handler_sp, saved_regs_addr = stack_pointer;
    const char *regs_name[] = { "R0 ", "R1 ", "R2 ", "R3 ", "R12", "LR ", "PC ", "PSR" };

#ifdef CMB_USING_DUMP_STACK_INFO
    uint32_t stack_start_addr = main_stack_start_addr;
    size_t stack_size = main_stack_size;
#endif

    CMB_ASSERT(init_ok);
    /* only call once */
    CMB_ASSERT(!on_fault);

    on_fault = true;

    cmb_println("");
    cm_backtrace_firmware_info();

#ifdef CMB_USING_OS_PLATFORM
    on_thread_before_fault = fault_handler_lr & (1UL << 2);
    /* check which stack was used before (MSP or PSP) */
    if (on_thread_before_fault) {
        cmb_println(print_info[PRINT_FAULT_ON_THREAD], get_cur_thread_name() != NULL ? get_cur_thread_name() : "NO_NAME");
        saved_regs_addr = stack_pointer = cmb_get_psp();

#ifdef CMB_USING_DUMP_STACK_INFO
        get_cur_thread_stack_info(stack_pointer, &stack_start_addr, &stack_size);
#endif /* CMB_USING_DUMP_STACK_INFO */

    } else {
        cmb_println(print_info[PRINT_FAULT_ON_HANDLER]);
    }
#else
    /* bare metal(no OS) environment */
    cmb_println(print_info[PRINT_FAULT_ON_HANDLER]);
#endif /* CMB_USING_OS_PLATFORM */

    /* delete saved R0~R3, R12, LR,PC,xPSR registers space */
    stack_pointer += sizeof(size_t) * 8;

#if (CMB_CPU_PLATFORM_TYPE == CMB_CPU_ARM_CORTEX_M4) || (CMB_CPU_PLATFORM_TYPE == CMB_CPU_ARM_CORTEX_M7) || \
    (CMB_CPU_PLATFORM_TYPE == CMB_CPU_ARM_CORTEX_M33)
    stack_pointer = statck_del_fpu_regs(fault_handler_lr, stack_pointer);
#endif /* (CMB_CPU_PLATFORM_TYPE == CMB_CPU_ARM_CORTEX_M4) || (CMB_CPU_PLATFORM_TYPE == CMB_CPU_ARM_CORTEX_M7) */

#ifdef CMB_USING_DUMP_STACK_INFO
    /* check stack overflow */
    if (stack_pointer < stack_start_addr || stack_pointer > stack_start_addr + stack_size) {
        stack_is_overflow = true;
    }
    /* dump stack information */
    dump_stack(stack_start_addr, stack_size, (uint32_t *) stack_pointer);
#endif /* CMB_USING_DUMP_STACK_INFO */

    /* the stack frame may be get failed when it is overflow  */
    if (!stack_is_overflow) {
        /* dump register */
        cmb_println(print_info[PRINT_REGS_TITLE]);

        regs.saved.r0        = ((uint32_t *)saved_regs_addr)[0];  // Register R0
        regs.saved.r1        = ((uint32_t *)saved_regs_addr)[1];  // Register R1
        regs.saved.r2        = ((uint32_t *)saved_regs_addr)[2];  // Register R2
        regs.saved.r3        = ((uint32_t *)saved_regs_addr)[3];  // Register R3
        regs.saved.r12       = ((uint32_t *)saved_regs_addr)[4];  // Register R12
        regs.saved.lr        = ((uint32_t *)saved_regs_addr)[5];  // Link register LR
        regs.saved.pc        = ((uint32_t *)saved_regs_addr)[6];  // Program counter PC
        regs.saved.psr.value = ((uint32_t *)saved_regs_addr)[7];  // Program status word PSR

        cmb_println("  %s: %08x  %s: %08x  %s: %08x  %s: %08x", regs_name[0], regs.saved.r0,
                                                                regs_name[1], regs.saved.r1,
                                                                regs_name[2], regs.saved.r2,
                                                                regs_name[3], regs.saved.r3);
        cmb_println("  %s: %08x  %s: %08x  %s: %08x  %s: %08x", regs_name[4], regs.saved.r12,
                                                                regs_name[5], regs.saved.lr,
                                                                regs_name[6], regs.saved.pc,
                                                                regs_name[7], regs.saved.psr.value);
        cmb_println("==============================================================");
    }

    /* the Cortex-M0 is not support fault diagnosis */
#if (CMB_CPU_PLATFORM_TYPE != CMB_CPU_ARM_CORTEX_M0)
    regs.syshndctrl.value = CMB_SYSHND_CTRL;  // System Handler Control and State Register
    regs.mfsr.value       = CMB_NVIC_MFSR;    // Memory Fault Status Register
    regs.mmar             = CMB_NVIC_MMAR;    // Memory Management Fault Address Register
    regs.bfsr.value       = CMB_NVIC_BFSR;    // Bus Fault Status Register
    regs.bfar             = CMB_NVIC_BFAR;    // Bus Fault Manage Address Register
    regs.ufsr.value       = CMB_NVIC_UFSR;    // Usage Fault Status Register
    regs.hfsr.value       = CMB_NVIC_HFSR;    // Hard Fault Status Register
    regs.dfsr.value       = CMB_NVIC_DFSR;    // Debug Fault Status Register
    regs.afsr             = CMB_NVIC_AFSR;    // Auxiliary Fault Status Register

    fault_diagnosis();
#endif

    print_call_stack(stack_pointer);
}

第6、7行是获取主栈的起始地址和大小，这个源码README有解释，实际上在有OS的时候，用的是27行处取到的栈信息。

第24行，这里获取了psp的值，而不是直接使用sp的值，这是为什么呢？前面说了，在使用了嵌入式系统时，应用线程使用psp，而中断和异常使用msp，也就是说现在的sp实际上是msp，所以这里只有取psp的值才是触发死机的那个应用函数栈的栈顶。

ps2.这里再扩展第二个知识点，解释一下60-67行，这几行代码就是获取死机发生时寄存器的值。只看代码的表面意思，这段代码是取了psp指向的地址后面八个字的数据，分别作为R0-R3，R12，lr，pc，和psr寄存器的值。那么为什么是这么获取的呢？

第一：在发生异常时，cortex-M3/M4会通过硬件自动将R0-R3，R12，lr，pc，和psr寄存器的值压入到栈中，并且由于cortex-M3/M4具有独立的数据总线和指令总线，所以在Dbus压栈操作的同时，Ibus还会同步的去进行识别异常向量，获取异常处理函数的地址的取指令操作。

第二：arm都是满递减栈，所以sp每+4，就相当于回溯了栈内一个字。

第27行，获取线程栈的起始地址和大小。

第48-50，判断栈是否溢出。

第95行，将psp的值传给了print_call_stack，很明显，这个函数就是调用栈打印的实现函数。

3.print_call_stack函数分析

static void print_call_stack(uint32_t sp) {
    size_t i, cur_depth = 0;
    uint32_t call_stack_buf[CMB_CALL_STACK_MAX_DEPTH] = {0};

    cur_depth = cm_backtrace_call_stack(call_stack_buf, CMB_CALL_STACK_MAX_DEPTH, sp);

    for (i = 0; i < cur_depth; i++) {
        sprintf(call_stack_info + i * (8 + 1), "%08lx", (unsigned long)call_stack_buf[i]);
        call_stack_info[i * (8 + 1) + 8] = ' ';
    }

    if (cur_depth) {
        call_stack_info[cur_depth * (8 + 1) - 1] = '\0';
        cmb_println(print_info[PRINT_CALL_STACK_INFO], fw_name, CMB_ELF_FILE_EXTENSION_NAME, call_stack_info);
    } else {
        cmb_println(print_info[PRINT_CALL_STACK_ERR]);
    }
}

        这里很简单，就是创建了一个缓存区用于缓存调用栈信息，然后调用cm_backtrace_call_stack获取调用栈，再打印出来。

4.cm_backtrace_call_stack函数分析

size_t cm_backtrace_call_stack(uint32_t *buffer, size_t size, uint32_t sp) {
    uint32_t stack_start_addr = main_stack_start_addr, pc;
    size_t depth = 0, stack_size = main_stack_size;
    bool regs_saved_lr_is_valid = false;

    if (on_fault) {
        if (!stack_is_overflow) {
            /* first depth is PC */
            buffer[depth++] = regs.saved.pc;
            /* fix the LR address in thumb mode */
            pc = regs.saved.lr - 1;
            if ((pc >= code_start_addr) && (pc <= code_start_addr + code_size) && (depth < CMB_CALL_STACK_MAX_DEPTH)
                    && (depth < size)) {
                buffer[depth++] = pc;
                regs_saved_lr_is_valid = true;
            }
        }

#ifdef CMB_USING_OS_PLATFORM
        /* program is running on thread before fault */
        if (on_thread_before_fault) {
            get_cur_thread_stack_info(sp, &stack_start_addr, &stack_size);
        }
    } else {
        /* OS environment */
        if (cmb_get_sp() == cmb_get_psp()) {
            get_cur_thread_stack_info(sp, &stack_start_addr, &stack_size);
        }
#endif /* CMB_USING_OS_PLATFORM */

    }

    if (stack_is_overflow) {
        if (sp < stack_start_addr) {
            sp = stack_start_addr;
        } else if (sp > stack_start_addr + stack_size) {
            sp = stack_start_addr + stack_size;
        }
    }

    /* copy called function address */
    for (; sp < stack_start_addr + stack_size; sp += sizeof(size_t)) {
        /* the *sp value may be LR, so need decrease a word to PC */
        pc = *((uint32_t *) sp) - sizeof(size_t);
        /* the Cortex-M using thumb instruction, so the pc must be an odd number */
        if (pc % 2 == 0) {
            continue;
        }
        /* fix the PC address in thumb mode */
        pc = *((uint32_t *) sp) - 1;
        if ((pc >= code_start_addr + sizeof(size_t)) && (pc <= code_start_addr + code_size) && (depth < CMB_CALL_STACK_MAX_DEPTH)
                /* check the the instruction before PC address is 'BL' or 'BLX' */
                && disassembly_ins_is_bl_blx(pc - sizeof(size_t)) && (depth < size)) {
            /* the second depth function may be already saved, so need ignore repeat */
            if ((depth == 2) && regs_saved_lr_is_valid && (pc == buffer[1])) {
                continue;
            }
            buffer[depth++] = pc;
        }
    }

    return depth;
}

第6行：这里判断是否是从错误处理函数调用过来的，因为断言处理函数也会调用当前函数。

第11行：获取第一层调用栈，就是pc的值。

第12-16行：获取第二层调用栈，即lr的值-1。

p3.这里扩展第三个知识点：为什么要减1？

减1是因为返回地址总是偶数，LR地址的第0位用于表示是否为Thumb状态，而M系列处理器都是采用的Thumb指令集跳转，这一位总是1。所以减1之后才是真正的要跳转的地址。

溢出处理不谈，其实如果是栈溢出了的话，整个栈空间的信息已经是不可靠的了

第42-60就是循环获取调用栈：

第42行：这里的意思就是要再当前线程栈中逐字查找了，那么查找的是什么呢？

ps4.这里扩展第四个知识点：线程栈中有什么？以及我们到底在回溯什么？

下图是我画的一个线程栈中的内容，假设是c->b->a的调用关系，然后在a中发生死机的这么一个场景：

         arm都是满减栈，所以栈的生长方向是由上到下的。栈内的内容依次是：异常发生时压栈的寄存器内容、a的函数栈、b的函数栈、c的函数栈。而函数栈的最里面就是当前函数的返回地址，也就是lr的值。而只需要把这个值给记录下来，就能够找到要返回的函数了，我们要回溯的也就是这个lr的值。

第46行：前面已经说了，lr的值都是奇数，所以说如果是偶数的话，那肯定就不是lr了，直接找下一个。这里的代码有一个不太好的点，那就是我们这里实际查找的是lr，但这里的变量命名却是pc，所以十分容易对那些不是很了解cortex-M3/M4函数栈内容的同学造成误解。我猜测作者在这里用pc命名是想表达这是上一个函数的pc指针指向的值？

第50行：假设当前查找的位置是lr，那么将其转化为实际跳转的地址，也就是减1.

第51行：判断转化后的跳转地址是否在代码空间内。代码空间其实地址和大小就是.text段的起始地址和大小，不同编译器的获取方法不一样。这里的代码也略微有一点小小的问题，那就是(pc >= code_start_addr + sizeof(size_t)) && (pc

第53行：disassembly_ins_is_bl_blx这个函数实际上是判断lr返回的地址的前面一条指令是不是BL/BLX指令。这个很好理解，b到a肯定是发生了调用吗，那么肯定也就是对应了一条跳转指令。那么他是如何判断的呢？

一条arm指令的宽度是4字节，而一条Thumb指令的宽度是2字节。而每个指令都有其对应的指令码，判断是否相等就好了。

到这里，如果栈内刚好有个值，他指向了代码段，同时他指向的代码段的前面还刚好是一个跟跳转指令一样的值，那基本也就确定这个值就是lr了。当然也存在恰好的情况，但这种概率极低，可以不予考虑。

第55行：从上面的图很容易看出，对于最后一个函数的lr，栈内是存了两次的，所以丢掉第二次就好了。

到这里，整个回溯代码也就分析完毕了。

5.总结

        CmBacktrace代码量并不大，但是要读懂却需要很多的相关知识，所以嵌入式开发其实是一项非常有挑战性的工作。与app开发相比，嵌入式开发的核心并不在软件编码能力，而是需要对硬件、处理器架构、系统内核有一个全面的了解。