# 嵌入式Linux远程调试skills

**Repository Path**: leo_liu28/embedded-linux-debug-skills

## Basic Information

- **Project Name**: 嵌入式Linux远程调试skills
- **Description**: 嵌入式Linux远程调试skills
- **Primary Language**: Unknown
- **License**: GPL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🔧 Embedded Linux Remote Debug Skill

> **Windows → SSH → 嵌入式 Linux** 一站式远程性能分析与稳定性调试工具集

---

## 功能概述

本 Skill 提供从 Windows 主机通过 SSH 远程调试嵌入式 Linux 设备的完整方案，覆盖：

- **性能分析**：CPU 热点、内存泄漏、IO 瓶颈定位
- **稳定性诊断**：panic / oops / OOM / 看门狗 / 硬件错误排查
- **内核级追踪**：ftrace 抓取 + Perfetto 可视化（支持 RT 内核）
- **一键收集**：综合诊断打包，现场一次取走全部数据

所有脚本均处理了工具缺失的情况，自动降级到 `/proc` 文件系统读取。

---

## 目录结构

```
.qoder/skills/embedded-linux-debug/
├── SKILL.md                    # Skill 定义与完整使用指南
├── reference.md                # 调试命令参考手册（dmesg/perf/strace/top/ftrace）
└── scripts/
    ├── detect-ssh.ps1          # Windows SSH 客户端自动检测
    ├── cpu-profiling.sh        # CPU 性能分析（top/perf/vmstat/中断）
    ├── memory-analysis.sh      # 内存分析（free/slab/buddyinfo/smaps/OOM）
    ├── io-analysis.sh          # IO 分析（iostat/diskstats/strace/调度器）
    ├── stability-check.sh      # 稳定性排查（panic/oops/MCE/温度/看门狗）
    ├── full-diagnosis.sh       # 一键综合诊断（调用以上所有+打包）
    ├── ftrace-capture.sh       # ftrace Perfetto 兼容抓取脚本
    └── rt_trace_converter.py   # RT内核 ftrace 7位flags→标准4位转换
```

---

## 环境要求

| 端 | 要求 |
|----|------|
| **Windows 主机** | OpenSSH 客户端（Win10 1809+ 自带）或 PuTTY（plink/pscp）；Python 3（RT trace 转换用） |
| **嵌入式 Linux** | SSH 服务（dropbear/openssh-server）；root 权限；建议安装：`perf` `strace` `iostat` |
| **内核配置** | `CONFIG_PERF_EVENTS` `CONFIG_FUNCTION_TRACER` `CONFIG_PSTORE` `CONFIG_PSTORE_RAM`（按需） |
| **网络** | Windows 可访问设备 IP（同网段或可路由） |

---

## 快速开始

```powershell
# ① 检测 SSH 客户端
powershell -ExecutionPolicy Bypass -File scripts/detect-ssh.ps1

# ② 上传脚本到设备
scp scripts/*.sh root@192.168.1.100:/tmp/

# ③ 远程执行综合诊断
ssh root@192.168.1.100 "chmod +x /tmp/*.sh; /tmp/full-diagnosis.sh"

# ④ 取回诊断报告
scp root@192.168.1.100:/tmp/diagnosis_output.tar.gz .

# ⑤ 解压分析
tar -xzf diagnosis_output.tar.gz
```

> **提示**：推荐使用密钥认证免密登录，避免每次输入密码。

---

## 调试场景一览

| # | 场景 | 脚本/方法 | 适用问题 |
|---|------|-----------|----------|
| 1 | CPU 性能分析 | `cpu-profiling.sh [PID] [秒数]` | CPU 占用高、负载异常、响应慢 |
| 2 | 内存分析 | `memory-analysis.sh [PID]` | 内存泄漏、OOM、Slab 异常、碎片 |
| 3 | IO 性能分析 | `io-analysis.sh [PID] [秒数]` | 磁盘/Flash 读写慢、写放大 |
| 4 | 稳定性排查 | `stability-check.sh` | 重启、卡死、内核错误、硬件故障 |
| 5 | 综合诊断 | `full-diagnosis.sh` | 一次性打包全部信息 |
| 6 | ftrace Perfetto | `ftrace-capture.sh [输出] [秒数]` | 调度延迟、中断分析、IO 调度 |
| 7 | strace 单线程 | `strace -p <TID>` 手动执行 | 多线程应用特定线程系统调用跟踪 |
| 8 | pstore 崩溃日志 | 读取 `/var/lib/systemd/pstore/` | 内核崩溃后的 dmesg 恢复 |

---

## 工具命令速查

### dmesg

```bash
dmesg -T                                    # 人类可读时间戳
dmesg -T --level=err,warn                   # 仅错误和警告
dmesg | grep -iE "panic|oops|bug"           # 内核崩溃
dmesg | grep -iE "oom|killed process"       # OOM 排查
dmesg | grep -iE "mce|ecc|hardware error"   # 硬件错误
```

### perf

```bash
perf top -p <PID>                           # 实时热点函数
perf record -g -p <PID> -- sleep 10         # 采样10秒（含调用栈）
perf report --stdio                         # 查看采样结果
perf stat -p <PID> -- sleep 10              # 硬件计数器汇总
perf sched latency                          # 调度延迟分布
```

### strace

```bash
strace -c -p <PID>                          # 统计模式（耗时+计数）
strace -tt -T -p <PID>                      # 时间戳+每次调用耗时
strace -e trace=file <cmd>                  # 仅跟踪文件IO
strace -f -p <PID>                          # 跟踪所有子进程/线程
timeout 20s strace -tt -yy -T -s 1024 -p <TID>  # 单线程精确跟踪
```

### top

```bash
top -b -n 1                                 # 批处理模式单次输出
top -H -p <PID>                             # 线程视图
ps auxww --sort=-%cpu | head                # CPU Top 进程
```

### ftrace

```bash
echo function > /sys/kernel/debug/tracing/current_tracer   # 设置tracer
echo 1 > /sys/kernel/debug/tracing/tracing_on              # 开始
echo 0 > /sys/kernel/debug/tracing/tracing_on              # 停止
cat /sys/kernel/debug/tracing/trace > /tmp/ftrace.log      # 导出
echo nop > /sys/kernel/debug/tracing/current_tracer        # 清理
```

---

## ftrace + Perfetto 工作流

### 标准内核流程

```powershell
# 1. 上传抓取脚本
scp scripts/ftrace-capture.sh root@<IP>:/tmp/

# 2. 远程执行（默认10秒）
ssh root@<IP> "chmod +x /tmp/ftrace-capture.sh; /tmp/ftrace-capture.sh /tmp/ftrace.txt 10"

# 3. 取回 trace 文件
scp root@<IP>:/tmp/ftrace.txt ./results/

# 4. 打开 https://ui.perfetto.dev 导入 ftrace.txt
```

### RT 内核额外步骤（必须）

RT（PREEMPT_RT）内核的 ftrace 使用 **7位 flags 格式**，Perfetto 无法直接识别：

| flags 格式 | 示例 | 内核类型 | 是否需要转换 |
|------------|------|----------|:---:|
| 4位 | `dnh1` | 标准内核 | ❌ |
| 7位 | `dn.h1..` | RT 内核 | ✅ |

```powershell
# 在 Windows 本地执行转换（需 Python3）
python scripts/rt_trace_converter.py ./results/ftrace.txt ./results/ftrace_perfetto.txt

# 然后导入 ftrace_perfetto.txt 到 Perfetto
```

> **转换原理**：保留 Perfetto 需要的 4 个关键位（irqs-off / need-resched / hardirq / preempt-depth），过滤 RT 专有字段（need-resched-lazy / preempt-lazy-depth / migrate-disable）。

---

## 注意事项

| # | 事项 | 说明 |
|---|------|------|
| 1 | 资源限制 | 嵌入式设备 RAM/Flash 有限，`perf record` 建议 ≤10s，及时清理 `/tmp` |
| 2 | ftrace 开销 | `function`/`function_graph` tracer 可能造成 30%+ 性能下降，**生产环境勿长时间开启** |
| 3 | 存储空间 | 执行前先 `df -h /tmp` 确认空间，综合诊断输出可达数 MB |
| 4 | 权限要求 | `perf record` / ftrace 写操作必须 root |
| 5 | 工具缺失 | 脚本自动降级，`iostat` 不存在会使用 `/proc/diskstats` 替代 |
| 6 | 网络抖动 | 弱网建议 `ssh -o ServerAliveInterval=30`，长任务用 `nohup` 后台执行 |
| 7 | 安全 | 优先使用密钥认证，避免明文密码；`plink -pw` 仅限内部调试网络 |
| 8 | ftrace 清理 | 使用后务必执行 `echo nop > current_tracer; echo 0 > tracing_on` |

---

## 文件说明

| 文件 | 参数 | 用途 |
|------|------|------|
| `detect-ssh.ps1` | 无 | 检测 Windows 上可用的 SSH 客户端（OpenSSH/PuTTY） |
| `cpu-profiling.sh` | `[PID] [秒数]` | CPU 分析：top + perf stat/record + 中断 + vmstat |
| `memory-analysis.sh` | `[PID]` | 内存分析：free + Slab + buddyinfo + smaps + OOM 历史 |
| `io-analysis.sh` | `[PID] [秒数]` | IO 分析：df + iostat + diskstats + 进程IO + 调度器 |
| `stability-check.sh` | 无 | 稳定性：内核错误 + panic/oops + MCE + 看门狗 + 温度 + 重启原因 |
| `full-diagnosis.sh` | 无 | 综合诊断：调用全部脚本 + 系统/网络/进程信息，输出 tar.gz |
| `ftrace-capture.sh` | `[输出路径] [秒数]` | ftrace 抓取：配置 Perfetto 兼容选项 + 启用事件 + 定时采集 |
| `rt_trace_converter.py` | `<输入> <输出>` | RT 内核 7位 flags 转换为标准 4位，输出 Perfetto 兼容文件 |