[文章]OpenHarmony：全流程讲解如何编写Watchdog平台驱动以及应用程序

1、程序介绍

本程序是基于OpenHarmony标准系统编写的平台驱动案例：Watchdog

目前已在凌蒙派-RK3568开发板跑通。详细资料请参考官网：https://gitee.com/Lockzhiner-Electronics/lockzhiner-rk3568-openharmony/tree/master/samples/b10_platform_device_watchdog

详细资料请参考官网：

• Watchdog平台驱动开发
• Watchdog应用程序开发

由于开发板只有1个Watchdog，且已被OpenHarmony内部占用，本案例只能让读者熟悉Watchdog相关接口以及应用，无法应用呈现。

2、基础知识

2.1、Watchdog简介

看门狗（Watchdog），又称看门狗计时器（Watchdog timer），是一种硬件计时设备。一般有一个输入、一个输出，输入叫做喂狗，输出连接到系统的复位端。当系统主程序发生错误导致未及时清除看门狗计时器的计时值时，看门狗计时器就会对系统发出复位信号，使系统从悬停状态恢复到正常运作状态。

系统正常工作的时候，每隔一段时间输出一个信号到喂狗端，给看门狗清零，这个操作就叫做喂狗。如果超过规定的时间不喂狗，看门狗定时超时，就会给出一个复位信号到系统，使系统复位。

2.2、Watchdog驱动开发

2.2.1、Watchdog驱动开发接口

为了保证上层在调用Watchdog接口时能够正确的操作Watchdog控制器，核心层在//drivers/hdf_core/framework/support/platform/include/watchdog/watchdog_core.h中定义了以下钩子函数，驱动适配者需要在适配层实现这些函数的具体功能，并与钩子函数挂接，从而完成适配层与核心层的交互。

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成员的钩子函数功能说明：

2.2.2、Watchdog驱动开发步骤

Watchdog模块适配HDF框架包含以下四个步骤：

• 实例化驱动入口。
• 配置属性文件。
• 实例化Watchdog控制器对象。
• 驱动调试。

我们以///drivers/hdf_core/adapter/khdf/linux/platform/watchdog/watchdog_adapter.c为例（该watchdog驱动是建立于Linux Watchdog子系统基础上创建）。

2.2.2.1、驱动实例化驱动入口

驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。

Watchdog驱动入口开发参考：

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框架中

2.2.2.2、配置属性文件

完成驱动入口注册之后，需要在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 {									// 设备节点
    device0 :: deviceNode {									// 驱动的DeviceNode节点	
        policy = 2;											// policy字段是驱动服务发布的策略,如果需要面向用户态，则为2
        priority = 20;										// 驱动启动优先级
        permission = 0644;									// 驱动创建设备节点权限
        moduleName = "HDF_PLATFORM_WATCHDOG";				// 【必要】用于指定驱动名称，该字段的值必须和驱动入口结构的moduleName值一致
        serviceName = "HDF_PLATFORM_WATCHDOG_0";			// 【必要】驱动对外发布服务的名称，必须唯一。
        deviceMatchAttr = "rockchip_rk3568_watchdog_0";		// 【必要】用于配置控制器私有数据，必须和驱动私有数据配置表watchdog_config.hcs中的match_attr值保持一致。
    }
}

在//vendor/lockzhiner/rk3568/hdf_config/khdf/platform/rk3568_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";
            }
        }
    }
}

2.2.2.3、实例化Watchdog控制器对象

完成驱动入口注册之后，下一步就是以核心层WatchdogCntlr对象的初始化为核心，包括驱动适配者自定义结构体（传递参数和数据），实例化WatchdogCntlr成员WatchdogMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。

WatchdogCntlr成员钩子函数结构体WatchdogMethod的实例化，其他成员在Init和Bind函数中初始化。

// 钩子函数实例化
static struct WatchdogMethod g_wdtMethod = {
    .getStatus = WdtAdapterGetStatus,		// 获取看门狗状态
    .start = WdtAdapterStart,				// 启动看门狗
    .stop = WdtAdapterStop,					// 停止看门狗
    .setTimeout = WdtAdapterSetTimeout,		// 设置看门狗超时时间
    .getTimeout = WdtAdapterGetTimeout,		// 获取看门狗超时时间
    .feed = WdtAdapterFeed,					// 喂狗函数
    .getPriv = WdtOpenFile,
    .releasePriv = WdtAdapterClose,
};

2.2.2.4、驱动调试

建议先在Linux下修改确认，再移植到OpenHarmony。

2.3、Watchdog应用开发

看门狗（Watchdog），又称看门狗计时器（Watchdog timer），是一种硬件计时设备。一般有一个输入、一个输出，输入叫做喂狗，输出连接到系统的复位端。当系统主程序发生错误导致未及时清除看门狗计时器的计时值时，看门狗计时器就会对系统发出复位信号，使系统从悬停状态恢复到正常运作状态。

Watchdog接口定义了看门狗操作的通用方法集合，包括：

• 打开/关闭看门狗设备
• 启动/停止看门狗设备
• 设置/获取看门狗设备超时时间
• 获取看门狗设备状态
• 喂狗

2.3.1、接口说明

Watchdog模块提供的主要接口如表1所示，具体API详见//drivers/hdf_core/framework/include/platform/watchdog_if.h。

Watchdog驱动API接口功能介绍如下所示：

（1）WatchdogOpen

在操作看门狗之前，需要调用WatchdogOpen打开看门狗设备，一个系统可能有多个看门狗，通过看门狗ID号来打开指定的看门狗设备。

DevHandle WatchdogOpen(int16_t wdtId, DevHandle *handle);

WatchdogOpen参数定义如下：

WatchdogOpen返回值定义如下：

（2）WatchdogClose

当所有操作完毕后，调用WatchdogClose关闭打开的看门狗设备。

void WatchdogClose(DevHandle handle);

WatchdogClose参数定义如下：

（3）WatchdogStart

启动看门狗。

int32_t WatchdogStart(DevHandle handle);

WatchdogStart参数定义如下：

WatchdogStart返回值定义如下：

（4）WatchdogStop

停止看门狗。

int32_t WatchdogStop(DevHandle handle);

WatchdogStop参数定义如下：

WatchdogStop返回值定义如下：
（5）WatchdogSetTimeout

设置超时时间。

int32_t WatchdogSetTimeout(DevHandle *handle, uint32_t seconds);

WatchdogSetTimeout参数定义如下：

WatchdogSetTimeout返回值定义如下：

（6）WatchdogGetTimeout

获取超时时间。

int32_t WatchdogGetTimeout(DevHandle *handle, uint32_t *seconds);

WatchdogGetTimeout参数定义如下：

WatchdogGetTimeout返回值定义如下：

（7）WatchdogGetStatus

获取看门狗状态。

int32_t WatchdogGetStatus(DevHandle handle, int32_t *status); 

WatchdogGetStatus参数定义如下：

WatchdogGetStatus返回值定义如下：

（8）WatchdogFeed

喂狗。

int32_t WatchdogFeed(DevHandle handle);

WatchdogFeed参数定义如下：

WatchdogFeed返回值定义如下：

2.2.2、开发流程

使用Watchdog设备的一般流程如下图所示：

3、程序解析

3.1、准备工作

无

3.2、Linux内核解析

3.2.1、创建Linux内核Git

请参考《OpenHarmony如何为内核打patch》（即Git仓库的//docs/OpenHarmony如何为内核打patch.docx）。

3.2.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.2.3、创建内核patch

请参考《OpenHarmony如何为内核打patch》（即Git仓库的//docs/OpenHarmony如何为内核打patch.docx）。

3.2.4、替换OpenHarmony的内核patch

将制作出的kernel.patch替换到//kernel/linux/patches/linux-5.10/rk3568_patch/kernel.patch即可。

3.2.5、开启watchdog内核配置

在//kernel/linux/config/linux-5.10/arch/arm64/configs/rk3568_standard_defconfig（即该目录为OpenHarmony主目录），开启watchdog的hdf驱动，具体如下所示：

CONFIG_DRIVERS_HDF_PLATFORM_WATCHDOG=y

3.3、OpenHarmony配置树配置

3.3.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个设备节点即可。
• policy：policy字段是驱动服务发布的策略，如果需要面向用户态，则为2。
• moduleName：用于指定驱动名称，该字段的值必须和驱动入口结构的moduleName值一直，表示该节点对应。于//drivers/hdf_core/adapter/khdf/linux/platform/watchdog/watchdog_adapter.c，该驱动是对接Linux Watchdog子系统。
• deviceMatchAttr：用于配置控制器私有数据，必须和驱动私有数据配置表watchdog_config.hcs中的match_attr值保持一致

3.3.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系统中watchdog的设备号（即/dev/watchdog0）。
• match_attr：必须与之前的device_info.hcs一致。

3.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);

该部分代码不细述，感兴趣的读者可以去详读。

3.5、应用程序

3.5.1、Watchdog_test.c

Watchdog相关头文件如下所示：

#include "watchdog_if.h"                 // watchdog标准接口头文件

主函数负责看门狗相关操作。

其中，打开看门狗操作源代码具体如下：

// 打开看门狗设备
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;
}

查看看门狗相关状态，如下所示：

// 获取看门狗状态，是否启动
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);

3.5.2、BUILD.gn

编写应用程序的BUILD.gn，具体内容如下：

import("//build/ohos.gni")
import("//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",
    "//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 = "product_rk3568"
  install_enable = true
}

3.5.3、参与应用程序编译

编辑//vendor/lockzhiner/rk3568/samples/BUILD.gn，开启编译选项。具体如下：

"b10_platform_device_watchdog/app:rk3568_watchdog_test"

4、程序编译

建议使用docker编译方法，运行如下：

hb set -root .
hb set
# 选择lockzhiner下的rk3568编译分支。
hb build -f

5、运行结果

运行如下：

# 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被其他程序占用。