MCoreDump — Embedded System Core Dump Component | Technical Collection

7 min readSep 4, 2025

Open-source repository: https://github.com/Rbb666/MCoreDump

Verified platforms: Renesas RA6M3 (Cortex-M4), Renesas RA6M4 (Cortex-M33). For more platforms, please check the open-source repository.

Component Introduction

MCoreDump (mini-coredump) is a core dump component designed for embedded systems. When the system encounters a hard fault, assertion failure, or other exception, it automatically generates a standard ELF format core dump file for offline debugging and fault analysis.

Key Features

🔧 ELF Format Compatible: Generates standard ELF core dump files, compatible with GDB, objdump, and other debugging tools

💾 Multiple Output Modes: Supports serial output, memory buffer storage, and filesystem saving

🏗️ Multithreading Support: Captures state information of all threads in multithreaded environments

⚡ Power-Failure Retention: Data stored in memory mode can persist after reset and power cycle (hardware-dependent)

🛡️ Fault Safety: Uses static memory allocation to avoid dynamic memory usage during faults

📊 Complete State Capture: Includes registers, stack information, memory data, and full system state

Application Scenarios

● Embedded system debugging: Locate hard faults, stack overflows, memory access errors

● Product quality assurance: Fault recording and analysis in production environments

● Firmware development: Multithreaded program debugging and optimization

● Field failure analysis: Remote diagnosis of deployed devices

Supported Architectures

● Armv7-M

● Armv8-M

System Architecture

MCoreDump Component Architecture
┌─────────────────────────────────────────────────────────┐
│                    User Layer API                       │
├─────────────────────────────────────────────────────────┤
│  mcd_faultdump() │   mcd_test   │  mcd_dump_filesystem  │
├─────────────────────────────────────────────────────────┤
│                    Core Engine Layer                    │
├─────────────────────────────────────────────────────────┤
│ mcd_mini_dump() │ mcd_multi_dump() │ mcd_gen_coredump() │
├─────────────────────────────────────────────────────────┤
│                    Output Adaptation Layer              │
├─────────────────────────────────────────────────────────┤
│     Serial Output │ Memory Buffer │ File System         │
├─────────────────────────────────────────────────────────┤
│                    Platform Abstraction Layer           │
├─────────────────────────────────────────────────────────┤
│      RT-Thread Adaptation │ Architecture-specific Code  │
├─────────────────────────────────────────────────────────┤
│                          Hardware                       │
└─────────────────────────────────────────────────────────┘

Directory Structure

MCoreDump uses a modular design:

MCoreDump/
├── README.md                   # Documentation
├── Kconfig                     # Configuration options
├── SConscript                  # Build script
│
├── inc/                        # Header files
│   ├── mcd_cfg.h               # Config & OS abstraction
│   ├── coredump.h              # Main API declarations
│   └── mcd_elf_define.h        # ELF definitions
│
├── src/                        # Core implementation
│   ├── coredump.c              # Core dump generation engine
│   ├── faultdump.c             # Fault handling & output mgmt
│   └── arm/                    # ARM-specific code
│       ├── mcd_arm.c           # ARM (32/64) implementation
│       └── mcd_arm_define.h    # ARM definitions
│
├── arch/                       # Architecture abstraction
│   ├── mcd_arch_interface.h    # Architecture interfaces
│   └── armv7m/                 # Cortex-M (ARMv7-M)
│       ├── armv7m.c            # Register collection
│       └── registers.h         # Register structure
│
├── osal/                       # OS adaptation layer
│   └── rtthread.c              # RT-Thread adaptation
│
└── example/                    # Example code
    └── mcd_example.c           # Usage demo & test commands

Directory Description

Core Modules

● inc/ — Public headers

○ mcd_cfg.h: Config & OS abstraction, multi-OS compatible

○ coredump.h: Main APIs & data structures

○ mcd_elf_define.h: ELF format definitions

● src/ — Core implementation

○ coredump.c: Core dump engine, ELF output

○ faultdump.c: Fault handler & output management

○ arm/: ARM-specific code (32/64 unified)

Architecture Support

● arch/ — Architecture abstraction layer

○ mcd_arch_interface.h: Architecture-independent interface

○ armv7m/: Cortex-M implementation (registers, exceptions, stack frames)

OS Adaptation

● osal/ — Operating system adaptation layer

○ rtthread.c: RT-Thread thread and memory adaptation

Examples

● example/ — Example code

○ API usage demo, MSH commands, fault tests

Key Files

Configuration Options

Kconfig (via RTT ENV menuconfig: RT-Thread Components → tools packages → MCoreDump)

Memory Requirements:

● Minimum RAM: ~10KB (buffer + code)

● Flash: ~15–20KB (depending on config)

Quick Start

Adaptation Work

GCC Toolchain

Add to linker script (place .noinit before .bss):

.noinit (NOLOAD) : ALIGN(4)
{
    . = ALIGN(4);
    __noinit_start__ = .;
    *(.noinit)
    *(.noinit.*)
    . = ALIGN(4);
    __noinit_end__ = .;
} > RAM1

__bss_start = .;
.bss :
{
    ...
} > RAM1
__bss_end = .;

Keil Toolchain (ac5/ac6)

RW_IRAM2 (0x20000000 + (0x00020000 - 0x2400)) UNINIT 0x2400  {
    *(.bss.NoInit)
}

CPU Exception Hooks

● Cortex-M3: https://github.com/RT-Thread/rt-thread/pull/10619

● Cortex-M4: https://github.com/RT-Thread/rt-thread/pull/10618

● Cortex-M33: https://github.com/RT-Thread/rt-thread/pull/10624

1. Enable Component

pkgs --upgrade-force
menuconfig
# Navigate: RT-Thread online packages → tools packages → MCoreDump

2. Build & Run

scons
# Flash to target board, MCoreDump auto-initializes

3. Basic Usage

● On startup: prints memory buffer info, or “No valid coredump found in memory.”

● Run mcd_test FAULT to trigger exception → generates coredump.

● After reset: system detects stored coredump → use mcd_dump_memory or mcd_dump_filesystem.

API Reference

voidmcd_init(mcd_writeout_func_t func);

● Feature: Initializes MCoreDump, automatically detects FPU support

● Parameter func: output callback for dump data

● Detects FPU by compiler macros __VFP_FP__, __SOFTFP__; includes FP registers if hardware FPU, otherwise core registers only

Example:


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

Main Functions

mcd_faultdump()

intmcd_faultdump(mcd_output_mode_t output_mode);

int mcd_faultdump(mcd_output_mode_t output_mode)

● Function: generate coredump and output to specified target

● Modes: MCD_OUTPUT_SERIAL, MCD_OUTPUT_MEMORY, MCD_OUTPUT_FILESYSTEM

● Returns: MCD_OK on success, MCD_ERROR on failure

rt_bool_t mcd_check_memory_coredump(void)

● Checks if a valid core dump exists in memory

● Returns: RT_TRUE or RT_FALSE

void mcd_print_memoryinfo(void)

● Prints memory buffer information; typically on startup

void mcd_mini_dump(void)

● Features: generates simplified core dump of current thread only

● Smaller size, faster generation; suitable for quick debug

void mcd_multi_dump(void)

● Generates full core dump with all thread info

● Suitable for deep analysis

Size query functions:

int32_t mcd_mini_dump_size(void)
int32_t mcd_multi_dump_size(void)

Debugging with GDB

arm-none-eabi-gdb rt-thread.elf core_0001.elf
(gdb) bt
(gdb) info registers all

Output Modes Explained

1. Serial Output Mode (MCD_OUTPUT_SERIAL)

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

mcd_faultdump(MCD_OUTPUT_SERIAL);

● Real-time hex output with CRC32 checksum

● Format:

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

coredump start : { 7f454c4601010100… } coredump end crc32 : 12345678

2. Memory Buffer Mode (MCD_OUTPUT_MEMORY)

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

mcd_faultdump(MCD_OUTPUT_MEMORY); if (mcd_check_memory_coredump()) { mcd_dump_memory_to_serial(); }

● Persistent buffer, CRC32-checked

● Suitable for field recording

3. Filesystem Mode (MCD_OUTPUT_FILESYSTEM)

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

mcd_faultdump(MCD_OUTPUT_FILESYSTEM); mcd_dump_filesystem();

● Standard ELF file output

● Timestamped naming

● Requires filesystem support

Advanced Configuration

● Custom output function:

voidmy_custom_output(uint8_t *data, int len){
    // 自定义数据处理逻辑
    // 例如：网络传输、专用存储等
}

● Memory buffer configuration:

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

● Filesystem path:

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

Debugging with GDB

# 模拟异常情况：

msh />mcd_test FAULT
thread           pri  status      sp     stack size max used left tick   error  tcb addr
---------------- ---  ------- ---------- ----------  ------  ---------- ------- ----------
tshell            20  running 0x000000d40x00001000    13%   0x00000008 OK      0x20006e28
mmcsd_detect      22  suspend 0x000000c40x00000800    51%   0x00000001 EINTRPT 0x20004d68
tidle0            31  ready   0x0000008c0x00000400    16%   0x00000005 OK      0x20005878
main              10  suspend 0x000000d40x00000800    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 19202513: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 Analysis

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