【产出】 > 在嵌入式 Linux 上不写驱动、直接从用户态控制 GPIO:知道为什么不再用
/sys/class/gpio,会用 gpiodetect / gpioinfo / gpioget / gpioset 查看和操作引脚,并能用 libgpiod 的 C 接口写一个点灯程序;同时分清 libgpiod v1 和 v2 的命令与 API 差异。
【版本】 > 正文以 libgpiod v2.x(2.0 及以后)为准,v1.6.x 的写法单独列出。内核接口按 docs.kernel.org 的 GPIO 用户态 API 文档编写;工具参数取自 libgpiod 官方仓库中各工具的
--help文本。
一、sysfs 接口已经弃用
很多老教程这样点灯:
echo 19 > /sys/class/gpio/export
echo out > /sys/class/gpio/gpio19/direction
echo 1 > /sys/class/gpio/gpio19/value
内核文档对这套 sysfs 接口的定性很明确:它已被 GPIO 字符设备用户态 API 取代,新开发应使用字符设备接口,sysfs 接口将来会被移除,并且新功能只会加到新接口里。
sysfs 接口的主要问题:
| 问题 | 说明 |
|---|---|
| 用全局编号 | 19 是内核内部的全局编号,换内核版本或加载顺序不同就可能变 |
| 进程退出不释放 | 导出后一直占着,程序崩溃也不会自动回收 |
| 功能少 | 不能设置上拉 / 下拉、开漏,也不能一次原子地设置多个引脚 |
二、字符设备接口是怎么组织的
内核把每个 GPIO 控制器暴露成一个设备文件 /dev/gpiochipN。控制器上的每根线用**偏移量(offset)**标识,范围是 0 到"线数 − 1"。
使用流程:
- 打开
/dev/gpiochipN。 - 向它**申请(request)**一根或多根线,同时给出方向、偏置、驱动方式和使用者名称(consumer)。
- 内核返回一个新的文件描述符,之后读写电平、接收边沿事件都通过它进行。
- 关闭描述符或进程退出,线就被释放。
当前内核接口是 v2 版,从 Linux 5.10 开始提供。直接调用 ioctl 很繁琐,实际开发都用 libgpiod 这个官方配套库,它同时提供命令行工具。
【注意】 > 内核文档特别提醒:已经有内核驱动的硬件,不要用用户态 GPIO 去模拟。I2C、SPI、PWM、1-Wire 等应使用对应的子系统接口。用户态 GPIO 适合按键、指示灯、继电器、片选这类简单控制。
三、先确认 libgpiod 版本
两个大版本的命令行参数不兼容,先查清楚手上是哪个:
sudo apt install gpiod libgpiod-dev # Debian / Ubuntu 上的包名
gpioget --version
官方 NEWS 说明,v2.0 是一次与 v1.6.x 系列不兼容的大改:C 库和 C++ / Python 绑定全部重写,命令行工具改为以线名为中心,删除了 gpiofind(工具已能自己解析线名),给 gpioset 增加了交互模式。
四、命令行工具(v2)
1. gpiodetect:列出控制器
gpiodetect
每行显示一个控制器:设备名(如 gpiochip0)、标签(驱动名)和线数。
2. gpioinfo:查看每根线
gpioinfo # 所有控制器的所有线
gpioinfo -c gpiochip0 # 只看一个控制器
gpioinfo GPIO17 # 按线名查
输出包含偏移量、线名、方向(input / output)、是否 active-low,以及被谁占用(consumer)。线名由设备树的 gpio-line-names 属性提供,很多板子(如树莓派)会给出 GPIO17 这样的名字。
-c 指定控制器时,可以写编号、名称或路径:0、gpiochip0、/dev/gpiochip0 三者等价。
3. gpioget:读电平
gpioget GPIO17 # 按线名
gpioget -c gpiochip0 17 # 指定控制器后可以用偏移量
gpioget -c 0 --numeric 17 # 输出 0 或 1
gpioget -c 0 -b pull-up 17 # 读之前打开上拉
| 选项 | 作用 |
|---|---|
-c, --chip | 限定控制器,之后才能用偏移量指定线 |
-a, --as-is | 不强制切成输入方向,保持原方向读取 |
-b, --bias | pull-up、pull-down、disabled |
-l, --active-low | 低电平视为有效 |
--numeric | 以 0 / 1 显示 |
4. gpioset:写电平
gpioset GPIO17=1 # 设为高,进程保持运行,Ctrl+C 退出
gpioset -c 0 17=1 18=0 # 一次设多根线
gpioset -c 0 -t 500ms 17=1 # 每 500 ms 翻转一次,形成闪烁
gpioset -c 0 -z 17=1 # 设好后转入后台
gpioset -c 0 -i 17=0 # 交互模式,输入 help 查看命令
值可以写 1 / 0、active / inactive 或 on / off。时间单位支持 us、ms、s、m,不写单位时按毫秒计。-t 可以给出多个周期,如果最后一个是 0,翻转一轮后退出,否则循环。
【注意】 > v2 的 gpioset 默认不退出,这是有意设计。官方帮助解释:进程退出时它申请的线会被自动释放,释放后线的状态可能被内核或其他进程改掉。所以不能假设 gpioset 退出后引脚还保持原值。需要长期保持时,让 gpioset 用
-z留在后台,或者由自己的程序持有这根线。
此外还有 gpiomon(等待并打印边沿事件,适合调试按键)和 gpionotify(监视线的申请、释放、配置变化),用法见各自的 --help。
五、v1 与 v2 的命令对照
v1 的工具以"控制器 + 偏移量"作为位置参数,没有 -c:
| 操作 | v1.6.x | v2.x |
|---|---|---|
| 读 | gpioget gpiochip0 17 | gpioget -c gpiochip0 17 或 gpioget GPIO17 |
| 写并等待回车 | gpioset --mode=wait gpiochip0 17=1 | gpioset -c gpiochip0 17=1(默认就保持) |
| 写后保持 N 秒 | gpioset --mode=time --sec=2 gpiochip0 17=1 | gpioset -c 0 -p 2s -t 0 17=1 |
| 后台保持 | gpioset -b --mode=signal gpiochip0 17=1 | gpioset -z -c 0 17=1 |
| 查看某个控制器 | gpioinfo gpiochip0 | gpioinfo -c gpiochip0 |
| 按名字找线 | gpiofind GPIO17 | 已删除,直接用线名 |
| 偏置 | -B pull-up | -b pull-up |
| 驱动方式 | -D open-drain | -d open-drain |
v1 的 gpioset 默认 --mode=exit,设完立刻退出。v1 帮助里也写明:退出后线会恢复默认,引脚保持原值只是碰巧,属于未定义行为。很多人"设了高电平但灯不亮"就是这个原因。
六、C 程序(v2 API)
v2 的思路是:先建 line settings(方向、初始值等),放进 line config(哪些偏移量用哪套设置),再加上可选的 request config(consumer 名称),最后向控制器申请得到 line request。下面的程序依据官方 examples/toggle_line_value.c 改写,让 gpiochip0 的 17 号线每秒翻转:
// blink.c
#include <gpiod.h>
#include <stdio.h>
#include <unistd.h>
int main(void)
{
const char *chip_path = "/dev/gpiochip0";
unsigned int offset = 17;
enum gpiod_line_value v = GPIOD_LINE_VALUE_ACTIVE;
struct gpiod_chip *chip = gpiod_chip_open(chip_path);
if (!chip) { perror("open chip"); return 1; }
struct gpiod_line_settings *st = gpiod_line_settings_new();
gpiod_line_settings_set_direction(st, GPIOD_LINE_DIRECTION_OUTPUT);
gpiod_line_settings_set_output_value(st, v);
struct gpiod_line_config *lc = gpiod_line_config_new();
gpiod_line_config_add_line_settings(lc, &offset, 1, st);
struct gpiod_request_config *rc = gpiod_request_config_new();
gpiod_request_config_set_consumer(rc, "blink");
struct gpiod_line_request *req = gpiod_chip_request_lines(chip, rc, lc);
/* 申请完成后,配置对象和 chip 都可以释放,req 继续有效 */
gpiod_request_config_free(rc);
gpiod_line_config_free(lc);
gpiod_line_settings_free(st);
gpiod_chip_close(chip);
if (!req) { perror("request lines"); return 1; }
for (int i = 0; i < 10; i++) {
sleep(1);
v = (v == GPIOD_LINE_VALUE_ACTIVE) ? GPIOD_LINE_VALUE_INACTIVE
: GPIOD_LINE_VALUE_ACTIVE;
gpiod_line_request_set_value(req, offset, v);
}
gpiod_line_request_release(req);
return 0;
}
gcc -o blink blink.c -lgpiod
# 交叉编译时加 --sysroot,sysroot 里要有 ARM 版 libgpiod
读输入时把方向设为 GPIOD_LINE_DIRECTION_INPUT,需要上拉就再调用 gpiod_line_settings_set_bias(),然后用 gpiod_line_request_get_value(req, offset) 读取。
【提示】 > v2 用"有效 / 无效(active / inactive)"而不是"高 / 低"表示值。配置了 active-low 之后,
ACTIVE对应物理低电平。这样按键、低电平点亮的 LED 在代码里都能写成"有效 = 按下 / 亮"。
七、v1 API 的写法
v1.6.x 以 struct gpiod_line 为中心,同样的功能写法如下,不能和 v2 头文件混用:
struct gpiod_chip *chip = gpiod_chip_open_by_name("gpiochip0");
struct gpiod_line *line = gpiod_chip_get_line(chip, 17);
gpiod_line_request_output(line, "blink", 0); /* consumer 名、初始值 */
gpiod_line_set_value(line, 1);
gpiod_line_release(line);
gpiod_chip_close(chip);
| 概念 | v1 | v2 |
|---|---|---|
| 核心对象 | gpiod_line | gpiod_line_request |
| 申请输出 | gpiod_line_request_output() | settings + line config + gpiod_chip_request_lines() |
| 写值 | gpiod_line_set_value(line, 1) | gpiod_line_request_set_value(req, offset, GPIOD_LINE_VALUE_ACTIVE) |
| 按名称打开控制器 | gpiod_chip_open_by_name() 等 | 只有 gpiod_chip_open(path) |
八、排查
| 现象 | 原因与处理 |
|---|---|
Permission denied | 普通用户没有 /dev/gpiochipN 权限。用 root 测试,或按发行版惯例把用户加入对应用户组 / 写 udev 规则 |
Device or resource busy | 线已被内核驱动或其他进程占用,gpioinfo 看 consumer 是谁 |
| 命令报参数错误 | 网上教程和本机 libgpiod 大版本不一致,先 gpioget --version |
| 设完值灯不亮 / 马上灭 | v1 gpioset 默认立即退出、线被释放,改用 --mode=wait 或换 v2 |
| 偏移量对不上板子丝印 | 丝印编号不一定等于偏移量,以 gpioinfo 显示的线名为准 |
参考资料
- Linux 内核 GPIO 字符设备用户态 API:https://docs.kernel.org/userspace-api/gpio/chardev.html
- Linux 内核 sysfs GPIO 接口(已弃用):https://docs.kernel.org/userspace-api/gpio/sysfs.html
- libgpiod 官方仓库:https://git.kernel.org/pub/scm/libs/libgpiod/libgpiod.git/
- libgpiod GitHub 镜像(README、NEWS、tools/、examples/):https://github.com/brgl/libgpiod
- libgpiod v1.6.x 分支:https://github.com/brgl/libgpiod/tree/v1.6.x
评价 (0)