# kdump_proj

**Repository Path**: jose47/kdump_proj

## Basic Information

- **Project Name**: kdump_proj
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# kdump_proj — x-kernel as Crash Kernel via kexec

This project demonstrates using [x-kernel](https://gitee.com/jose47/x-kernel) (a Rust-based aarch64 microkernel) as a **crash kernel** on the Linux kexec/kdump path. When Linux panics, kexec hands control to x-kernel, which then extracts and prints the crashed kernel's complete dmesg — including the panic backtrace — via UART.

Everything runs on **QEMU aarch64 virt** (no physical hardware required). Currently only the **ARM64** target is supported.

## Repository Structure

```
kdump_proj/
├── x-kernel/                 # [submodule] Rust microkernel (branch: kexec_demo)
├── kexec-tools/              # [submodule] kexec-tools (builds the kexec binary)
├── boot-assets/              # Prebuilt files for QEMU boot
│   ├── Image                     # Linux 6.6 ARM64 kernel
│   ├── initramfs-arm64-kexec.cpio.gz  # Initramfs (busybox + kexec)
│   └── rootfs/                   # Unpacked rootfs source tree
├── scripts/
│   ├── run-qemu.sh               # Launch QEMU with all options configured
│   ├── kexec-load.sh             # Load x-kernel as crash kernel (kexec -p)
│   ├── kexec-exec.sh             # Trigger panic to switch to crash kernel
│   ├── kexec-xkernel.sh          # One-shot: load + exec via kexec -l / kexec -e
│   └── build-initramfs-arm64.sh  # Rebuild initramfs from scratch (native ARM64)
└── docs/
    ├── technical-details.md       # Full technical documentation
    └── kexec-debug-journal.md     # Chronological debugging journal (Chinese)
```

## Prerequisites

| Tool | Version | Purpose |
|------|---------|---------|
| `qemu-system-aarch64` | 7.0+ | ARM64 virtual machine |
| Rust toolchain | nightly | Build x-kernel |
| `aarch64-none-elf` toolchain | any | Cross-compilation (objcopy) |
| `musl` headers + toolchain | any | Bindgen headers and cross-linker |
| `make` | any | x-kernel build system |

### Install on Ubuntu/Debian

The host machine can be x86_64 or ARM64 — QEMU handles the emulation. On ARM64 hosts QEMU runs with KVM acceleration; on x86_64 it uses full emulation (slower but functional).

```bash
# QEMU
sudo apt install qemu-system-arm

# Rust nightly
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default nightly
rustup target add aarch64-unknown-none-softfloat

# AArch64 bare-metal toolchain (for objcopy)
sudo apt install gcc-aarch64-linux-gnu binutils-aarch64-linux-gnu
# or: install rust-objcopy via cargo install cargo-binutils

# musl headers and cross-compilation toolchain
# (x-kernel's Makefile sets BINDGEN_EXTRA_CLANG_ARGS="-I/usr/include/aarch64-linux-musl"
#  and uses aarch64-linux-musl-gcc as the cross-linker)
sudo apt install musl-tools musl-dev
# On x86_64 hosts cross-compiling for aarch64, also install:
sudo apt install gcc-aarch64-linux-gnu musl:arm64 2>/dev/null || true
# Or install the musl cross-toolchain manually if the above is unavailable.
# Ensure /usr/include/aarch64-linux-musl/ exists with standard C headers.
```

## Quick Start

### 1. Clone with submodules

```bash
git clone --recurse-submodules git@gitee.com:jose47/kdump_proj.git
cd kdump_proj
```

If already cloned without submodules:
```bash
git submodule update --init --recursive
```

### 2. Build x-kernel (crash kernel)

```bash
cd x-kernel

# Copy the crashdump-specific defconfig
cp platforms/aarch64-qemu-virt/defconfig-coredump .config

# Build
make build
```

This produces `x-kernel/xkernel_aarch64-qemu-virt.bin`.

### 3. Launch QEMU

```bash
cd ..  # back to kdump_proj root
./scripts/run-qemu.sh
```

This boots Linux with:
- `crashkernel=512M@0xb8000000` — reserves 512 MB for the crash kernel
- `nokaslr` — disables address randomization for deterministic layout
- 9p virtfs sharing the project directory to guest `/host`

You should see the Linux boot messages and a busybox shell prompt.

### 4. Inside the guest: mount host directory

The init script auto-mounts via 9p, but if needed:

```sh
mkdir -p /host
mount -t 9p -o trans=virtio host0 /host
```

### 5. Load x-kernel as crash kernel

```sh
sh /host/scripts/kexec-load.sh
```

This runs `kexec -p` to load x-kernel into the reserved crashkernel region.

### 6. Trigger a crash

```sh
sh /host/scripts/kexec-exec.sh
```

This triggers a kernel panic via sysrq. Linux's panic path then:
1. Stops all CPUs
2. Disables MMU
3. Jumps to x-kernel at `0xb8200000`

### 7. Observe the output

After the crash, you'll see x-kernel boot and print:

```
ABCDEFGH
[crashdump] Checking for crash kernel scenario...
[crashdump] elfcorehdr at PA 0xd7ff0000 size=0x1000
[crashdump] ===== First kernel dmesg =====
[    0.000000] Booting Linux on physical CPU 0x0000000000 [0x410fd083]
[    0.000000] Linux version 6.6.129 ...
...
[    4.923641] sysrq: Trigger a crash
[    4.923858] Kernel panic - not syncing: sysrq triggered crash
...
[    4.926956] Bye!
[crashdump] ===== End of first kernel dmesg =====
```

x-kernel successfully extracted the complete dmesg from the crashed kernel's memory.

## Rebuilding the Initramfs

The prebuilt initramfs is included in the repo. To rebuild from scratch (must run on a **native ARM64** machine, e.g. OrbStack VM):

```bash
bash scripts/build-initramfs-arm64.sh
```

The script outputs directly to `boot-assets/`.

This builds busybox (static) and kexec-tools (dynamic, with libs bundled), creates a minimal rootfs, and packs it as a cpio archive.

## Scripts Reference

| Script | Run where | Description |
|--------|-----------|-------------|
| `scripts/run-qemu.sh` | Host | Launch QEMU with all flags configured |
| `scripts/kexec-load.sh` | Guest | `kexec -p` to load x-kernel as crash kernel |
| `scripts/kexec-exec.sh` | Guest | Trigger sysrq panic to switch to crash kernel |
| `scripts/kexec-xkernel.sh` | Guest | **Broken** — `kexec -l` + `kexec -e` (see note below) |
| `scripts/build-initramfs-arm64.sh` | ARM64 host | Rebuild initramfs from scratch |

> **Note on `kexec-xkernel.sh`:** This script uses `kexec -l` (non-crash path), which loads x-kernel at an arbitrary address chosen by Linux's memory allocator. Since x-kernel is not a Position Independent Executable (PIE), absolute addresses embedded in data sections (function pointers, vtables, linkme slices) will point to the wrong physical memory, causing a crash shortly after `rust_main` starts. **Always use `kexec-load.sh` + `kexec-exec.sh`** (`kexec -p`, crash path), which loads x-kernel at the predictable crashkernel reserved address matching `KERNEL_BASE_PADDR`. See [Issue 5 in technical details](docs/technical-details.md#65-kexec--l-load-address-mismatch) for the full explanation.

## Debugging

- **QEMU debug log**: `/tmp/qemu.log` (exceptions, CPU resets, guest errors)
- **GDB attach**: `gdb-multiarch -ex "target remote :1234"` (QEMU `-s` flag)
- **Early boot markers**: x-kernel prints `A` through `H` via direct UART writes during boot — if it hangs, the last letter tells you exactly which stage failed
- **Page table dump**: x-kernel prints L1 page table entries and current PC before enabling MMU

## Known Limitations

1. **64-bit PCI MMIO**: x-kernel's boot page tables don't cover `0x8000000000+` (QEMU's 64-bit PCI BAR space), so VirtIO PCI devices fail to initialize. This doesn't affect the dmesg extraction demo.
2. **No persistent storage**: Extracted dmesg is printed to UART only. Writing to disk requires PCI + virtio-blk driver support (blocked by #1).
3. **Timestamp formatting**: Dmesg microsecond timestamps lack leading zeros (cosmetic).

## Further Reading

- [`docs/technical-details.md`](docs/technical-details.md) — Full technical documentation of the crash kernel pipeline, memory layout, boot sequence, and all issues encountered
- [`docs/kexec-debug-journal.md`](docs/kexec-debug-journal.md) — Chronological debugging journal (Chinese, 2026-03-20 ~ 2026-03-23)

## License

- x-kernel: Apache-2.0
- kexec-tools: GPL-2.0