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。芯片上的线路由 0 到 chip.lines - 1 范围内的 offset 标识，即 [0,chip.lines)。

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

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

操作¶

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

线路请求¶

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

在本文档中，线路请求文件描述符称为 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}: anonymous
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¶

芯片¶

操作¶

线路请求¶

操作¶

类型¶