> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 内核探针与跟踪

Linux 内核提供了多种动态插桩机制,使你无需修补或重新编译内核即可插入探针、收集跟踪信息并测量耗时。本页涵盖用于代码路径断点的 kprobes、用于函数级性能分析的 ftrace,以及用于调试驱动寄存器访问故障的 MMIO 跟踪。

## Kprobes

Kprobes 允许你在任意内核指令地址上设置断点,并在执行到达该位置时运行自定义处理程序。该技术是非中断性的——运行中的内核不会停止,其他 CPU 继续执行。

### Kprobes 的工作原理

1. 你在符号或地址上注册一个探针。
2. 内核将目标指令替换为陷阱(trap)。
3. 当陷阱触发时,kprobe 处理程序在与被中断代码相同的上下文中运行。
4. 内核恢复原始指令并继续执行。

Kprobes 特别适用于:

* 跟踪调度器事件(`schedule()`、`try_to_wake_up()`)
* 统计慢速代码路径的执行次数
* 捕获调用参数,而无需添加 `printk` 并重新构建

### Kconfig

```text theme={null}
CONFIG_KPROBES=y
CONFIG_KPROBE_EVENTS=y   # enables kprobe trace events via tracefs
```

在目标设备上验证:

```bash theme={null}
zcat /proc/config.gz | grep CONFIG_KPROBE
```

### 通过 tracefs 使用 kprobe 跟踪事件

使用 kprobes 最简单的方式是通过 tracefs 的 `kprobe_events` 接口:

```bash theme={null}
# Register a kprobe on qcom_geni_serial_probe
echo "p:qcom_probe qcom_geni_serial_probe" > /sys/kernel/tracing/kprobe_events

# Enable the event
echo 1 > /sys/kernel/tracing/events/kprobes/qcom_probe/enable

# Start tracing
echo 1 > /sys/kernel/tracing/tracing_on

# ... trigger the probe by loading the driver or booting ...

# Read results
cat /sys/kernel/tracing/trace

# Clean up
echo 0 > /sys/kernel/tracing/tracing_on
echo "-:qcom_probe" >> /sys/kernel/tracing/kprobe_events
```

有关完整的 kprobes 文档,请参阅
[Kernel Probes (kprobes)](https://docs.kernel.org/trace/kprobes.html)。

## Ftrace

Ftrace 是内核内置的函数跟踪器。它可以记录内核中的每个函数调用、跟踪特定子系统,或分析对延迟敏感的代码路径。结果从 tracefs 接口(`/sys/kernel/tracing/`)读取。

### 函数跟踪器

`function` 跟踪器记录每个被调用的内核函数的名称和 CPU:

```bash theme={null}
echo function > /sys/kernel/tracing/current_tracer
echo 1 > /sys/kernel/tracing/tracing_on
sleep 1
echo 0 > /sys/kernel/tracing/tracing_on
cat /sys/kernel/tracing/trace | head -30
```

### 函数调用图跟踪器

`function_graph` 跟踪器记录每个函数的进入和退出,包括执行时间。可用于识别慢速代码路径:

```bash theme={null}
echo function_graph > /sys/kernel/tracing/current_tracer
echo 1 > /sys/kernel/tracing/tracing_on
# ... trigger the code path ...
echo 0 > /sys/kernel/tracing/tracing_on
cat /sys/kernel/tracing/trace | grep -E "qcom|remoteproc" | head -20
```

示例输出:

```text theme={null}
 2)   0.432 us    |          qcom_geni_serial_isr();
 2)   1.201 us    |        handle_irq_event_percpu();
 2)   3.567 us    |      handle_fasteoi_irq();
```

### 跟踪启动 initcall

添加到内核命令行,以在启动时跟踪所有 initcall:

```text theme={null}
initcall_debug
```

使用以下命令解析结果:

```bash theme={null}
dmesg | grep "initcall.*after" \
      | sed 's/.*initcall \(.*\) returned.* after \([0-9]*\) usecs/\2 \1/' \
      | sort -rn | head -20
```

有关完整的 ftrace 文档,请参阅
[Function Tracer](https://docs.kernel.org/trace/ftrace.html)。

## MMIO 跟踪事件

内存映射 I/O(MMIO)跟踪记录内核通过 `__raw_{read,write}{b,l,w,q}` 访问器执行的每次寄存器读写。它们对于在 Qualcomm<sup>®</sup> SoC 上诊断以下崩溃类别至关重要:

**表:MMIO 崩溃场景**

| **场景**    | **说明**                                      | **典型症状**      |
| :-------- | :------------------------------------------ | :------------ |
| 未使能时钟的访问  | 在该模块的时钟启用之前尝试访问寄存器                          | 立即重启 / SError |
| 受保护的寄存器空间 | 寄存器区域需要 EL3 特权;来自 EL1/EL2 的访问被 TrustZone 拒绝 | 同步异常 / NoC 错误 |
| xPU 违规    | 内存保护单元阻止来自该总线主设备的访问                         | 互连挂起或同步中止     |

### 启用 MMIO 跟踪

Kconfig:

```text theme={null}
CONFIG_TRACE_MMIO_ACCESS=y
```

在运行时,通过 tracefs 启用 `rwmmio` 跟踪事件:

```bash theme={null}
# List available rwmmio events
cat /sys/kernel/tracing/available_events | grep rwmmio

# Enable all rwmmio events
cat /sys/kernel/tracing/available_events | grep rwmmio >> /sys/kernel/tracing/set_event

# Enable tracing
echo 1 > /sys/kernel/tracing/tracing_on

# ... reproduce the crash or trigger the driver ...

# Read the trace
echo 0 > /sys/kernel/tracing/tracing_on
cat /sys/kernel/tracing/trace
```

示例输出:

```text theme={null}
rwmmio_read:  gic_peek_irq+0xd0/0xd8       readl  addr=0xffff800010040104
rwmmio_write: gic_poke_irq+0xe4/0xf0       writel addr=0xffff800010040184
rwmmio_read:  gic_do_wait_for_rwp+0x54/0x90 readl  addr=0xffff800010040000
rwmmio_write: gic_set_affinity+0x1bc/0x1e8  writeq addr=0xffff800010046130
```

每一行标识调用函数(带偏移)、访问类型(`readl`/`writel`/`writeq`)和物理地址。将该地址与 SoC 技术参考手册进行对照,以识别崩溃所涉及的寄存器模块。

### 崩溃时在控制台转储 MMIO 跟踪

要在系统崩溃、来不及读取 tracefs 的情况下也能捕获 MMIO 跟踪,请启用 ftrace 缓冲区的控制台转储:

```bash theme={null}
echo 1 > /proc/sys/kernel/ftrace_dump_on_oops
```

这样,最后的跟踪条目将包含在串行控制台上的内核 panic 输出中。