CmBacktrace Documentation

CmBacktrace (Cortex Microcontroller Backtrace) is an open-source library designed for ARM Cortex-M series MCUs to automatically track, locate, and analyze error codes. It helps developers move beyond manual register analysis by providing automated diagnostics and call stack reconstruction.

Key Features:

• Supported Errors: Automatically handles assert failures and various hardware faults including Hard Fault, Memory Management Fault, Bus Fault, Usage Fault, and Debug Fault.
• Automated Diagnosis: Analyzes fault causes and locates the offending code position without requiring manual register inspection.
• Call Stack Reconstruction: Outputs the function call stack at the time of error (requires addr2line for precise symbol mapping). It can also be used in normal operation to retrieve the current call stack.
• Stack Support: Outputs either the thread stack (for RTOS) or the C main stack based on the error context.
• Multi-language Support: Diagnostic information is available in Simplified Chinese and English.
• Hardware & Toolchain Compatibility:
  • MCUs: Cortex-M0, M3, M4, M7.
  • Compilers: IAR, Keil, GCC.
  • Platforms: Bare-metal, RT-Thread, UCOS, and FreeRTOS (FreeRTOS requires source code modification).

CmBacktrace (Cortex Microcontroller Backtrace) is an open-source library designed for ARM Cortex-M series MCUs to automatically track, locate, and analyze error codes. It automates the diagnosis of complex fault registers and provides the function call stack to help developers pinpoint problematic code and logic quickly.

Key Features:

• Supported Errors: Automatically handles Assert and various Fault types (Hard Fault, Memory Management Fault, Bus Fault, Usage Fault, Debug Fault).
• Automatic Diagnosis: Analyzes the cause of failure and locates the code location without manual register analysis.
• Call Stack Recovery: Outputs the function call stack (requires addr2line for precise source mapping) and restores field information at the time of error.
• Platform Support:
  • Hardware: Cortex-M0, M3, M4, and M7 MCUs.
  • Operating Systems: Bare metal, RT-Thread, UCOS, and FreeRTOS (requires source code modification).
  • Compilers: IAR, KEIL, and GCC.
• Multi-language Support: Fault diagnosis information is available in Simplified Chinese and English.

To test the CmBacktrace functionality on an STM32F10x platform without an OS, follow these steps:

1. Open the Project: Use the Keil project located in the RVMDK folder or the IAR project in the EMARM folder.
2. Select a Test Case: In app/src/app.c, choose one of the following HardFault test functions to execute:
   • fault_test_by_unalign()
   • fault_test_by_div0()
3. Hardware Setup: Download the program to your development board and connect its UART1 to your computer.
4. Monitor Output: Open a serial terminal on your computer with the following configuration:
   • Baud rate: 115200
   • Data bits: 8
   • Parity: None
   • Stop bits: 1
5. Observe Fault Diagnosis: Upon powering the board, the terminal will display stack information, register values, and the diagnosed fault reason (e.g., Usage fault is caused by Indicates a divide by zero has taken place).

CmBacktrace provides memory addresses for the fault location. To map these addresses to specific function names and code lines, use the addr2line tool.

1. Locate the Executable: Navigate to the directory containing your project's executable file in your command line tool:
   • Keil: Usually in the Output folder (file extension .axf).
   • IAR: Usually in the Exe folder (file extension .out).
2. Execute addr2line: Copy the command provided in the CmBacktrace serial output (from STEP 3) and run it. The command follows this format: addr2line -e <executable_file> -a -f <address1> <address2> ...

Example Command:

addr2line -e CmBacktrace.out -a -f 0800035c 0800018d 080009e1

Example Output:

0x0800035c
fault_test_by_div0
D:\Program\STM32\CmBacktrace\demos\os\rtthread\stm32f4xx\app\src/fault_test.c:38
0x0800018d
thread_entry_sys_monitor
D:\Program\STM32\CmBacktrace\demos\os\rtthread\stm32f4xx\app\src/app_task.c:36

CmBacktrace provides memory addresses in its fault report. To translate these addresses into human-readable function names and line numbers, use the addr2line tool.

1. Locate the Executable: Navigate to the directory containing your project's executable file in your terminal:
   • Keil: Usually in the Output folder (file extension .axf).
   • IAR: Usually in the Exe folder (file extension .out).
2. Execute addr2line: Copy the command provided in the last line of the CmBacktrace serial output and run it in your terminal. The command follows this format:

   addr2line -e <executable_name> -a -f <address1> <address2> ...

Example Command (based on demo output):

addr2line -e CmBacktrace.out -a -f 08001d24 08000191 08001c95

Example Output:

0x08001d24
fault_test_by_div0
D:\Program\STM32\CmBacktrace\demos\os\ucosii\stm32f10x\app\src/fault_test.c:38
0x08000191
AppTaskStart
D:\Program\STM32\CmBacktrace\demos\os\ucosii\stm32f10x\app\src/app.c:49
...

To integrate CmBacktrace into an ARM Cortex-M project, follow these steps:

1. Identify Platform: Determine your CPU (M0/M3/M4/M7) and whether you are using a Bare Metal platform or an Operating System (RT-Thread, UCOSII, UCOSIII, or FreeRTOS).
2. Add Source Files: Add all files from the \src directory to your project and ensure the source directory is in your include path.
3. Handle Fault Handler (Two Options):
   • Option A (Recommended): Add the cmb_fault.s assembly file to your project. You must comment out your project's existing HardFault_Handler to avoid multiple definition errors.
   • Option B: If you do not use cmb_fault.s, you must manually call cm_backtrace_fault(fault_handler_lr, fault_handler_sp) inside your existing HardFault_Handler. Ensure the parameters are passed correctly to avoid further faults.
4. Initialization: Call cm_backtrace_init during project startup.
5. Assertion Integration: Call cm_backtrace_assert within your project's assertion function.

Note on Demos: It is highly recommended to check the \demos directory for a template matching your platform (e.g., \demos\os\freertos\stm32f10x) and modify it rather than starting from scratch.