GPIO 字符设备用户空间 API (v1)¶

警告

此 API 已被 GPIO 字符设备用户空间 API (v2) 弃用。

新的开发应使用 v2 API，并且鼓励现有开发尽快迁移，因为此 API 将在未来被删除。v2 API 是 v1 API 的功能超集，因此任何 v1 调用都可以直接转换为等效的 v2 调用。

此接口将在迁移期间继续维护，但新功能只会添加到新的 API 中。

首次添加于 4.8。

该 API 基于三个主要对象：芯片、线路句柄和线路事件。

本文档中使用 “线路事件” 一词时，指的是可以监视线路边缘事件的请求，而不是边缘事件本身。

芯片¶

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

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

线路通过 GPIO_GET_LINEHANDLE_IOCTL 从芯片请求，并且生成的线路句柄用于访问 GPIO 芯片的线路，或者通过 GPIO_GET_LINEEVENT_IOCTL 请求，并且生成的线路事件用于监视 GPIO 线路的边缘事件。

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

操作¶

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

线路句柄¶

线路句柄由 GPIO_GET_LINEHANDLE_IOCTL 创建，并提供对一组请求线路的访问权限。线路句柄通过 GPIO_GET_LINEHANDLE_IOCTL 在 request.fd 中返回的匿名文件描述符公开给用户空间。

在本文档中，线路句柄文件描述符称为 handle_fd。

操作¶

可以在线路句柄上执行以下操作

线路事件¶

线路事件由 GPIO_GET_LINEEVENT_IOCTL 创建，并提供对请求线路的访问权限。线路事件通过 GPIO_GET_LINEEVENT_IOCTL 在 request.fd 中返回的匿名文件描述符公开给用户空间。

在本文档中，线路事件文件描述符称为 event_fd。

操作¶

可以在线路事件上执行以下操作

类型¶

本节包含 ABI v1 引用的结构。

struct gpiochip_info 在 ABI v1 和 v2 中是通用的。

struct gpioline_info¶: 有关特定 GPIO 线路的信息

定义:

struct gpioline_info {
    __u32 line_offset;
    __u32 flags;
    char name[GPIO_MAX_NAME_SIZE];
    char consumer[GPIO_MAX_NAME_SIZE];
};

成员

line_offset: 此 GPIO 设备上的本地偏移量，从内核请求线路信息时填写此项
flags: 此线路的各种标志
name: 此 GPIO 线路的名称，例如线路在芯片上的输出引脚、板上的导轨或引脚头名称，由 gpio 芯片指定，可以为空（即 name[0] == '0'）
consumer: 此 GPIO 线路的使用者的功能名称，由使用它的任何内容设置，如果没有当前用户则为空，但如果使用者未进行设置，也可能为空

注意

此结构是 ABI v1 的一部分，已弃用。请改用 ABI v2 和 struct gpio_v2_line_info。

struct gpioline_info_changed¶: 有关 GPIO 线路状态更改的信息

定义:

struct gpioline_info_changed {
    struct gpioline_info info;
    __u64 timestamp;
    __u32 event_type;
    __u32 padding[5];
};

成员

info: 更新的线路信息
timestamp: 状态更改发生时间的估计值，以纳秒为单位
event_type: 为 GPIOLINE_CHANGED_REQUESTED、GPIOLINE_CHANGED_RELEASED 和 GPIOLINE_CHANGED_CONFIG 之一
padding: 保留供将来使用

描述

此处嵌入的 struct gpioline_info 本身具有 32 位对齐，但也可以很好地与 64 位对齐一起使用。凭借其 72 字节的大小，我们可以保证它和后续成员之间没有隐式空洞。末尾的 20 字节填充确保我们不会在 64 位架构上的结构末尾添加任何隐式填充。

注意

此结构是 ABI v1 的一部分，已弃用。请改用 ABI v2 和 struct gpio_v2_line_info_changed。

struct gpiohandle_request¶: 有关 GPIO 句柄请求的信息

定义:

struct gpiohandle_request {
    __u32 lineoffsets[GPIOHANDLES_MAX];
    __u32 flags;
    __u8 default_values[GPIOHANDLES_MAX];
    char consumer_label[GPIO_MAX_NAME_SIZE];
    __u32 lines;
    int fd;
};

成员

lineoffsets: 所需线路的数组，通过关联 GPIO 设备的偏移量索引指定
flags: 所需 GPIO 线路的所需标志，例如 GPIOHANDLE_REQUEST_OUTPUT、GPIOHANDLE_REQUEST_ACTIVE_LOW 等，相加在一起。请注意，即使请求了多条线路，相同的标志也必须适用于所有线路，如果您想要设置了单独标志的线路，请逐个请求。可以选择一批输入或输出线路，但它们必须都具有相同的特性，即所有输入或所有输出，全部为低电平有效等
default_values: 如果为请求的线路设置了 GPIOHANDLE_REQUEST_OUTPUT，则此值指定默认输出值，应为 0（非活动）或 1（活动）。任何不是 0 或 1 的值都将被解释为活动。
consumer_label: 所选 GPIO 线路的所需使用者标签，例如“my-bitbanged-relay”
lines: 此请求中请求的线路数，即上述数组中有效字段的数量，设置为 1 以请求单条线路
fd: 成功执行 GPIO_GET_LINEHANDLE_IOCTL 操作后，包含表示请求的有效匿名文件描述符

注意

此结构是 ABI v1 的一部分，已弃用。请改用 ABI v2 和 struct gpio_v2_line_request。

struct gpiohandle_config¶: GPIO 句柄请求的配置

定义:

struct gpiohandle_config {
    __u32 flags;
    __u8 default_values[GPIOHANDLES_MAX];
    __u32 padding[4];
};

成员

flags: 请求的 GPIO 线路的更新标志，例如 GPIOHANDLE_REQUEST_OUTPUT、GPIOHANDLE_REQUEST_ACTIVE_LOW 等，相加在一起
default_values: 如果在标志中设置了 GPIOHANDLE_REQUEST_OUTPUT，则此值指定默认输出值，应为 0（非活动）或 1（活动）。任何不是 0 或 1 的值都将被解释为活动。
padding: 保留供将来使用，应填充为零

注意

此结构是 ABI v1 的一部分，已弃用。请改用 ABI v2 和 struct gpio_v2_line_config。

struct gpiohandle_data¶: 有关 GPIO 句柄上值的信息

定义:

struct gpiohandle_data {
    __u8 values[GPIOHANDLES_MAX];
};

成员

values: 当获取线路状态时，此值包含线路的当前状态；当设置线路状态时，这些值应包含所需的目标状态。状态为 0（非活动）或 1（活动）。设置时，任何不是 0 或 1 的值都将被解释为活动。

注意

此结构体是 ABI v1 的一部分，已被弃用。请使用 ABI v2 和 struct gpio_v2_line_values 代替。

struct gpioevent_request¶: 关于 GPIO 事件请求的信息

定义:

struct gpioevent_request {
    __u32 lineoffset;
    __u32 handleflags;
    __u32 eventflags;
    char consumer_label[GPIO_MAX_NAME_SIZE];
    int fd;
};

成员

lineoffset: 要订阅事件的所需线路，由关联 GPIO 设备的偏移索引指定
handleflags: 所需 GPIO 线路的所需句柄标志，例如 GPIOHANDLE_REQUEST_ACTIVE_LOW 或 GPIOHANDLE_REQUEST_OPEN_DRAIN
eventflags: 所需 GPIO 事件线路的所需标志，例如 GPIOEVENT_REQUEST_RISING_EDGE 或 GPIOEVENT_REQUEST_FALLING_EDGE
consumer_label: 所选 GPIO 线路的所需消费者标签，例如 “my-listener”
fd: 成功执行 GPIO_GET_LINEEVENT_IOCTL 操作后，包含表示该请求的有效匿名文件描述符

注意

此结构是 ABI v1 的一部分，已弃用。请改用 ABI v2 和 struct gpio_v2_line_request。

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

定义:

struct gpioevent_data {
    __u64 timestamp;
    __u32 id;
};

成员

timestamp: 事件发生时间的最佳估计，以纳秒为单位
id: 事件标识符，为 GPIOEVENT_EVENT_RISING_EDGE 或 GPIOEVENT_EVENT_FALLING_EDGE 之一

注意

此结构体是 ABI v1 的一部分，已被弃用。请使用 ABI v2 和 struct gpio_v2_line_event 代替。

Linux 内核

目录

本页

GPIO 字符设备用户空间 API (v1)¶

芯片¶

操作¶

线路句柄¶

操作¶

线路事件¶

操作¶

类型¶