{"id":47700489,"url":"https://github.com/jialongwang1201/mkdbg","last_synced_at":"2026-04-30T04:02:25.464Z","repository":{"id":346864624,"uuid":"1190823028","full_name":"JialongWang1201/mkdbg","owner":"JialongWang1201","description":"Hardware-first crash forensics for Cortex-M: staged bring-up, zero-probe UART diagnostics, and causal fault replay for STM32 + FreeRTOS MPU.","archived":false,"fork":false,"pushed_at":"2026-04-25T20:37:05.000Z","size":5580,"stargazers_count":62,"open_issues_count":0,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-25T22:16:56.166Z","etag":null,"topics":["bringup","cortex-m","crash-forensics","embedded-debugging","fault-telemetry","firmware","freertos","mpu","postmortem-analysis","stm32","stm32f446","uart-debugging"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JialongWang1201.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T16:48:31.000Z","updated_at":"2026-04-25T20:35:59.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/JialongWang1201/mkdbg","commit_stats":null,"previous_names":["jialongwang1201/mkdbg"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/JialongWang1201/mkdbg","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JialongWang1201%2Fmkdbg","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JialongWang1201%2Fmkdbg/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JialongWang1201%2Fmkdbg/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JialongWang1201%2Fmkdbg/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JialongWang1201","download_url":"https://codeload.github.com/JialongWang1201/mkdbg/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JialongWang1201%2Fmkdbg/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32454170,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"online","status_checked_at":"2026-04-30T02:00:05.929Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bringup","cortex-m","crash-forensics","embedded-debugging","fault-telemetry","firmware","freertos","mpu","postmortem-analysis","stm32","stm32f446","uart-debugging"],"created_at":"2026-04-02T17:07:16.035Z","updated_at":"2026-04-30T04:02:25.458Z","avatar_url":"https://github.com/JialongWang1201.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"docs/assets/logo.svg\" alt=\"mkdbg\" width=\"360\"/\u003e\n\n[![CI](https://github.com/JialongWang1201/mkdbg/actions/workflows/ci.yml/badge.svg)](https://github.com/JialongWang1201/mkdbg/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/JialongWang1201/mkdbg?include_prereleases\u0026label=release)](https://github.com/JialongWang1201/mkdbg/releases/latest)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n## Embedded firmware debugger. No debug probe required.\n\nmkdbg diagnoses crashes and runs a live debug session on your MCU over a **plain UART connection** — the same serial cable you already use for logs. If you do have an ST-Link or CMSIS-DAP, it works with that too.\n\nNo OpenOCD configuration. No GDB install. No JTAG adapter.\n\n```\n$ mkdbg attach --port /dev/ttyUSB0\n\nFAULT: HardFault (STKERR — stack overflow)\n  PC  0x0800a1f4  task_sensor_run+0x3e\n  LR  0x08009e34  vTaskStartScheduler\n\nBacktrace:\n  #0  fault_handler\n  #1  task_sensor_run     ← likely culprit\n  #2  vTaskStartScheduler\n```\n\n---\n\n## Install\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/JialongWang1201/mkdbg/main/scripts/install.sh | bash\n```\n\nOr download a pre-built binary directly from the [latest release](https://github.com/JialongWang1201/mkdbg/releases/latest):\n\n| Platform | Binary |\n|----------|--------|\n| Linux x86\\_64 | `mkdbg-native-linux-x86_64` |\n| Linux arm64 | `mkdbg-native-linux-arm64` |\n| macOS Apple Silicon | `mkdbg-native-darwin-arm64` |\n| macOS Intel | `mkdbg-native-darwin-x86_64` |\n\n---\n\n## Add to your firmware\n\nLink the `wire` agent into your project — ~300 lines of C99, no OS dependencies:\n\n```c\n// 1. Call from your fault handler:\nwire_on_fault();\n\n// 2. Implement two UART functions:\nvoid wire_uart_send(const uint8_t *buf, size_t len) { /* your HAL */ }\nvoid wire_uart_recv(uint8_t *buf, size_t len)       { /* your HAL */ }\n```\n\nThat's the entire integration. Works with FreeRTOS, Zephyr, bare-metal, or any custom RTOS.\n\nFull porting guide: [`docs/PORTING.md`](docs/PORTING.md) · Reference implementation: [`examples/stm32f446/`](examples/stm32f446/)\n\n---\n\n## What you can do\n\n**Crash report** — decode a fault the moment it happens:\n```bash\nmkdbg attach --port /dev/ttyUSB0\nmkdbg attach --probe --chip STM32F446RETx   # hardware probe\n```\n\n**Live debug session** — breakpoints, step, registers, inline disassembly, FreeRTOS task names:\n```bash\nmkdbg debug --port /dev/ttyUSB0 --elf build/firmware.elf\nmkdbg debug --probe --chip STM32F446RETx --elf build/firmware.elf\n```\n\n**Causal analysis** — trace the event chain that *led* to the crash:\n```bash\nmkdbg seam analyze capture.cfl\n```\n\n**GDB bridge** — connect `arm-none-eabi-gdb` without a hardware probe:\n```bash\nwire-host --port /dev/ttyUSB0\n```\n\n---\n\n## Architecture support\n\n| | Cortex-M (M0/M3/M4/M7) | RISC-V 32 |\n|--|:---:|:---:|\n| Crash report | ✓ | ✓ |\n| Live debug TUI | ✓ | ✓ |\n| FPU registers | ✓ | — |\n| Hardware probe | ✓ | — |\n\nThe built-in disassembler covers the full Thumb/Thumb-2 instruction set including FPU (VFPv4). No dependency on `objdump` or `addr2line`.\n\n---\n\n## Hardware probe support\n\nmkdbg supports ST-Link, CMSIS-DAP, and J-Link via [probe-rs](https://probe.rs).\n\nOn Linux, USB access requires a udev rule:\n```bash\nsudo cp tools/69-probe-rs.rules /etc/udev/rules.d/ \u0026\u0026 sudo udevadm control --reload\n```\n\n---\n\n## Documentation\n\n| | |\n|-|-|\n| [`docs/COMMANDS.md`](docs/COMMANDS.md) | Full command reference and config format |\n| [`docs/PORTING.md`](docs/PORTING.md) | Porting the firmware agent to a new board |\n| [`docs/DEVELOPER_GUIDE.md`](docs/DEVELOPER_GUIDE.md) | Build system, testing, adding arch plugins |\n\n---\n\n## License\n\nMIT. The `wire` and `seam` submodules are MIT. libgit2 is MIT.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjialongwang1201%2Fmkdbg","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjialongwang1201%2Fmkdbg","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjialongwang1201%2Fmkdbg/lists"}