3. GPIO 操作基础：GPIO 申请与释放、方向设置、电平读写、sysfs 接口与 libgpiod

本章是 Linux GPIO 驱动开发的基石。在嵌入式 Linux 系统中，GPIO 是最常用的外设接口之一，用于控制 LED、读取按键、驱动继电器等。掌握 GPIO 的申请与释放、方向设置、电平读写等核心操作，以及用户空间的 sysfs 和 libgpiod 接口，是编写可靠驱动程序的必备技能。

3.1 GPIO 操作核心概念

GPIO 操作在 Linux 内核中遵循“申请 → 配置 → 使用 → 释放”的生命周期模型。内核提供了标准的 GPIO 子系统框架，屏蔽了底层硬件差异，为驱动开发者提供统一的 API。

3.1.1 GPIO 操作生命周期

3.2 内核空间 GPIO 操作 API

Linux 内核从 2.6.21 开始引入通用 GPIO 子系统，提供了一套标准化的 API。以下是最常用的内核 GPIO 操作函数。

3.2.1 GPIO 申请与释放

3.2.2 方向设置

3.2.3 电平读写

3.2.4 完整示例代码

#include <linux/gpio.h>
#include <linux/delay.h>

#define LED_GPIO  17
#define KEY_GPIO  18

static int __init gpio_demo_init(void)
{
    int ret;

    /* 申请 LED GPIO，设置为输出，初始低电平 */
    ret = gpio_request_one(LED_GPIO, GPIOF_OUT_INIT_LOW, "led");
    if (ret < 0) {
        pr_err("Failed to request LED GPIO %d\n", LED_GPIO);
        return ret;
    }

    /* 申请按键 GPIO，设置为输入 */
    ret = gpio_request_one(KEY_GPIO, GPIOF_IN, "key");
    if (ret < 0) {
        pr_err("Failed to request KEY GPIO %d\n", KEY_GPIO);
        gpio_free(LED_GPIO);
        return ret;
    }

    /* 读取按键状态并控制 LED */
    if (gpio_get_value(KEY_GPIO)) {
        gpio_set_value(LED_GPIO, 1);
    } else {
        gpio_set_value(LED_GPIO, 0);
    }

    return 0;
}

static void __exit gpio_demo_exit(void)
{
    gpio_set_value(LED_GPIO, 0);
    gpio_free(LED_GPIO);
    gpio_free(KEY_GPIO);
}

module_init(gpio_demo_init);
module_exit(gpio_demo_exit);

3.3 用户空间 GPIO 操作接口

Linux 提供了两种用户空间 GPIO 操作方式：传统的 sysfs 接口和现代的 libgpiod 库。sysfs 接口在较新内核中已被标记为弃用，libgpiod 是推荐方案。

3.3.1 sysfs 接口（传统方式）

sysfs 接口通过 /sys/class/gpio 目录暴露 GPIO 操作。基本流程如下：

1. 导出 GPIO：向 /sys/class/gpio/export 写入 GPIO 编号
2. 设置方向：向 /sys/class/gpio/gpioN/direction 写入 "in" 或 "out"
3. 读写电平：读取或写入 /sys/class/gpio/gpioN/value
4. 取消导出：向 /sys/class/gpio/unexport 写入 GPIO 编号

# 导出 GPIO 17
echo 17 > /sys/class/gpio/export

# 设置为输出方向
echo out > /sys/class/gpio/gpio17/direction

# 设置高电平
echo 1 > /sys/class/gpio/gpio17/value

# 读取电平
cat /sys/class/gpio/gpio17/value

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

3.3.2 libgpiod 库（现代方式）

libgpiod 是 GPIO 字符设备接口的用户空间库，提供更安全、更高效的 GPIO 操作方式。它通过 /dev/gpiochipN 字符设备与内核交互。

3.3.3 libgpiod C 语言编程示例

#include <gpiod.h>
#include <stdio.h>
#include <unistd.h>

#define CONSUMER  "gpio-demo"
#define GPIO_CHIP "/dev/gpiochip0"

int main(void)
{
    struct gpiod_chip *chip;
    struct gpiod_line *led_line, *key_line;
    int ret, val;

    /* 打开 GPIO 芯片 */
    chip = gpiod_chip_open_by_name(GPIO_CHIP);
    if (!chip) {
        perror("Open gpiochip failed");
        return -1;
    }

    /* 获取 LED 线（GPIO 17）并设置为输出 */
    led_line = gpiod_chip_get_line(chip, 17);
    if (!led_line) {
        perror("Get LED line failed");
        gpiod_chip_close(chip);
        return -1;
    }

    ret = gpiod_line_request_output(led_line, CONSUMER, 0);
    if (ret < 0) {
        perror("Request LED output failed");
        gpiod_chip_close(chip);
        return -1;
    }

    /* 获取按键线（GPIO 18）并设置为输入 */
    key_line = gpiod_chip_get_line(chip, 18);
    if (!key_line) {
        perror("Get KEY line failed");
        gpiod_chip_close(chip);
        return -1;
    }

    ret = gpiod_line_request_input(key_line, CONSUMER);
    if (ret < 0) {
        perror("Request KEY input failed");
        gpiod_chip_close(chip);
        return -1;
    }

    /* 读取按键并控制 LED */
    val = gpiod_line_get_value(key_line);
    gpiod_line_set_value(led_line, val ? 1 : 0);

    printf("Key value: %d, LED set to %d\n", val, val ? 1 : 0);

    /* 清理 */
    gpiod_line_release(led_line);
    gpiod_line_release(key_line);
    gpiod_chip_close(chip);

    return 0;
}

3.4 sysfs 与 libgpiod 对比

3.5 GPIO 操作架构图

3.6 常见问题与避坑指南

• GPIO 编号冲突：多个驱动同时申请同一个 GPIO 会导致 gpio_request 返回 -EBUSY。使用 gpio_is_valid 检查编号有效性。
• 中断上下文操作：在中断处理函数中调用 gpio_set_value 可能触发睡眠，应使用 gpio_set_value_cansleep 的原子版本。
• 电平反转：部分硬件存在电平反转（如高电平灭灯），可通过设备树 gpio-active-low 属性或软件取反处理。
• sysfs 权限：sysfs 接口默认只有 root 可操作，嵌入式系统可通过 udev 规则或修改权限解决。
• libgpiod 版本兼容：不同发行版 libgpiod API 略有差异，编译时注意头文件路径和链接库 -lgpiod。

3.7 本章小结