Name	Name	Last commit message	Last commit date
Latest commit History 9 Commits
arch	arch
docs	docs
example	example
inc	inc
osal	osal
src	src
tools	tools
.gitignore	.gitignore
LICENSE	LICENSE
README.md	README.md
SConscript	SConscript

MCoreDump - 嵌入式系统故障转储组件

喜欢这个项目吗?欢迎 Star ⭐️ 以帮助改进!

📑 目录

📖 组件介绍
🚀 主要特性
🎯 应用场景
✅ 支持架构
🏗️ 系统架构
📂 目录结构
📦 配置选项
🚀 快速开始
📚 API 参考
- 主要函数
- 输出模式详解
🛠️ 高级配置
🔧 调试工具使用
💪 如何适配新架构
📊 性能特性
🐛 故障排除
🤝 贡献指南
📄 许可证

📖 组件介绍

MCoreDump(mini-coredump) 是专为嵌入式系统设计的故障转储(CoreDump)组件,能够在系统发生硬故障(Hard Fault)、断言失败或其他异常情况时,自动生成标准 ELF 格式的核心转储文件,用于离线调试和故障分析。

🎞️ 视频介绍

https://www.bilibili.com/video/BV11TeEzFEdf

🚀 主要特性

🔧 ELF 格式兼容:生成标准 ELF 格式的 core dump 文件,兼容 GDB、objdump 等调试工具
💾 多种输出模式:支持串口输出、内存缓冲区存储、文件系统保存
🏗️ 多线程支持:能够捕获多线程环境下所有线程的状态信息
⚡ 断电保持:内存模式下数据在断电重启后仍可保持(需硬件支持)
🛡️ 故障安全:采用静态内存分配,避免在故障时使用动态内存
📊 完整状态捕获:包含寄存器、栈信息、内存数据等完整系统状态

🎯 应用场景

嵌入式系统调试:定位硬故障、栈溢出、内存访问错误等问题
产品质量保证:生产环境故障记录和分析
固件开发:多线程程序调试和优化
现场故障分析:设备部署后的远程故障诊断

✅ 支持架构

Armv7-M
Armv8-M

🏗️ 系统架构

MCoreDump 组件架构
┌─────────────────────────────────────────────────────────┐
│ 用户层 API │
├─────────────────────────────────────────────────────────┤
│ mcd_faultdump() │ mcd_test │ mcd_dump_filesystem |
├─────────────────────────────────────────────────────────┤
│ 核心引擎层 │
├─────────────────────────────────────────────────────────┤
│ mcd_mini_dump() │ mcd_multi_dump() │ mcd_gen_coredump() │
├─────────────────────────────────────────────────────────┤
│ 输出适配层 │
├─────────────────────────────────────────────────────────┤
│ 串口输出 │ 内存缓冲区 │ 文件系统 │
├─────────────────────────────────────────────────────────┤
│ 平台抽象层 │
├─────────────────────────────────────────────────────────┤
│ RT-Thread 适配 │ 架构特定代码 │
├─────────────────────────────────────────────────────────┤
│ 硬件 │
└─────────────────────────────────────────────────────────┘

📂目录结构

MCoreDump 组件采用模块化设计:

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架构特定代码
│ ├── mcd_arm.c # ARM架构实现(统一ARM32/64)
│ └── mcd_arm_define.h # ARM架构定义
│
├── arch/ # 架构抽象层
│ ├── mcd_arch_interface.h # 架构接口定义
│ └── armv7m/ # ARM Cortex-M特定实现
│ ├── armv7m.c # ARMv7-M寄存器收集
│ └── registers.h # 寄存器结构定义
│
├── osal/ # 操作系统适配层
│ └── rtthread.c # RT-Thread特定适配代码
│
└── example/ # 示例代码
 └── mcd_example.c # 使用示例和测试命令

目录说明

📂 核心模块

inc/ - 公共头文件
- mcd_cfg.h: 配置管理和OS抽象,支持多OS兼容
- coredump.h: 主要API和数据结构定义
- mcd_elf_define.h: ELF文件格式相关定义
src/ - 核心实现
- mcoredump.c: 核心dump生成引擎,处理ELF格式输出
- faultdump.c: 故障处理入口,管理多种输出模式
- arm/: ARM架构特定实现(统一管理ARM32/ARM64)

📂 架构支持

arch/ - 架构抽象层
- mcd_arch_interface.h: 定义架构无关的接口
- armv7m/: ARM Cortex-M (ARMv7-M) 特定实现
  - 寄存器定义、异常处理、栈帧解析

📂 系统适配

osal/ - 操作系统适配层
- rtthread.c: RT-Thread系统的线程管理和内存操作适配

📂 示例代码

example/ - 使用示例
- 基本API使用演示
- MSH调试命令
- 故障触发测试

关键文件说明

文件	功能	特点
`mcd_cfg.h`	OS抽象和配置管理	支持多OS,统一API接口
`mcoredump.c`	ELF文件生成核心	ELF格式处理,内存布局
`faultdump.c`	故障处理入口	多输出模式,用户API
`mcd_arm.c`	ARM架构实现	统一ARM32/64支持
`armv7m.c`	Cortex-M特定代码	寄存器收集,异常处理
`rtthread.c`	RT-Thread适配	线程信息,系统调用
`mcd_example.c`	使用示例	MSH命令,测试用例

📦 配置选项

Kconfig 配置

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

配置项	说明	默认值
`PKG_USING_MCOREDUMP`	启用 MCoreDump 组件	n
`PKG_USING_MCOREDUMP_ARCH_ARMV7M`	支持 ARM Cortex-M 架构	y
`PKG_MCOREDUMP_MEMORY_SIZE`	内存缓冲区大小	8192 字节
`PKG_USING_MCOREDUMP_FILESYSTEM`	启用文件系统支持	n
`PKG_MCOREDUMP_FILESYSTEM_DIR`	文件系统保存目录	"/sdcard"
`PKG_MCOREDUMP_FILESYSTEM_PREFIX`	文件名前缀	"core_"
`PKG_USING_MCOREDUMP_EXAMPLE`	启用示例代码	y

内存要求

最小 RAM:约 10KB(包含缓冲区和代码)
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预留的内存空间 */
RW_IRAM2 (0x20000000 + (0x00020000 - 0x2400)) UNINIT 0x2400 {
 *(.bss.NoInit)
}

CPU 异常部分

cortex-m3 请参考此 PR 的内容进行修改
cortex-m4 请参考此 PR 的内容进行修改
cortex-m33 请参考此 PR 的内容进行修改

1. 启用组件

在 RT-Thread 项目中通过 menuconfig 启用 MCoreDump:

# 更新软件包索引
pkgs --upgrade-force
# 进入配置菜单
menuconfig
# 导航到: RT-Thread online packages → tools packages → MCoreDump

2. 编译和运行

# 编译项目
scons
# 烧录到目标板
# 启动系统,MCoreDump 会自动初始化

3. 基本使用

系统正常启动,会自动打印 MCoreDump 相关信息,包括:coredump 缓存区起始地址,缓冲区大小

演示第一次启动没有触发过异常因此会显示:"No valid coredump found in memory."

手动输入 mcd_test FAULT 触发非法地址访问异常,并触发硬件 fault,此时会打印出 coredump 信息。

芯片进行复位后,会打印 "Use 'mcd_dump_memory' command to dump memory to terminal."

由于 coredump 缓存区被定义到了 noinit 段,除非没有硬件断情况发生否则会正常的如下图所示

此时可以在 shell 中输入 mcd_dump_memory 将 coredump 信息打印出来。

工具使用:打开 MCoreDump/tools 下面的 coredump.exe 软件,下图介绍了具体功能字段信息:

点击 Begin GDB 按钮,启动 GDB 调试:

📚 API 参考

主要函数

`mcd_init()` - 初始化函数

void mcd_init(mcd_writeout_func_t func);

功能:初始化 MCoreDump 系统,自动检测FPU支持

参数:

func:输出回调函数指针,用于处理 coredump 数据

FPU检测:

自动检测:基于编译器宏 __VFP_FP__ 和 __SOFTFP__
硬件FPU:包含浮点寄存器信息
软件FPU:仅包含核心寄存器信息

示例:

void my_output(uint8_t *data, int len) {
 // 处理 coredump 数据
}
mcd_init(my_output); // 自动检测FPU

`mcd_faultdump()`

int mcd_faultdump(mcd_output_mode_t output_mode);

功能:生成 coredump 并输出到指定目标

参数:

output_mode:输出模式
- MCD_OUTPUT_SERIAL:串口输出
- MCD_OUTPUT_MEMORY:内存缓冲区
- MCD_OUTPUT_FILESYSTEM:文件系统

返回值:

MCD_OK:成功
MCD_ERROR:失败

`mcd_check_memory_coredump()`

rt_bool_t mcd_check_memory_coredump(void);

功能:检查内存中是否存在有效的 coredump

返回值:

RT_TRUE:存在有效 coredump
RT_FALSE:无有效 coredump

`mcd_print_memoryinfo()`

void mcd_print_memoryinfo(void);

功能:打印 coredump 内存信息,通常在启动时调用

`mcd_mini_dump()` - 简化 coredump

void mcd_mini_dump(void);

功能:生成当前线程的简化 coredump

特点:

仅包含当前线程信息
文件更小,生成更快
适合快速故障分析

`mcd_multi_dump()` - 完整 coredump(包括线程信息)

void mcd_multi_dump(void);

功能:生成包含所有线程的完整 coredump

特点:

包含系统所有线程信息
提供完整的系统快照
适合深度分析

尺寸计算函数

int32_t mcd_mini_dump_size(void); // 获取简化 coredump 大小
int32_t mcd_multi_dump_size(void); // 获取完整 coredump 大小

输出模式详解

1. 串口输出模式 (`MCD_OUTPUT_SERIAL`)

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

特点:

实时输出,无需额外存储空间
输出十六进制格式,带 CRC32 校验
适合实时调试和分析

输出格式:

coredump start : {
7f454c46010101000000000000000000...
} coredump end
crc32 : 12345678

2. 内存缓冲区模式 (`MCD_OUTPUT_MEMORY`)

// 保存到内存缓冲区
mcd_faultdump(MCD_OUTPUT_MEMORY);
// 检查和读取
if (mcd_check_memory_coredump()) {
 mcd_dump_memory_to_serial();
}

特点:

数据持久保存(断电保持)
缓冲区大小可配置
带完整性校验(CRC32)
适合现场故障记录

3. 文件系统模式 (`MCD_OUTPUT_FILESYSTEM`)

// 保存到文件系统
mcd_faultdump(MCD_OUTPUT_FILESYSTEM);
// 从内存保存到文件
mcd_dump_filesystem();

特点:

生成标准 ELF 文件
支持时间戳命名
可用标准调试工具分析
需要文件系统支持

🛠️ 高级配置

自定义输出函数

void my_custom_output(uint8_t *data, int len) {
 // 自定义数据处理逻辑
 // 例如:网络传输、专用存储等
}
// 新版本:自动FPU检测初始化(推荐)
mcd_init(my_custom_output);

内存缓冲区配置

在 rtconfig.h 中或通过 Kconfig 设置:

#define PKG_MCOREDUMP_MEMORY_SIZE (16 * 1024) // 16KB 缓冲区

文件系统路径配置

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

🔧 调试工具使用

使用 GDB 分析

获取 coredump 内容:

# 模拟异常情况:
msh />mcd_test FAULT
thread pri status sp stack size max used left tick error tcb addr
---------------- --- ------- ---------- ---------- ------ ---------- ------- ----------
tshell 20 running 0x000000d4 0x00001000 13% 0x00000008 OK 0x20006e28
mmcsd_detect 22 suspend 0x000000c4 0x00000800 51% 0x00000001 EINTRPT 0x20004d68
tidle0 31 ready 0x0000008c 0x00000400 16% 0x00000005 OK 0x20005878
main 10 suspend 0x000000d4 0x00000800 56% 0x0000000c EINTRPT 0x20005fc0
=== MCoreDump Memory Storage Started ===
Coredump saved to memory buffer:
 Address: 0x20000EF4
 Size: 3644 bytes
 CRC32: 0x86517DA7
=== MCoreDump Memory Storage Completed ===
# -------------------------------------软复位芯片-------------------------------------
 \ | /
- RT - Thread Operating System
 / | \  5.2.1 build Aug 19 2025 13:50:55
 2006 - 2024 Copyright by RT-Thread team
=== MCoreDump Memory Check ===
Memory buffer address: 0x20000EF4
Buffer size: 8208 bytes
*** COREDUMP FOUND IN MEMORY ***
Data size: 3644 bytes
Use 'mcd_dump_filesystem' command to save to file.
Use 'mcd_dump_memory' command to 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_filesystem
Creating coredump file: /sdcard/core_0001.elf
Coredump file opened successfully (fd: 3)
Saving coredump from memory to file: /sdcard/core_0001.elf
Coredump saved successfully to: /sdcard/core_0001.elf
msh />
msh /sdcard>ls
Directory /sdcard:
core_0001.elf 3736

GDB 分析(需要使用高版本 gcc 工具链,实测 >= 13.2):

# 启动 GDB + 加载 coredump
D:\...\gcc_arm1円3.2.rel1\bin\arm-none-eabi-gdb.exe rt-thread.elf core_0001.elf
# 查看崩溃位置
(gdb) bt
# 查看寄存器
(gdb) info registers
# 查看所有寄存器
(gdb) info registers all

查看寄存器内容:

查看系统线程信息:

💪 如何适配新架构

以 ARMV7-M 为例:

实现 rt_hw_exception_install 传入异常发生时的栈帧
packages\MCoreDump\arch 下新增架构文件夹,需要在 armv7m.c 中实现 armv7m_hard_fault_exception_hook,
在 armv7m.c 中实现 collect_registers_armv7m 函数,实现对 coredump 结构体成员赋值
packages\MCoreDump\osal\rtthread.c 中新增 arch_hard_fault_exception_hook 声明,调用关系:rtt_hard_fault_exception_hook—>arch_hard_fault_exception_hook
mcd_get_regset实现:把当前 CPU 的一组核心寄存器快照写入由 regset 指向的内存区,按约定的顺序保存
mcd_multi_dump 实现:用于收集当前 CPU 寄存器快照(core + 可选 FPU),再调用 RTOS 相关回调收集多线程信息,最后生成 core dump。与 mcd_mini_dump 的主要差别在于:mini 只准备单一线程/最小信息,multi 会通过 mcd_rtos_thread_ops 收集多线程/RTOS 信息然后生成完整 coredump
packages\MCoreDump\arch\armv7m\registers.h 中需要实现对应架构的栈帧(r0-r15,xpsr)

📊 性能特性

指标	值	说明
单线程 coredump 时间	< 100ms	不包含 I/O 时间
多线程 coredump 时间	< 500ms	取决于线程数量
内存占用	8-64KB	可配置缓冲区大小
Flash 占用	15-20KB	包含完整功能
支持线程数	无限制	受内存大小限制

🐛 故障排除

Q1: GDB 报错 "Core file format not supported"

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

Q2:控制台打印 "Failed to create coredump file"

请确认 SD 卡在成功挂载;

可使用 ls / 命令确认文件系统目录是否可见。

Q3: 系统启动后提示 "elm mount filesvstem failed!"

存储介质需要格式化为 FAT32 格式,可以在系统启动后输入mkfs -t elm sd0命令进行格式化。格式化成功后,重启系统,控制台打印 elm file system initializated!

注意:格式化会删除SD卡中的所有文件,请谨慎使用!!!

调试技巧

🤝 贡献指南

欢迎⭐支持此项目,欢迎参与 MCoreDump 组件的开发和改进!

开发环境

RT-Thread 开发环境
交叉编译工具链

📄 许可证

本项目采用 Apache 2.0 许可证。详见 LICENSE 文件。

License

Rbb666/MCoreDump

Folders and files

Latest commit

History

Repository files navigation