OpenHarmony:如何使用HDF平臺驅動控制PWM
一、程序介紹
本程序是基于OpenHarmony標準系統(tǒng)編寫的平臺驅動案例:PWM
目前已在凌蒙派-RK3568開發(fā)板跑通。詳細資料請參考官網(wǎng):https://gitee.com/Lockzhiner-Electronics/lockzhiner-rk3568-openharmony/tree/master/samples/b05_platform_device_pwm
詳細資料請參考官網(wǎng):
二、基礎知識
1、PWM概述
PWM(Pulse Width Modulation)即脈沖寬度調(diào)制,是一種對模擬信號電平進行數(shù)字編碼并將其轉換為脈沖的技術,廣泛應用在從測量、通信到功率控制與變換的許多領域中。通常情況下,在使用馬達控制、背光亮度調(diào)節(jié)時會用到PWM模塊。
在HDF框架中,PWM接口適配模式采用獨立服務模式(如圖1所示)。在這種模式下,每一個設備對象會獨立發(fā)布一個設備服務來處理外部訪問,設備管理器收到API的訪問請求之后,通過提取該請求的參數(shù),達到調(diào)用實際設備對象的相應內(nèi)部方法的目的。獨立服務模式可以直接借助HDF設備管理器的服務管理能力,但需要為每個設備單獨配置設備節(jié)點,增加內(nèi)存占用。
獨立服務模式下,核心層不會統(tǒng)一發(fā)布一個服務供上層使用,因此這種模式下驅動要為每個控制器發(fā)布一個服務,具體表現(xiàn)為:
- 驅動適配者需要實現(xiàn)HdfDriverEntry的Bind鉤子函數(shù)以綁定服務。
- device_info.hcs文件中deviceNode的policy字段為1或2,不能為0。
PWM模塊各分層作用:
- 接口層提供打開PWM設備、設置PWM設備周期、設置PWM設備占空時間、設置PWM設備極性、設置PWM設備參數(shù)、獲取PWM設備參數(shù)、使能PWM設備、禁止PWM設備、關閉PWM設備的接口。
- 核心層主要提供PWM控制器的添加、移除以及管理的能力,通過鉤子函數(shù)與適配層交互。
- 適配層主要是將鉤子函數(shù)的功能實例化,實現(xiàn)具體的功能。
PWM獨立服務模式結構圖,如下圖所示:
OpenHarmony:如何使用HDF平臺驅動控制PWM-開源基礎軟件社區(qū)
2、PWM驅動開發(fā)
(1)PWM驅動開發(fā)接口
為了保證上層在調(diào)用PWM接口時能夠正確的操作PWM控制器,核心層在//drivers/hdf_core/framework/support/platform/include/pwm/pwm_core.h中定義了以下鉤子函數(shù),驅動適配者需要在適配層實現(xiàn)這些函數(shù)的具體功能,并與鉤子函數(shù)掛接,從而完成適配層與核心層的交互。
PwmMethod定義:
struct PwmMethod {
int32_t (*setConfig)(struct PwmDev *pwm, struct PwmConfig *config);
int32_t (*open)(struct PwmDev *pwm);
int32_t (*close)(struct PwmDev *pwm);
};
PwmMethod結構體成員的鉤子函數(shù)功能說明:
OpenHarmony:如何使用HDF平臺驅動控制PWM-開源基礎軟件社區(qū)
(2)PWM驅動開發(fā)步驟
PWM模塊適配包含以下四個步驟:
- 驅動實例化驅動入口。
- 配置屬性文件。
- 實例化PWM控制器對象。
- 驅動調(diào)試。
我們以///drivers/hdf_core/adapter/khdf/linux/platform/pwm/pwm_adapter.c為例(該PWM驅動是建立于Linux PWM子系統(tǒng)基礎上創(chuàng)建)。
驅動實例化驅動入口
驅動入口必須為HdfDriverEntry(在hdf_device_desc.h中定義)類型的全局變量,且moduleName要和device_info.hcs中保持一致。HDF框架會將所有加載的驅動的HdfDriverEntry對象首地址匯總,形成一個類似數(shù)組的段地址空間,方便上層調(diào)用。 一般在加載驅動時HDF會先調(diào)用Bind函數(shù),再調(diào)用Init函數(shù)加載該驅動。當Init調(diào)用異常時,HDF框架會調(diào)用Release釋放驅動資源并退出。
PWM驅動入口開發(fā)參考:
struct HdfDriverEntry g_hdfPwm = {
.moduleVersion = 1,
.moduleName = "HDF_PLATFORM_PWM",
.Bind = HdfPwmBind,
.Init = HdfPwmInit,
.Release = HdfPwmRelease,
};
HDF_INIT(g_hdfPwm);
配置屬性文件
完成驅動入口注冊之后,需要在device_info.hcs文件中添加deviceNode信息,deviceNode信息與驅動入口注冊相關。本例以兩個PWM控制器為例,如有多個器件信息,則需要在device_info.hcs文件增加對應的deviceNode信息。器件屬性值與核心層PwmDev成員的默認值或限制范圍有密切關系,比如PWM設備號,需要在pwm_config.hcs文件中增加對應的器件屬性。
本次案例以rk3568為案例(即文件//vendor/lockzhiner/rk3568/hdf_config/khdf/device_info/device_info.hcs),添加deviceNode描述,具體修改如下:
device_pwm :: device {
device0 :: deviceNode { // 為每一個PWM控制器配置一個HDF設備節(jié)點
policy = 2; // 標識向內(nèi)核和用戶態(tài)發(fā)布服務
priority = 80; // 驅動啟動優(yōu)先級
permission = 0644; // 驅動創(chuàng)建設備節(jié)點權限
moduleName = "HDF_PLATFORM_PWM"; // 【必要】用于指定驅動名稱,需要與期望的驅動Entry中的moduleName一致
serviceName = "HDF_PLATFORM_PWM_0"; // 【必要且唯一】驅動對外發(fā)布服務的名稱
deviceMatchAttr = "linux_pwm_adapter_0"; // 【必要】用于配置控制器私有數(shù)據(jù),要與pwm_config.hcs中對應控制器保持一致,具體的控制器信息在pwm_config.hcs中
}
device1 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_1";
deviceMatchAttr = "linux_pwm_adapter_1";
}
device2 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_2";
deviceMatchAttr = "linux_pwm_adapter_2";
}
device3 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_3";
deviceMatchAttr = "linux_pwm_adapter_3";
}
device4 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_4";
deviceMatchAttr = "linux_pwm_adapter_4";
}
}
pwm_config.hcs 配置參考//vendor/lockzhiner/rk3568/hdf_config/khdf/platform/pwm_config.hcs,具體修改如下:
root {
platform {
pwm_config {
template pwm_device { // 【必要】配置模板,如果下面節(jié)點使用時繼承該模板,則節(jié)點中未聲明的字段會使用該模板中的默認值
serviceName = ""; // 對外服務名稱,必須是唯一
match_attr = ""; // 【必要】需要和device_info.hcs中的deviceMatchAttr值一致
num = 0; // 【必要】設備號
}
device_pwm_0x00000000 :: pwm_device { // 存在多個設備時,請逐一添加相關HDF節(jié)點和設備節(jié)點信息。
num = 0;
match_attr = "linux_pwm_adapter_0"; // 【必要】需要和device_info.hcs中的deviceMatchAttr值一致
}
device_pwm_0x00000001 :: pwm_device {
num = 1;
match_attr = "linux_pwm_adapter_1";
}
device_pwm_0x00000002 :: pwm_device {
num = 2;
match_attr = "linux_pwm_adapter_2";
}
device_pwm_0x00000003 :: pwm_device {
num = 3;
match_attr = "linux_pwm_adapter_3";
}
device_pwm_0x00000004 :: pwm_device {
num = 4;
match_attr = "linux_pwm_adapter_4";
}
}
}
}
實例化PWM控制器對象
完成驅動入口注冊之后,下一步就是以核心層PwmDev對象的初始化為核心,包括驅動適配者自定義結構體(傳遞參數(shù)和數(shù)據(jù)),實例化PwmDev成員PwmMethod(讓用戶可以通過接口來調(diào)用驅動底層函數(shù)),實現(xiàn)HdfDriverEntry成員函數(shù)(Bind、Init、Release)。
static int32_t HdfPwmOpen(struct PwmDev *pwm);
static int32_t HdfPwmClose(struct PwmDev *pwm);
static int32_t HdfPwmSetConfig(struct PwmDev *pwm, struct PwmConfig *config);
// 定義PwmDev成員PwmMethod,實現(xiàn)相應接口
struct PwmMethod g_pwmOps = {
.setConfig = HdfPwmSetConfig,
.open = HdfPwmOpen,
.close = HdfPwmClose,
};
static int32_t HdfPwmBind(struct HdfDeviceObject *obj);
static int32_t HdfPwmInit(struct HdfDeviceObject *obj)
{
......
pwm->cfg.number = 0;
pwm->num = num;
pwm->method = &g_pwmOps; // 將PwmMethod綁定到pwm->method
pwm->busy = false;
ret = PwmDeviceAdd(obj, pwm); // 添加Pwm設備到PWM列表中
if (ret != HDF_SUCCESS) {
HDF_LOGE("%s: error probe, ret is %d", __func__, ret);
OsalMemFree(pwm);
}
......
}
static void HdfPwmRelease(struct HdfDeviceObject *obj);
驅動調(diào)試
建議先在Linux下修改確認,再移植到OpenHarmony。
3、PWM應用開發(fā)
通常情況下,在使用馬達控制、背光亮度調(diào)節(jié)時會用到PWM模塊。
(1)接口說明
PWM模塊提供的主要接口如下表所示,具體API詳見//drivers/hdf_core/framework/include/platform/pwm_if.h。
PwmConfig結構體介紹如下所示:
PWM驅動API接口功能介紹如下所示:
PwmOpen
在操作PWM設備時,首先要調(diào)用PwmOpen獲取PWM設備句柄,該函數(shù)會返回指定設備號的PWM設備句柄。
DevHandle PwmOpen(uint32_t num);
PwmOpen參數(shù)定義如下:
PwmOpen返回值定義如下:
假設系統(tǒng)中的PWM設備號為0,獲取該PWM設備句柄的示例如下:
uint32_t num = 0; // PWM設備號
DevHandle handle = NULL;
handle = PwmOpen(num); // 打開PWM 0設備并獲取PWM設備句柄
if (handle == NULL) {
HDF_LOGE("PwmOpen: open pwm_%u failed.\n", num);
return;
}
PwmClose
關閉PWM設備,系統(tǒng)釋放對應的資源。
void PwmClose(DevHandle handle);
PwmClose參數(shù)定義如下:
PwmClose返回值定義如下:
PwmEnable
使能PWM設備。
int32_t PwmEnable(DevHandle handle);
PwmEnable參數(shù)定義如下:
PwmEnable返回值定義如下:
PwmDisable
禁用PWM設備。
int32_t PwmDisable(DevHandle handle);
PwmDisable參數(shù)定義如下:
PwmDisable返回值定義如下:
PwmSetPeriod
設置PWM設備周期
int32_t PwmSetPeriod(DevHandle handle, uint32_t period);
PwmSetPeriod參數(shù)定義如下:
PwmSetPeriod返回值定義如下:
PwmSetDuty
設置PWM設備占空時間。
int32_t PwmSetDuty(DevHandle handle, uint32_t duty);
PwmSetDuty參數(shù)定義如下:
PwmSetDuty返回值定義如下:
PwmSetPolarity
設置PWM設備極性。
int32_t PwmSetPolarity(DevHandle handle, uint8_t polarity);
PwmSetDuty參數(shù)定義如下:
PwmSetDuty返回值定義如下:
PwmSetConfig
設置PWM設備參數(shù)。
int32_t PwmSetConfig(DevHandle handle, struct PwmConfig *config);
PwmSetConfig參數(shù)定義如下:
PwmSetConfig返回值定義如下:
PwmGetConfig
獲取PWM設備參數(shù)。
int32_t PwmGetConfig(DevHandle handle, struct PwmConfig *config);
PwmGetConfig參數(shù)定義如下:
PwmGetConfig返回值定義如下:
(2)開發(fā)流程
使用PWM的一般流程如下圖所示:
三、程序解析
1、準備工作
查看《凌蒙派-RK3568開發(fā)板_排針說明表_》(即Git倉庫的//docs/board/凌蒙派-RK3568開發(fā)板_排針說明表_v1.0.xlsx),選中PWM7_IR(即GPIO0_C6)。
2、Linux內(nèi)核解析
(1)創(chuàng)建Linux內(nèi)核Git
請參考《OpenHarmony如何為內(nèi)核打patch》(即Git倉庫的//docs/OpenHarmony如何為內(nèi)核打patch.docx)。
(2)修改設備樹PWM7配置
修改//arch/arm64/boot/dts/rockchip/rk3568-lockzhiner.dtsi(即該目錄是指已打Patch后的Linux內(nèi)核,不是OpenHarmony主目錄),具體如下所示:
&pwm7 {
status = "okay";
};
(3)創(chuàng)建內(nèi)核patch
請參考《OpenHarmony如何為內(nèi)核打patch》(即Git倉庫的//docs/OpenHarmony如何為內(nèi)核打patch.docx)。
(4)替換OpenHarmony的內(nèi)核patch
將制作出的kernel.patch替換到//kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch即可。
3、OpenHarmony配置樹配置
該部分不用特殊配置,本開發(fā)案例已經(jīng)編寫好。
(1)device_info.hcs
//vendor/lockzhiner/rk3568/hdf_config/khdf/device_info/device_info.hcs已定義好,具體如下:
device_pwm :: device {
device0 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_0";
deviceMatchAttr = "linux_pwm_adapter_0";
}
device1 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_1";
deviceMatchAttr = "linux_pwm_adapter_1";
}
device2 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_2";
deviceMatchAttr = "linux_pwm_adapter_2";
}
device3 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_3";
deviceMatchAttr = "linux_pwm_adapter_3";
}
device4 :: deviceNode {
policy = 2;
priority = 80;
permission = 0644;
moduleName = "HDF_PLATFORM_PWM";
serviceName = "HDF_PLATFORM_PWM_4";
deviceMatchAttr = "linux_pwm_adapter_4";
}
}
注意:policy必須為2,表示對內(nèi)核態(tài)和用戶態(tài)提供服務。否則,應用程序無法調(diào)用。
(2)pwm_config.hcs
//vendor/lockzhiner/rk3568/hdf_config/khdf/platform/pwm_config.hcs,具體內(nèi)容如下:
root {
platform {
pwm_config {
template pwm_device {
serviceName = "";
match_attr = "";
num = 0;
}
device_pwm_0x00000000 :: pwm_device {
num = 0;
match_attr = "linux_pwm_adapter_0";
}
device_pwm_0x00000001 :: pwm_device {
num = 1;
match_attr = "linux_pwm_adapter_1";
}
device_pwm_0x00000002 :: pwm_device {
num = 2;
match_attr = "linux_pwm_adapter_2";
}
device_pwm_0x00000003 :: pwm_device {
num = 3;
match_attr = "linux_pwm_adapter_3";
}
device_pwm_0x00000004 :: pwm_device {
num = 4;
match_attr = "linux_pwm_adapter_4";
}
}
}
}
注意:上述的num為PwmOpen(uint32_t num),它是Linux PWM的排序序號(即PWM7的num是排列序號3,從0開始排序),不是特指PWM實際編號(即PWM7)。
4、OpenHarmony PWM平臺驅動
在//drivers/hdf_core/adapter/khdf/linux/platform/pwm/pwm_adapter.c已編寫對接Linux PWM驅動的相關代碼,具體內(nèi)容如下:
struct HdfDriverEntry g_hdfPwm = {
.moduleVersion = 1,
.moduleName = "HDF_PLATFORM_PWM",
.Bind = HdfPwmBind,
.Init = HdfPwmInit,
.Release = HdfPwmRelease,
};
HDF_INIT(g_hdfPwm);
5、應用程序
(1)pwm_test.c
PWM相關頭文件如下所示:
#include "pwm_if.h" // PWM標準接口頭文件
主函數(shù)定義PWM接口調(diào)用,具體如下:
int main(int argc, char* argv[])
{
DevHandle handle = NULL;
int32_t ret;
......
// 打開pwm設備
handle = PwmOpen(m_pwm_device_id);
if (handle == NULL) {
PRINT_ERROR("PwmOpen failed\n");
return -1;
}
// 配置pwm設備
ret = PwmSetCfg_Ext1(handle, m_pwm_period, m_pwm_duty, m_pwm_polarity, m_pwm_status, m_pwm_wave_number);
// ret = PwmSetCfg_Ext2(handle, m_pwm_period, m_pwm_duty, m_pwm_polarity, m_pwm_status, m_pwm_wave_number);
if (ret != 0) {
PRINT_ERROR("PwmSetCfg_Ext failed and ret = %d\n", ret);
// 關閉pwm設備
PwmClose(handle);
return -1;
}
printf("Pwm enable successful and pwm device id(%d), period(%d), duty(%d), polarity(%d), status(%d), number(%d)\n",
m_pwm_device_id, m_pwm_period, m_pwm_duty, m_pwm_polarity, m_pwm_status, m_pwm_wave_number);
// 關閉pwm設備
PwmClose(handle);
return 0;
}
其中,PwmSetCfg_Ext1函數(shù)定義如何配置PWM相關參數(shù),具體如下所示:
/***************************************************************
* 函數(shù)名稱: PwmSetCfg_Ext1
* 說 明: 設置PWM相關屬性,使用PwmSetConfig等接口
* 參 數(shù):
* @handle: PWM設備句柄
* @period: PWM設備周期
* @duty: PWM設備占空時間
* @polarity: PWM設備極性
* @status: PWM使能/禁用
* @number: PWM產(chǎn)生方波的數(shù)目
* 返 回 值: 0為成功,反之為失敗
***************************************************************/
int32_t PwmSetCfg_Ext1(DevHandle handle, uint32_t period, uint32_t duty, uint8_t polarity, uint8_t status, uint32_t number)
{
int32_t ret;
struct PwmConfig config;
// 判斷handle是否為空
if (handle == NULL) {
PRINT_ERROR("handle is error\n");
return -1;
}
// 獲取pwm設備參數(shù)
ret = PwmGetConfig(handle, &config);
if (ret != 0) {
PRINT_ERROR("PwmGetConfig failed and ret = %d\n", ret);
return -1;
}
// 設置config
config.period = period;
config.duty = duty;
config.polarity = polarity;
config.status = status;
config.number = number;
// 設置pwm設備參數(shù)
ret = PwmSetConfig(handle, &config);
if (ret != 0) {
PRINT_ERROR("PwmSetConfig failed and ret = %d\n", ret);
return -1;
}
return 0;
}
(2)BUILD.gn
編寫應用程序的BUILD.gn,具體內(nèi)容如下:
import("http://build/ohos.gni")
import("http://drivers/hdf_core/adapter/uhdf2/uhdf.gni")
print("samples: compile rk3568_pwm_test")
ohos_executable("rk3568_pwm_test") {
sources = [ "pwm_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",
"http://base/hiviewdfx/hilog/interfaces/native/kits/include",
"http://third_party/bounds_checking_function/include",
]
deps = [
"$hdf_uhdf_path/platform:libhdf_platform",
"$hdf_uhdf_path/utils:libhdf_utils",
"http://base/hiviewdfx/hilog/interfaces/native/innerkits:libhilog",
]
cflags = [
"-Wall",
"-Wextra",
"-Werror",
"-Wno-format",
"-Wno-format-extra-args",
]
part_name = "product_rk3568"
install_enable = true
}
(3)參與應用程序編譯
編輯//vendor/lockzhiner/rk3568/samples/BUILD.gn,開啟編譯選項。具體如下:
"b05_platform_device_pwm/app:rk3568_pwm_test",
四、程序編譯
建議使用docker編譯方法,運行如下:
hb set -root .
hb set
# 選擇lockzhiner下的rk3568編譯分支。
hb build -f
五、運行結果
運行如下:
# rk3568_pwm_test -P 40000000 -d 20000000 -p 0 -s 1 -n 1000000 -i 3
pwm id: 3
pwm period: 40000000
pwm duty: 20000000
pwm polarity: 0
pwm status: 1
pwm wave number: 1000000
Pwm enable successful and pwm device id(3), period(40000000), duty(20000000), polarity(0), status(1), number(1000000)
#
使用示波器連接排線的0_C6(即GPIO0_C6,即PWM7),可以看到如下: