I3C 主控制器驅動 API¶

void i3c_bus_maintenance_lock(struct i3c_bus *bus)¶: 鎖定匯流排以進行維護操作

引數

struct i3c_bus *bus: 要獲取鎖定的 I3C 匯流排

描述

此函式獲取匯流排鎖，以便不會在總線上發生其他操作。這對於所有型別的匯流排維護操作都是必需的，例如 - 啟用/停用從機事件 - 重新觸發 DAA - 更改裝置的動態地址 - 放棄主控權 - ...

這種鎖定的原因是，我們不希望驅動程式和核心邏輯依賴於可能在其背後更改的 I3C 裝置資訊。

void i3c_bus_maintenance_unlock(struct i3c_bus *bus)¶: 在維護操作後釋放匯流排鎖

引數

struct i3c_bus *bus: 要釋放鎖定的 I3C 匯流排

描述

應在匯流排維護操作完成後呼叫。有關這些維護操作的更多詳細資訊，請參見i3c_bus_maintenance_lock()。

void i3c_bus_normaluse_lock(struct i3c_bus *bus)¶: 鎖定匯流排以進行正常操作

引數

struct i3c_bus *bus: 要獲取鎖定的 I3C 匯流排

描述

此函式獲取匯流排鎖，用於任何非維護操作的操作（有關非詳盡的維護操作列表，請參見i3c_bus_maintenance_lock()）。基本上，與 I3C 裝置的所有通訊都是正常操作（HDR、SDR 傳輸或不更改匯流排狀態或 I3C 動態地址的 CCC 命令）。

請注意，此鎖不保證正常操作的序列化。換句話說，傳遞給 I3C 主站的傳輸請求可以並行提交，並且 I3C 主驅動程式必須使用其自己的鎖定來確保兩個不同的通訊不會混合在一起，或者在引擎繁忙時不會訪問輸出/輸入佇列。

void i3c_bus_normaluse_unlock(struct i3c_bus *bus)¶: 在正常操作後釋放匯流排鎖

引數

struct i3c_bus *bus: 要釋放鎖定的 I3C 匯流排

描述

應在正常操作完成後呼叫。有關這些正常操作的更多詳細資訊，請參見i3c_bus_normaluse_lock()。

int i3c_master_get_free_addr(struct i3c_master_controller *master, u8 start_addr)¶: 在總線上獲取空閒地址

引數

struct i3c_master_controller *master: I3C 主物件
u8 start_addr: 從哪裡開始搜尋

描述

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

從 start_addr (包含) 開始的第一個空閒地址，如果沒有更多可用地址，則返回 -ENOMEM。

int i3c_master_entdaa_locked(struct i3c_master_controller *master)¶: 啟動 DAA (動態地址分配) 過程

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站

描述

傳送 ENTDAA CCC 命令以啟動 DAA 過程。

請注意，此函式僅傳送 ENTDAA CCC 命令，動態地址分配背後的所有邏輯都必須在 I3C 主驅動程式中處理。

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

成功時返回 0，如果錯誤是官方 Mx 錯誤程式碼之一，則返回正 I3C 錯誤程式碼，否則返回負錯誤程式碼。

int i3c_master_disec_locked(struct i3c_master_controller *master, u8 addr, u8 evts)¶: 傳送 DISEC CCC 命令

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站
u8 addr: 有效的 I3C 從機地址或 I3C_BROADCAST_ADDR
u8 evts: 要停用的事件

描述

傳送 DISEC CCC 命令以停用來自特定從機的一些或所有事件，如果 addr 是 I3C_BROADCAST_ADDR，則停用來自所有裝置的事件。

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

成功時返回 0，如果錯誤是官方 Mx 錯誤程式碼之一，則返回正 I3C 錯誤程式碼，否則返回負錯誤程式碼。

int i3c_master_enec_locked(struct i3c_master_controller *master, u8 addr, u8 evts)¶: 傳送 ENEC CCC 命令

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站
u8 addr: 有效的 I3C 從機地址或 I3C_BROADCAST_ADDR
u8 evts: 要停用的事件

描述

傳送 ENEC CCC 命令以啟用來自特定從機的一些或所有事件，如果 addr 是 I3C_BROADCAST_ADDR，則啟用來自所有裝置的事件。

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

成功時返回 0，如果錯誤是官方 Mx 錯誤程式碼之一，則返回正 I3C 錯誤程式碼，否則返回負錯誤程式碼。

int i3c_master_defslvs_locked(struct i3c_master_controller *master)¶: 傳送 DEFSLVS CCC 命令

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站

描述

傳送包含 master 已知的所有裝置的 DEFSLVS CCC 命令。當您在總線上有輔助主站來傳播裝置資訊時，這非常有用。

應在發現所有 I3C 裝置後（換句話說，在 DAA 過程完成後）並在 i3c_master_controller_ops->bus_init() 中例項化這些裝置後呼叫此方法。如果主站確認了熱插拔請求並將動態地址分配給加入匯流排的裝置，也應呼叫此方法。

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

成功時返回 0，如果錯誤是官方 Mx 錯誤程式碼之一，則返回正 I3C 錯誤程式碼，否則返回負錯誤程式碼。

int i3c_master_do_daa(struct i3c_master_controller *master)¶: 執行 DAA (動態地址分配)

引數

struct i3c_master_controller *master: 執行 DAA 的主站

描述

此函式例項化 I3C 裝置物件，並將其新增到 I3C 裝置列表中。所有裝置資訊都使用標準 CCC 命令自動檢索。

如果主站想要使用 i3c_dev_set_master_data() 將私有資料附加到該物件，則返回 I3C 裝置物件。

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

成功時返回 0，否則返回負錯誤程式碼。

int i3c_master_set_info(struct i3c_master_controller *master, const struct i3c_device_info *info)¶: 設定主裝置資訊

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站
const struct i3c_device_info *info: I3C 裝置資訊

描述

設定主裝置資訊。應從 i3c_master_controller_ops->bus_init() 呼叫此方法。

並非所有 i3c_device_info 欄位對於主裝置都有意義。以下是應正確填充的欄位列表

i3c_device_info->dyn_addr
i3c_device_info->bcr
i3c_device_info->dcr
i3c_device_info->pid
如果 i3c_device_info->bcr 中設定了 I3C_BCR_HDR_CAP 位，則設定 i3c_device_info->hdr_cap

必須在維護模式下保持匯流排鎖定的情況下呼叫此函式。

返回值

如果 info 包含有效資訊（並非所有資訊都可以檢查，但我們至少可以確保 info->dyn_addr 和 info->bcr 正確），則返回 0，否則返回 -EINVAL。

int i3c_master_bus_init(struct i3c_master_controller *master)¶: 初始化 I3C 匯流排

引數

struct i3c_master_controller *master: 初始化匯流排的主主站

描述

此函式遵循 I3C 規範中描述的所有初始化步驟

將 I2C 裝置附加到主站，以便主站可以適當地填充其內部裝置表
呼叫 i3c_master_controller_ops->bus_init() 方法以初始化主控制器。通常在那裡選擇匯流排模式（純匯流排或快速/慢速混合匯流排）
指示總線上的所有裝置都放棄其動態地址。當匯流排先前由其他人配置時（例如，引導載入程式），這一點尤其重要
停用所有從機事件。
為具有 init_dyn_addr 的 I3C 裝置保留地址槽。並且，如果裝置還具有 static_addr，則嘗試預先分配 FW 請求的動態地址 (使用 SETDASA)，並將相應的靜態定義的 I3C 裝置附加到主站。
執行 DAA (動態地址分配) 以將動態地址分配給所有剩餘的 I3C 裝置

完成後，所有 I3C 和 I2C 裝置都應該可用。

返回值

成功時返回 0，否則返回負錯誤程式碼。

int i3c_master_add_i3c_dev_locked(struct i3c_master_controller *master, u8 addr)¶: 將 I3C 從機新增到匯流排

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站
u8 addr: 分配給裝置的 I3C 從機動態地址

描述

此函式例項化 I3C 裝置物件，並將其新增到 I3C 裝置列表中。所有裝置資訊都使用標準 CCC 命令自動檢索。

如果主站想要使用 i3c_dev_set_master_data() 將私有資料附加到該物件，則返回 I3C 裝置物件。

必須在以寫入模式保持匯流排鎖定的情況下呼叫此函式。

返回值

成功時返回 0，否則返回負錯誤程式碼。

void i3c_master_queue_ibi(struct i3c_dev_desc *dev, struct i3c_ibi_slot *slot)¶: 將 IBI 排隊

引數

struct i3c_dev_desc *dev: 此 IBI 來自的裝置
struct i3c_ibi_slot *slot: 用於儲存有效負載的 IBI 槽

描述

將 IBI 排隊到控制器工作佇列。連線到 dev 的 IBI 處理程式將從工作佇列上下文中呼叫。

void i3c_generic_ibi_free_pool(struct i3c_generic_ibi_pool *pool)¶: 釋放通用 IBI 池

引數

struct i3c_generic_ibi_pool *pool: 要釋放的 IBI 池

描述

釋放通用 IBI 池分配的所有 IBI 槽。

struct i3c_generic_ibi_pool *i3c_generic_ibi_alloc_pool(struct i3c_dev_desc *dev, const struct i3c_ibi_setup *req)¶: 建立通用 IBI 池

引數

struct i3c_dev_desc *dev: 此池將用於的裝置
const struct i3c_ibi_setup *req: IBI 設定請求，描述裝置驅動程式的期望

描述

基於 req 中提供的資訊建立通用 IBI 池。

返回值

成功時返回有效的 IBI 池，否則返回 ERR_PTR()。

struct i3c_ibi_slot *i3c_generic_ibi_get_free_slot(struct i3c_generic_ibi_pool *pool)¶: 從通用 IBI 池中獲取空閒槽

引數

struct i3c_generic_ibi_pool *pool: 要在其上查詢 IBI 槽的池

描述

在通用 IBI 池中搜索空閒槽。在不再需要該槽時，應使用 i3c_generic_ibi_recycle_slot() 將該槽返回到池中。

返回值

指向空閒槽的指標，如果沒有空閒槽可用，則返回 NULL。

void i3c_generic_ibi_recycle_slot(struct i3c_generic_ibi_pool *pool, struct i3c_ibi_slot *s)¶: 將槽返回到通用 IBI 池

引數

struct i3c_generic_ibi_pool *pool: 要將 IBI 槽返回到的池
struct i3c_ibi_slot *s: 要回收的 IBI 槽

描述

將 IBI 槽添加回其通用 IBI 池。應從主驅動程式 struct_master_controller_ops->recycle_ibi() 方法呼叫。

int i3c_master_register(struct i3c_master_controller *master, struct device *parent, const struct i3c_master_controller_ops *ops, bool secondary)¶: 註冊 I3C 主站

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站
struct device *parent: 父裝置（提供此 I3C 主控制器的裝置）
const struct i3c_master_controller_ops *ops: 主控制器操作
bool secondary: 如果要註冊輔助主站，則為 true。如果設定為 true，將返回 -ENOTSUPP，因為尚不支援輔助主站

描述

此函式會為您處理所有事情

建立並初始化 I3C 匯流排
如果 parent->of_node 不為 NULL，則使用靜態 I2C 裝置填充匯流排
註冊控制器在匯流排初始化期間新增的所有 I3C 裝置
註冊 I2C 介面卡和所有 I2C 裝置

返回值

成功時返回 0，否則返回負錯誤程式碼。

void i3c_master_unregister(struct i3c_master_controller *master)¶: 登出 I3C 主站

引數

struct i3c_master_controller *master: 用於在總線上傳送幀的主站

描述

基本上撤消 i3c_master_register() 中所做的一切。

struct i3c_i2c_dev_desc¶: I3C/I2C 裝置描述符的公共部分

定義:

struct i3c_i2c_dev_desc {
    struct list_head node;
    struct i3c_master_controller *master;
    void *master_priv;
};

成員

node: 用於將槽插入 I2C 或 I3C 裝置列表的節點元素
master: 例項化此裝置的 I3C 主站。將用於執行 I2C/I3C 傳輸
master_priv: 分配給裝置的主站私有資料。可用於新增主站特定資訊

描述

此結構描述了公共 I3C/I2C 裝置資訊。

struct i2c_dev_boardinfo¶: I2C 裝置板資訊

定義:

struct i2c_dev_boardinfo {
    struct list_head node;
    struct i2c_board_info base;
    u8 lvr;
};

成員

node: 用於將 boardinfo 物件插入 I2C boardinfo 列表
base: 常規 I2C 板資訊
lvr: I3C 核心需要 LVR (舊版虛擬暫存器) 來了解 I2C 裝置的限制

描述

此結構用於將板級資訊附加到 I2C 裝置。連線在 I3C 總線上的每個 I2C 裝置都應具有一個。

struct i2c_dev_desc¶: I2C 裝置描述符

定義:

struct i2c_dev_desc {
    struct i3c_i2c_dev_desc common;
    struct i2c_client *dev;
    u16 addr;
    u8 lvr;
};

成員

common: I2C 裝置描述符的公共部分
dev: 註冊到 I2C 框架的 I2C 裝置物件
addr: I2C 裝置地址
lvr: I3C 核心需要 LVR (舊版虛擬暫存器) 來了解 I2C 裝置的限制

描述

連線在總線上的每個 I2C 裝置都將具有 i2c_dev_desc。此物件由核心建立，稍後使用 struct_i3c_master_controller->ops->attach_i2c_dev() 連線到控制器。

struct_i2c_dev_desc 是連線在 I3C 總線上的 I2C 裝置的內部表示。此物件也會傳遞到所有 struct_i3c_master_controller_ops 掛鉤。

struct i3c_ibi_slot¶: I3C IBI (帶內中斷) 槽

定義:

struct i3c_ibi_slot {
    struct work_struct work;
    struct i3c_dev_desc *dev;
    unsigned int len;
    void *data;
};

成員

work: 與此槽關聯的工作。 IBI 處理程式將從那裡呼叫
dev: 生成此 IBI 的 I3C 裝置
len: 與此 IBI 關聯的有效負載的長度
data: 有效負載緩衝區

描述

IBI 槽是由控制器預分配的物件，並在 IBI 進入時使用。每次 IBI 進入時，I3C 主驅動程式應在其 IBI 槽池中找到一個空閒 IBI 槽，檢索 IBI 有效負載，並使用 i3c_master_queue_ibi() 將 IBI 排隊。

IBI 槽的分配方式留給 I3C 主驅動程式處理，但是，對於簡單的基於 kmalloc 的分配，可以使用通用 IBI 槽池。

struct i3c_device_ibi_info¶: 附加到特定裝置的 IBI 資訊

定義:

struct i3c_device_ibi_info {
    struct completion all_ibis_handled;
    atomic_t pending_ibis;
    unsigned int max_payload_len;
    unsigned int num_slots;
    unsigned int enabled;
    struct workqueue_struct *wq;
    void (*handler)(struct i3c_device *dev, const struct i3c_ibi_payload *payload);
};

成員

all_ibis_handled: 用於在沒有更多 IBI 等待處理時通知。 i3c_device_disable_ibi() 使用此功能來等待所有 IBI 出隊
pending_ibis: 計算掛起的 IBI 的數量。每個掛起的 IBI 都將其工作元素排隊到控制器工作佇列
max_payload_len: 來自此 IBI 的 IBI 的最大有效負載長度。在呼叫 i3c_device_request_ibi() 時指定此值，並且不應在執行時更改。主站應拒絕所有超過此限制的訊息 IBI
num_slots: 為此裝置保留的 IBI 槽的數量
enabled: 反映 IBI 狀態
wq: 用於執行 IBI 處理程式的工作佇列。
handler: 在 i3c_device_request_ibi() 呼叫時指定的 IBI 處理程式。此處理程式將從控制器工作佇列呼叫，因此允許休眠（儘管建議儘可能快地處理 IBI，以避免阻止在同一工作佇列上排隊的其他 IBI 的處理）。可以從 IBI 處理程式傳送新的 I3C 訊息

描述

在呼叫 i3c_device_request_ibi() 並附加到特定裝置時，會分配 struct_i3c_device_ibi_info 物件。此物件用於管理來自特定 I3C 裝置的 IBI。

請注意，此結構是 IBI 管理基礎結構的通用檢視。 I3C 主驅動程式可能具有自己的內部表示，可以使用控制器私有資料將其與裝置關聯。

struct i3c_dev_boardinfo¶: I3C 裝置板資訊

定義:

struct i3c_dev_boardinfo {
    struct list_head node;
    u8 init_dyn_addr;
    u8 static_addr;
    u64 pid;
    struct device_node *of_node;
};

成員

node: 用於將 boardinfo 物件插入 I3C boardinfo 列表
init_dyn_addr: FW 請求的初始動態地址。我們不保證裝置最終將使用此地址，但會盡力將此特定地址分配給裝置
static_addr: I3C 裝置在主站為其分配動態地址之前偵聽的靜態地址。將在匯流排初始化期間使用此地址為其分配特定動態地址，然後再啟動 DAA (動態地址分配)
pid: 裝置暴露的 I3C Provisioned ID。當裝置沒有靜態地址時，這可以用作將 boardinfo 附加到 i3c_dev_desc 的唯一識別符號。
of_node: 可選的 DT 節點，以防裝置已在 DT 中描述。

描述

此結構用於將板級資訊附加到 I3C 裝置。並非總線上連線的所有 I3C 裝置都有 boardinfo。只有當您想將額外的資源附加到裝置或為其分配特定的動態地址時才需要。

struct i3c_dev_desc¶: I3C 裝置描述符

定義:

struct i3c_dev_desc {
    struct i3c_i2c_dev_desc common;
    struct i3c_device_info info;
    struct mutex ibi_lock;
    struct i3c_device_ibi_info *ibi;
    struct i3c_device *dev;
    const struct i3c_dev_boardinfo *boardinfo;
};

成員

common: I3C 裝置描述符的公共部分
info: I3C 裝置資訊。當您使用 i3c_master_add_i3c_dev_locked() 建立裝置時，將自動填充。
ibi_lock: 用於保護 struct_i3c_device->ibi 的鎖
ibi: 附加到裝置的 IBI 資訊。在呼叫 i3c_device_request_ibi() 之前應為 NULL
dev: 指向暴露給 I3C 裝置驅動程式的 I3C 裝置物件的指標。永遠不應從 I3C 主控制器驅動程式訪問此物件。只有核心程式碼應在更新 dev <-> desc 連結或將 IBI 事件傳播到驅動程式時操作它。
boardinfo: 指向附加到此 I3C 裝置的 boardinfo 的指標

描述

I3C 裝置的內部表示。此物件僅由核心使用，並在請求對裝置執行某些操作時傳遞給 I3C 主控制器驅動程式。核心維護內部 I3C 裝置描述符和暴露給 I3C 裝置驅動程式的物件 (struct_i3c_device) 之間的連結。

struct i3c_device¶: I3C 裝置物件

定義:

struct i3c_device {
    struct device dev;
    struct i3c_dev_desc *desc;
    struct i3c_bus *bus;
};

成員

dev: 用於將 I3C 設備註冊到裝置模型的裝置物件
desc: 指向 i3c 裝置描述符物件的指標。每次使用分配的不同動態地址重新發現 I3C 裝置時，都會更新此連結。
bus: 此裝置連線到的 I3C 匯流排

描述

暴露給 I3C 裝置驅動程式的 I3C 裝置物件。負責將此物件連結到相關的 struct_i3c_dev_desc 物件。I3C 總線上的所有 I3C 裝置都已表示，包括 I3C 主裝置。對於每個裝置，我們都有一個 struct i3c_device 的例項。

enum i3c_bus_mode¶: I3C 匯流排模式

常量

I3C_BUS_MODE_PURE: 只有 I3C 裝置連線到匯流排。沒有預期限制。
I3C_BUS_MODE_MIXED_FAST: 總線上存在帶有 50ns 尖峰濾波器的 I2C 裝置。此模式下的唯一影響是高 SCL 脈衝必須保持在 50ns 以下，才能在傳輸 I3C 幀時欺騙 I2C 裝置。
I3C_BUS_MODE_MIXED_LIMITED: 總線上存在沒有 50ns 尖峰濾波器的 I2C 裝置。但是，它們允許符合高達最大 SDR SCL 時鐘頻率的要求。
I3C_BUS_MODE_MIXED_SLOW: 總線上存在沒有 50ns 尖峰濾波器的 I2C 裝置。

enum i3c_open_drain_speed¶: I3C 開漏速度

常量

I3C_OPEN_DRAIN_SLOW_SPEED: 用於傳送第一個廣播地址的慢速開漏速度。此速度下的第一個廣播地址對 I3C 總線上的所有裝置可見。以 I2C 模式工作的 I3C 裝置將在切換到 I3C 模式時關閉其尖峰濾波器。
I3C_OPEN_DRAIN_NORMAL_SPEED: I3C 匯流排模式下的正常開漏速度。

enum i3c_addr_slot_status¶: I3C 地址槽狀態

常量

I3C_ADDR_SLOT_FREE: 地址空閒
I3C_ADDR_SLOT_RSVD: 地址已保留
I3C_ADDR_SLOT_I2C_DEV: 地址已分配給 I2C 裝置
I3C_ADDR_SLOT_I3C_DEV: 地址已分配給 I3C 裝置
I3C_ADDR_SLOT_STATUS_MASK: 地址槽掩碼
I3C_ADDR_SLOT_EXT_STATUS_MASK: 帶有擴充套件資訊的地址槽掩碼
I3C_ADDR_SLOT_EXT_DESIRED: 該位掩碼錶示某些裝置首選的地址，例如裝置樹源中的“assigned-address”屬性。在 I3C 總線上，地址是動態分配的，我們需要知道哪些地址可以自由使用，哪些地址已經被分配。

描述

標記為保留的地址是 I3C 協議保留的地址（廣播地址等）。

struct i3c_bus¶: I3C 匯流排物件

定義:

struct i3c_bus {
    struct i3c_dev_desc *cur_master;
    int id;
    unsigned long addrslots[((I2C_MAX_ADDR + 1) * I3C_ADDR_SLOT_STATUS_BITS) / BITS_PER_LONG];
    enum i3c_bus_mode mode;
    struct {
        unsigned long i3c;
        unsigned long i2c;
    } scl_rate;
    struct {
        struct list_head i3c;
        struct list_head i2c;
    } devs;
    struct rw_semaphore lock;
};

成員

cur_master: 當前驅動匯流排的 I3C 主裝置。由於 I3C 是多主裝置，因此這可能會隨時間變化。將用於讓主裝置知道是否需要在傳送幀之前請求匯流排所有權。
id: 匯流排 ID。由框架在註冊匯流排時分配。
addrslots: 一個位圖，每個插槽 2 位，用於編碼地址狀態並簡化 DAA（動態地址分配）過程（參見 enum i3c_addr_slot_status）。
mode: 匯流排模式（參見 enum i3c_bus_mode）。
scl_rate: I3C 和 I2C 模式下的 SCL 訊號速率
scl_rate.i3c: 執行 I3C SDR/私有傳輸時時鐘訊號的最大速率
scl_rate.i2c: 執行 I2C 傳輸時時鐘訊號的最大速率
devs: 2 個列表，其中包含連線到匯流排的所有 I3C/I2C 裝置
devs.i3c: 包含 I3C 裝置描述符列表，這些描述符表示連線到匯流排併成功附加到 I3C 主裝置的 I3C 裝置
devs.i2c: 包含 I2C 裝置描述符列表，這些描述符表示連線到匯流排併成功附加到 I3C 主裝置的 I2C 裝置
lock: 總線上的讀/寫鎖。這是為了防止對整個匯流排及其連線的裝置產生影響的操作。例如，當要求從裝置放棄其動態地址 (RSTDAA CCC) 時，我們需要確保沒有人嘗試向這些裝置傳送 I3C 幀。請注意，此鎖不能防止裝置之間的併發：多個驅動程式可以並行透過同一個主裝置傳送不同的 I3C/I2C 幀。主裝置有責任保證幀實際上是按順序傳送而不是交錯傳送的。

描述

I3C 匯流排用其自身的物件表示，而不是由 I3C 主裝置隱式描述，以處理多主裝置功能，其中一個匯流排可以在多個主裝置之間共享，每個主裝置在需要時請求匯流排所有權。

struct i3c_master_controller_ops¶: I3C 主裝置方法

定義:

struct i3c_master_controller_ops {
    int (*bus_init)(struct i3c_master_controller *master);
    void (*bus_cleanup)(struct i3c_master_controller *master);
    int (*attach_i3c_dev)(struct i3c_dev_desc *dev);
    int (*reattach_i3c_dev)(struct i3c_dev_desc *dev, u8 old_dyn_addr);
    void (*detach_i3c_dev)(struct i3c_dev_desc *dev);
    int (*do_daa)(struct i3c_master_controller *master);
    bool (*supports_ccc_cmd)(struct i3c_master_controller *master, const struct i3c_ccc_cmd *cmd);
    int (*send_ccc_cmd)(struct i3c_master_controller *master, struct i3c_ccc_cmd *cmd);
    int (*priv_xfers)(struct i3c_dev_desc *dev,struct i3c_priv_xfer *xfers, int nxfers);
    int (*attach_i2c_dev)(struct i2c_dev_desc *dev);
    void (*detach_i2c_dev)(struct i2c_dev_desc *dev);
    int (*i2c_xfers)(struct i2c_dev_desc *dev, struct i2c_msg *xfers, int nxfers);
    int (*request_ibi)(struct i3c_dev_desc *dev, const struct i3c_ibi_setup *req);
    void (*free_ibi)(struct i3c_dev_desc *dev);
    int (*enable_ibi)(struct i3c_dev_desc *dev);
    int (*disable_ibi)(struct i3c_dev_desc *dev);
    void (*recycle_ibi_slot)(struct i3c_dev_desc *dev, struct i3c_ibi_slot *slot);
    int (*enable_hotjoin)(struct i3c_master_controller *master);
    int (*disable_hotjoin)(struct i3c_master_controller *master);
    int (*set_speed)(struct i3c_master_controller *master, enum i3c_open_drain_speed speed);
};

成員

bus_init: 負責 I3C 匯流排初始化的鉤子。您至少應該從那裡呼叫 master_set_info() 並設定匯流排模式。您也可以將控制器特定的初始化放在那裡。此方法是必需的。
bus_cleanup: 清理在 i3c_master_controller_ops->bus_init() 中完成的所有操作。此方法是可選的。
attach_i3c_dev: 每次將 I3C 裝置連線到匯流排時呼叫。它可以在 DAA 之後，也可以在裝置由韌體靜態宣告時呼叫，在這種情況下，它將只有靜態地址，動態地址將為 0。呼叫此函式時，尚未檢索裝置資訊。這是將主控制器特定資料附加到 I3C 裝置的好地方。此方法是可選的。
reattach_i3c_dev: 每次 I3C 裝置的地址更改時呼叫。可能是因為裝置已斷電並丟失了其地址，或者當裝置具有靜態地址並且已使用 SETDASA 分配了動態地址時發生。此方法是可選的。
detach_i3c_dev: 當 I3C 裝置從匯流排分離時呼叫。通常在登出主裝置時發生。此方法是可選的。
do_daa: 執行 DAA（動態地址分配）過程。此過程應傳送 ENTDAA CCC 命令，然後使用 i3c_master_add_i3c_dev_locked() 新增 DAA 發現的所有裝置。使用 i3c_master_add_i3c_dev_locked() 新增的裝置隨後將連線或重新連線到控制器。此方法是必需的。
supports_ccc_cmd: 如果支援 CCC 命令，則應返回 true，否則返回 false。此方法是可選的，如果未提供，則核心假定支援所有 CCC 命令。
send_ccc_cmd: 傳送 CCC 命令。此方法是必需的。
priv_xfers: 執行一個或多個私有 I3C SDR 傳輸。此方法是必需的。
attach_i2c_dev: 每次將 I2C 裝置連線到匯流排時呼叫。這是將主控制器特定資料附加到 I2C 裝置的好地方。此方法是可選的。
detach_i2c_dev: 當 I2C 裝置從匯流排分離時呼叫。通常在登出主裝置時發生。此方法是可選的。
i2c_xfers: 執行一個或多個 I2C 傳輸。請注意，與 i3c 傳輸不同，核心不保證附加到傳輸的緩衝區是 DMA 安全的。如果驅動程式想要具有 DMA 安全緩衝區，則應使用 I2C 框架提供的 i2c_get_dma_safe_msg_buf() 和 i2c_put_dma_safe_msg_buf() 輔助函式。此方法是必需的。
request_ibi: 將 IBI 處理程式附加到 I3C 裝置。這意味著定義 IBI 處理程式和 IBI 的約束（最大有效負載長度和預分配槽的數量）。某些控制器支援的具有 IBI 功能的裝置少於常規裝置，因此如果沒有更多空間用於額外的 IBI 註冊，則此方法可能會返回 -EBUSY。此方法是可選的。
free_ibi: 釋放先前使用 ->request_ibi() 請求的 IBI。IBI 應該在使用 ->disable_irq() 停用的情況下進行。僅當 ->request_ibi 不為 NULL 時，此方法才是必需的。
enable_ibi: 啟用 IBI。僅當先前已呼叫 ->request_ibi() 時，->enable_ibi() 才有效。控制器應首先在控制器端啟用 IBI（例如，取消遮蔽硬體 IRQ），然後將 ENEC CCC 命令（設定了 IBI 標誌）傳送到 I3C 裝置。僅當 ->request_ibi 不為 NULL 時，此方法才是必需的。
disable_ibi: 停用 IBI。首先發送帶有 IBI 標誌的 DISEC CCC 命令，然後在控制器端停用硬體 IRQ。僅當 ->request_ibi 不為 NULL 時，此方法才是必需的。
recycle_ibi_slot: 回收 IBI 插槽。每次 IBI 由其處理程式處理時呼叫。IBI 插槽應放回 IBI 插槽池中，以便控制器可以將其重新用於將來的 IBI。僅當 ->request_ibi 不為 NULL 時，此方法才是必需的。
enable_hotjoin: 啟用熱插拔事件檢測。
disable_hotjoin: 停用熱插拔事件檢測。
set_speed: 調整 I3C 開漏模式時序。

struct i3c_master_controller¶: I3C 主控制器物件

定義:

struct i3c_master_controller {
    struct device dev;
    struct i3c_dev_desc *this;
    struct i2c_adapter i2c;
    const struct i3c_master_controller_ops *ops;
    unsigned int secondary : 1;
    unsigned int init_done : 1;
    unsigned int hotjoin: 1;
    struct {
        struct list_head i3c;
        struct list_head i2c;
    } boardinfo;
    struct i3c_bus bus;
    struct workqueue_struct *wq;
};

成員

dev: 要註冊到裝置模型的裝置
this: 表示此主裝置的 I3C 裝置物件。此裝置將新增到總線上可用的 I3C 裝置列表中。
i2c: 用於向後相容的 I2C 介面卡。此介面卡已註冊到 I2C 子系統，以便儘可能透明地處理現有的 I2C 驅動程式。
ops: 主裝置操作。參見 struct i3c_master_controller_ops。
secondary: 如果主裝置是輔助主裝置，則為 true。
init_done: 匯流排初始化完成時為 true。
hotjoin: 如果主裝置支援熱插拔，則為 true。
boardinfo: 附加到總線上連線的裝置的板級資訊
boardinfo.i3c: I3C boardinfo 物件列表
boardinfo.i2c: I2C boardinfo 物件列表
bus: 此主裝置暴露的 I3C 匯流排
wq: 工作佇列，如果主驅動程式需要推遲需要線上程上下文中發生的操作，則可以使用該佇列。典型的例子是熱插拔處理，它需要在維護中獲取匯流排鎖，而這隻能從可睡眠的上下文中完成。

描述

必須透過 i3c_master_register() 將 struct i3c_master_controller 註冊到 I3C 子系統。不應手動設定 struct i3c_master_controller 的任何欄位，只需將適當的值傳遞給 i3c_master_register()。

i3c_bus_for_each_i2cdev¶

i3c_bus_for_each_i2cdev (bus, dev)

迭代總線上存在的所有 I2C 裝置

引數

bus: I3C 匯流排
dev: 一個 I2C 裝置描述符指標，更新為指向迴圈的每次迭代中的當前插槽

描述

迭代總線上存在的所有 I2C 裝置。

i3c_bus_for_each_i3cdev¶

i3c_bus_for_each_i3cdev (bus, dev)

迭代總線上存在的所有 I3C 裝置

引數

bus: I3C 匯流排
dev: 一個 I3C 裝置描述符指標，更新為指向迴圈的每次迭代中的當前插槽

描述

迭代總線上存在的所有 I3C 裝置。

void *i3c_dev_get_master_data(const struct i3c_dev_desc *dev)¶: 獲取附加到 I3C 裝置描述符的主裝置私有資料

引數

const struct i3c_dev_desc *dev: 從中獲取私有資料的 I3C 裝置描述符

返回值

先前使用 i3c_dev_set_master_data() 附加的私有資料: 如果沒有任何資料附加到裝置，則為 NULL。

void i3c_dev_set_master_data(struct i3c_dev_desc *dev, void *data)¶: 將主裝置私有資料附加到 I3C 裝置描述符

引數

struct i3c_dev_desc *dev: 要將私有資料附加到的 I3C 裝置描述符
void *data: 私有資料

描述

此函式允許主控制器附加每個裝置的私有資料，然後可以使用 i3c_dev_get_master_data() 檢索該資料。

void *i2c_dev_get_master_data(const struct i2c_dev_desc *dev)¶: 獲取附加到 I2C 裝置描述符的主裝置私有資料

引數

const struct i2c_dev_desc *dev: 從中獲取私有資料的 I2C 裝置描述符

返回值

先前使用 i2c_dev_set_master_data() 附加的私有資料: 如果沒有任何資料附加到裝置，則為 NULL。

void i2c_dev_set_master_data(struct i2c_dev_desc *dev, void *data)¶: 將主裝置私有資料附加到 I2C 裝置描述符

引數

struct i2c_dev_desc *dev: 要將私有資料附加到的 I2C 裝置描述符
void *data: 私有資料

描述

此函式允許主控制器附加每個裝置的私有資料，然後可以使用 i2c_device_get_master_data() 檢索該資料。

struct i3c_master_controller *i3c_dev_get_master(struct i3c_dev_desc *dev)¶: 獲取用於與裝置通訊的主裝置

引數

struct i3c_dev_desc *dev: I3C 裝置

返回值

驅動 dev 的主控制器

struct i3c_master_controller *i2c_dev_get_master(struct i2c_dev_desc *dev)¶: 獲取用於與裝置通訊的主裝置

引數

struct i2c_dev_desc *dev: I2C 裝置

返回值

驅動 dev 的主控制器

struct i3c_bus *i3c_master_get_bus(struct i3c_master_controller *master)¶: 獲取附加到主裝置的匯流排

引數

struct i3c_master_controller *master: 主裝置物件

返回值

master 連線到的 I3C 匯流排

Linux 核心

目錄

此頁面

I3C 主控制器驅動 API¶