4. procfs 调试接口

在 Linux 内核调试中，procfs（Process File System）是最早也是最直观的用户态与内核态交互接口之一。它最初用于暴露进程信息，后来被广泛用于驱动开发者导出运行时状态、配置参数和调试计数器。本章将系统讲解 procfs 的核心概念、文件创建、读写实现以及驱动参数导出方法，帮助你快速搭建属于自己的调试“仪表盘”。

4.1 procfs 文件系统简介

procfs 是一个虚拟文件系统，通常挂载在 /proc 目录下。它不占用磁盘空间，文件内容由内核动态生成。驱动开发者可以在 /proc 下创建自己的文件节点，用于输出调试信息或接收控制指令。

4.2 创建 proc 文件

创建 proc 文件的核心 API 是 proc_create()，它需要提供文件名、权限、父目录指针和一个 file_operations 结构体。驱动模块加载时创建，卸载时删除。

4.2.1 核心 API

#include <linux/proc_fs.h>

// 创建 proc 文件
struct proc_dir_entry *proc_create(
    const char *name,          // 文件名，如 "my_driver_debug"
    umode_t mode,              // 权限，如 0666
    struct proc_dir_entry *parent, // 父目录，NULL 表示 /proc
    const struct file_operations *proc_fops // 文件操作函数集
);

// 删除 proc 文件
void remove_proc_entry(const char *name, struct proc_dir_entry *parent);

4.2.2 完整创建示例

static struct proc_dir_entry *my_proc_file;

static int __init my_driver_init(void)
{
    // 在 /proc 下创建 my_driver_debug 文件，权限 0644
    my_proc_file = proc_create("my_driver_debug", 0644, NULL, &my_proc_fops);
    if (!my_proc_file) {
        pr_err("Failed to create /proc/my_driver_debug\n");
        return -ENOMEM;
    }
    pr_info("my_driver: /proc/my_driver_debug created\n");
    return 0;
}

static void __exit my_driver_exit(void)
{
    remove_proc_entry("my_driver_debug", NULL);
    pr_info("my_driver: /proc/my_driver_debug removed\n");
}

4.3 读写 proc 文件

proc 文件的读写通过 file_operations 中的 read 和 write 回调实现。内核提供了辅助函数 proc_simple_read() 和 proc_simple_write()，但更灵活的方式是手动实现回调。

4.3.1 file_operations 结构体

static ssize_t my_proc_read(struct file *filp, char __user *buf,
                            size_t count, loff_t *ppos);
static ssize_t my_proc_write(struct file *filp, const char __user *buf,
                             size_t count, loff_t *ppos);

static const struct file_operations my_proc_fops = {
    .owner = THIS_MODULE,
    .read  = my_proc_read,
    .write = my_proc_write,
};

4.3.2 read 回调实现：导出驱动状态

static int driver_status = 0;  // 模拟驱动内部变量
static int driver_counter = 0;

static ssize_t my_proc_read(struct file *filp, char __user *buf,
                            size_t count, loff_t *ppos)
{
    char kbuf[256];
    int len;

    // 只在文件偏移为 0 时生成内容
    if (*ppos > 0)
        return 0;

    len = snprintf(kbuf, sizeof(kbuf),
                   "Driver Status: %d\n"
                   "Driver Counter: %d\n"
                   "Uptime (jiffies): %lu\n",
                   driver_status, driver_counter, jiffies);

    if (copy_to_user(buf, kbuf, len))
        return -EFAULT;

    *ppos = len;
    return len;
}

4.3.3 write 回调实现：接收控制指令

static ssize_t my_proc_write(struct file *filp, const char __user *buf,
                             size_t count, loff_t *ppos)
{
    char kbuf[32];
    int value;

    if (count > sizeof(kbuf) - 1)
        return -EINVAL;

    if (copy_from_user(kbuf, buf, count))
        return -EFAULT;

    kbuf[count] = '\0';

    // 解析用户输入：期望格式 "status=1" 或 "counter=100"
    if (sscanf(kbuf, "status=%d", &value) == 1) {
        driver_status = value;
        pr_info("my_driver: status set to %d\n", driver_status);
    } else if (sscanf(kbuf, "counter=%d", &value) == 1) {
        driver_counter = value;
        pr_info("my_driver: counter set to %d\n", driver_counter);
    } else {
        pr_warn("my_driver: invalid write format: %s\n", kbuf);
        return -EINVAL;
    }

    return count;
}

4.4 驱动参数导出实战

将驱动内部变量通过 procfs 导出，是调试中最常见的需求。下面给出一个完整的实战示例，包含多类型变量导出和格式化输出。

4.4.1 定义驱动参数结构

struct driver_debug_info {
    int          status;          // 运行状态
    unsigned long counter;        // 计数器
    int          error_count;     // 错误次数
    char         version[32];     // 驱动版本
    spinlock_t   lock;            // 保护上述变量的自旋锁
};

static struct driver_debug_info my_debug = {
    .status      = 0,
    .counter     = 0,
    .error_count = 0,
    .version     = "v1.2.3",
};

4.4.2 带锁保护的 proc 读实现

static ssize_t debug_proc_read(struct file *filp, char __user *buf,
                               size_t count, loff_t *ppos)
{
    char kbuf[512];
    int len;
    unsigned long flags;

    if (*ppos > 0)
        return 0;

    // 加锁保护，防止读取过程中变量被中断或其它 CPU 修改
    spin_lock_irqsave(&my_debug.lock, flags);
    len = snprintf(kbuf, sizeof(kbuf),
                   "Driver Debug Info:\n"
                   "  Status      : %d\n"
                   "  Counter     : %lu\n"
                   "  Error Count : %d\n"
                   "  Version     : %s\n"
                   "  Jiffies     : %lu\n",
                   my_debug.status,
                   my_debug.counter,
                   my_debug.error_count,
                   my_debug.version,
                   jiffies);
    spin_unlock_irqrestore(&my_debug.lock, flags);

    if (copy_to_user(buf, kbuf, len))
        return -EFAULT;

    *ppos = len;
    return len;
}

4.4.3 用户态测试命令

4.5 常见问题与避坑指南

• 文件权限不足： 使用 0666 权限时，确保系统未启用 procfs 的权限限制（某些安全模块会拦截）。
• 缓冲区溢出： read 回调中 snprintf 的缓冲区要足够大，避免截断关键信息。建议至少 512 字节。
• 并发访问： 多个用户同时读写同一个 proc 文件时，必须使用锁保护共享数据，否则会导致数据不一致或崩溃。
• 文件未删除： 模块卸载时忘记调用 remove_proc_entry()，下次加载时会创建失败（返回 NULL）。
• 返回值错误： read 回调返回 0 表示文件结束，返回负值表示错误。write 回调返回写入的字节数，负值表示错误。