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¶

晶片¶

操作¶

線路請求¶

操作¶

型別¶