1、程序介紹
本程序是基于OpenHarmony標準系統編寫的平臺驅動案例:I2C
系統版本:openharmony5.0.0
開發板:dayu200
編譯環境:ubuntu22
部署路徑: //sample/04_platform_i2c
2、基礎知識
2.1、I2C簡介
I2C(Inter Integrated Circuit)總線是由Philips公司開發的一種簡單、雙向二線制同步串行總線。由于其硬件連接簡單、成本低廉,因此被廣泛應用于各種短距離通信的場景。
I2C以主從方式工作,通常有一個主設備和一個或者多個從設備,主從設備通過SDA(SerialData)串行數據線以及SCL(SerialClock)串行時鐘線兩根線相連(如下圖)。
I2C數據的傳輸必須以一個起始信號作為開始條件,以一個結束信號作為傳輸的停止條件。數據傳輸以字節為單位,高位在前,逐個bit進行傳輸。
I2C總線上的每一個設備都可以作為主設備或者從設備,而且每一個設備都會對應一個唯一的地址,當主設備需要和某一個從設備通信時,通過廣播的方式,將從設備地址寫到總線上,如果某個從設備符合此地址,將會發出應答信號,建立傳輸。
I2C接口定義了完成I2C傳輸的通用方法集合,包括:
-
I2C控制器管理:打開或關閉I2C控制器
-
I2C消息傳輸:通過消息傳輸結構體數組進行自定義傳輸
I2C物理連線示意圖
2.2、I2C驅動開發
I2C模塊各分層的作用為:
- 接口層:提供打開設備,數據傳輸以及關閉設備的能力。
- 核心層:主要負責服務綁定、初始化以及釋放管理器,并提供添加、刪除以及獲取控制器的能力。
- 適配層:由驅動適配者實現與硬件相關的具體功能,如控制器的初始化等。
2.2.1、I2C驅動開發接口
為了保證上層在調用I2C接口時能夠正確的操作硬件,核心層在//drivers/hdf_core/framework/support/platform/include/i2c/i2c_core.h中定義了以下鉤子函數。驅動適配者需要在適配層實現這些函數的具體功能,并與這些鉤子函數掛接,從而完成接口層與核心層的交互。
I2cMethod和I2cLockMethod定義:
struct I2cMethod {int32_t (*transfer)(struct I2cCntlr *cntlr, struct I2cMsg *msgs, int16_t count);
};struct I2cLockMethod { // 鎖機制操作結構體int32_t (*lock)(struct I2cCntlr *cntlr);void (*unlock)(struct I2cCntlr *cntlr);
};
在適配層中,I2cMethod必須被實現,I2cLockMethod可根據實際情況考慮是否實現。核心層提供了默認的I2cLockMethod,其中使用mutex作為保護臨界區的鎖:
static int32_t I2cCntlrLockDefault(struct I2cCntlr *cntlr)
{if (cntlr == NULL) {return HDF_ERR_INVALID_OBJECT;}return OsalMutexLock(&cntlr->lock);
}static void I2cCntlrUnlockDefault(struct I2cCntlr *cntlr)
{if (cntlr == NULL) {return;}(void)OsalMutexUnlock(&cntlr->lock);
}static const struct I2cLockMethod g_i2cLockOpsDefault = {.lock = I2cCntlrLockDefault,.unlock = I2cCntlrUnlockDefault,
};
若實際情況不允許使用mutex(例如使用者可能在中斷上下文調用I2C接口,mutex可能導致休眠,而中斷上下文不允許休眠)時,驅動適配者可以考慮使用其他類型的鎖來實現一個自定義的I2cLockMethod。一旦實現了自定義的I2cLockMethod,默認的I2cLockMethod將被覆蓋。
I2cMethod結構體成員函數功能說明:
函數成員 | 入參 | 出參 | 返回值 | 功能 |
---|---|---|---|---|
transfer | cntlr:結構體指針,核心層I2C控制器。 msgs:結構體指針,用戶消息。 count:uint16_t,消息數量。 | 無 | HDF_STATUS相關狀態 | 傳遞用戶消息 |
I2cLockMethod結構體成員函數功能說明:
函數成員 | 入參 | 出參 | 返回值 | 功能 |
---|---|---|---|---|
lock | cntlr:結構體指針,核心層I2C控制器。 | 無 | HDF_STATUS相關狀態 | 獲取臨界區鎖 |
unlock | cntlr:結構體指針,核心層I2C控制器。 | 無 | HDF_STATUS相關狀態 | 釋放臨界區鎖 |
2.2.2、I2C驅動開發步驟
I2C模塊適配HDF框架包含以下四個步驟:
- 實例化驅動入口。
- 配置屬性文件。
- 實例化I2C控制器對象。
- 驅動調試。
2.3、I2C應用開發
2.3.1、接口說明
I2C模塊提供的主要接口如表1所示,具體API詳見//drivers/hdf_core/framework/include/platform/i2c_if.h。
I2C驅動API接口功能介紹如下所示:
接口名 | 接口描述 |
---|---|
DevHandle I2cOpen(int16_t number) | 打開I2C控制器 |
void I2cClose(DevHandle handle) | 關閉I2C控制器 |
int32_t I2cTransfer(DevHandle handle, struct I2cMsg *msgs, int16_t count) | 自定義傳輸 |
(1)I2cOpen
在進行I2C通信前,首先要調用I2cOpen打開I2C控制器。
DevHandle I2cOpen(int16_t number);
I2cOpen參數定義如下:
參數 | 參數描述 |
---|---|
number | I2C控制器號 |
I2cOpen返回值定義如下:
返回值 | 返回值描述 |
---|---|
NULL | 打開I2C控制器失敗 |
設備句柄 | 打開的I2C控制器設備句柄 |
假設系統中存在8個I2C控制器,編號從0到7,以下代碼示例為獲取3號控制器:
DevHandle i2cHandle = NULL; /* I2C控制器句柄 //* 打開I2C控制器 */
i2cHandle = I2cOpen(3);
if (i2cHandle == NULL) {HDF_LOGE("I2cOpen: failed\n");return;
}
(2)I2cClose
I2C通信完成之后,需要關閉I2C控制器。
void I2cClose(DevHandle handle);
I2cClose參數定義如下:
參數 | 參數描述 |
---|---|
handle | I2C控制器設備句柄 |
(3)I2cTransfer
i2c消息傳輸。
int32_t I2cTransfer(DevHandle handle, struct I2cMsg \*msgs, int16_t count);
I2cTransfer參數定義如下:
參數 | 參數描述 |
---|---|
handle | I2C控制器設備句柄 |
msgs | 待傳輸數據的消息結構體數組 |
count | 消息數組長度 |
I2cTransfer返回值定義如下:
返回值 | 返回值描述 |
---|---|
正整數 | 成功傳輸的消息結構體數目 |
負數 | 執行失敗 |
I2C傳輸消息類型為I2cMsg,每個傳輸消息結構體表示一次讀或寫,通過一個消息數組,可以執行若干次的讀寫組合操作。組合讀寫示例:
int32_t ret;
uint8_t wbuff[2] = { 0x12, 0x13 };
uint8_t rbuff[2] = { 0 };
struct I2cMsg msgs[2]; /* 自定義傳輸的消息結構體數組 */
msgs[0].buf = wbuff; /* 寫入的數據 */
msgs[0].len = 2; /* 寫入數據長度為2 */
msgs[0].addr = 0x5A; /* 寫入設備地址為0x5A */
msgs[0].flags = 0; /* 傳輸標記為0,默認為寫 */
msgs[1].buf = rbuff; /* 要讀取的數據 */
msgs[1].len = 2; /* 讀取數據長度為2 */
msgs[1].addr = 0x5A; /* 讀取設備地址為0x5A */
msgs[1].flags = I2C_FLAG_READ /* I2C_FLAG_READ置位 */
/* 進行一次自定義傳輸,傳輸的消息個數為2 */
ret = I2cTransfer(i2cHandle, msgs, 2);
if (ret != 2) {HDF_LOGE("I2cTransfer: failed, ret %d\n", ret);return;
}
2.2.2、開發流程
使用I2C設備的一般流程如下圖所示:
3、程序解析
3.1、源碼目錄
3.2、接口流程梳理
- I2cOpen執行流程
//drivers\hdf_core\framework\support\platform\src\i2c\i2c_if.c
DevHandle I2cOpen(int16_t number)
|-->return (DevHandle)I2cCntlrGet(number);|-->return I2cManagerFindCntlr(number);|-->struct I2cCntlr *cntlr = g_i2cManager->cntlrs[number];|-->return cntlr
- I2cTransfer執行流程
//drivers\hdf_core\framework\support\platform\src\i2c\i2c_if.c
int32_t I2cTransfer(DevHandle handle, struct I2cMsg *msgs, int16_t count)
|-->return I2cCntlrTransfer((struct I2cCntlr *)handle, msgs, count);|-->return cntlr->ops->transfer(cntlr, msgs, count);
由上可見設備節點由全局變量g_i2cManager提供,此變量由下文中平臺驅動linux_i2c_adapter(drivers\hdf_core\adapter\khdf\linux\platform\i2c\i2c_adapter.c)進行設置。
3.3、平臺驅動說明
- 驅動實例化驅動入口
I2C控制器會出現很多個設備掛接的情況,因而在HDF框架中首先會為此類型的設備創建一個管理器對象,并同時對外發布一個管理器服務來統一處理外部訪問。這樣,用戶需要打開某個設備時,會先獲取到管理器服務,然后管理器服務根據用戶指定參數查找到指定設備。
I2C管理器服務的驅動由核心層實現,驅動適配者不需要關注這部分內容的實現,但在實現Init函數的時候需要調用核心層的I2cCntlrAdd函數,它會實現相應功能。
I2C驅動入口開發參考:
struct HdfDriverEntry g_i2cLinuxDriverEntry = {.moduleVersion = 1,.Bind = LinuxI2cBind,.Init = LinuxI2cInit,.Release = LinuxI2cRelease,.moduleName = "linux_i2c_adapter", // 【必要且與device_info.hcs文件里面匹配】
};
HDF_INIT(g_i2cLinuxDriverEntry); // 調用HDF_INIT將驅動入口注冊到HDF框架中/* 核心層i2c_core.c管理器服務的驅動入口 */
struct HdfDriverEntry g_i2cManagerEntry = {.moduleVersion = 1,.Bind = I2cManagerBind,.Init = I2cManagerInit,.Release = I2cManagerRelease,.moduleName = "HDF_PLATFORM_I2C_MANAGER", // 這與device_info.hcs文件中device0對應
};
HDF_INIT(g_i2cManagerEntry);
- 配置屬性文件
deviceNode信息與驅動入口注冊相關,器件屬性值對于驅動適配者的驅動實現以及核心層I2cCntlr相關成員的默認值或限制范圍有密切關系。
統一服務模式的特點是device_info.hcs文件中第一個設備節點必須為I2C管理器,其各項參數如下所示:
成員名 | 值 |
---|---|
moduleName | 固定為HDF_PLATFORM_I2C_MANAGER |
serviceName | 固定為HDF_PLATFORM_I2C_MANAGER |
policy | 具體配置為1或2取決于是否對用戶態可見 |
deviceMatchAttr | 沒有使用,可忽略 |
從第二個節點開始配置具體I2C控制器信息,此節點并不表示某一路I2C控制器,而是代表一個資源性質設備,用于描述一類I2C控制器的信息。多個控制器之間相互區分的參數是busId和reg_pbase,這在i2c_config.hcs文件中有所體現。如下:
//vendor/hihope/rk3568/hdf_config/khdf/device_info/device_info.hcs已定義好,具體如下:
注意:
- device1是rk3568原有的配置,也是我們需要的,作為OpenHarmony的i2c配置。
- moduleName定義為linux_i2c_adapter,表示該節點對應于//drivers/hdf_core/adapter/khdf/linux/platform/i2c/i2c_adapter.c,該驅動是對接Linux i2c子系統。
在//vendor/hihope/rk3568/hdf_config/khdf/platform/i2c_config.hcs,具體內容如下:
注意:
- controller_0x120b2000是為i2c2準備的。
- bus用于確定Linux i2c控制器序號。
具體執行流程如下:
//drivers\hdf_core\adapter\khdf\linux\platform\i2c\i2c_adapter.c
// 定義I2cMethod結構體變量g_method,實現i2c相應接口
static struct I2cMethod g_method = {.transfer = LinuxI2cTransfer,
};
static int32_t LinuxI2cInit(struct HdfDeviceObject *device)
|-->struct I2cCntlr *cntlr = (struct I2cCntlr *)OsalMemCalloc(sizeof(*cntlr));//為I2cCntlr對象分配內存
|-->cntlr->ops = &g_method;//分配i2c相應接口
|-->ret = I2cCntlrAdd(cntlr);//添加新創建的I2cCntlr對象到全局變量g_i2cManager中|-->ret = I2cManagerAddCntlr(cntlr);|-->manager->cntlrs[cntlr->busId] = cntlr;
由HDF驅動框架通過init和bind調用此驅動入口,注冊之后,下一步就是以核心層I2cCntlr對象的初始化為核心,包括驅動適配者自定義結構體(傳遞參數和數據),實例化I2cCntlr成員I2cMethod(讓用戶可以通過接口來調用驅動底層函數),實現HdfDriverEntry成員函數(Bind,Init,Release)。
3.4、應用程序
3.4.1、i2c_test.c
i2c相關頭文件如下所示:
#include "i2c_if.h" // i2c標準接口頭文件
主函數負責i2c讀寫操作。
其中,讀操作源代碼具體如下:
int main(int argc, char* argv[])
{DevHandle handle = NULL;int32_t ret = 0;struct I2cMsg msgs[2]; // 消息結構體數組int16_t msgs_count = 0;uint8_t wbuff[STRING_MAXSIZE] = { 0 };uint8_t rbuff[STRING_MAXSIZE] = { 0 };// 解析參數......// 打開i2c控制器handle = I2cOpen(m_i2c_number);if (handle == NULL) {PRINT_ERROR("I2cOpen failed\n");return -1;}if (m_i2c_flags_read == 1) {// 讀操作// 設置msgs數組有效數目msgs_count = 2;// 初始化msgs[0],該部分為主設備發送從設備的i2c內容msgs[0].addr = m_i2c_slave_address;msgs[0].flags = toI2cFlags(0, m_i2c_flags_addr_10bit, m_i2c_flags_read_no_ack, m_i2c_flags_ignore_no_ack, m_i2c_flags_no_start, m_i2c_flags_stop);msgs[0].len = 1;wbuff[0] = m_i2c_reg_address; // 本案例的i2c從設備是第1字節是寄存器地址msgs[0].buf = wbuff;// 初始化msgs[1],該部分為主設備讀取從設備發送的i2c內容msgs[1].addr = m_i2c_slave_address;msgs[1].flags = toI2cFlags(1, m_i2c_flags_addr_10bit, m_i2c_flags_read_no_ack, m_i2c_flags_ignore_no_ack, m_i2c_flags_no_start, m_i2c_flags_stop);msgs[1].len = m_i2c_read_data_length;msgs[1].buf = rbuff;// i2c數據傳輸,傳輸次數為2次ret = I2cTransfer(handle, msgs, msgs_count);if (ret != msgs_count) {PRINT_ERROR("I2cTransfer(read) failed and ret = %d\n", ret);goto out;}printf("I2cTransfer success and read data length = %d\n", strlen((char *)rbuff));for (uint32_t i = 0; i < strlen((char *)rbuff); i++) {printf("rbuff[%d] = 0x%x\n", i, rbuff[i]);}} else {......}out:// 關閉i2c控制器I2cClose(handle);return ret;
}
寫操作源代碼如下所示:
int main(int argc, char* argv[])
{DevHandle handle = NULL;int32_t ret = 0;struct I2cMsg msgs[2]; // 消息結構體數組int16_t msgs_count = 0;uint8_t wbuff[STRING_MAXSIZE] = { 0 };uint8_t rbuff[STRING_MAXSIZE] = { 0 };// 解析參數......// 打開i2c控制器handle = I2cOpen(m_i2c_number);if (handle == NULL) {PRINT_ERROR("I2cOpen failed\n");return -1;}if (m_i2c_flags_read == 1) {......} else {// 寫操作// 設置msgs數組有效數目msgs_count = 1;// 初始化msgs[0],該部分為主設備發送從設備的i2c內容msgs[0].addr = m_i2c_slave_address;msgs[0].flags = toI2cFlags(0, m_i2c_flags_addr_10bit, m_i2c_flags_read_no_ack, m_i2c_flags_ignore_no_ack, m_i2c_flags_no_start, m_i2c_flags_stop);msgs[0].len = 2;wbuff[0] = m_i2c_reg_address; // 本案例的i2c從設備是第1字節是寄存器地址wbuff[1] = m_i2c_reg_value; // 本案例的i2c從設備是第2字節是寄存器數值msgs[0].buf = wbuff;// i2c數據傳輸,傳輸次數為2次ret = I2cTransfer(handle, msgs, msgs_count);if (ret != msgs_count) {PRINT_ERROR("I2cTransfer(write) failed and ret = %d\n", ret);goto out;}printf("I2cTransfer success and write reg(%d), data(%d)\n", m_i2c_reg_address, m_i2c_reg_value);}out:// 關閉i2c控制器I2cClose(handle);return ret;
}
3.4.2、BUILD.gn
編寫應用程序的BUILD.gn,具體內容如下:
import("//build/ohos.gni")
import("//drivers/hdf_core/adapter/uhdf2/uhdf.gni")print("samples: compile rk3568_i2c_test")
ohos_executable("rk3568_i2c_test") {sources = [ "i2c_test.c" ]include_dirs = ["$hdf_framework_path/include","$hdf_framework_path/include/core","$hdf_framework_path/include/osal","$hdf_framework_path/include/platform","$hdf_framework_path/include/utils","$hdf_uhdf_path/osal/include","$hdf_uhdf_path/ipc/include","//base/hiviewdfx/hilog/interfaces/native/kits/include","//third_party/bounds_checking_function/include",]deps = ["$hdf_uhdf_path/platform:libhdf_platform","$hdf_uhdf_path/utils:libhdf_utils","//base/hiviewdfx/hilog/interfaces/native/innerkits:libhilog",]cflags = ["-Wall","-Wextra","-Werror","-Wno-format","-Wno-format-extra-args",]part_name = "rk3568_i2c_test"install_enable = true
}
3.4.3、bundle.json
編寫應用程序的bundle.json,具體內容如下:
{"name": "@ohos/i2c_test","description": "rk3568_i2c_test example.","version": "3.1","license": "Apache License 2.0","publishAs": "code-segment","segment": {"destPath": "sample/04_platform_i2c"},"dirs": {},"scripts": {},"component": {"name": "rk3568_i2c_test","subsystem": "sample","syscap": [],"features": [],"adapted_system_type": ["mini","small","standard"],"rom": "10KB","ram": "10KB","deps": {"components": ["hdf_core","hilog"],"third_party": []},"build": {"sub_component": ["//sample/04_platform_i2c:rk3568_i2c_test"],"inner_kits": [],"test": []}}
}
4、程序編譯
sudo ./build.sh --product-name rk3568 --build-target rk3568_i2c_test
5、運行結果
通過i2cdetect命令查看發現I2C 5中包含地址為0x15的設備,所以直接通過此設備進行測試了。
在i2c調試過程中,OpenHarmony還提供Linux i2c-tools工具,具體使用方法可以參考這篇。
運行如下:
上述命令為:查看i2c 5控制器,從設備地址21(即0x15,該地址為開發板外接i2c芯片),讀取寄存器地址0,數據長度為3。
6.參考資料
- I2C平臺驅動開發
- I2C應用程序開發
- OpenHarmony平臺驅動案例–I2C