Linux 硬體時間戳引擎 (HTE)¶

作者:: Dipen Patel

簡介¶

某些裝置具有內建的硬體時間戳引擎，可以即時監控系統訊號、線路、匯流排等的狀態變化；檢測到變化時，它們可以自動儲存發生時刻的時間戳。與使用軟體對應項（例如 ktime 及其變體）相比，這種功能可能有助於在獲取時間戳時實現更高的準確性。

本文件描述了希望使用硬體時間戳引擎 (HTE) 框架的硬體時間戳引擎提供程式和使用者驅動程式可以使用的 API。使用者和提供程式都必須包含 #include <linux/hte.h>。

提供程式的 HTE 框架 API¶

int hte_push_ts_ns(const struct hte_chip *chip, u32 xlated_id, struct hte_ts_data *data)¶: 推送納秒級時間戳資料。

引數

const struct hte_chip *chip: HTE 晶片，在註冊期間使用。
u32 xlated_id: 子系統和提供程式都理解的實體 ID，這是從請求 API 期間的 xlate 回撥獲得的。
struct hte_ts_data *data: 時間戳資料。

描述

它被提供程式用於推送時間戳資料。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int devm_hte_register_chip(struct hte_chip *chip)¶: 資源管理 API，用於註冊 HTE 晶片。

引數

struct hte_chip *chip: 要新增到子系統的 HTE 晶片。

描述

它被提供程式用於向 HTE 子系統註冊自身。當提供程式退出時，將自動完成登出。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

消費者的 HTE 框架 API¶

int hte_ts_put(struct hte_ts_desc *desc)¶: 釋放並停用給定描述符的時間戳。

引數

struct hte_ts_desc *desc: 時間戳描述符。

上下文

debugfs_remove_recursive() 函式呼叫可能使用睡眠鎖，不適合在原子上下文中呼叫。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int hte_disable_ts(struct hte_ts_desc *desc)¶: 在給定描述符上停用時間戳。

引數

struct hte_ts_desc *desc: 時間戳描述符，與請求 API 返回的相同。

描述

該 API 不會釋放與 desc 關聯的任何資源。

上下文

持有互斥鎖，不適合在原子上下文中呼叫。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int hte_enable_ts(struct hte_ts_desc *desc)¶: 在給定描述符上啟用時間戳。

引數

struct hte_ts_desc *desc: 時間戳描述符，與請求 API 返回的相同。

上下文

持有互斥鎖，不適合在原子上下文中呼叫。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int of_hte_req_count(struct device *dev)¶: 返回要新增時間戳的實體數量。

引數

struct device *dev: HTE 消費者。

描述

該函式透過解析裝置樹返回請求新增時間戳的實體總數。

返回值

成功時返回正數，如果不存在條目則返回 -ENOENT，其他錯誤返回 -EINVAL。

int hte_ts_get(struct device *dev, struct hte_ts_desc *desc, int index)¶: 初始化並獲取 HTE 描述符的函式。

引數

struct device *dev: HTE 消費者/客戶端裝置，用於解析裝置樹節點的情況。
struct hte_ts_desc *desc: 預分配的時間戳描述符。
int index: 如果存在節點，該索引將用作解析裝置樹節點中 line_id 的索引。

描述

該函式初始化消費者提供的 HTE 描述符。如果消費者具有裝置樹節點，則 index 用於解析行 ID 和其他詳細資訊。在使用任何請求 API 之前，需要呼叫該函式。

上下文

持有互斥鎖。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int hte_request_ts_ns(struct hte_ts_desc *desc, hte_ts_cb_t cb, hte_ts_sec_cb_t tcb, void *data)¶: 請求並啟用納秒級硬體時間戳的 API。

引數

struct hte_ts_desc *desc: 預分配和初始化的時間戳描述符。
hte_ts_cb_t cb: 回撥以將時間戳資料推送到消費者。
hte_ts_sec_cb_t tcb: 可選回撥。如果提供，子系統將初始化工作佇列。當 cb 返回 HTE_RUN_SECOND_CB 時呼叫。
void *data: 客戶端資料，在 cb 和 tcb 回撥期間使用。

描述

實體是提供程式特定的，例如，GPIO 線、訊號、匯流排等。該 API 分配必要的資源並啟用時間戳。

上下文

持有互斥鎖。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int devm_hte_request_ts_ns(struct device *dev, struct hte_ts_desc *desc, hte_ts_cb_t cb, hte_ts_sec_cb_t tcb, void *data)¶: 資源管理 API，用於請求並啟用納秒級硬體時間戳。

引數

struct device *dev: HTE 消費者/客戶端裝置。
struct hte_ts_desc *desc: 預分配和初始化的時間戳描述符。
hte_ts_cb_t cb: 回撥以將時間戳資料推送到消費者。
hte_ts_sec_cb_t tcb: 可選回撥。如果提供，子系統將初始化工作佇列。當 cb 返回 HTE_RUN_SECOND_CB 時呼叫。
void *data: 客戶端資料，在 cb 和 tcb 回撥期間使用。

描述

實體是提供程式特定的，例如，GPIO 線、訊號、匯流排等。該 API 分配必要的資源並啟用時間戳。當消費者退出時，它會自動釋放和停用資源。

上下文

持有互斥鎖。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int hte_init_line_attr(struct hte_ts_desc *desc, u32 line_id, unsigned long edge_flags, const char *name, void *data)¶: 初始化線路屬性。

引數

struct hte_ts_desc *desc: 預分配的時間戳描述符。
u32 line_id: 線路 ID。
unsigned long edge_flags: 與 line_id 相關的邊沿標誌。
const char *name: 線路名稱。
void *data: 與 line_id 相關的線路資料。

描述

清除線路屬性並使用提供的引數進行初始化。在呼叫任何面向消費者的函式之前，需要呼叫該函式。

上下文

任何。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

int hte_get_clk_src_info(const struct hte_ts_desc *desc, struct hte_clk_info *ci)¶: 獲取時間戳描述符的時鐘源資訊。

引數

const struct hte_ts_desc *desc: 時間戳描述符，與請求 API 返回的相同。
struct hte_clk_info *ci: API 使用時鐘資訊資料填充此結構。

上下文

任何上下文。

返回值

成功時返回 0，失敗時返回負錯誤程式碼。

HTE 框架公共結構¶

enum hte_edge¶: HTE 線路邊沿標誌。

常量

HTE_EDGE_NO_SETUP: 無邊沿設定。在這種情況下，消費者將設定邊沿，例如在請求 irq 呼叫期間。
HTE_RISING_EDGE_TS: 上升沿。
HTE_FALLING_EDGE_TS: 下降沿。

enum hte_return¶: 在回撥期間使用的 HTE 子系統返回值。

常量

HTE_CB_HANDLED: 消費者處理了資料。
HTE_RUN_SECOND_CB: 消費者需要進一步處理，在這種情況下，HTE 子系統呼叫消費者提供的輔助回撥，允許在其中睡眠。

struct hte_ts_data¶: HTE 時間戳資料。

定義:

struct hte_ts_data {
    u64 tsc;
    u64 seq;
    int raw_level;
};

成員

tsc: 時間戳值。
seq: 時間戳的序列計數器。
raw_level: 如果提供程式支援，則在時間戳處的線路電平，否則為 -1。

struct hte_clk_info¶: HTE 提供者用於時間戳的時鐘源資訊。

定義:

struct hte_clk_info {
    u64 hz;
    clockid_t type;
};

成員

hz: 支援的時鐘頻率，單位為赫茲 (HZ)，例如 1KHz 時鐘 = 1000。
type: 支援的時鐘型別。

hte_ts_cb_t¶: Typedef：HTE 時間戳資料處理的主要回調函式。

語法

enum hte_return hte_ts_cb_t (struct hte_ts_data *ts, void *data)

引數

struct hte_ts_data *ts: 硬體時間戳資料。
void *data: 客戶端提供的資料。

描述

此回撥函式用於將時間戳資料推送給客戶端，不允許睡眠。

hte_ts_sec_cb_t¶: Typedef：HTE 時間戳資料處理的次要回調函式。

語法

enum hte_return hte_ts_sec_cb_t (void *data)

引數

void *data: 客戶端提供的資料。

描述

當客戶端需要進一步處理並且允許睡眠時使用此回撥函式。

struct hte_line_attr¶: 線路屬性。

定義:

struct hte_line_attr {
    u32 line_id;
    void *line_data;
    unsigned long edge_flags;
    const char *name;
};

成員

line_id: 消費者和提供者都理解的邏輯 ID。
line_data: 與 line_id 相關的線路資料。
edge_flags: 邊沿設定標誌。
name: 被監控以進行硬體時間戳的實體的描述性名稱。如果為空，HTE 核心將構造名稱。

struct hte_ts_desc¶: HTE 時間戳描述符。

定義:

struct hte_ts_desc {
    struct hte_line_attr attr;
    void *hte_data;
};

成員

attr: 線路屬性。
hte_data: 子系統的私有資料，由 HTE 子系統設定。

描述

此結構是消費者與子系統以及子系統與提供者之間的通訊令牌。

struct hte_ops¶: 由提供者設定的 HTE 操作集。

定義:

struct hte_ops {
    int (*request)(struct hte_chip *chip, struct hte_ts_desc *desc, u32 xlated_id);
    int (*release)(struct hte_chip *chip, struct hte_ts_desc *desc, u32 xlated_id);
    int (*enable)(struct hte_chip *chip, u32 xlated_id);
    int (*disable)(struct hte_chip *chip, u32 xlated_id);
    int (*get_clk_src_info)(struct hte_chip *chip, struct hte_clk_info *ci);
};

成員

request: 用於請求 HTE 時間戳的鉤子。成功時返回 0，失敗時返回非零值。
release: 用於釋放 HTE 時間戳的鉤子。成功時返回 0，失敗時返回非零值。
enable: 用於啟用指定時間戳的鉤子。成功時返回 0，失敗時返回非零值。
disable: 用於停用指定時間戳的鉤子。成功時返回 0，失敗時返回非零值。
get_clk_src_info: 用於獲取提供者用於時間戳的時鐘資訊的鉤子。成功時返回 0，失敗時返回負錯誤程式碼。成功後，HTE 子系統將填充提供的 struct hte_clk_info。

描述

xlated_id 引數用於 HTE 子系統和提供者之間的通訊，並由提供者翻譯。

struct hte_chip¶: 抽象 HTE 晶片。

定義:

struct hte_chip {
    const char *name;
    struct device *dev;
    const struct hte_ops *ops;
    u32 nlines;
    int (*xlate_of)(struct hte_chip *gc,const struct of_phandle_args *args, struct hte_ts_desc *desc, u32 *xlated_id);
    int (*xlate_plat)(struct hte_chip *gc, struct hte_ts_desc *desc, u32 *xlated_id);
    bool (*match_from_linedata)(const struct hte_chip *chip, const struct hte_ts_desc *hdesc);
    u8 of_hte_n_cells;
    struct hte_device *gdev;
    void *data;
};

成員

name: HTE IP 塊的功能名稱。
dev: 提供 HTE 的裝置。
ops: 此 HTE 的回撥函式。
nlines: 此晶片支援的線路/訊號數量。
xlate_of: 回撥函式，用於將消費者提供的邏輯 ID 轉換為物理 ID，成功時返回 0，失敗時返回負值。成功時，它將（0 到 nlines 之間）儲存在 xlated_id 引數中。
xlate_plat: 與上述相同，但適用於沒有 DT 節點的消費者。
match_from_linedata: 使用 line_data 匹配 HTE 裝置。
of_hte_n_cells: 用於形成 HTE 說明符的單元格數。
gdev: HTE 子系統抽象裝置，HTE 子系統內部使用。
data: 晶片特定的私有資料。

關於 HTE 時間戳資料的更多資訊¶

struct hte_ts_data 用於在消費者和提供者之間傳遞時間戳詳細資訊。它以 u64 納秒為單位表示時間戳資料。例如，GPIO 線路的典型時間戳資料生命週期如下：

- Monitors GPIO line change.
- Detects the state change on GPIO line.
- Converts timestamps in nanoseconds.
- Stores GPIO raw level in raw_level variable if the provider has that
hardware capability.
- Pushes this hte_ts_data object to HTE subsystem.
- HTE subsystem increments seq counter and invokes consumer provided callback.
Based on callback return value, the HTE core invokes secondary callback in
the thread context.

HTE 子系統 debugfs 屬性¶

HTE 子系統在 /sys/kernel/debug/hte/ 建立 debugfs 屬性。它還在 /sys/kernel/debug/hte/<provider>/<label or line id>/ 建立與線路/訊號相關的 debugfs 屬性。請注意，這些屬性是隻讀的。

ts_requested: 從給定提供者請求的實體總數，其中實體由提供者指定，並且可以代表線路、GPIO、晶片訊號、匯流排等。該屬性將在 /sys/kernel/debug/hte/<provider>/ 中可用。
total_ts: 提供者支援的實體總數。該屬性將在 /sys/kernel/debug/hte/<provider>/ 中可用。
dropped_timestamps: 給定線路的丟棄的時間戳。該屬性將在 /sys/kernel/debug/hte/<provider>/<label or line id>/ 中可用。

Linux 核心

目錄

本頁

Linux 硬體時間戳引擎 (HTE)¶

簡介¶

提供程式的 HTE 框架 API¶

消費者的 HTE 框架 API¶

HTE 框架公共結構¶

關於 HTE 時間戳資料的更多資訊¶

HTE 子系統 debugfs 屬性¶