GPIO 字符设备用户空间 API¶

这是字符设备 API 的最新版本 (v2)，定义在 include/uapi/linux/gpio.h 中。

首次添加于 5.10。

注意

不要滥用用户空间 API 来控制具有适当内核驱动程序的硬件。您的用例可能已经有驱动程序，并且现有的内核驱动程序肯定会提供比从用户空间进行位操作更好的解决方案。

阅读使用 GPIO 的子系统驱动程序，以避免在用户空间中重新发明内核轮子。

同样，对于多功能线路，可能存在其他子系统，例如串行外围接口 (SPI)、I2C/SMBus 子系统、脉冲宽度调制 (PWM) 接口、1-Wire 子系统等，它们为您的硬件提供了合适的驱动程序和 API。

使用字符设备 API 的基本示例可以在 tools/gpio/* 中找到。

该 API 基于两个主要对象，芯片和线路请求。

芯片¶

芯片表示单个 GPIO 芯片，并使用 /dev/gpiochipX 形式的设备文件暴露给用户空间。

每个芯片支持多个 GPIO 线路，chip.lines。芯片上的线路由 offset 标识，范围为 0 到 chip.lines - 1，即 [0,chip.lines)。

使用 GPIO_V2_GET_LINE_IOCTL 从芯片请求线路，并且使用生成的线路请求来访问 GPIO 芯片的线路或监视线路的边缘事件。

在此文档中，通过在 GPIO 设备文件上调用 open() 返回的文件描述符称为 chip_fd。

操作¶

可以在芯片上执行以下操作

线路请求¶

线路请求由 GPIO_V2_GET_LINE_IOCTL 创建，并提供对一组请求线路的访问。线路请求通过 request.fd 中返回的匿名文件描述符暴露给用户空间，该描述符由 GPIO_V2_GET_LINE_IOCTL 返回。

在此文档中，线路请求文件描述符称为 req_fd。

操作¶

可以在线路请求上执行以下操作

类型¶

本节包含 API v2 引用的结构体和枚举，如 include/uapi/linux/gpio.h 中定义的那样。

struct gpiochip_info¶: 有关特定 GPIO 芯片的信息

定义:

struct gpiochip_info {
    char name[GPIO_MAX_NAME_SIZE];
    char label[GPIO_MAX_NAME_SIZE];
    __u32 lines;
};

成员

name: 此 GPIO 芯片的 Linux 内核名称
label: 此 GPIO 芯片的功能名称，例如产品编号，可能为空（即 label[0] == ‘0’）
lines: 此芯片上的 GPIO 线路数

enum gpio_v2_line_flag¶: struct gpio_v2_line_attribute.flags 值

常量

GPIO_V2_LINE_FLAG_USED: 线路不可用于请求
GPIO_V2_LINE_FLAG_ACTIVE_LOW: 线路的活动状态为物理低电平
GPIO_V2_LINE_FLAG_INPUT: 线路是输入
GPIO_V2_LINE_FLAG_OUTPUT: 线路是输出
GPIO_V2_LINE_FLAG_EDGE_RISING: 线路检测上升沿（从不活动到活动）
GPIO_V2_LINE_FLAG_EDGE_FALLING: 线路检测下降沿（从活动到不活动）
GPIO_V2_LINE_FLAG_OPEN_DRAIN: 线路是开漏输出
GPIO_V2_LINE_FLAG_OPEN_SOURCE: 线路是开路源输出
GPIO_V2_LINE_FLAG_BIAS_PULL_UP: 线路启用了上拉偏置
GPIO_V2_LINE_FLAG_BIAS_PULL_DOWN: 线路启用了下拉偏置
GPIO_V2_LINE_FLAG_BIAS_DISABLED: 线路禁用了偏置
GPIO_V2_LINE_FLAG_EVENT_CLOCK_REALTIME: 线路事件包含 REALTIME 时间戳
GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE: 线路事件包含来自硬件时间戳引擎 (HTE) 子系统的时间戳

struct gpio_v2_line_values¶: GPIO 线路的值

定义:

struct gpio_v2_line_values {
    __aligned_u64 bits;
    __aligned_u64 mask;
};

成员

bits: 包含线路值的位图，活动状态设置为 1，不活动状态设置为 0
mask: 一个位图，用于标识要获取或设置的线路，每个位号对应于 struct gpio_v2_line_request.offsets 中的索引

enum gpio_v2_line_attr_id¶: struct gpio_v2_line_attribute.id 值，用于标识正在使用哪个属性联合字段。

常量

GPIO_V2_LINE_ATTR_ID_FLAGS: flags 字段正在使用
GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES: values 字段正在使用
GPIO_V2_LINE_ATTR_ID_DEBOUNCE: debounce_period_us 字段正在使用

struct gpio_v2_line_attribute¶: 线路的可配置属性

定义:

struct gpio_v2_line_attribute {
    __u32 id;
    __u32 padding;
    union {
        __aligned_u64 flags;
        __aligned_u64 values;
        __u32 debounce_period_us;
    };
};

成员

id: 属性标识符，其值来自 enum gpio_v2_line_attr_id
padding: 保留供将来使用，必须填充为零
{unnamed_union}: 匿名
flags: 如果 id 为 GPIO_V2_LINE_ATTR_ID_FLAGS，则为 GPIO 线路的标志，其值来自 enum gpio_v2_line_flag，例如 GPIO_V2_LINE_FLAG_ACTIVE_LOW、GPIO_V2_LINE_FLAG_OUTPUT 等，加在一起。这将覆盖与相关线路的 struct gpio_v2_line_config 中包含的默认标志。
values: 如果 id 为 GPIO_V2_LINE_ATTR_ID_OUTPUT_VALUES，则为包含要设置的线路值的位图，每个位号对应于 struct gpio_v2_line_request.offsets 中的索引
debounce_period_us: 如果 id 为 GPIO_V2_LINE_ATTR_ID_DEBOUNCE，则为所需的防抖动周期，以微秒为单位

struct gpio_v2_line_config_attribute¶: 与一个或多个请求的线路关联的配置属性。

定义:

struct gpio_v2_line_config_attribute {
    struct gpio_v2_line_attribute attr;
    __aligned_u64 mask;
};

成员

attr: 可配置的属性
mask: 一个位图，用于标识该属性所应用的线路，每个位号对应于 struct gpio_v2_line_request.offsets 中的索引

struct gpio_v2_line_config¶: GPIO 线路的配置

定义:

struct gpio_v2_line_config {
    __aligned_u64 flags;
    __u32 num_attrs;
    __u32 padding[5];
    struct gpio_v2_line_config_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];
};

成员

flags: GPIO 线路的标志，其值来自 enum gpio_v2_line_flag，例如 GPIO_V2_LINE_FLAG_ACTIVE_LOW、GPIO_V2_LINE_FLAG_OUTPUT 等，加在一起。这是所有请求线路的默认值，但可以使用 attrs 覆盖特定线路。
num_attrs: attrs 中的属性数
padding: 保留供将来使用，必须填充为零
attrs: 与请求的线路关联的配置属性。任何属性都应该只与特定线路关联一次。如果一个属性与一个线路关联多次，则第一次出现（即最低索引）优先。

struct gpio_v2_line_request¶: 关于 GPIO 线请求的信息

定义:

struct gpio_v2_line_request {
    __u32 offsets[GPIO_V2_LINES_MAX];
    char consumer[GPIO_MAX_NAME_SIZE];
    struct gpio_v2_line_config config;
    __u32 num_lines;
    __u32 event_buffer_size;
    __u32 padding[5];
    __s32 fd;
};

成员

offsets: 一个所需线的数组，由关联的 GPIO 芯片的偏移索引指定
consumer: 选定 GPIO 线的所需使用者标签，例如“my-bitbanged-relay”
config: 请求的线的配置
num_lines: 此请求中请求的线数，即 GPIO_V2_LINES_MAX 大小数组中的有效字段数，设置为 1 以请求单条线
event_buffer_size: 内核应缓冲的建议最小行事件数。仅当配置中启用了边缘检测时，此项才相关。请注意，这只是一个建议值，内核可能会分配更大的缓冲区或限制缓冲区的大小。如果此字段为零，则缓冲区大小默认为最小 num_lines * 16。
padding: 保留供将来使用，必须填充为零
fd: 在成功执行 GPIO_V2_GET_LINE_IOCTL 操作后，包含表示请求的有效匿名文件描述符

struct gpio_v2_line_info¶: 关于特定 GPIO 线的信息

定义:

struct gpio_v2_line_info {
    char name[GPIO_MAX_NAME_SIZE];
    char consumer[GPIO_MAX_NAME_SIZE];
    __u32 offset;
    __u32 num_attrs;
    __aligned_u64 flags;
    struct gpio_v2_line_attribute attrs[GPIO_V2_LINE_NUM_ATTRS_MAX];
    __u32 padding[4];
};

成员

name: 此 GPIO 线的名称，例如芯片上线的输出引脚、板上的导轨或引脚头名称，由 GPIO 芯片指定，可能为空（即 name[0] == '0'）
consumer: 此 GPIO 线的使用者的功能名称，由使用它的任何程序设置，如果没有当前使用者将为空，但如果使用者未设置此项也可能为空
offset: 此 GPIO 芯片上的本地偏移量，在从内核请求行信息时填写此项
num_attrs: attrs 中的属性数
flags: 此 GPIO 线的标志，其值来自 enum gpio_v2_line_flag，例如 GPIO_V2_LINE_FLAG_ACTIVE_LOW，GPIO_V2_LINE_FLAG_OUTPUT 等，相加在一起
attrs: 与该线关联的配置属性
padding: 保留供将来使用

enum gpio_v2_line_changed_type¶: struct gpio_v2_line_changed.event_type 值

常量

GPIO_V2_LINE_CHANGED_REQUESTED: 已请求该行
GPIO_V2_LINE_CHANGED_RELEASED: 已释放该行
GPIO_V2_LINE_CHANGED_CONFIG: 已重新配置该行

struct gpio_v2_line_info_changed¶: 关于 GPIO 行状态更改的信息

定义:

struct gpio_v2_line_info_changed {
    struct gpio_v2_line_info info;
    __aligned_u64 timestamp_ns;
    __u32 event_type;
    __u32 padding[5];
};

成员

info: 更新的行信息
timestamp_ns: 状态更改发生时间的估计值，以纳秒为单位
event_type: 更改的类型，其值来自 enum gpio_v2_line_changed_type
padding: 保留供将来使用

enum gpio_v2_line_event_id¶: struct gpio_v2_line_event.id 值

常量

GPIO_V2_LINE_EVENT_RISING_EDGE: 由上升沿触发的事件
GPIO_V2_LINE_EVENT_FALLING_EDGE: 由下降沿触发的事件

struct gpio_v2_line_event¶: 推送给用户空间的实际事件

定义:

struct gpio_v2_line_event {
    __aligned_u64 timestamp_ns;
    __u32 id;
    __u32 offset;
    __u32 seqno;
    __u32 line_seqno;
    __u32 padding[6];
};

成员

timestamp_ns: 事件发生时间的最佳估计值，以纳秒为单位
id: 事件标识符，其值来自 enum gpio_v2_line_event_id
offset: 触发事件的线的偏移量
seqno: 此事件在此行请求中所有线的事件序列中的序列号
line_seqno: 此事件在此特定线上的事件序列中的序列号
padding: 保留供将来使用

描述

默认情况下，timestamp_ns 从 CLOCK_MONOTONIC 读取，旨在允许准确测量事件之间的时间。它不提供挂钟时间。

如果设置了 GPIO_V2_LINE_FLAG_EVENT_CLOCK_REALTIME 标志，则 timestamp_ns 将从 CLOCK_REALTIME 读取。

如果设置了 GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE 标志，则 timestamp_ns 由硬件时间戳引擎 (HTE) 子系统提供。

Linux 内核

目录

本页

GPIO 字符设备用户空间 API¶

芯片¶

操作¶

线路请求¶

操作¶

类型¶