OpenHarmony：全流程講解如何編寫Watchdog平臺驅動以及應用程序
一、程序介紹
本程序是基于OpenHarmony標準系統(tǒng)編寫的平臺驅動案例：Watchdog。
目前已在凌蒙派-RK3568開發(fā)板跑通。詳細資料請參考官網：https://gitee.com/Lockzhiner-Electronics/lockzhiner-rk3568-openharmony/tree/master/samples/b10_platform_device_watchdog。
詳細資料請參考官網：
- Watchdog平臺驅動開發(fā)
- Watchdog應用程序開發(fā)
由于開發(fā)板只有1個Watchdog，且已被OpenHarmony內部占用，本案例只能讓讀者熟悉Watchdog相關接口以及應用，無法應用呈現(xiàn)。
二、基礎知識
1、Watchdog簡介
看門狗（Watchdog），又稱看門狗計時器（Watchdog timer），是一種硬件計時設備。一般有一個輸入、一個輸出，輸入叫做喂狗，輸出連接到系統(tǒng)的復位端。當系統(tǒng)主程序發(fā)生錯誤導致未及時清除看門狗計時器的計時值時，看門狗計時器就會對系統(tǒng)發(fā)出復位信號，使系統(tǒng)從懸停狀態(tài)恢復到正常運作狀態(tài)。
系統(tǒng)正常工作的時候，每隔一段時間輸出一個信號到喂狗端，給看門狗清零，這個操作就叫做喂狗。如果超過規(guī)定的時間不喂狗，看門狗定時超時，就會給出一個復位信號到系統(tǒng)，使系統(tǒng)復位。
2、Watchdog驅動開發(fā)
（1）Watchdog驅動開發(fā)接口
為了保證上層在調用Watchdog接口時能夠正確的操作Watchdog控制器，核心層在//drivers/hdf_core/framework/support/platform/include/watchdog/watchdog_core.h中定義了以下鉤子函數(shù)，驅動適配者需要在適配層實現(xiàn)這些函數(shù)的具體功能，并與鉤子函數(shù)掛接，從而完成適配層與核心層的交互。
WatchdogMethod定義：
struct WatchdogMethod {
int32_t (*getStatus)(struct WatchdogCntlr *wdt, int32_t *status);
int32_t (*setTimeout)(struct WatchdogCntlr *wdt, uint32_t seconds);
int32_t (*getTimeout)(struct WatchdogCntlr *wdt, uint32_t *seconds);
int32_t (*start)(struct WatchdogCntlr *wdt);
int32_t (*stop)(struct WatchdogCntlr *wdt);
int32_t (*feed)(struct WatchdogCntlr *wdt);
int32_t (*getPriv)(struct WatchdogCntlr *wdt); // 【可選】如果WatchdogCntlr中的priv成員存在，則按需實例化
void (*releasePriv)(struct WatchdogCntlr *wdt); // 【可選】
};WatchdogMethod成員的鉤子函數(shù)功能說明：
（2）Watchdog驅動開發(fā)步驟
Watchdog模塊適配HDF框架包含以下四個步驟：
- 實例化驅動入口。
- 配置屬性文件。
- 實例化Watchdog控制器對象。
- 驅動調試。
我們以///drivers/hdf_core/adapter/khdf/linux/platform/watchdog/watchdog_adapter.c為例（該watchdog驅動是建立于Linux Watchdog子系統(tǒng)基礎上創(chuàng)建）。
驅動實例化驅動入口
驅動入口必須為HdfDriverEntry（在 hdf_device_desc.h 中定義）類型的全局變量，且moduleName要和device_info.hcs中保持一致。HDF框架會將所有加載的驅動的HdfDriverEntry對象首地址匯總，形成一個類似數(shù)組的段地址空間，方便上層調用。 一般在加載驅動時HDF會先調用Bind函數(shù)，再調用Init函數(shù)加載該驅動。當Init調用異常時，HDF框架會調用Release釋放驅動資源并退出。
Watchdog驅動入口開發(fā)參考：
struct HdfDriverEntry g_hdfWdtchdog = {
.moduleVersion = 1,
.moduleName = "HDF_PLATFORM_WATCHDOG", // 【必要且與HCS文件中里面的moduleName匹配】
.Bind = HdfWdtBind, // 見Bind參考
.Init = HdfWdtInit, // 見Init參考
.Release = HdfWdtRelease, // 見Release參考
};
HDF_INIT(g_hdfWdtchdog); // 調用HDF_INIT將驅動入口注冊到HDF框架中配置屬性文件
完成驅動入口注冊之后，需要在device_info.hcs文件中添加deviceNode描述。deviceNode信息與驅動入口注冊相關。本例以一個Watchdog控制器為例，如有多個器件信息，則需要在device_info文件增加對應的deviceNode描述。器件屬性值與核心層WatchdogCntlr成員的默認值或限制范圍有密切關系，比如Watchdog設備號，需要在watchdog_config.hcs文件中增加對應的器件屬性。
在//vendor/lockzhiner/rk3568/hdf_config/khdf/device_info/device_info.hcs文件中添加deviceNode描述：
device_watchdog :: device { // 設備節(jié)點
device0 :: deviceNode { // 驅動的DeviceNode節(jié)點
policy = 2; // policy字段是驅動服務發(fā)布的策略,如果需要面向用戶態(tài)，則為2
priority = 20; // 驅動啟動優(yōu)先級
permission = 0644; // 驅動創(chuàng)建設備節(jié)點權限
moduleName = "HDF_PLATFORM_WATCHDOG"; // 【必要】用于指定驅動名稱，該字段的值必須和驅動入口結構的moduleName值一致
serviceName = "HDF_PLATFORM_WATCHDOG_0"; // 【必要】驅動對外發(fā)布服務的名稱，必須唯一。
deviceMatchAttr = "rockchip_rk3568_watchdog_0"; // 【必要】用于配置控制器私有數(shù)據(jù)，必須和驅動私有數(shù)據(jù)配置表watchdog_config.hcs中的match_attr值保持一致。
}
}在//vendor/lockzhiner/rk3568/hdf_config/khdf/platform/rk3568_watchdog_config.hcs文件配置器件屬性，其中配置參數(shù)如下：
root {
platform {
watchdog_config {
template watchdog_device {
serviceName = "HDF_PLATFORM_WATCHDOG_0";
match_attr = "";
id = 0;
}
device_0x12050000 :: watchdog_device {
id = 0;
match_attr = "rockchip_rk3568_watchdog_0";
}
}
}
}實例化Watchdog控制器對象
完成驅動入口注冊之后，下一步就是以核心層WatchdogCntlr對象的初始化為核心，包括驅動適配者自定義結構體（傳遞參數(shù)和數(shù)據(jù)），實例化WatchdogCntlr成員WatchdogMethod（讓用戶可以通過接口來調用驅動底層函數(shù)），實現(xiàn)HdfDriverEntry成員函數(shù)（Bind，Init，Release）。
WatchdogCntlr成員鉤子函數(shù)結構體WatchdogMethod的實例化，其他成員在Init和Bind函數(shù)中初始化。
// 鉤子函數(shù)實例化
static struct WatchdogMethod g_wdtMethod = {
.getStatus = WdtAdapterGetStatus, // 獲取看門狗狀態(tài)
.start = WdtAdapterStart, // 啟動看門狗
.stop = WdtAdapterStop, // 停止看門狗
.setTimeout = WdtAdapterSetTimeout, // 設置看門狗超時時間
.getTimeout = WdtAdapterGetTimeout, // 獲取看門狗超時時間
.feed = WdtAdapterFeed, // 喂狗函數(shù)
.getPriv = WdtOpenFile,
.releasePriv = WdtAdapterClose,
};驅動調試
建議先在Linux下修改確認，再移植到OpenHarmony。
3、Watchdog應用開發(fā)
看門狗（Watchdog），又稱看門狗計時器（Watchdog timer），是一種硬件計時設備。一般有一個輸入、一個輸出，輸入叫做喂狗，輸出連接到系統(tǒng)的復位端。當系統(tǒng)主程序發(fā)生錯誤導致未及時清除看門狗計時器的計時值時，看門狗計時器就會對系統(tǒng)發(fā)出復位信號，使系統(tǒng)從懸停狀態(tài)恢復到正常運作狀態(tài)。
Watchdog接口定義了看門狗操作的通用方法集合，包括：
- 打開/關閉看門狗設備
- 啟動/停止看門狗設備
- 設置/獲取看門狗設備超時時間
- 獲取看門狗設備狀態(tài)
- 喂狗
（1）接口說明
Watchdog模塊提供的主要接口如表1所示，具體API詳見//drivers/hdf_core/framework/include/platform/watchdog_if.h。
Watchdog驅動API接口功能介紹如下所示：
WatchdogOpen
在操作看門狗之前，需要調用WatchdogOpen打開看門狗設備，一個系統(tǒng)可能有多個看門狗，通過看門狗ID號來打開指定的看門狗設備。
DevHandle WatchdogOpen(int16_t wdtId, DevHandle *handle);WatchdogOpen參數(shù)定義如下：
WatchdogOpen返回值定義如下：
WatchdogClose
當所有操作完畢后，調用WatchdogClose關閉打開的看門狗設備。
void WatchdogClose(DevHandle handle);WatchdogClose參數(shù)定義如下：
WatchdogStart
啟動看門狗。
int32_t WatchdogStart(DevHandle handle);WatchdogStart參數(shù)定義如下：
WatchdogStart返回值定義如下：
WatchdogStop
停止看門狗。
int32_t WatchdogStop(DevHandle handle);WatchdogStop參數(shù)定義如下：
WatchdogStop返回值定義如下：
WatchdogSetTimeout
設置超時時間。
int32_t WatchdogSetTimeout(DevHandle *handle, uint32_t seconds);WatchdogSetTimeout參數(shù)定義如下：
WatchdogSetTimeout返回值定義如下：
WatchdogGetTimeout
獲取超時時間。
int32_t WatchdogGetTimeout(DevHandle *handle, uint32_t *seconds);WatchdogGetTimeout參數(shù)定義如下：
WatchdogGetTimeout返回值定義如下：
WatchdogGetStatus
獲取看門狗狀態(tài)。
int32_t WatchdogGetStatus(DevHandle handle, int32_t *status);WatchdogGetStatus參數(shù)定義如下：
WatchdogGetStatus返回值定義如下：
WatchdogFeed
喂狗。
int32_t WatchdogFeed(DevHandle handle);WatchdogFeed參數(shù)定義如下：
WatchdogFeed返回值定義如下：
（2）開發(fā)流程
使用Watchdog設備的一般流程如下圖所示：
三、程序解析
1、準備工作
無
2、Linux內核解析
（1）創(chuàng)建Linux內核Git
請參考《OpenHarmony如何為內核打patch》（即Git倉庫的//docs/OpenHarmony如何為內核打patch.docx）。
（2）修改設備樹Watchdog配置
修改//arch/arm64/boot/dts/rockchip/rk3568.dtsi（即該目錄是指已打Patch后的Linux內核，不是OpenHarmony主目錄），定義Watchdog啟用，具體如下所示：
wdt: watchdog@fe600000 {
compatible = "snps,dw-wdt";
reg = <0x0 0xfe600000 0x0 0x100>;
clocks = <&cru TCLK_WDT_NS>, <&cru PCLK_WDT_NS>;
clock-names = "tclk", "pclk";
interrupts = <GIC_SPI 149 IRQ_TYPE_LEVEL_HIGH>;
status = "okay";
};該部分為默認啟動看門狗。
（3）創(chuàng)建內核patch
請參考《OpenHarmony如何為內核打patch》（即Git倉庫的//docs/OpenHarmony如何為內核打patch.docx）。
（4）替換OpenHarmony的內核patch
將制作出的kernel.patch替換到//kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch即可。
（5）開啟watchdog內核配置
在//kernel/linux/config/linux-5.10/arch/arm64/configs/rk3568_standard_defconfig（即該目錄為OpenHarmony主目錄），開啟watchdog的hdf驅動，具體如下所示：
CONFIG_DRIVERS_HDF_PLATFORM_WATCHDOG=y3、OpenHarmony配置樹配置
（1）device_info.hcs
//vendor/lockzhiner/rk3568/hdf_config/khdf/device_info/device_info.hcs已定義好，具體如下：
device_watchdog :: device {
device0 :: deviceNode {
policy = 2;
priority = 20;
permission = 0644;
moduleName = "HDF_PLATFORM_WATCHDOG";
serviceName = "HDF_PLATFORM_WATCHDOG_0";
deviceMatchAttr = "rockchip_rk3568_watchdog_0";
}
}注意：
- device0：watchdog一般只需要1個設備節(jié)點即可。
- policy：policy字段是驅動服務發(fā)布的策略，如果需要面向用戶態(tài)，則為2。
- moduleName：用于指定驅動名稱，該字段的值必須和驅動入口結構的moduleName值一直，表示該節(jié)點對應。于//drivers/hdf_core/adapter/khdf/linux/platform/watchdog/watchdog_adapter.c，該驅動是對接Linux Watchdog子系統(tǒng)。
- deviceMatchAttr：用于配置控制器私有數(shù)據(jù)，必須和驅動私有數(shù)據(jù)配置表watchdog_config.hcs中的match_attr值保持一致
（2）Watchdog_config.hcs
在//vendor/lockzhiner/rk3568/hdf_config/khdf/platform/watchdog_config.hcs，具體內容如下：
root {
platform {
watchdog_config {
template watchdog_device {
serviceName = "HDF_PLATFORM_WATCHDOG_0";
match_attr = "";
id = 0;
}
device_0x12050000 :: watchdog_device {
id = 0;
match_attr = "rockchip_rk3568_watchdog_0";
}
}
}
}注意：
- id：表示Linux系統(tǒng)中watchdog的設備號（即/dev/watchdog0）。
- match_attr：必須與之前的device_info.hcs一致。
4、OpenHarmony Watchdog平臺驅動
在//drivers/hdf_core/adapter/khdf/linux/platform/watchdog/watchdog_adapter.c已編寫對接Linux Watchdog驅動的相關代碼，具體內容如下：
struct HdfDriverEntry g_hdfWdtchdog = {
.moduleVersion = 1,
.moduleName = "HDF_PLATFORM_WATCHDOG",
.Bind = HdfWdtBind,
.Init = HdfWdtInit,
.Release = HdfWdtRelease,
};
HDF_INIT(g_hdfWdtchdog);該部分代碼不細述，感興趣的讀者可以去詳讀。
5、應用程序
（1）Watchdog_test.c
Watchdog相關頭文件如下所示：
#include "watchdog_if.h" // watchdog標準接口頭文件主函數(shù)負責看門狗相關操作。
其中，打開看門狗操作源代碼具體如下：
// 打開看門狗設備
ret = WatchdogOpen(m_watchdog_id, handle);
if (ret != 0) {
PRINT_ERROR("WatchdogOpen failed and ret = %d\n", ret);
goto out;
}
if (handle == NULL) {
PRINT_ERROR("WatchdogOpen failed and handle is null\n");
goto out;
}
......設置和獲取看門狗超時時間操作源代碼如下所示：
// 設置超時時間
ret = WatchdogSetTimeout(handle, m_watchdog_timeout);
if (ret != 0) {
PRINT_ERROR("WatchdogSetTimeout failed and ret = %d\n", ret);
goto out;
}
printf("WatchdogSetTimeout Successful and Watchdog timeout = %d\n", m_watchdog_timeout);
// 獲取超時時間
ret = WatchdogGetTimeout(handle, &timeout);
if (ret != 0) {
PRINT_ERROR("WatchdogGetTimeout failed and ret = %d\n", ret);
goto out;
}
printf("WatchdogGetTimeout Successful and Watchdog timeout = %d\n", timeout);啟動看門狗操作，如下所示：
// 啟動看門狗
ret = WatchdogStart(handle);
if (ret != 0) {
PRINT_ERROR("WatchdogStart failed and ret = %d\n", ret);
goto out;
}查看看門狗相關狀態(tài)，如下所示：
// 獲取看門狗狀態(tài)，是否啟動
status = WATCHDOG_STOP;
ret = WatchdogGetStatus(handle, &status);
if (ret != 0) {
PRINT_ERROR("WatchdogGetStatus failed and ret = %d\n", ret);
goto out;
}
printf("WatchdogGetStatus Successful and Watchdog status = %d, WATCHDOG_START = %d, WATCHDOG_STOP = %d\n",
status, WATCHDOG_START, WATCHDOG_STOP);喂狗和停止喂狗操作，如下所示：
// 喂狗
for (i = 0; i < m_watchdog_feed_count; i++) {
sleep(m_watchdog_feed);
printf("Watchdog: feed number = %d and feed time = %d\n", i, m_watchdog_feed);
ret = WatchdogFeed(handle);
if (ret != 0) {
PRINT_ERROR("WatchdogFeed failed and ret = %d\n", ret);
goto out;
}
}
// 停止喂狗
ret = WatchdogStop(handle);
if (ret != 0) {
PRINT_ERROR("WatchdogStop failed and ret = %d\n", ret);
goto out;
}關閉喂狗，如下所示：
WatchdogClose(handle);（2）BUILD.gn
編寫應用程序的BUILD.gn，具體內容如下：
import("http://build/ohos.gni")
import("http://drivers/hdf_core/adapter/uhdf2/uhdf.gni")
print("samples: compile rk3568_watchdog_test")
ohos_executable("rk3568_watchdog_test") {
sources = [ "watchdog_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，開啟編譯選項。具體如下：
"b10_platform_device_watchdog/app:rk3568_watchdog_test"四、程序編譯
建議使用docker編譯方法，運行如下：
hb set -root .
hb set
# 選擇lockzhiner下的rk3568編譯分支。
hb build -f五、運行結果
運行如下：
# rk3568_Watchdog_test
Watchdog Params:
watchdog id = 0
watchdog timeout sec = 5
watchdog feed sec = 1
watchdog feed count = 5
../../vendor/lockzhiner/rk3568/samples/b10_platform_device_watchdog/app/watchdog_test.c, main, 121, error: WatchdogOpen failed and ret = -16
WatchdogClose Successful
#注意：
（1）WatchdogOpen返回值為-16，查看//drivers/hdf_core/framework/include/utils/hdf_base.h，具體如下：
/**
* @brief Enumerates HDF return value types.
*/
typedef enum {
HDF_SUCCESS = 0, /**< The operation is successful. */
HDF_FAILURE = -1, /**< Failed to invoke the OS underlying function. */
HDF_ERR_NOT_SUPPORT = -2, /**< Not supported. */
HDF_ERR_INVALID_PARAM = -3, /**< Invalid parameter. */
HDF_ERR_INVALID_OBJECT = -4, /**< Invalid object. */
HDF_ERR_MALLOC_FAIL = -6, /**< Memory allocation fails. */
HDF_ERR_TIMEOUT = -7, /**< Timeout occurs. */
HDF_ERR_THREAD_CREATE_FAIL = -10, /**< Failed to create a thread. */
HDF_ERR_QUEUE_FULL = -15, /**< The queue is full. */
HDF_ERR_DEVICE_BUSY = -16, /**< The device is busy. */
HDF_ERR_IO = -17, /**< I/O error. */
HDF_ERR_BAD_FD = -18, /**< Incorrect file descriptor. */
HDF_ERR_NOPERM = -19, /**< No permission. */
......
} HDF_STATUS;如此可知，watchdog被其他程序占用。
