📚 课程目录第3章 GPIO驱动调试实战

第3章 GPIO驱动调试实战：从寄存器到用户态

GPIO 驱动，说简单也简单，说复杂也复杂。简单是因为它本质就是读写几个寄存器；复杂在于，它在车载系统里往往承担着「信号链最后一公里」的角色——一个 GPIO 电平不对，可能导致摄像头无法上电、CAN 收发器静默、甚至整机无法休眠。

我个人习惯把 GPIO 调试分成三个层次：寄存器层 → 内核驱动层 → 用户态验证层。这一章我们就沿着这条线走一遍。

  本章核心脉络： GPIO 控制器寄存器分析 → Linux GPIO 子系统驱动开发 → sysfs / libgpiod 调试方法

3.1 GPIO 控制器寄存器分析

拿到一份新的 SoC 数据手册，我第一件事就是翻 GPIO 章节。为什么？因为 GPIO 寄存器往往是最直观的「硬件接口说明书」。你想想看，一个 GPIO 控制器通常就这几类寄存器：

寄存器类型	典型名称	位宽	作用
数据寄存器	GPIO_DAT / GPIO_DATA	32 bit	读：当前引脚电平；写：输出值
方向寄存器	GPIO_DIR / GPIO_OE	32 bit	0=输入，1=输出
功能选择寄存器	GPIO_FUN / GPIO_AF	2 bit per pin	00=GPIO，01/10/11=复用功能
上拉/下拉寄存器	GPIO_PULL / GPIO_PAD	2 bit per pin	00=无，01=上拉，10=下拉
中断相关寄存器	GPIO_IS / GPIO_IEV	32 bit	触发类型、使能

我在项目中遇到过最典型的坑：功能选择寄存器没切回 GPIO 模式。某次调试车载摄像头供电使能引脚，写 DAT 寄存器死活拉不高电平，用示波器一看引脚一直低。查了半小时才发现 FUN 寄存器默认值是 0x01（UART 复用），根本没切到 GPIO 模式。

调试技巧： 拿到开发板后，先用 devmem2 或 /dev/mem 直接读 GPIO 控制器的基地址偏移，确认复位默认值。比如：
devmem2 0x01C20800 32 # 读 GPIO 数据寄存器

3.2 基于 Linux GPIO 子系统的驱动开发

Linux GPIO 子系统说白了就是一套标准框架。你不需要自己实现所有功能，只需要填充几个关键结构体。核心就两个：pinctrl 和 gpio_chip。

3.2.1 pinctrl 注册

pinctrl 负责引脚复用和电气属性配置。我习惯先确认 SoC 的 pinctrl 驱动是否已经支持你的芯片。如果不支持，你需要实现 pinconf_ops 和 pinctrl_ops。

static const struct pinctrl_pin_desc my_pins[] = {
    PINCTRL_PIN(0, "GPIO0"),
    PINCTRL_PIN(1, "GPIO1"),
    // ... 每个引脚一个描述
};

static struct pinctrl_desc my_pinctrl_desc = {
    .name = "my-soc-pinctrl",
    .pins = my_pins,
    .npins = ARRAY_SIZE(my_pins),
    .pctlops = &my_pctl_ops,
    .pmxops = &my_pmx_ops,
    .confops = &my_conf_ops,
};

3.2.2 gpio_chip 注册

gpio_chip 是 GPIO 子系统的核心接口。你需要实现 direction_input、direction_output、get、set 这四个回调。嗯，这里要注意：set 回调里一定要操作 DAT 寄存器，而不是缓存。

static int my_gpio_direction_output(struct gpio_chip *chip,
                                    unsigned offset, int value)
{
    struct my_gpio_bank *bank = gpiochip_get_data(chip);
    unsigned long flags;
    u32 reg;

    spin_lock_irqsave(&bank->lock, flags);

    // 1. 设置方向寄存器为输出
    reg = readl(bank->base + GPIO_DIR);
    reg |= BIT(offset);
    writel(reg, bank->base + GPIO_DIR);

    // 2. 设置输出值
    reg = readl(bank->base + GPIO_DAT);
    if (value)
        reg |= BIT(offset);
    else
        reg &= ~BIT(offset);
    writel(reg, bank->base + GPIO_DAT);

    spin_unlock_irqrestore(&bank->lock, flags);
    return 0;
}

我曾经踩过的坑： 某次在 direction_output 里先写 DAT 再设 DIR，结果导致输出瞬间出现毛刺。正确的顺序应该是：先设 DIR 为输出，再写 DAT 值。否则在 DIR 还是输入时写 DAT 是无效的。

3.2.3 设备树绑定

设备树里需要描述 GPIO 控制器的寄存器基地址、中断号、引脚数量等信息。我一般这样写：

gpio0: gpio@01c20800 {
    compatible = "my-soc,gpio";
    reg = <0x01c20800 0x400>;
    interrupts = <GIC_SPI 42 IRQ_TYPE_LEVEL_HIGH>;
    gpio-controller;
    #gpio-cells = <2>;
    ngpios = <32>;
};

3.3 使用 sysfs 和 libgpiod 调试 GPIO

驱动写好了，怎么验证？我个人强烈建议先用用户态工具测一轮，再上应用层代码。这样能快速隔离问题——到底是驱动没注册成功，还是上层逻辑写错了。

3.3.1 sysfs 方式（传统但有效）

sysfs 接口在 /sys/class/gpio 下。操作步骤很简单：

导出 GPIO：echo 42 > /sys/class/gpio/export
设置方向：echo out > /sys/class/gpio/gpio42/direction
写值：echo 1 > /sys/class/gpio/gpio42/value
读值：cat /sys/class/gpio/gpio42/value
释放：echo 42 > /sys/class/gpio/unexport

但 sysfs 有个问题：它不支持中断检测。你想监测一个 GPIO 的电平变化？sysfs 只能轮询，效率很低。

快速检查驱动是否注册成功：
ls /sys/class/gpio/ 看看有没有 gpiochip 目录。
cat /sys/kernel/debug/gpio 可以列出所有已注册的 GPIO 控制器和引脚状态。

3.3.2 libgpiod 方式（推荐）

libgpiod 是内核社区推荐的新一代 GPIO 用户态接口。它通过字符设备（/dev/gpiochipN）操作，支持中断、批量操作、事件监听。我最近的项目基本都切到 libgpiod 了。

常用命令行工具：

命令	作用	示例
gpiodetect	列出所有 GPIO 控制器	gpiodetect
gpioinfo	查看某个控制器的引脚信息	gpioinfo gpiochip0
gpioget	读取引脚电平	gpioget gpiochip0 5
gpioset	设置引脚电平	gpioset gpiochip0 5=1
gpiomon	监听引脚中断事件	gpiomon gpiochip0 5

举个例子，你要调试一个按键中断：

# 先确认 gpiochip 编号
gpiodetect

# 查看引脚 5 的当前状态
gpioget gpiochip0 5

# 监听引脚 5 的上升沿和下降沿
gpiomon --rising-edge --falling-edge gpiochip0 5

输出会实时显示事件时间戳和电平变化：

event: RISING EDGE offset: 5 timestamp: [1234.567890123]
event: FALLING EDGE offset: 5 timestamp: [1234.678901234]

注意： libgpiod 的引脚编号是控制器内偏移，不是系统全局编号。比如 gpiochip0 的 pin 5，对应设备树里该控制器下的第 5 个引脚。别和 sysfs 的全局编号搞混了。

3.4 实战调试流程总结

最后，我总结一套我自己常用的 GPIO 调试 checklist：

硬件确认：用万用表/示波器测引脚电平，排除硬件虚焊或短路
寄存器确认：devmem2 读 FUN/DIR/DAT 寄存器，确认配置是否正确
驱动确认：cat /sys/kernel/debug/gpio 看 gpio_chip 是否注册
用户态验证：先用 gpioset/gpioget 做基本读写测试
中断验证：用 gpiomon 监听中断事件，确认触发是否正常
应用层对接：确认设备树里 gpio 属性与驱动匹配

这套流程走下来，90% 的 GPIO 问题都能定位。剩下的 10%，嗯，往往是硬件设计问题——比如引脚被其他外设占用了，或者 PCB 走线有串扰。那就不只是驱动工程师的事了。