Linux GPIO 子系统深度实战：从内核驱动到 libgpiod 生产级应用

概述

通用输入输出（GPIO）是嵌入式系统中最基础也是最常用的硬件接口。无论是点亮 LED、读取按键状态，还是实现复杂的时序协议（如 I2C bit-bang、SPI over GPIO），GPIO 都是硬件工程师和驱动开发者绕不开的核心接口。

本文将全面解析 Linux 内核 GPIO 子系统：从 GPIO 硬件基础、旧版 sysfs 接口、新版 GPIO Character Device（gpiochip）内核架构，到用户空间 libgpiod 库 的生产级编程实战。涵盖设备树绑定、GPIO 控制器驱动框架（gpiolib）、中断处理和 sysfs 到新接口迁移的完整工程指南。

1. GPIO 硬件基础

GPIO 引脚是微控制器或 SoC 上可以编程控制方向的数字信号引脚。每个 GPIO 通常支持以下操作模式：

• 输出模式：驱动高电平（通常为 VDD，如 3.3V 或 1.8V）或低电平（GND）
• 输入模式：读取外部电路的电平状态（高/低），通常带可选上拉/下拉电阻
• 高阻态（Hi-Z）：既不驱动也不拉取，常用于开漏（Open-Drain）总线
• 复用模式（Alternate Function）：引脚连接到内部外设（如 UART、I2C、SPI、PWM）

现代 SoC 通常集成多个 GPIO 控制器（gpiochip），每个控制器管理一组引脚（常见 32 或 64 个为一组），通过 APB/AHB 总线与 CPU 通信。关键的硬件寄存器包括：

• 数据方向寄存器（DDR / GPIO_DIR）：控制每位是输入（0）还是输出（1）
• 数据输出寄存器（GPIO_DATAOUT / DOUT）：写 1/0 驱动对应电平
• 数据输入寄存器（GPIO_DATAIN / DIN）：读取引脚实时电平
• 中断配置寄存器（IRQ_TYPE / IRQ_EN）：使能中断、配置触发条件
• 上拉/下拉寄存器（PULL_UP / PULL_DOWN）：配置内部电阻
• 复用选择寄存器（MUX / PAD_CFG）：选择引脚功能

2. 旧版 GPIO Sysfs 接口（已废弃）

在 Linux 4.8 之前，用户空间通过 /sys/class/gpio/ 目录下的虚拟文件操作 GPIO。虽然该接口已在 Linux 4.8 标记为 deprecated 并在后续内核中逐步移除，但仍有大量遗留系统和嵌入式脚本在使用。理解它有助于维护旧设备。

基本操作：

# 导出 GPIO（假设控制器 gpiochip0，引脚偏移 17）
echo 17 > /sys/class/gpio/export

# 设置为输出模式
echo out > /sys/class/gpio/gpio17/direction

# 输出高电平
echo 1 > /sys/class/gpio/gpio17/value

# 设置为输入模式
echo in > /sys/class/gpio/gpio17/direction

# 读取输入值
cat /sys/class/gpio/gpio17/value

# 配置上升沿触发中断
echo rising > /sys/class/gpio/gpio17/edge

# 取消导出
echo 17 > /sys/class/gpio/unexport

sysfs 接口的严重缺陷：

• 操作不可原子：设置方向和输出值需要两次独立文件操作，中间可能被其他进程修改
• 全局编号不稳定：GPIO 编号 base + offset 取决于加载顺序，重启后可能变化
• 无批量操作：无法原子性读取或写入多位总线信号
• 无法授权/租约：无法独占访问某个 GPIO 防止误操作
• 无去抖动/定时器：需要用户空间自行实现
• 无引脚标签：通过数字编号操作，难以与硬件原理图对应

3. GPIO Character Device 新架构（Linux 4.8+）

Linux 4.8 引入了 GPIO Character Device 用户空间接口，将 GPIO 操作映射到 /dev/gpiochipN（N = 0, 1, 2…）字符设备上。用户空间通过文件描述符调用 ioctl()，获取结构化的 gpiohandle_request 或 gpioevent_request 句柄，进而读写 GPIO 状态。这一设计的关键改进是：原子操作、命名引脚、独占租约、批量读写。

3.1 核心数据结构

// include/uapi/linux/gpio.h

// 控制器信息
struct gpiochip_info {
    char name[32];       // 控制器名（如 "gpiochip0"）
    char label[32];      // 驱动标签（如 "zynq-gpio"）
    __u32 lines;         // 引脚数量（如 118）
};

// 单引脚信息
struct gpioline_info {
    __u32 line_offset;   // 偏移量（0-based）
    __u32 flags;         // GPIOLINE_FLAG_KERNEL / OUT / ACTIVE_LOW / OPEN_DRAIN / OPEN_SOURCE
    char name[32];       // DT 分配的引脚名（如 "SDMMC_WP"）
    char consumer[32];   // 当前消费者标签
};

// 批量请求结构（一次获取多条引脚）
struct gpiohandle_request {
    __u32 lineoffsets[GPIOHANDLES_MAX];  // 偏移量数组
    __u32 flags;              // GPIOHANDLE_REQUEST_INPUT / OUTPUT / ACTIVE_LOW / OPEN_DRAIN / OPEN_SOURCE
    __u8 default_values[GPIOHANDLES_MAX]; // 输出引脚的默认值
    char consumer_label[32];   // 租约标签（显示在 gpiodetect 中）
    __u32 lines;               // 实际引脚数
    int fd;                    // 返回的文件描述符
};

// 批量读（原子性一次读所有引脚）
struct gpiohandle_data {
    __u8 values[GPIOHANDLES_MAX];
};

// 引脚中断事件
struct gpioevent_request {
    __u32 lineoffset;
    __u32 handleflags;         // GPIOHANDLE_REQUEST_INPUT
    __u32 eventflags;          // GPIOEVENT_REQUEST_RISING_EDGE / FALLING_EDGE / BOTH_EDGES
    char consumer_label[32];
    int fd;
};

struct gpioevent_data {
    __u64 timestamp;           // 纳秒级时间戳（CLOCK_MONOTONIC）
    __u32 id;                  // GPIOEVENT_EVENT_RISING_EDGE / FALLING_EDGE
};

3.2 关键 ioctl 命令

// 获取控制器信息
ioctl(fd, GPIO_GET_CHIPINFO_IOCTL, &chipinfo);

// 查询某引脚信息
ioctl(fd, GPIO_GET_LINEINFO_IOCTL, &lineinfo);

// 获取引脚操作句柄（输出模式）
ioctl(fd, GPIO_GET_LINEHANDLE_IOCTL, &req);

// 获取中断事件句柄
ioctl(fd, GPIO_GET_LINEEVENT_IOCTL, &req);

// 批量读取引脚值（原子操作）
ioctl(handle_fd, GPIOHANDLE_GET_LINE_VALUES_IOCTL, &data);

// 批量写入引脚值（原子操作）
ioctl(handle_fd, GPIOHANDLE_SET_LINE_VALUES_IOCTL, &data);

3.3 与 sysfs 的核心差异对比

4. libgpiod 库生产实战

libgpiod 是基于 GPIO Character Device 的 C 库封装，由 Linux 内核 GPIO 子系统维护者提供。它提供了简洁的 API 完成所有 GPIO 操作，是替代 sysfs 的首选方案。几乎所有现代嵌入式 Linux 发行版（Buildroot、Yocto、Debian for ARM）均已预装。

4.1 编译与安装

# Ubuntu / Debian
sudo apt install libgpiod-dev gpiod

# Buildroot
make menuconfig -> Target packages -> Hardware handling -> libgpiod

# Yocto (meta-openembedded)
IMAGE_INSTALL += "libgpiod libgpiod-tools"

# 验证安装
gpiodetect
gpioinfo gpiochip0
gpiofind "LED_RED"
gpioget gpiochip0 17
gpioset gpiochip0 17=1
gpiomon gpiochip0 17 --falling-edge

4.2 libgpiod API 核心接口

// 头文件
#include 

// 1. 打开 GPIO 控制器
struct gpiod_chip *chip = gpiod_chip_open("/dev/gpiochip0");
if (!chip) { /* 错误处理 */ }

// 2. 获取引脚行对象
struct gpiod_line *line = gpiod_chip_get_line(chip, 17);

// 3. 申请输出（带默认值）
gpiod_line_request_output(line, "my-app", 0);

// 4. 申请输入
gpiod_line_request_input(line, "my-app");

// 5. 设置值
gpiod_line_set_value(line, 1);

// 6. 读取值
int val = gpiod_line_get_value(line);

// 7. 申请中断（上升沿触发）
gpiod_line_request_rising_edge_events(line, "my-app");

// 8. 等待事件（带超时）
struct timespec ts = { 1, 0 }; // 1秒超时
struct gpiod_line_event event;
int ret = gpiod_line_event_wait(line, &ts);
if (ret > 0) {
    gpiod_line_event_read(line, &event);
    printf("Event: %d, timestamp: %llu\n",
           event.event_type, (unsigned long long)event.ts.tv_sec);
}

// 9. 释放资源
gpiod_line_release(line);
gpiod_chip_close(chip);

// === 批量操作（推荐总线场景）===
struct gpiod_line_bulk bulk;
struct gpiod_line *lines[3];
gpiod_chip_get_lines(chip, (unsigned int[]){17, 18, 27}, 3, &bulk);
gpiod_line_request_bulk_output(&bulk, "spi-bitbang", (int[]){0, 0, 1});
int values[3] = {1, 0, 0};
gpiod_line_set_values(&bulk, values);  // 原子性同时设置

4.3 生产级 LED 驱动示例

// led_driver.c - 通过 GPIO 控制板载 LED
#include 
#include 
#include 
#include 

#define LED_GPIO_CHIP  "/dev/gpiochip0"
#define LED_LINE       17  // 根据具体硬件调整

struct gpiod_chip *chip;
struct gpiod_line *led;

int led_init(void) {
    chip = gpiod_chip_open(LED_GPIO_CHIP);
    if (!chip) { perror("gpiod_chip_open"); return -1; }

    led = gpiod_chip_get_line(chip, LED_LINE);
    if (!led) { perror("gpiod_chip_get_line"); return -1; }

    // 申请输出模式，默认低电平（LED 灭）
    if (gpiod_line_request_output(led, "heartbeat-led", 0) < 0 xss=removed>

// button.c - 带硬件去抖的按键检测（libgpiod 1.5+ 支持 debounce）
#include 
#include 
#include 
#include 

#define BTN_LINE  27
#define DEBOUNCE_US 50000  // 50ms 去抖动窗口

static volatile int running = 1;

void sigint_handler(int sig) { running = 0; }

int main(int argc, char *argv[]) {
    struct gpiod_chip *chip = gpiod_chip_open("/dev/gpiochip0");
    struct gpiod_line *btn = gpiod_chip_get_line(chip, BTN_LINE);

    // 申请输入模式，带硬件去抖动
    struct gpiod_line_config *line_cfg = gpiod_line_config_new();
    gpiod_line_config_set_direction(line_cfg, GPIOD_LINE_DIRECTION_INPUT);
    gpiod_line_config_set_debounce_period_us(line_cfg, DEBOUNCE_US);
    gpiod_line_config_add_line_settings(line_cfg, &BTN_LINE, 1, NULL);

    struct gpiod_request_config *req_cfg = gpiod_request_config_new();
    gpiod_request_config_set_consumer(req_cfg, "button-mon");
    struct gpiod_line_request *request =
        gpiod_chip_request_lines(chip, req_cfg, line_cfg);

    signal(SIGINT, sigint_handler);
    printf("Press button to log events. Ctrl+C to exit.\n");
    fflush(stdout);

    while (running) {
        struct timespec ts = { 1, 0 };
        int ret = gpiod_line_request_wait_edge_events(request, &ts);
        if (ret > 0) {
            struct gpiod_edge_event *event =
                gpiod_line_request_read_edge_event(request);
            if (event) {
                struct timespec now;
                clock_gettime(CLOCK_MONOTONIC, &now);
                printf("Button: %s @ %lu ms\n",
                       gpiod_edge_event_get_event_type(event) ==
                           GPIOD_EDGE_EVENT_RISING_EDGE ? "RELEASED" : "PRESSED",
                       now.tv_sec * 1000 + now.tv_nsec / 1000000);
                gpiod_edge_event_free(event);
                fflush(stdout);
            }
        }
    }

    gpiod_line_request_release(request);
    gpiod_chip_close(chip);
    return 0;
}

#!/usr/bin/env python3
# button_led.py - 短按按钮翻转 LED 状态

import gpiod
from gpiod.line import Direction, Value, Edge, Bias
import select
import time

LED_CHIP = "/dev/gpiochip0"
LED_OFFSET  = 17
BTN_OFFSET  = 27

def main():
    # 配置 LED 输出（默认低电平）
    led_settings = gpiod.LineSettings(direction=Direction.OUTPUT, output_value=Value.INACTIVE)
    btn_settings = gpiod.LineSettings(
        direction=Direction.INPUT,
        edge_detection=Edge.BOTH,
        bias=Bias.PULL_UP,
        debounce_period=timedelta(milliseconds=50)
    )

    request = gpiod.request_lines(
        LED_CHIP,
        consumer="py-button-led",
        config={
            LED_OFFSET: led_settings,
            BTN_OFFSET: btn_settings,
        }
    )

    led_state = False
    print("Running... Press button to toggle LED. Ctrl+C to exit.")

    while True:
        # 等待边沿事件（超时 1 秒）
        if request.wait_edge_events(timedelta(seconds=1)):
            events = request.read_edge_events()
            for event in events:
                if event.line_offset == BTN_OFFSET:
                    if event.event_type == event.Type.RISING_EDGE:  # 释放
                        led_state = not led_state
                        request.set_value(LED_OFFSET,
                                          Value.ACTIVE if led_state else Value.INACTIVE)
                        print(f"LED {'ON' if led_state else 'OFF'}")

if __name__ == "__main__":
    main()

// 在消费者节点中引用 GPIO
&gpio0 {
    led-gpios = <&gpio0 17 GPIO_ACTIVE_HIGH>;
    button-gpios = <&gpio0 27 GPIO_ACTIVE_LOW>;
};

// 在驱动代码中获取
struct gpio_desc *led = gpiod_get(dev, "led", GPIOD_OUT_LOW);
gpiod_set_value(led, 1);  // 点亮
gpiod_put(led);

// arch/arm64/boot/dts/vendor/myboard-gpio.dtsi
gpio0: gpio@e000a000 {
    compatible = "vendor,my-gpio-1000";
    reg = <0x0>;
    interrupts = ;
    gpio-controller;
    #gpio-cells = ;        // [pin_offset, flags]
    interrupt-controller;
    #interrupt-cells = ;   // [trigger_type, trigger_polarity]
    ngpios = ;           // 实际管理的引脚数
    status = "okay";
};

// include/gpio/driver.h
struct gpio_chip {
    struct device *parent;
    struct module *owner;
    int (*request)(struct gpio_chip *chip, unsigned offset);
    void (*free)(struct gpio_chip *chip, unsigned offset);
    int (*get_direction)(struct gpio_chip *chip, unsigned offset);
    int (*direction_input)(struct gpio_chip *chip, unsigned offset);
    int (*direction_output)(struct gpio_chip *chip, unsigned offset, int value);
    int (*get)(struct gpio_chip *chip, unsigned offset);
    void (*set)(struct gpio_chip *chip, unsigned offset, int value);
    int (*get_multiple)(struct gpio_chip *chip, unsigned long *bits, unsigned long *values);
    void (*set_multiple)(struct gpio_chip *chip, unsigned long *bits, unsigned long *values);
    int (*set_config)(struct gpio_chip *chip, unsigned offset, unsigned long config);
    int (*to_irq)(struct gpio_chip *chip, unsigned offset);
    unsigned int base;
    u16 ngpio;
    const char *label;
    bool can_sleep;
};

// 初始化流程
int my_gpio_probe(struct platform_device *pdev) {
    struct gpio_chip *gc = devm_kzalloc(&pdev->dev, sizeof(*gc), GFP_KERNEL);
    gc->label = "my-gpio-controller";
    gc->parent = &pdev->dev;
    gc->owner = THIS_MODULE;
    gc->base = -1;           // 动态分配 base
    gc->ngpio = 32;          // 32 个引脚
    gc->direction_input  = my_gpio_dir_in;
    gc->direction_output = my_gpio_dir_out;
    gc->get = my_gpio_get;
    gc->set = my_gpio_set;
    gc->get_multiple = my_gpio_get_multiple;
    gc->set_multiple = my_gpio_set_multiple;
    gc->to_irq = my_gpio_to_irq;

    return devm_gpiochip_add_data(&pdev->dev, gc, NULL);
}

CONFIG_GPIO_SYSFS        # 旧 sysfs 接口（已废弃，默认关闭）
CONFIG_GPIO_GENERIC      # 通用内存映射 / PCI GPIO 控制器
CONFIG_GPIO_DEVRES       # devm_gpiod_get() 简化驱动写法
CONFIG_GPIOLIB           # 核心 gpiolib 框架
CONFIG_GPIOLIB_FASTPI    # 快速路径优化
CONFIG_GPIO_DWAPB        # Synopsys DesignWare APB GPIO
CONFIG_GPIO_PL061        # ARM PL061 PrimeCell GPIO
CONFIG_GPIO_PXA          # Marvell PXA GPIO
CONFIG_GPIO_XGENE        # AppliedMicro X-Gene GPIO
CONFIG_GPIO_ZYNQ         # Xilinx Zynq GPIO
CONFIG_GPIO_RCAR         # Renesas R-Car GPIO
CONFIG_GPIO_TEGRA        # NVIDIA Tegra GPIO

// 内核驱动中获取 GPIO 映射的 IRQ
int irq = gpiod_to_irq(gpio_desc);
if (irq < 0 xss=removed>dev, irq, NULL,
                            my_gpio_irq_thread,
                            IRQF_ONESHOT | IRQF_TRIGGER_FALLING,
                            "my-button", priv);

// 中断处理线程
static irqreturn_t my_gpio_irq_thread(int irq, void *data) {
    // 读取当前状态、消抖处理、唤醒工作队列等
    return IRQ_HANDLED;
}

# 查看 DT 中的 GPIO 分配
ls /sys/firmware/devicetree/base/ocp/ | grep gpio

# 查看某控制器已申请引脚
for i in /sys/class/gpio/gpiochip*; do
    echo "$i: $(cat $i/label) $(cat $i/base) $(cat $i/ngpio)"
done

# 调试 GPIO 中断触发
cat /proc/interrupts | grep gpio
cat /sys/kernel/debug/gpio          # 需要 CONFIG_DEBUG_FS

# libgpiod 检测 GPIO 占用（标签显示消费者）
gpioinfo gpiochip0

# 查看谁占用了 GPIO（段显示 consumer 字段）
gpioinfo gpiochip0 | head -5
# line   17: "LED_RED" "my-app" output [active-high]
# line   18: "LED_BLUE" unused input [active-high]
# line   27: "BTN_USER" "button-mon" input [active-high pull-up]