開源倉庫鏈接：https://github.com/Rbb666/MCoreDump

本組件已驗證過的平臺：瑞薩 RA6M3（Cortex-M4）、瑞薩 RA6M4（Cortex-M33）上均可跑通，更多平臺請關(guān)注開源倉庫。

目錄

組件介紹

主要特性

應(yīng)用場景

支持架構(gòu)

系統(tǒng)架構(gòu)

目錄結(jié)構(gòu)

配置選項

快速開始

API 參考

主要函數(shù)

輸出模式詳解

高級配置

調(diào)試工具使用

如何適配新架構(gòu)

性能特性

故障排除

貢獻指南

許可證

組件介紹

MCoreDump（mini-coredump） 是專為嵌入式系統(tǒng)設(shè)計的故障轉(zhuǎn)儲（CoreDump）組件，能夠在系統(tǒng)發(fā)生硬故障（Hard Fault）、斷言失敗或其他異常情況時，自動生成標(biāo)準(zhǔn) ELF 格式的核心轉(zhuǎn)儲文件，用于離線調(diào)試和故障分析。

主要特性

ELF 格式兼容：生成標(biāo)準(zhǔn) ELF 格式的 core dump 文件，兼容 GDB、objdump 等調(diào)試工具

多種輸出模式：支持串口輸出、內(nèi)存緩沖區(qū)存儲、文件系統(tǒng)保存

多線程支持：能夠捕獲多線程環(huán)境下所有線程的狀態(tài)信息

斷電保持：內(nèi)存模式下數(shù)據(jù)在斷電重啟后仍可保持（需硬件支持）

故障安全：采用靜態(tài)內(nèi)存分配，避免在故障時使用動態(tài)內(nèi)存

完整狀態(tài)捕獲：包含寄存器、棧信息、內(nèi)存數(shù)據(jù)等完整系統(tǒng)狀態(tài)

應(yīng)用場景

嵌入式系統(tǒng)調(diào)試：定位硬故障、棧溢出、內(nèi)存訪問錯誤等問題

產(chǎn)品質(zhì)量保證：生產(chǎn)環(huán)境故障記錄和分析

固件開發(fā)：多線程程序調(diào)試和優(yōu)化

現(xiàn)場故障分析：設(shè)備部署后的遠(yuǎn)程故障診斷

支持架構(gòu)

Armv7-M

Armv8-M

系統(tǒng)架構(gòu)

MCoreDump組件架構(gòu)┌─────────────────────────────────────────────────────────┐│ 用戶層 API │├─────────────────────────────────────────────────────────┤│ mcd_faultdump() │ mcd_test │ mcd_dump_filesystem |├─────────────────────────────────────────────────────────┤│ 核心引擎層 │├─────────────────────────────────────────────────────────┤│ mcd_mini_dump() │ mcd_multi_dump() │ mcd_gen_coredump() │├─────────────────────────────────────────────────────────┤│ 輸出適配層 │├─────────────────────────────────────────────────────────┤│ 串口輸出 │ 內(nèi)存緩沖區(qū) │ 文件系統(tǒng) │├─────────────────────────────────────────────────────────┤│ 平臺抽象層 │├─────────────────────────────────────────────────────────┤│ RT-Thread 適配 │ 架構(gòu)特定代碼 │├─────────────────────────────────────────────────────────┤│ 硬件 │└─────────────────────────────────────────────────────────┘

目錄結(jié)構(gòu)

MCoreDump 組件采用模塊化設(shè)計：

MCoreDump/├── README.md # 組件說明文檔├── Kconfig # 配置選項定義├── SConscript # 編譯腳本│├── inc/ # 頭文件目錄│ ├── mcd_cfg.h # 配置文件和OS抽象層│ ├── coredump.h # 主要API聲明│ └── mcd_elf_define.h # ELF格式定義│├── src/ # 源代碼目錄│ ├── coredump.c # 核心dump生成引擎│ ├── faultdump.c # 故障處理和輸出管理│ └── arm/ # ARM架構(gòu)特定代碼│ ├── mcd_arm.c # ARM架構(gòu)實現(xiàn)（統(tǒng)一ARM32/64）│ └── mcd_arm_define.h # ARM架構(gòu)定義│├──arch/ # 架構(gòu)抽象層│ ├── mcd_arch_interface.h # 架構(gòu)接口定義│ └── armv7m/ # ARM Cortex-M特定實現(xiàn)│ ├── armv7m.c # ARMv7-M寄存器收集│ └── registers.h # 寄存器結(jié)構(gòu)定義│├── osal/ # 操作系統(tǒng)適配層│ └── rtthread.c # RT-Thread特定適配代碼│└── example/ # 示例代碼 └── mcd_example.c # 使用示例和測試命令

目錄說明

核心模塊

inc/ - 公共頭文件

mcd_cfg.h: 配置管理和OS抽象，支持多OS兼容

coredump.h: 主要API和數(shù)據(jù)結(jié)構(gòu)定義

mcd_elf_define.h: ELF文件格式相關(guān)定義

src/ - 核心實現(xiàn)

mcoredump.c: 核心dump生成引擎，處理ELF格式輸出

faultdump.c: 故障處理入口，管理多種輸出模式

arm/: ARM架構(gòu)特定實現(xiàn)（統(tǒng)一管理ARM32/ARM64）

架構(gòu)支持

arch/ - 架構(gòu)抽象層

mcd_arch_interface.h: 定義架構(gòu)無關(guān)的接口

armv7m/: ARM Cortex-M (ARMv7-M) 特定實現(xiàn)

寄存器定義、異常處理、棧幀解析

系統(tǒng)適配

osal/ - 操作系統(tǒng)適配層

rtthread.c: RT-Thread系統(tǒng)的線程管理和內(nèi)存操作適配

示例代碼

example/ - 使用示例

基本API使用演示

MSH調(diào)試命令

故障觸發(fā)測試

關(guān)鍵文件說明

配置選項

Kconfig 配置

使用 RTT ENV 工具 menuconfig 進入 RT-Thread Components → tools packages → MCoreDump 進行配置：

內(nèi)存要求

最小 RAM：約 10KB（包含緩沖區(qū)和代碼）

Flash 占用：約 15-20KB（取決于配置）

快速開始

適配工作

GCC 工具鏈

需要在項目的鏈接腳本中添加如下代碼（noinit 段需要加到 bss 段前面）：

/* Section for persistent data that survives reset (no load, no init) */.noinit(NOLOAD) :ALIGN(4){ . =ALIGN(4); __noinit_start__ = .; *(.noinit) *(.noinit.*) . =ALIGN(4); __noinit_end__ = .;} >RAM1
__bss_start = .;.bss:{ ...} >RAM1__bss_end = .;

Keil 工具鏈（ac5/ac6）

/* 0x2400 是coredump預(yù)留的內(nèi)存空間 */RW_IRAM2(0x20000000+ (0x00020000-0x2400))UNINIT0x2400 { *(.bss.NoInit)}

CPU 異常部分

cortex-m3 請參考此 PR 的內(nèi)容進行修改：https://github.com/RT-Thread/rt-thread/pull/10619

cortex-m4 請參考此 PR 的內(nèi)容進行修改：https://github.com/RT-Thread/rt-thread/pull/10618

cortex-m33 請參考此 PR 的內(nèi)容進行修改：https://github.com/RT-Thread/rt-thread/pull/10624

1. 啟用組件

在 RT-Thread 項目中通過 menuconfig 啟用 MCoreDump：

# 更新軟件包索引pkgs--upgrade-force
# 進入配置菜單menuconfig
# 導(dǎo)航到: RT-Thread online packages → tools packages → MCoreDump

2. 編譯和運行

# 編譯項目scons
# 燒錄到目標(biāo)板# 啟動系統(tǒng)，MCoreDump 會自動初始化

3. 基本使用

系統(tǒng)正常啟動，會自動打印 MCoreDump 相關(guān)信息，包括：coredump 緩存區(qū)起始地址，緩沖區(qū)大小

演示第一次啟動沒有觸發(fā)過異常因此會顯示：”No valid coredump found in memory.“

手動輸入 mcd_test FAULT 觸發(fā)非法地址訪問異常，并觸發(fā)硬件 fault，此時會打印出 coredump 信息。

芯片進行復(fù)位后，會打印 ”Use ‘mcd_dump_memory’ command to dump memory to terminal.“

由于 coredump 緩存區(qū)被定義到了 noinit 段，除非沒有硬件斷情況發(fā)生否則會正常的如下圖所示

此時可以在 shell 中輸入 mcd_dump_memory 將 coredump 信息打印出來。

工具使用：打開 MCoreDump/tools 下面的 coredump.exe 軟件，下圖介紹了具體功能字段信息：

點擊 Begin GDB 按鈕，啟動 GDB 調(diào)試：

API 參考

主要函數(shù)

mcd_init() - 初始化函數(shù)

voidmcd_init(mcd_writeout_func_tfunc);

功能：初始化 MCoreDump 系統(tǒng)，自動檢測FPU支持

參數(shù)：

func：輸出回調(diào)函數(shù)指針，用于處理 coredump 數(shù)據(jù)

FPU檢測：

自動檢測：基于編譯器宏 __VFP_FP__ 和 __SOFTFP__

硬件FPU：包含浮點寄存器信息

軟件FPU：僅包含核心寄存器信息

示例：

voidmy_output(uint8_t *data, int len){ // 處理 coredump 數(shù)據(jù)}mcd_init(my_output); // 自動檢測FPU

mcd_faultdump()

intmcd_faultdump(mcd_output_mode_toutput_mode);

功能：生成 coredump 并輸出到指定目標(biāo)

參數(shù)：

output_mode：輸出模式

MCD_OUTPUT_SERIAL：串口輸出

MCD_OUTPUT_MEMORY：內(nèi)存緩沖區(qū)

MCD_OUTPUT_FILESYSTEM：文件系統(tǒng)

返回值：

MCD_OK：成功

MCD_ERROR：失敗

mcd_check_memory_coredump()

rt_bool_tmcd_check_memory_coredump(void);

功能：檢查內(nèi)存中是否存在有效的 coredump

返回值：

RT_TRUE：存在有效 coredump

RT_FALSE：無有效 coredump

mcd_print_memoryinfo()

voidmcd_print_memoryinfo(void);

功能：打印 coredump 內(nèi)存信息，通常在啟動時調(diào)用

mcd_mini_dump() -簡化 coredump

voidmcd_mini_dump(void);

功能：生成當(dāng)前線程的簡化 coredump

特點：

僅包含當(dāng)前線程信息

文件更小，生成更快

適合快速故障分析

mcd_multi_dump() -完整 coredump（包括線程信息）

voidmcd_multi_dump(void);

功能：生成包含所有線程的完整 coredump

特點：

包含系統(tǒng)所有線程信息

提供完整的系統(tǒng)快照

適合深度分析

尺寸計算函數(shù)

int32_tmcd_mini_dump_size(void); // 獲取簡化 coredump 大小int32_tmcd_multi_dump_size(void); // 獲取完整 coredump 大小

輸出模式詳解

1. 串口輸出模式 (MCD_OUTPUT_SERIAL)

// 直接輸出 coredump 到串口mcd_faultdump(MCD_OUTPUT_SERIAL);

特點：

實時輸出，無需額外存儲空間

輸出十六進制格式，帶 CRC32 校驗

適合實時調(diào)試和分析

輸出格式：

coredumpstart: {7f454c46010101000000000000000000...} coredumpendcrc32 :12345678

內(nèi)存緩沖區(qū)模式 (MCD_OUTPUT_MEMORY)

// 保存到內(nèi)存緩沖區(qū)mcd_faultdump(MCD_OUTPUT_MEMORY);// 檢查和讀取if(mcd_check_memory_coredump()) { mcd_dump_memory_to_serial();}

特點：

數(shù)據(jù)持久保存（斷電保持）

緩沖區(qū)大小可配置

帶完整性校驗（CRC32）

適合現(xiàn)場故障記錄

3. 文件系統(tǒng)模式 (MCD_OUTPUT_FILESYSTEM)

// 保存到文件系統(tǒng)mcd_faultdump(MCD_OUTPUT_FILESYSTEM);// 從內(nèi)存保存到文件mcd_dump_filesystem();

特點：

生成標(biāo)準(zhǔn) ELF 文件

支持時間戳命名

可用標(biāo)準(zhǔn)調(diào)試工具分析

需要文件系統(tǒng)支持

高級配置

自定義輸出函數(shù)

voidmy_custom_output(uint8_t *data, int len){ // 自定義數(shù)據(jù)處理邏輯 // 例如：網(wǎng)絡(luò)傳輸、專用存儲等}

內(nèi)存緩沖區(qū)配置

在 rtconfig.h 中或通過 Kconfig 設(shè)置：

#definePKG_MCOREDUMP_MEMORY_SIZE (16 * 1024) // 16KB 緩沖區(qū)

文件系統(tǒng)路徑配置

#define PKG_MCOREDUMP_FILESYSTEM_DIR "/data/coredump"#define PKG_MCOREDUMP_FILESYSTEM_PREFIX "crash_"

調(diào)試工具使用

使用 GDB 分析

獲取 coredump 內(nèi)容：

# 模擬異常情況：
msh />mcd_test FAULTthread pri status sp stack size max used left tick error tcb addr---------------- --- ------- ---------- ---------- ------ ---------- ------- ----------tshell 20 running 0x000000d40x00001000 13% 0x00000008 OK 0x20006e28mmcsd_detect 22 suspend0x000000c40x00000800 51% 0x00000001 EINTRPT 0x20004d68tidle0 31 ready 0x0000008c0x00000400 16% 0x00000005 OK 0x20005878main 10 suspend0x000000d40x00000800 56% 0x0000000c EINTRPT 0x20005fc0
=== MCoreDump Memory Storage Started ===Coredump saved to memory buffer:
Address: 0x20000EF4 Size: 3644 bytes CRC32: 0x86517DA7=== MCoreDump Memory Storage Completed ===
# -------------------------------------軟復(fù)位芯片-------------------------------------
\ | /- RT - Thread Operating System/ | \ 5.2.1 build Aug 19202513552006 - 2024 Copyright by RT-Thread team
=== MCoreDump Memory Check ===Memory buffer address: 0x20000EF4Buffer size: 8208 bytes*** COREDUMP FOUND IN MEMORY ***Data size: 3644 bytesUse'mcd_dump_filesystem'commandto save to file.Use'mcd_dump_memory'commandto dump memory to terminal.File counter: 0 (next file will be 0001)============================
[I/SDIO] SD card capacity 31166976 KB.[I/SDIO] sd: switch to High Speed / SDR25 mode
found part[0], begin: 1048576, size: 29.739GB[I/app.filesystem] SD card mount to'/sdcard'msh />msh />mcd_dump_filesystemCreating coredump file: /sdcard/core_0001.elfCoredump file opened successfully (fd: 3)Saving coredump from memory to file: /sdcard/core_0001.elfCoredump saved successfully to: /sdcard/core_0001.elfmsh />msh /sdcard>lsDirectory /sdcard:core_0001.elf 3736

GDB 分析（需要使用高版本 gcc 工具鏈，實測 >= 13.2）：

# 啟動 GDB + 加載 coredumpD:\...\gcc_arm\13.2.rel1\bin\arm-none-eabi-gdb.exe rt-thread.elf core_0001.elf
# 查看崩潰位置(gdb) bt
# 查看寄存器(gdb) info registers
# 查看所有寄存器(gdb) info registersall

查看寄存器內(nèi)容：

查看系統(tǒng)線程信息：

如何適配新架構(gòu)

以 ARMV7-M 為例：

實現(xiàn) rt_hw_exception_install 傳入異常發(fā)生時的棧幀

packages\MCoreDump\arch 下新增架構(gòu)文件夾，需要在 armv7m.c 中實現(xiàn) armv7m_hard_fault_exception_hook，

在 armv7m.c 中實現(xiàn) collect_registers_armv7m 函數(shù)，實現(xiàn)對 coredump 結(jié)構(gòu)體成員賦值

packages\MCoreDump\osal\rtthread.c 中新增 arch_hard_fault_exception_hook 聲明，調(diào)用關(guān)系：rtt_hard_fault_exception_hook—>arch_hard_fault_exception_hook

mcd_get_regset實現(xiàn)：把當(dāng)前 CPU 的一組核心寄存器快照寫入由 regset 指向的內(nèi)存區(qū)，按約定的順序保存

mcd_multi_dump 實現(xiàn)：用于收集當(dāng)前 CPU 寄存器快照（core + 可選 FPU），再調(diào)用 RTOS 相關(guān)回調(diào)收集多線程信息，最后生成 core dump。與 mcd_mini_dump 的主要差別在于：mini 只準(zhǔn)備單一線程/最小信息，multi 會通過 mcd_rtos_thread_ops 收集多線程/RTOS 信息然后生成完整 coredump

packages\MCoreDump\arch\armv7m\registers.h 中需要實現(xiàn)對應(yīng)架構(gòu)的棧幀（r0-r15，xpsr）

性能特性

故障排除

Q1: GDB 報錯 “Core file format not supported”

請使用 gdb-multiarch 或 更高版本 arm-none-eabi-gdb。

Q2：控制臺打印 “Failed to create coredump file”

請確認(rèn) SD 卡 在成功掛載；

可使用 ls / 命令確認(rèn)文件系統(tǒng)目錄是否可見。

Q3: 系統(tǒng)啟動后提示 “elm mount filesvstem failed!”

存儲介質(zhì)需要格式化為 FAT32 格式，可以在系統(tǒng)啟動后輸入mkfs -t elm sd0命令進行格式化。格式化成功后，重啟系統(tǒng)，控制臺打印 elm file system initializated!

注意：格式化會刪除SD卡中的所有文件，請謹(jǐn)慎使用?。。?/p>

貢獻指南

歡迎支持此項目，歡迎參與 MCoreDump 組件的開發(fā)和改進！

開發(fā)環(huán)境

RT-Thread 開發(fā)環(huán)境

交叉編譯工具鏈

許可證

本項目采用 Apache 2.0 許可證。詳見 LICENSE 文件。

https://github.com/RT-Thread/rt-thread/blob/master/LICENSE