I²C 和 SMBus 子系統¶

I²C（或者沒有花哨的排版，“I2C”）是“Inter-IC”匯流排的首字母縮寫，這是一種簡單的匯流排協議，廣泛用於低資料速率通訊足夠的情況。由於它也是一個獲得許可的商標，因此一些供應商對同一匯流排使用另一個名稱（例如“雙線介面”，TWI）。 I2C 只需要兩個訊號（SCL 用於時鐘，SDA 用於資料），從而節省了電路板空間並最大限度地減少了訊號質量問題。大多數 I2C 裝置使用七位地址，匯流排速度高達 400 kHz；還有一個高速擴充套件（3.4 MHz），但尚未得到廣泛應用。 I2C 是一種多主機匯流排；開漏訊號用於在主機之間進行仲裁，以及握手和同步來自較慢客戶端的時鐘。

Linux I2C 程式設計介面支援匯流排互動的主機端和從機端。程式設計介面圍繞兩種驅動程式和兩種裝置構建。 I2C“介面卡驅動程式”抽象了控制器硬體；它繫結到物理裝置（可能是 PCI 裝置或 platform_device），並公開一個 struct i2c_adapter，表示它管理的每個 I2C 匯流排段。每個 I2C 匯流排段上都有一個 struct i2c_client 表示的 I2C 裝置。這些裝置將繫結到 struct i2c_driver，它應遵循標準的 Linux 驅動程式模型。有一些函式可以執行各種 I2C 協議操作；在撰寫本文時，所有此類函式只能從任務上下文中使用。

系統管理匯流排 (SMBus) 是一種同級協議。大多數 SMBus 系統也符合 I2C 標準。 SMBus 的電氣約束更嚴格，並且它標準化了特定的協議訊息和習慣用法。支援 I2C 的控制器也可以支援大多數 SMBus 操作，但 SMBus 控制器不支援 I2C 控制器支援的所有協議選項。有一些函式可以執行各種 SMBus 協議操作，或者使用 I2C 原語，或者向不支援這些 I2C 操作的 i2c_adapter 裝置發出 SMBus 命令。

int i2c_master_recv(const struct i2c_client *client, char *buf, int count)¶: 以主機接收模式發出單個 I2C 訊息

引數

const struct i2c_client *client: 從機裝置的控制代碼
char *buf: 在何處儲存從從機讀取的資料
int count: 要讀取的位元組數，必須小於 64k，因為 msg.len 是 u16

描述

返回負 errno，否則返回讀取的位元組數。

int i2c_master_recv_dmasafe(const struct i2c_client *client, char *buf, int count)¶: 使用 DMA 安全緩衝區以主機接收模式發出單個 I2C 訊息

引數

const struct i2c_client *client: 從機裝置的控制代碼
char *buf: 在何處儲存從從機讀取的資料，必須可以安全地與 DMA 一起使用
int count: 要讀取的位元組數，必須小於 64k，因為 msg.len 是 u16

描述

返回負 errno，否則返回讀取的位元組數。

int i2c_master_send(const struct i2c_client *client, const char *buf, int count)¶: 以主機發送模式發出單個 I2C 訊息

引數

const struct i2c_client *client: 從機裝置的控制代碼
const char *buf: 將寫入從機的資料
int count: 要寫入的位元組數，必須小於 64k，因為 msg.len 是 u16

描述

返回負 errno，否則返回寫入的位元組數。

int i2c_master_send_dmasafe(const struct i2c_client *client, const char *buf, int count)¶: 使用 DMA 安全緩衝區以主機發送模式發出單個 I2C 訊息

引數

const struct i2c_client *client: 從機裝置的控制代碼
const char *buf: 將寫入從機的資料，必須可以安全地與 DMA 一起使用
int count: 要寫入的位元組數，必須小於 64k，因為 msg.len 是 u16

描述

返回負 errno，否則返回寫入的位元組數。

struct i2c_device_identity¶: i2c 客戶端裝置標識

定義:

struct i2c_device_identity {
    u16 manufacturer_id;
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS                0;
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_1              1;
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_2              2;
#define I2C_DEVICE_ID_NXP_SEMICONDUCTORS_3              3;
#define I2C_DEVICE_ID_RAMTRON_INTERNATIONAL             4;
#define I2C_DEVICE_ID_ANALOG_DEVICES                    5;
#define I2C_DEVICE_ID_STMICROELECTRONICS                6;
#define I2C_DEVICE_ID_ON_SEMICONDUCTOR                  7;
#define I2C_DEVICE_ID_SPRINTEK_CORPORATION              8;
#define I2C_DEVICE_ID_ESPROS_PHOTONICS_AG               9;
#define I2C_DEVICE_ID_FUJITSU_SEMICONDUCTOR            10;
#define I2C_DEVICE_ID_FLIR                             11;
#define I2C_DEVICE_ID_O2MICRO                          12;
#define I2C_DEVICE_ID_ATMEL                            13;
#define I2C_DEVICE_ID_NONE                         0xffff;
    u16 part_id;
    u8 die_revision;
};

成員

manufacturer_id: 0 - 4095，資料庫由 NXP 維護
part_id: 0 - 511，根據製造商
die_revision: 0 - 7，根據製造商

enum i2c_driver_flags¶: I2C 裝置驅動程式的標誌

常量

I2C_DRV_ACPI_WAIVE_D0_PROBE: 不要將裝置置於 D0 狀態以進行探測

struct i2c_driver¶: 表示 I2C 裝置驅動程式

定義:

struct i2c_driver {
    unsigned int class;
    int (*probe)(struct i2c_client *client);
    void (*remove)(struct i2c_client *client);
    void (*shutdown)(struct i2c_client *client);
    void (*alert)(struct i2c_client *client, enum i2c_alert_protocol protocol, unsigned int data);
    int (*command)(struct i2c_client *client, unsigned int cmd, void *arg);
    struct device_driver driver;
    const struct i2c_device_id *id_table;
    int (*detect)(struct i2c_client *client, struct i2c_board_info *info);
    const unsigned short *address_list;
    struct list_head clients;
    u32 flags;
};

成員

類: 我們例項化哪種 i2c 裝置（用於檢測）
probe: 用於裝置繫結的回撥
remove: 用於裝置取消繫結的回撥
shutdown: 用於裝置關閉的回撥
alert: 警報回撥，例如用於 SMBus 警報協議
command: 用於匯流排範圍訊號的回撥（可選）
driver: 裝置驅動程式模型驅動程式
id_table: 此驅動程式支援的 I2C 裝置列表
detect: 用於裝置檢測的回撥
address_list: 要探測的 I2C 地址（用於檢測）
clients: 我們建立的檢測到的客戶端列表（僅供 i2c-core 使用）
flags: 在 enum i2c_driver_flags 中定義的標誌的位掩碼

描述

driver.owner 欄位應設定為此驅動程式的模組所有者。 driver.name 欄位應設定為此驅動程式的名稱。

對於自動裝置檢測，必須定義 detect 和 address_list。還應設定 class，否則只會建立使用模組引數強制的裝置。 detect 函式必須至少填寫它在成功檢測時傳遞的 i2c_board_info 結構的 name 欄位，並且可能還填寫 flags 欄位。

如果缺少 detect，則驅動程式對於列舉的裝置仍然可以正常工作。只是不會支援檢測到的裝置。這對於許多無法可靠檢測的 I2C/SMBus 裝置，以及實際上始終可以列舉的裝置來說是預期的。

傳遞給 detect 回撥的 i2c_client 結構不是真正的 i2c_client。它經過了足夠的初始化，以便您可以在其上呼叫 i2c_smbus_read_byte_data 及其朋友。不要用它做任何其他事情。特別是，不允許在其上呼叫 dev_dbg 及其朋友。

struct i2c_client¶: 表示 I2C 從機裝置

定義:

struct i2c_client {
    unsigned short flags;
#define I2C_CLIENT_PEC          0x04    ;
#define I2C_CLIENT_TEN          0x10    ;
#define I2C_CLIENT_SLAVE        0x20    ;
#define I2C_CLIENT_HOST_NOTIFY  0x40    ;
#define I2C_CLIENT_WAKE         0x80    ;
#define I2C_CLIENT_SCCB         0x9000  ;
    unsigned short addr;
    char name[I2C_NAME_SIZE];
    struct i2c_adapter *adapter;
    struct device dev;
    int init_irq;
    int irq;
    struct list_head detected;
#if IS_ENABLED(CONFIG_I2C_SLAVE);
    i2c_slave_cb_t slave_cb;
#endif;
    void *devres_group_id;
    struct dentry *debugfs;
};

成員

flags: 有關可能的標誌，請參閱 I2C_CLIENT_*
addr: 在連線到父介面卡的 I2C 總線上使用的地址。
name: 指示裝置的型別，通常是一個晶片名稱，它足夠通用，可以隱藏第二來源和相容的修訂版。
adapter: 管理託管此 I2C 裝置的匯流排段
dev: 從機的驅動程式模型裝置節點。
init_irq: 初始化時設定的 IRQ
irq: 指示由此裝置生成的 IRQ（如果有）
detected: i2c_driver.clients 列表或 i2c-core 的 userspace_devices 列表的成員
slave_cb: 當使用介面卡的 I2C 從機模式時，進行回撥。介面卡呼叫它以將從機事件傳遞給從機驅動程式。
devres_group_id: 將為此裝置探測時獲取的資源建立的 devres 組的 id。
debugfs: 指向 I2C 核心為此客戶端建立的 debugfs 子目錄的指標。

描述

i2c_client 標識連線到 i2c 匯流排的單個裝置（即晶片）。暴露給 Linux 的行為由管理該裝置的驅動程式定義。

struct i2c_board_info¶: 用於裝置建立的模板

定義:

struct i2c_board_info {
    char type[I2C_NAME_SIZE];
    unsigned short  flags;
    unsigned short  addr;
    const char      *dev_name;
    void *platform_data;
    struct fwnode_handle *fwnode;
    const struct software_node *swnode;
    const struct resource *resources;
    unsigned int    num_resources;
    int irq;
};

成員

type: 晶片型別，用於初始化 i2c_client.name
flags: 用於初始化 i2c_client.flags
addr: 儲存在 i2c_client.addr 中
dev_name: 如果設定，則覆蓋預設的 <busnr>-<addr> dev_name
platform_data: 儲存在 i2c_client.dev.platform_data 中
fwnode: 平臺韌體提供的裝置節點
swnode: 裝置的軟體節點
resources: 與裝置關聯的資源
num_resources: resources 陣列中的資源數
irq: 儲存在 i2c_client.irq 中

描述

I2C 實際上不支援硬體探測，儘管控制器和裝置可能能夠使用 I2C_SMBUS_QUICK 來判斷給定地址上是否存在裝置。驅動程式通常需要比這更多的資訊，例如晶片型別、配置、關聯的 IRQ 等。

i2c_board_info 用於構建列出存在的 I2C 裝置的資訊表。此資訊用於擴充套件驅動程式模型樹。對於主機板，這是使用 i2c_register_board_info() 靜態完成的；匯流排編號標識尚未可用的介面卡。對於附加板，i2c_new_client_device() 在介面卡已知的情況下動態地執行此操作。

I2C_BOARD_INFO¶

I2C_BOARD_INFO (dev_type, dev_addr)

用於列出 i2c 裝置及其地址的宏

引數

dev_type: 標識裝置型別
dev_addr: 裝置在總線上的地址。

描述

此宏初始化 struct i2c_board_info 的基本欄位，宣告在特定板上提供了什麼。可選欄位（例如關聯的 irq 或裝置特定的 platform_data）使用傳統的語法提供。

struct i2c_algorithm¶: 表示 I2C 傳輸方法

定義:

struct i2c_algorithm {
    union {
        int (*xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num);
        int (*master_xfer)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num);
    };
    union {
        int (*xfer_atomic)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num);
        int (*master_xfer_atomic)(struct i2c_adapter *adap, struct i2c_msg *msgs, int num);
    };
    int (*smbus_xfer)(struct i2c_adapter *adap, u16 addr,unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data);
    int (*smbus_xfer_atomic)(struct i2c_adapter *adap, u16 addr,unsigned short flags, char read_write, u8 command, int size, union i2c_smbus_data *data);
    u32 (*functionality)(struct i2c_adapter *adap);
#if IS_ENABLED(CONFIG_I2C_SLAVE);
    union {
        int (*reg_target)(struct i2c_client *client);
        int (*reg_slave)(struct i2c_client *client);
    };
    union {
        int (*unreg_target)(struct i2c_client *client);
        int (*unreg_slave)(struct i2c_client *client);
    };
#endif;
};

成員

{unnamed_union}: 匿名
xfer: 透過指定的介面卡傳輸由 msgs 陣列定義的給定數量的訊息。
master_xfer: 已棄用，請使用 xfer
{unnamed_union}: 匿名
xfer_atomic: 與 xfer 相同。但是，僅使用原子上下文，因此例如可以在關閉之前非常晚地訪問 PMIC。可選。
master_xfer_atomic: 已棄用，請使用 xfer_atomic
smbus_xfer: 向給定的 I2C 介面卡發出 SMBus 事務。如果不存在此項，則匯流排層將嘗試將 SMBus 呼叫轉換為 I2C 傳輸。
smbus_xfer_atomic: 與 smbus_xfer 相同。但是，僅使用原子上下文，因此例如可以在關閉之前非常晚地訪問 PMIC。可選。
functionality: 從 I2C_FUNC_* 標誌返回此演算法/介面卡對支援的標誌。
{unnamed_union}: 匿名
reg_target: 將給定的客戶端註冊到此介面卡的本地目標模式
reg_slave: 已棄用，請使用 reg_target
{unnamed_union}: 匿名
unreg_target: 從此介面卡的本地目標模式取消註冊給定的客戶端
unreg_slave: 已棄用，請使用 unreg_target

描述

i2c_algorithm 是硬體解決方案類別的介面，可以使用相同的匯流排演算法定址這些硬體解決方案類別 - 即位操作或 PCF8584，以命名兩個最常見的演算法。

來自 xfer{_atomic} 欄位的返回程式碼應指示傳輸期間發生的錯誤程式碼型別，如核心文件檔案 I2C/SMBUS 故障程式碼中所述。否則，應返回執行的訊息數。

struct i2c_lock_operations¶: 表示 I2C 鎖定操作

定義:

struct i2c_lock_operations {
    void (*lock_bus)(struct i2c_adapter *adapter, unsigned int flags);
    int (*trylock_bus)(struct i2c_adapter *adapter, unsigned int flags);
    void (*unlock_bus)(struct i2c_adapter *adapter, unsigned int flags);
};

成員

lock_bus: 獲取對 I2C 匯流排段的獨佔訪問許可權
trylock_bus: 嘗試獲取對 I2C 匯流排段的獨佔訪問權
unlock_bus: 釋放對 I2C 匯流排段的獨佔訪問權

描述

主要操作由 i2c_lock_bus 和 i2c_unlock_bus 包裝。

struct i2c_timings¶: I2C 時序資訊

定義:

struct i2c_timings {
    u32 bus_freq_hz;
    u32 scl_rise_ns;
    u32 scl_fall_ns;
    u32 scl_int_delay_ns;
    u32 sda_fall_ns;
    u32 sda_hold_ns;
    u32 digital_filter_width_ns;
    u32 analog_filter_cutoff_freq_hz;
};

成員

bus_freq_hz: 匯流排頻率，單位為 Hz
scl_rise_ns: SCL 訊號上升所需的時間，單位為 ns；I2C 規範中的 t(r)
scl_fall_ns: SCL 訊號下降所需的時間，單位為 ns；I2C 規範中的 t(f)
scl_int_delay_ns: IP 核額外需要的 SCL 建立時間，單位為 ns
sda_fall_ns: SDA 訊號下降所需的時間，單位為 ns；I2C 規範中的 t(f)
sda_hold_ns: IP 核額外需要的 SDA 保持時間，單位為 ns
digital_filter_width_ns: IP 核數字濾波器可以濾除的 I2C 線上尖峰的寬度，單位為 ns
analog_filter_cutoff_freq_hz: 低通 IP 核模擬濾波器的截止頻率

struct i2c_bus_recovery_info¶: I2C 匯流排恢復資訊

定義:

struct i2c_bus_recovery_info {
    int (*recover_bus)(struct i2c_adapter *adap);
    int (*get_scl)(struct i2c_adapter *adap);
    void (*set_scl)(struct i2c_adapter *adap, int val);
    int (*get_sda)(struct i2c_adapter *adap);
    void (*set_sda)(struct i2c_adapter *adap, int val);
    int (*get_bus_free)(struct i2c_adapter *adap);
    void (*prepare_recovery)(struct i2c_adapter *adap);
    void (*unprepare_recovery)(struct i2c_adapter *adap);
    struct gpio_desc *scl_gpiod;
    struct gpio_desc *sda_gpiod;
    struct pinctrl *pinctrl;
    struct pinctrl_state *pins_default;
    struct pinctrl_state *pins_gpio;
};

成員

recover_bus: 恢復例程。傳遞驅動程式的 recover_bus() 例程或 i2c_generic_scl_recovery()。
get_scl: 獲取 SCL 線路的當前值。對於通用 SCL 恢復是強制性的。對於通用 GPIO 恢復，在內部填充。
set_scl: 設定/清除 SCL 線路。對於通用 SCL 恢復是強制性的。對於通用 GPIO 恢復，在內部填充。
get_sda: 獲取 SDA 線路的當前值。對於通用 SCL 恢復，這或 set_sda() 是強制性的。如果 sda_gpio 是有效的 GPIO，則對於通用 GPIO 恢復，在內部填充。
set_sda: 設定/清除 SDA 線路。對於通用 SCL 恢復，這或 get_sda() 是強制性的。如果 sda_gpio 是有效的 GPIO，則對於通用 GPIO 恢復，在內部填充。
get_bus_free: 如果 IP 核具有比僅讀取 SDA 更復雜的內部邏輯，則返回從 IP 核看到的匯流排空閒狀態。可選。
prepare_recovery: 這將在開始恢復之前呼叫。平臺可以在此處為 SDA/SCL 線路配置 padmux 或其他任何他們想要的東西。
unprepare_recovery: 這將在完成恢復後呼叫。平臺可以在此處為 SDA/SCL 線路配置 padmux 或其他任何他們想要的東西。
scl_gpiod: SCL 線路的 gpiod。僅 GPIO 恢復需要。
sda_gpiod: SDA 線路的 gpiod。僅 GPIO 恢復需要。
pinctrl: GPIO 恢復用來更改 I2C 引腳狀態的 pinctrl。可選。
pins_default: SCL/SDA 線路的預設 pinctrl 狀態，當它們分配給 I2C 匯流排時。可選。如果找到名稱為 PINCTRL_STATE_DEFAULT 的狀態並且 pinctrl 有效，則對於 GPIO 恢復，在內部填充。
pins_gpio: SCL/SDA 線路的恢復 pinctrl 狀態，當它們用作 GPIO 時。可選。如果此狀態稱為“gpio”或“recovery”並且 pinctrl 有效，則對於 GPIO 恢復，在內部填充。

struct i2c_adapter_quirks¶: 描述 I2C 介面卡的缺陷

定義:

struct i2c_adapter_quirks {
    u64 flags;
    int max_num_msgs;
    u16 max_write_len;
    u16 max_read_len;
    u16 max_comb_1st_msg_len;
    u16 max_comb_2nd_msg_len;
};

成員

flags: 有關可能的標誌，請參見 I2C_AQ_*，並閱讀下文
max_num_msgs: 每次傳輸的最大訊息數
max_write_len: 寫入訊息的最大長度
max_read_len: 讀取訊息的最大長度
max_comb_1st_msg_len: 組合訊息中第一個訊息的最大長度
max_comb_2nd_msg_len: 組合訊息中第二個訊息的最大長度

描述

關於組合訊息的說明：某些 I2C 控制器每次傳輸只能傳送一條訊息，以及一種稱為組合訊息或先寫後讀的訊息。這（通常）是一條小的寫訊息，後跟一條讀訊息，並且幾乎足以訪問基於暫存器的裝置，例如 EEPROM。有一個標誌來支援此模式。它意味著 max_num_msg = 2，並使用 max_comb_*_len 進行長度檢查，因為組合訊息模式通常有其自身的限制。由於硬體實現的原因，某些控制器實際上可以執行先寫後任何操作或其他變體。為了支援這一點，先寫後讀已被分解為更小的位，例如先寫和後讀，可以根據需要進行組合。

void i2c_lock_bus(struct i2c_adapter *adapter, unsigned int flags)¶: 獲取對 I2C 匯流排段的獨佔訪問許可權

引數

struct i2c_adapter *adapter: 目標 I2C 匯流排段
unsigned int flags: I2C_LOCK_ROOT_ADAPTER 鎖定根 I2C 介面卡，I2C_LOCK_SEGMENT 僅鎖定介面卡樹中的此分支

int i2c_trylock_bus(struct i2c_adapter *adapter, unsigned int flags)¶: 嘗試獲取對 I2C 匯流排段的獨佔訪問權

引數

struct i2c_adapter *adapter: 目標 I2C 匯流排段
unsigned int flags: I2C_LOCK_ROOT_ADAPTER 嘗試鎖定根 I2C 介面卡，I2C_LOCK_SEGMENT 嘗試僅鎖定介面卡樹中的此分支

返回

如果 I2C 匯流排段已鎖定，則為 true，否則為 false

void i2c_unlock_bus(struct i2c_adapter *adapter, unsigned int flags)¶: 釋放對 I2C 匯流排段的獨佔訪問權

引數

struct i2c_adapter *adapter: 目標 I2C 匯流排段
unsigned int flags: I2C_LOCK_ROOT_ADAPTER 解鎖根 I2C 介面卡，I2C_LOCK_SEGMENT 僅解鎖介面卡樹中的此分支

void i2c_mark_adapter_suspended(struct i2c_adapter *adap)¶: 將介面卡的掛起狀態報告給核心

引數

struct i2c_adapter *adap: 要標記為掛起的介面卡

描述

當使用此幫助程式將介面卡標記為掛起時，核心將拒絕進一步傳輸到此介面卡。此幫助程式的使用是可選的，但建議用於具有針對系統掛起和執行時掛起的不同處理程式的裝置。更復雜的裝置可以自由地實現自定義解決方案，以在掛起時拒絕傳輸。

void i2c_mark_adapter_resumed(struct i2c_adapter *adap)¶: 將介面卡的恢復狀態報告給核心

引數

struct i2c_adapter *adap: 要標記為恢復的介面卡

描述

當使用此幫助程式將介面卡標記為恢復時，核心將允許進一步傳輸到此介面卡。另請參見 i2c_mark_adapter_suspended() 的更多說明。

bool i2c_check_quirks(struct i2c_adapter *adap, u64 quirks)¶: 用於檢查 I2C 介面卡中 quirk 標誌的函式

引數

struct i2c_adapter *adap: I2C 介面卡
u64 quirks: quirk 標誌

返回

如果介面卡具有所有指定的 quirk 標誌，則為 true，否則為 false

module_i2c_driver¶

module_i2c_driver (__i2c_driver)

用於註冊模組化 I2C 驅動程式的幫助程式宏

引數

__i2c_driver: i2c_driver 結構

描述

用於在模組 init/exit 中不執行任何特殊操作的 I2C 驅動程式的幫助程式宏。這消除了大量的樣板程式碼。每個模組只能使用此宏一次，並且呼叫它會替換 module_init() 和 module_exit()

builtin_i2c_driver¶

builtin_i2c_driver (__i2c_driver)

用於註冊內建 I2C 驅動程式的幫助程式宏

引數

__i2c_driver: i2c_driver 結構

描述

用於在其 init 中不執行任何特殊操作的 I2C 驅動程式的幫助程式宏。這消除了大量的樣板程式碼。每個驅動程式只能使用此宏一次，並且呼叫它會替換 device_initcall()。

int i2c_register_board_info(int busnum, struct i2c_board_info const *info, unsigned len)¶: 靜態宣告 I2C 裝置

引數

int busnum: 標識這些裝置所屬的匯流排
struct i2c_board_info const *info: I2C 裝置描述符向量
unsigned len: 向量中有多少個描述符；可以為零以保留指定的匯流排號。

描述

使用 Linux I2C 驅動程式堆疊的系統可以在初始化時聲明板資訊表。這應該在特定於板的初始化程式碼中 arch_initcall() 時間附近或等效時間完成，然後在註冊任何 I2C 介面卡驅動程式之前。例如，主機板初始化程式碼可以定義多個裝置，板堆疊中每個子卡的初始化程式碼也可以定義多個裝置。

I2C 裝置將在稍後建立，在相關匯流排的介面卡註冊後。在那之後，使用標準的驅動程式模型工具將“新式”I2C 驅動程式繫結到裝置。使用此例程宣告的任何裝置的匯流排號都不可用於動態分配。

傳遞的板資訊可以安全地是 __initdata，但要注意嵌入式指標（對於 platform_data、函式等），因為這不會被複制。

struct i2c_client *i2c_verify_client(struct device *dev)¶: 將引數作為 i2c_client 返回，或返回 NULL

引數

struct device *dev: 裝置，可能來自某些驅動程式模型迭代器

描述

當遍歷驅動程式模型樹時，可能使用驅動程式模型迭代器，如 device_for_each_child()，您無法對找到的節點做出太多假設。使用此函式可以避免由於錯誤地將某些非 I2C 裝置視為 i2c_client 而導致的崩潰。

struct i2c_client *i2c_new_client_device(struct i2c_adapter *adap, struct i2c_board_info const *info)¶: 例項化一個 I2C 裝置

引數

struct i2c_adapter *adap: 管理裝置的介面卡
struct i2c_board_info const *info: 描述一個 I2C 裝置；bus_num 被忽略

上下文

可以休眠

描述

建立一個 I2C 裝置。繫結透過驅動程式模型 probe()/remove() 方法處理。當我們從該函式返回時，或在任何後續時刻（例如，可能熱插拔將載入驅動程式模組），驅動程式可能會繫結到此裝置。此呼叫不適合由主機板初始化邏輯使用，該邏輯通常在 arch_initcall() 期間執行，遠早於任何 i2c_adapter 都可能存在的時間。

這將返回新的 I2C 客戶端，可以儲存它以供以後與 i2c_unregister_device() 一起使用；或一個 ERR_PTR 來描述錯誤。

void i2c_unregister_device(struct i2c_client *client)¶: i2c_new_*_device() 的反向效果

引數

struct i2c_client *client: 從 i2c_new_*_device() 返回的值

上下文

可以休眠

struct i2c_client *i2c_find_device_by_fwnode(struct fwnode_handle *fwnode)¶: 查詢 fwnode 的 i2c_client

引數

struct fwnode_handle *fwnode: 對應於 struct i2c_client 的 struct fwnode_handle

描述

查詢並返回對應於 fwnode 的 struct i2c_client。如果找不到任何客戶端，或者 fwnode 為 NULL，則返回 NULL。

使用者必須在使用完 I2C 客戶端後呼叫 put_device(client->dev)。

struct i2c_client *i2c_new_dummy_device(struct i2c_adapter *adapter, u16 address)¶: 返回繫結到虛擬驅動程式的新 I2C 裝置

引數

struct i2c_adapter *adapter: 管理裝置的介面卡
u16 address: 要使用的七位地址

上下文

可以休眠

描述

這將返回繫結到“虛擬”驅動程式的 I2C 客戶端，旨在與消耗多個地址的裝置一起使用。此類晶片的示例包括各種 EEPROM（如 24c04 和 24c08 型號）。

這些虛擬裝置有兩個主要用途。首先，除了 i2c_transfer() 之外，大多數 I2C 和 SMBus 呼叫都需要客戶端控制代碼；虛擬裝置將是該控制代碼。其次，這可以防止指定的地址繫結到其他驅動程式。

這將返回新的 I2C 客戶端，應將其儲存以供以後與 i2c_unregister_device() 一起使用；或一個 ERR_PTR 來描述錯誤。

struct i2c_client *devm_i2c_new_dummy_device(struct device *dev, struct i2c_adapter *adapter, u16 address)¶: 返回繫結到虛擬驅動程式的新 I2C 裝置

引數

struct device *dev: 託管資源繫結到的裝置
struct i2c_adapter *adapter: 管理裝置的介面卡
u16 address: 要使用的七位地址

上下文

可以休眠

描述

這是裝置託管版本的 i2c_new_dummy_device。它返回新的 i2c 客戶端，如果發生錯誤，則返回 ERR_PTR。

struct i2c_client *i2c_new_ancillary_device(struct i2c_client *client, const char *name, u16 default_addr)¶: 用於獲取例項化的輔助地址並建立關聯裝置的輔助函式

引數

struct i2c_client *client: 主客戶端的控制代碼
const char *name: 用於指定要獲取哪個輔助地址的控制代碼
u16 default_addr: 如果沒有指定輔助地址，則用作回退

上下文

可以休眠

描述

I2C 客戶端可以由繫結在單個元件中的多個 I2C 從裝置組成。然後，I2C 客戶端驅動程式繫結到主 I2C 從裝置，並且需要建立 I2C 虛擬客戶端以與所有其他從裝置通訊。

此函式建立並返回一個 I2C 虛擬客戶端，該客戶端的 I2C 地址是從平臺韌體根據給定的從裝置名稱檢索的。如果韌體未指定地址，則使用 default_addr。

在基於 DT 的平臺上，地址是從“reg”屬性條目單元格檢索的，該單元格的“reg-names”值與從裝置名稱匹配。

這將返回新的 I2C 客戶端，應將其儲存以供以後與 i2c_unregister_device() 一起使用；或一個 ERR_PTR 來描述錯誤。

struct i2c_adapter *i2c_verify_adapter(struct device *dev)¶: 將引數作為 i2c_adapter 返回，否則返回 NULL

引數

struct device *dev: 裝置，可能來自某些驅動程式模型迭代器

描述

當遍歷驅動程式模型樹時，可能使用驅動程式模型迭代器，如 device_for_each_child()，您不能對找到的節點做過多的假設。使用此函式可以避免因錯誤地將某些非 I2C 裝置視為 i2c_adapter 而導致的崩潰。

int i2c_handle_smbus_host_notify(struct i2c_adapter *adap, unsigned short addr)¶: 將主機通知事件轉發到正確的 I2C 客戶端。

引數

struct i2c_adapter *adap: 介面卡
unsigned short addr: 通知裝置的 I2C 地址

上下文

無法休眠

描述

要從 I2C 匯流排驅動程式的 Interrupt 處理程式呼叫的輔助函式。它將安排主機通知 IRQ。

int i2c_add_adapter(struct i2c_adapter *adapter)¶: 宣告 i2c 介面卡，使用動態匯流排編號

引數

struct i2c_adapter *adapter: 要新增的介面卡

上下文

可以休眠

描述

當 I2C 介面卡的匯流排編號無關緊要或匯流排編號由 dt 別名指定時，使用此例程來宣告 I2C 介面卡。匯流排編號無關緊要的基礎示例：由 USB 連結或 PCI 外掛卡動態新增的 I2C 介面卡。

當此函式返回零時，將分配一個新的匯流排編號並將其儲存在 adap->nr 中，並且指定的介面卡可供客戶端使用。否則，將返回一個負的 errno 值。

int i2c_add_numbered_adapter(struct i2c_adapter *adap)¶: 宣告 i2c 介面卡，使用靜態匯流排編號

引數

struct i2c_adapter *adap: 要註冊的介面卡（使用初始化的 adap->nr）

上下文

可以休眠

描述

當 I2C 介面卡的匯流排編號很重要時，使用此例程來宣告 I2C 介面卡。例如，將其用於來自片上系統 CPU 的 I2C 介面卡，或以其他方式內建到系統的主機板上，並且 i2c_board_info 用於正確配置 I2C 裝置。

如果請求的匯流排編號設定為 -1，則此函式將與 i2c_add_adapter 的行為完全相同，並將動態分配一個匯流排編號。

如果此匯流排尚未宣告任何裝置，請確保在動態分配的裝置之前註冊介面卡。否則，所需的匯流排 ID 可能不可用。

當此函式返回零時，指定的介面卡可供使用 adap->nr 中提供的匯流排編號的客戶端使用。此外，使用 i2c_register_board_info() 預先宣告的 I2C 裝置表將被掃描，並且將建立相應的驅動程式模型裝置節點。否則，將返回一個負的 errno 值。

void i2c_del_adapter(struct i2c_adapter *adap)¶: 登出 I2C 介面卡

引數

struct i2c_adapter *adap: 正在登出的介面卡

上下文

可以休眠

描述

這將登出先前由 i2c_add_adapter 或 i2c_add_numbered_adapter 註冊的 I2C 介面卡。

int devm_i2c_add_adapter(struct device *dev, struct i2c_adapter *adapter)¶: i2c_add_adapter() 的裝置託管變體

引數

struct device *dev: 用於新增此 I2C 介面卡的管理裝置
struct i2c_adapter *adapter: 要新增的介面卡

上下文

可以休眠

描述

新增具有動態匯流排編號的介面卡，與 i2c_add_adapter() 相同，但介面卡將在驅動程式分離時自動刪除。

struct i2c_adapter *i2c_find_adapter_by_fwnode(struct fwnode_handle *fwnode)¶: 為 fwnode 查詢 i2c_adapter

引數

struct fwnode_handle *fwnode: 對應於 struct i2c_adapter 的 struct fwnode_handle

描述

查詢並返回對應於 fwnode 的 struct i2c_adapter。如果找不到介面卡，或者 fwnode 為 NULL，則此函式返回 NULL。

使用者必須在使用完 i2c 介面卡後呼叫 put_device(adapter->dev)。

struct i2c_adapter *i2c_get_adapter_by_fwnode(struct fwnode_handle *fwnode)¶: 為 fwnode 查詢 i2c_adapter

引數

struct fwnode_handle *fwnode: 對應於 struct i2c_adapter 的 struct fwnode_handle

描述

查詢並返回對應於 fwnode 的 struct i2c_adapter，並增加介面卡模組的使用計數。如果找不到介面卡，或者 fwnode 為 NULL，則此函式返回 NULL。

在使用完 i2c 介面卡後，使用者必須呼叫 i2c_put_adapter(adapter)。請注意，這與 i2c_find_adapter_by_node() 不同。

void i2c_parse_fw_timings(struct device *dev, struct i2c_timings *t, bool use_defaults)¶: 從韌體獲取 I2C 相關的時序引數

引數

struct device *dev: 要掃描 I2C 時序屬性的裝置
struct i2c_timings *t: 要填充值的 i2c_timings 結構
bool use_defaults: 一個布林值，用於在使用規範中匯出的合理預設值找不到屬性時，否則不更新

描述

掃描裝置以查詢描述訊號時序引數的通用 I2C 屬性，並將結果填充到給定的結構中。如果未找到屬性且 use_defaults 為 true，則假定從 I2C 規範匯出的最大時序。如果未使用 use_defaults，則結果將與以前相同，因此驅動程式可以在呼叫此輔助程式之前應用其自己的預設值。後者主要用於避免想要切換到此函式的現有驅動程式發生迴歸。新驅動程式幾乎總是應該使用預設值。

void i2c_del_driver(struct i2c_driver *driver)¶: 登出 I2C 驅動程式

引數

struct i2c_driver *driver: 正在登出的驅動程式

上下文

可以休眠

int __i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num)¶: i2c_transfer 的非鎖定風格

引數

struct i2c_adapter *adap: I2C 匯流排的控制代碼
struct i2c_msg *msgs: 在發出 STOP 以終止操作之前要執行的一個或多個訊息；每個訊息都以 START 開頭。
int num: 要執行的訊息數。

描述

返回負的 errno，否則返回已執行的訊息數。

呼叫此函式時必須持有介面卡鎖。不會進行除錯日誌記錄。

int i2c_transfer(struct i2c_adapter *adap, struct i2c_msg *msgs, int num)¶: 執行單個或組合的 I2C 訊息

引數

struct i2c_adapter *adap: I2C 匯流排的控制代碼
struct i2c_msg *msgs: 在發出 STOP 以終止操作之前要執行的一個或多個訊息；每個訊息都以 START 開頭。
int num: 要執行的訊息數。

描述

返回負的 errno，否則返回已執行的訊息數。

請注意，沒有要求每個訊息都發送到相同的從裝置地址，儘管這是最常見的模型。

int i2c_transfer_buffer_flags(const struct i2c_client *client, char *buf, int count, u16 flags)¶: 發出一個 I2C 訊息，將資料傳輸到/從緩衝區

引數

const struct i2c_client *client: 從機裝置的控制代碼
char *buf: 資料儲存的位置
int count: 要傳輸多少位元組，必須小於 64k，因為 msg.len 是 u16
u16 flags: 用於訊息的標誌，例如，I2C_M_RD 用於讀取

描述

返回負的 errno，或者返回傳輸的位元組數。

int i2c_get_device_id(const struct i2c_client *client, struct i2c_device_identity *id)¶: 獲取裝置的製造商、零件 ID 和晶片修訂版

引數

const struct i2c_client *client: 要查詢的裝置
struct i2c_device_identity *id: 查詢的資訊

描述

錯誤時返回負的 errno，成功時返回零。

const struct i2c_device_id *i2c_client_get_device_id(const struct i2c_client *client)¶: 獲取裝置的驅動程式匹配表條目

引數

const struct i2c_client *client: 要查詢的裝置。裝置必須繫結到驅動程式

描述

如果找到匹配的條目，則返回指向該條目的指標，否則返回 NULL。

u8 *i2c_get_dma_safe_msg_buf(struct i2c_msg *msg, unsigned int threshold)¶: 為給定的 i2c_msg 獲取 DMA 安全緩衝區

引數

struct i2c_msg *msg: 要檢查的訊息
unsigned int threshold: 使用 DMA 有意義的最小位元組數。應該至少為 1。

返回

如果未獲得 DMA 安全緩衝區，則為 NULL。使用 msg->buf 和 PIO。: 或者，用於 DMA 的有效指標。使用後，透過呼叫 i2c_put_dma_safe_msg_buf() 來釋放它。

描述

此函式只能從程序上下文中呼叫！

void i2c_put_dma_safe_msg_buf(u8 *buf, struct i2c_msg *msg, bool xferred)¶: 釋放 DMA 安全緩衝區並與 i2c_msg 同步

引數

u8 *buf: 從 i2c_get_dma_safe_msg_buf() 獲得的緩衝區。可能為 NULL。
struct i2c_msg *msg: 緩衝區對應的訊息
bool xferred: 布林值，指示訊息是否已傳輸

u8 i2c_smbus_pec(u8 crc, u8 *p, size_t count)¶: 在給定的輸入資料陣列上進行增量 CRC8 計算

引數

u8 crc: 之前的 CRC8 返回值
u8 *p: 指向資料緩衝區的指標。
size_t count: 資料緩衝區中的位元組數。

描述

在 p 指向的陣列中的 count 個位元組上進行增量 CRC8 計算

s32 i2c_smbus_read_byte(const struct i2c_client *client)¶: SMBus “接收位元組” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼

描述

執行 SMBus “接收位元組” 協議，如果發生錯誤則返回負的 errno，否則返回從裝置接收的位元組。

s32 i2c_smbus_write_byte(const struct i2c_client *client, u8 value)¶: SMBus “傳送位元組” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 value: 要傳送的位元組

描述

執行 SMBus “傳送位元組” 協議，如果發生錯誤則返回負的 errno，成功則返回零。

s32 i2c_smbus_read_byte_data(const struct i2c_client *client, u8 command)¶: SMBus “讀取位元組” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組

描述

執行 SMBus “讀取位元組” 協議，如果發生錯誤則返回負的 errno，否則返回從裝置接收的資料位元組。

s32 i2c_smbus_write_byte_data(const struct i2c_client *client, u8 command, u8 value)¶: SMBus “寫入位元組” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組
u8 value: 正在寫入的位元組

描述

執行 SMBus “寫入位元組” 協議，如果發生錯誤則返回負的 errno，成功則返回零。

s32 i2c_smbus_read_word_data(const struct i2c_client *client, u8 command)¶: SMBus “讀取字” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組

描述

執行 SMBus “讀取字” 協議，如果發生錯誤則返回負的 errno，否則返回從裝置接收的 16 位無符號 “字”。

s32 i2c_smbus_write_word_data(const struct i2c_client *client, u8 command, u16 value)¶: SMBus “寫入字” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組
u16 value: 正在寫入的 16 位 “字”

描述

執行 SMBus “寫入字” 協議，如果發生錯誤則返回負的 errno，成功則返回零。

s32 i2c_smbus_read_block_data(const struct i2c_client *client, u8 command, u8 *values)¶: SMBus “塊讀取” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組
u8 *values: 將在其中讀取資料的位元組陣列；必須足夠大以容納從機返回的資料。SMBus 最多允許 32 個位元組。

描述

執行 SMBus “塊讀取” 協議，如果發生錯誤則返回負的 errno，否則返回從機響應中的資料位元組數。

請注意，使用此函式需要客戶端的介面卡支援 I2C_FUNC_SMBUS_READ_BLOCK_DATA 功能。並非所有介面卡驅動程式都支援此功能；透過 I2C 訊息傳遞進行的模擬依賴於特定的機制 (I2C_M_RECV_LEN)，該機制可能未實現。

s32 i2c_smbus_write_block_data(const struct i2c_client *client, u8 command, u8 length, const u8 *values)¶: SMBus “塊寫入” 協議

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組
u8 length: 資料塊的大小；SMBus 最多允許 32 個位元組
const u8 *values: 將被寫入的位元組陣列。

描述

執行 SMBus “塊寫入” 協議，如果發生錯誤則返回負的 errno，成功則返回零。

s32 i2c_smbus_xfer(struct i2c_adapter *adapter, u16 addr, unsigned short flags, char read_write, u8 command, int protocol, union i2c_smbus_data *data)¶: 執行 SMBus 協議操作

引數

struct i2c_adapter *adapter: I2C 匯流排的控制代碼
u16 addr: 總線上 SMBus 從機的地址
unsigned short flags: I2C_CLIENT_* 標誌（通常為零或 I2C_CLIENT_PEC）
char read_write: I2C_SMBUS_READ 或 I2C_SMBUS_WRITE
u8 command: 從機解釋的位元組，用於使用此類位元組的協議
int protocol: 要執行的 SMBus 協議操作，例如 I2C_SMBUS_PROC_CALL
union i2c_smbus_data *data: 要讀取或寫入的資料

描述

執行 SMBus 協議操作，如果發生錯誤則返回負的 errno 程式碼，成功則返回零。

s32 i2c_smbus_read_i2c_block_data_or_emulated(const struct i2c_client *client, u8 command, u8 length, u8 *values)¶: 讀取塊或模擬

引數

const struct i2c_client *client: 從機裝置的控制代碼
u8 command: 從機解釋的位元組
u8 length: 資料塊的大小；SMBus 最多允許 I2C_SMBUS_BLOCK_MAX 個位元組
u8 *values: 將在其中讀取資料的位元組陣列；必須足夠大以容納從機返回的資料。SMBus 最多允許 I2C_SMBUS_BLOCK_MAX 個位元組。

描述

如果介面卡支援，則執行 SMBus “塊讀取” 協議。如果不支援塊讀取，則根據可用性使用字或位元組讀取協議模擬它。

使用此函式訪問的 I2C 從裝置地址必須對映到線性區域，以便塊讀取與位元組讀取具有相同的效果。在使用此函式之前，必須仔細檢查 I2C 從裝置是否支援與位元組傳輸交換塊傳輸。

struct i2c_client *i2c_new_smbus_alert_device(struct i2c_adapter *adapter, struct i2c_smbus_alert_setup *setup)¶: 獲取用於 SMBus 警報支援的 ara 客戶端

引數

struct i2c_adapter *adapter: 目標介面卡
struct i2c_smbus_alert_setup *setup: SMBus 警報處理程式的設定資料

上下文

可以休眠

描述

設定給定 I2C 匯流排段上 SMBus 警報協議的處理。

可以透過我們的 IRQ 處理程式，或透過介面卡（從其處理程式、定期輪詢或任何方式）來完成處理。

這將返回 ara 客戶端，應儲存以供以後與 i2c_handle_smbus_alert() 一起使用，最終與 i2c_unregister_device() 一起使用；或者返回 ERRPTR 以指示錯誤。

Linux 核心

目錄

本頁

I²C 和 SMBus 子系統¶

I2C 和 SMBus 子系統¶

I²C 和 SMBus 子系統¶