4. kprobe 注册与注销 API：register_kprobe()、unregister_kprobe()、register_kretprobe()、unregister_kretprobe()

kprobe 与 kretprobe 的注册与注销是驱动调试的核心操作。内核提供了两组对称的 API，分别用于管理 kprobe（指令级探测点）和 kretprobe（函数入口/返回探测点）。正确理解这些 API 的参数、返回值与生命周期，是编写稳定探测程序的前提。

4.1 API 原型与参数说明

四个核心 API 均定义在 <linux/kprobes.h> 中，其函数原型如下：

#include <linux/kprobes.h>

/* kprobe 注册与注销 */
int register_kprobe(struct kprobe *kp);
void unregister_kprobe(struct kprobe *kp);

/* kretprobe 注册与注销 */
int register_kretprobe(struct kretprobe *rp);
void unregister_kretprobe(struct kretprobe *rp);

4.2 数据结构初始化规范

注册前必须正确初始化探测结构体。以下是两种探测器的标准初始化模板：

/* kprobe 初始化示例 */
static struct kprobe kp = {
    .symbol_name    = "do_sys_openat2",
    .pre_handler    = handler_pre,
    .post_handler   = handler_post,
    .fault_handler  = handler_fault,
};

/* kretprobe 初始化示例 */
static struct kretprobe rp = {
    .kp.symbol_name = "vfs_write",
    .entry_handler  = entry_handler,
    .handler        = return_handler,
    .maxactive      = 20,   /* 最大并发探测实例数 */
    .data_size      = sizeof(struct my_ret_data),
};

4.3 注册与注销的完整生命周期

下图展示了 kprobe 从注册到注销的完整状态流转，以及内核在后台执行的同步操作：

4.4 返回值与错误码速查

注册 API 返回负值 errno 时，常见错误码及原因如下：

4.5 对称注销与同步语义

unregister_kprobe() 和 unregister_kretprobe() 具有以下重要特性：

• 幂等性： 多次调用 unregister_kprobe() 是安全的，第二次调用不会产生副作用。
• 同步等待： 注销函数会调用 synchronize_rcu() 或 synchronize_sched()，确保所有正在执行的 handler 退出后才返回。
• 模块卸载必调： 在模块 exit 函数中必须调用注销 API，否则内核会残留断点，导致系统崩溃。
• 注销顺序： 如果同时注册了 kprobe 和 kretprobe，建议按注册的逆序注销。

/* 模块退出时的标准清理模式 */
static void __exit my_kprobe_exit(void)
{
    unregister_kretprobe(&rp);   /* 先注销 kretprobe */
    unregister_kprobe(&kp);      /* 再注销 kprobe */
    pr_info("kprobe/kretprobe unregistered successfully\n");
}

4.6 kprobe vs kretprobe 注册对比

下表从多个维度对比两种探测器的注册差异，帮助你在实际场景中做出选择：

4.7 完整注册/注销代码模板

以下是一个可直接编译的 kretprobe 注册/注销模板，包含完整的错误处理和资源清理：

#include <linux/kernel.h>
#include <linux/module.h>
#include <linux/kprobes.h>

MODULE_LICENSE("GPL");
MODULE_AUTHOR("Kprobe Expert");

/* 私有数据结构：记录时间戳 */
struct my_data {
    u64 entry_time;
};

/* 入口 handler：记录进入时间 */
static int entry_handler(struct kretprobe_instance *ri, struct pt_regs *regs)
{
    struct my_data *data;
    data = (struct my_data *)ri->data;
    data->entry_time = ktime_get_ns();
    return 0;
}

/* 返回 handler：计算耗时 */
static int return_handler(struct kretprobe_instance *ri, struct pt_regs *regs)
{
    struct my_data *data;
    u64 delta;
    data = (struct my_data *)ri->data;
    delta = ktime_get_ns() - data->entry_time;
    pr_info("vfs_write duration: %llu ns\n", delta);
    return 0;
}

/* 定义 kretprobe 实例 */
static struct kretprobe rp = {
    .kp.symbol_name = "vfs_write",
    .entry_handler  = entry_handler,
    .handler        = return_handler,
    .maxactive      = 50,
    .data_size      = sizeof(struct my_data),
};

static int __init my_probe_init(void)
{
    int ret;

    ret = register_kretprobe(&rp);
    if (ret < 0) {
        pr_err("register_kretprobe failed: %d\n", ret);
        return ret;
    }
    pr_info("kretprobe registered on %s\n", rp.kp.symbol_name);
    return 0;
}

static void __exit my_probe_exit(void)
{
    unregister_kretprobe(&rp);
    pr_info("kretprobe unregistered\n");
}

module_init(my_probe_init);
module_exit(my_probe_exit);