diff --git a/zh-cn/device-dev/driver/driver-platform-watchdog-des.md b/zh-cn/device-dev/driver/driver-platform-watchdog-des.md index d23190f4463a1c4e63e68fd070f8795996ac14b0..c2067ec61e0b9408faa7a13b390f510bb3902fa5 100644 --- a/zh-cn/device-dev/driver/driver-platform-watchdog-des.md +++ b/zh-cn/device-dev/driver/driver-platform-watchdog-des.md @@ -1,126 +1,57 @@ -# Watchdog - - - -## 概述 - -看门狗（Watchdog），又叫看门狗计时器（Watchdog Timer），是一种硬件的计时设备，当系统的主程序发生某些错误时，导致未及时清除看门狗计时器的计时值，这时看门狗计时器就会对系统发出复位信号，使系统从悬停状态恢复到正常运作状态。 - -## 接口说明 - -**表 1** 看门狗 API接口功能介绍 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

功能分类

-

接口名

-

描述

-

打开/关闭看门狗

-

WatchdogOpen

-

打开看门狗设备

-

WatchdogClose

-

关闭看门狗设备

-

启动/停止看门狗

-

WatchdogStart

-

启动看门狗

-

WatchdogStop

-

停止看门狗

-

设置/获取超时时间

-

WatchdogSetTimeout

-

设置看门狗超时时间

-

WatchdogGetTimeout

-

获取看门狗超时时间

-

获取看门狗状态

-

WatchdogGetStatus

-

获取看门狗状态

-

清除看门狗定时器

-

WatchdogFeed

-

清除看门狗定时器(喂狗)

-
- ->![](../public_sys-resources/icon-note.gif) **说明：** ->本文涉及看门狗的所有接口，仅限内核态使用，不支持在用户态使用。 - -## 使用指导 - -### 使用流程 - -使用看门狗的一般流程如[图1](#fig430533913392)所示。 - -**图 1** 看门狗使用流程图 -![](figures/看门狗使用流程图.png "看门狗使用流程图") - -### 打开看门狗设备 +# Watchdog + + +## 概述 + +看门狗（Watchdog），又叫看门狗计时器（Watchdog timer），是一种硬件的计时设备。当系统主程序发生错误导致未及时清除看门狗计时器的计时值时，看门狗计时器就会对系统发出复位信号，使系统从悬停状态恢复到正常运作状态。 + + +## 接口说明 + +**表1** 看门狗API接口功能介绍 + +| 接口 | 接口描述 | +| -------- | -------- | +| WatchdogOpen | 打开看门狗 | +| WatchdogClose | 关闭看门狗 | +| WatchdogStart | 启动看门狗 | +| WatchdogStop | 停止看门狗 | +| WatchdogSetTimeout | 设置看门狗超时时间 | +| WatchdogGetTimeout | 获取看门狗超时时间 | +| WatchdogGetStatus | 获取看门狗状态 | +| WatchdogFeed | 清除看门狗定时器（喂狗) | + +> ![](../public_sys-resources/icon-note.gif) **说明：**
+> 本文涉及的看门狗的所有接口，仅限内核态使用，不支持在用户态使用。 + + +## 使用指导 + + +### 使用流程 + +使用看门狗的一般流程如下图所示。 + +**图1** 看门狗使用流程图 + +![image](figures/看门狗使用流程图.png "看门狗使用流程图") + + +### 打开看门狗设备 在操作看门狗之前，需要使用WatchdogOpen打开一个看门狗设备，一个系统可能有多个看门狗，通过ID号来打开指定的看门狗设备： -DevHandle WatchdogOpen\(int16\_t wdtId\); - -**表 2** WatchdogOpen参数和返回值描述 - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

wdtId

-

看门狗设备号

-

返回值

-

返回值描述

-

NULL

-

打开失败

-

DevHandle类型指针

-

看门狗设备句柄

-
+DevHandle WatchdogOpen(int16_t wdtId); + +**表2** WatchdogOpen参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| wdtId | 看门狗设备号 | +| **返回值** | **返回值描述** | +| NULL | 打开失败 | +| DevHandle类型指针 | 看门狗设备句柄 | + ``` DevHandle handle = NULL; @@ -131,46 +62,21 @@ if (handle == NULL) { } ``` -### 获取看门狗状态 - -int32\_t WatchdogGetStatus\(DevHandle handle, int32\_t \*status\); - -**表 3** WatchdogGetStatus参数和返回值描述 - - - - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-

status

-

获取到的启动状态指针

-

返回值

-

返回值描述

-

0

-

获取成功

-

负数

-

获取失败

-
+ +### 获取看门狗状态 + +int32_t WatchdogGetStatus(DevHandle handle, int32_t *status); + +**表3** WatchdogGetStatus参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | +| status | 获取到的看门狗状态的指针 | +| **返回值** | **返回值描述** | +| 0 | 获取成功 | +| 负数 | 获取失败 | + ``` int32_t ret; @@ -183,46 +89,21 @@ if (ret != 0) { } ``` -### 设置超时时间 - -int32\_t WatchdogSetTimeout\(DevHandle \*handle, uint32\_t seconds\); - -**表 4** WatchdogSetTimeout参数和返回值描述 - - - - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-

seconds

-

超时时间，单位为秒

-

返回值

-

返回值描述

-

0

-

设置成功

-

负数

-

设置失败

-
+ +### 设置超时时间 + +int32_t WatchdogSetTimeout(DevHandle *handle, uint32_t seconds); + +**表4** WatchdogSetTimeout参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | +| seconds | 超时时间，单位为秒 | +| **返回值** | **返回值描述** | +| 0 | 设置成功 | +| 负数 | 设置失败 | + ``` int32_t ret; @@ -235,46 +116,21 @@ if (ret != 0) { } ``` -### 获取超时时间 - -int32\_t WatchdogGetTimeout\(DevHandle \*handle, uint32\_t \*seconds\); - -**表 5** WatchdogGetTimeout参数和返回值描述 - - - - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-

seconds

-

接收超时时间的指针，单位为秒

-

返回值

-

返回值描述

-

0

-

获取成功

-

负数

-

获取失败

-
+ +### 获取超时时间 + +int32_t WatchdogGetTimeout(DevHandle *handle, uint32_t *seconds); + +**表5** WatchdogGetTimeout参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | +| seconds | 接收超时时间的指针，单位为秒 | +| **返回值** | **返回值描述** | +| 0 | 获取成功 | +| 负数 | 获取失败 | + ``` int32_t ret; @@ -287,41 +143,20 @@ if (ret != 0) { } ``` -### 启动看门狗 - -int32\_t WatchdogStart\(DevHandle handle\); - -**表 6** WatchdogStart参数和返回值描述 - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-

返回值

-

返回值描述

-

0

-

启动成功

-

负数

-

启动失败

-
+ +### 启动看门狗 + +int32_t WatchdogStart(DevHandle handle); + +**表6** WatchdogStart参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | +| **返回值** | **返回值描述** | +| 0 | 启动成功 | +| 负数 | 启动失败 | + ``` int32_t ret; @@ -333,41 +168,20 @@ if (ret != 0) { } ``` -### 喂狗 - -int32\_t WatchdogFeed\(DevHandle handle\); - -**表 7** WatchdogFeed参数和返回值描述 - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-

返回值

-

返回值描述

-

0

-

喂狗成功

-

负数

-

喂狗失败

-
+ +### 喂狗 + +int32_t WatchdogFeed(DevHandle handle); + +**表7** WatchdogFeed参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | +| **返回值** | **返回值描述** | +| 0 | 喂狗成功 | +| 负数 | 喂狗失败 | + ``` int32_t ret; @@ -379,41 +193,20 @@ if (ret != 0) { } ``` -### 停止看门狗 - -int32\_t WatchdogStop\(DevHandle handle\); - -**表 8** WatchdogStop参数和返回值描述 - - - - - - - - - - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-

返回值

-

返回值描述

-

0

-

停止成功

-

负数

-

停止失败

-
+ +### 停止看门狗 + +int32_t WatchdogStop(DevHandle handle); + +**表8** WatchdogStop参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | +| **返回值** | **返回值描述** | +| 0 | 停止成功 | +| 负数 | 停止失败 | + ``` int32_t ret; @@ -425,45 +218,38 @@ if (ret != 0) { } ``` -### 关闭看门狗设备 + +### 关闭看门狗设备 当操作完毕时，使用WatchdogClose关闭打开的设备句柄： -void WatchdogClose\(DevHandle handle\); - -**表 9** WatchdogClose参数和返回值描述 - - - - - - - - - - -

参数

-

参数描述

-

handle

-

看门狗设备句柄

-
+void WatchdogClose(DevHandle handle); + +**表9** WatchdogClose参数和返回值描述 + +| **参数** | **参数描述** | +| -------- | -------- | +| handle | 看门狗设备句柄 | + ``` /* 关闭看门狗 */ ret = WatchdogClose(handle); ``` -## 使用实例 + +## 使用实例 本例程提供看门狗的完整使用流程。 在本例程中，我们打开一个看门狗设备，设置超时时间并启动计时: -- 首先定期喂狗，即按时清除看门狗定时器，确保系统不会因定时器超时而复位。 -- 接着再停止喂狗，观察定时器到期后系统是否发生复位行为。 +- 首先定期喂狗，即按时清除看门狗定时器，确保系统不会因定时器超时而复位。 -示例如下： +- 接着再停止喂狗，观察定时器到期后系统是否发生复位行为。 + 示例如下： + ``` #include "watchdog_if.h" #include "hdf_log.h" @@ -483,7 +269,7 @@ static int32_t TestCaseWatchdog(void) /* 打开0号看门狗设备 */ handle = WatchdogOpen(0); if (handle == NULL) { - HDF_LOGE("Open watchdog fail!"); + HDF_LOGE("Open watchdog failed!"); return -1; } @@ -507,14 +293,14 @@ static int32_t TestCaseWatchdog(void) /* 启动看门狗，开始计时 */ ret = WatchdogStart(handle); if (ret != HDF_SUCCESS) { - HDF_LOGE("%s: satrt fail! ret:%d\n", __func__, ret); + HDF_LOGE("%s: start fail! ret:%d\n", __func__, ret); WatchdogClose(handle); return ret; } /* 每隔1S喂狗一次 */ for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) { - HDF_LOGE("%s: feeding watchdog %d times... \n", __func__, i); + HDF_LOGI("%s: feeding watchdog %d times... \n", __func__, i); ret = WatchdogFeed(handle); if (ret != HDF_SUCCESS) { HDF_LOGE("%s: feed dog fail! ret:%d\n", __func__, ret); @@ -524,18 +310,17 @@ static int32_t TestCaseWatchdog(void) OsalSleep(1); } /* 由于喂狗间隔小于超时时间，系统不会发生复位，此日志可以正常打印 */ - HDF_LOGE("%s: no reset ... feeding test OK!!!\n", __func__); + HDF_LOGI("%s: no reset ... feeding test OK!!!\n", __func__); /* 接下来持续不喂狗，使得看门狗计时器超时 */ for (i = 0; i < WATCHDOG_TEST_FEED_TIME; i++) { - HDF_LOGE("%s: watiting dog back %d times... \n", __func__, i); + HDF_LOGI("%s: waiting dog buck %d times... \n", __func__, i); OsalSleep(1); } /* 当不喂狗时间到达之前设定的超时时间的时候，系统会发生复位，理论上观察不到此日志的打印 */ - HDF_LOGE("%s: dog hasn't back!!! \n", __func__, i); + HDF_LOGI("%s: dog hasn't back!!! \n", __func__, i); WatchdogClose(handle); return -1; } -``` - +``` \ No newline at end of file diff --git a/zh-cn/device-dev/driver/driver-platform-watchdog-develop.md b/zh-cn/device-dev/driver/driver-platform-watchdog-develop.md index 986db11f17ffdf04bc7b9bfaf6404f9b19482529..1b47d28a96141c55f2c782b95f20834734a08dc4 100755 --- a/zh-cn/device-dev/driver/driver-platform-watchdog-develop.md +++ b/zh-cn/device-dev/driver/driver-platform-watchdog-develop.md @@ -1,17 +1,20 @@ -# WatchDog +# Watchdog -## 概述 +## 概述 -看门狗（Watchdog），又叫看门狗计时器（Watchdog timer），是一种硬件的计时设备，在HDF框架中，Watchdog接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。 +看门狗（Watchdog），又叫看门狗计时器（Watchdog timer），是一种硬件的计时设备。在HDF框架中，Watchdog接口适配模式采用独立服务模式，在这种模式下，每一个设备对象会独立发布一个设备服务来处理外部访问，设备管理器收到API的访问请求之后，通过提取该请求的参数，达到调用实际设备对象的相应内部方法的目的。独立服务模式可以直接借助HDFDeviceManager的服务管理能力，但需要为每个设备单独配置设备节点，增加内存占用。 -**图 1** Watchdog独立服务模式结构图 -![](figures/独立服务模式结构图.png "Watchdog独立服务模式结构图") + **图1** Watchdog独立服务模式结构图 -## 接口说明 + ![image](figures/独立服务模式结构图.png "Watchdog独立服务模式结构图") + + +## 接口说明 WatchdogMethod定义： + ``` struct WatchdogMethod { int32_t (*getStatus)(struct WatchdogCntlr *wdt, int32_t *status); @@ -20,342 +23,238 @@ struct WatchdogMethod { 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);//【可选】 + int32_t (*getPriv)(struct WatchdogCntlr *wdt); // 【可选】如果WatchdogCntlr中的priv成员存在，则按需实例化 + void (*releasePriv)(struct WatchdogCntlr *wdt);// 【可选】 }; ``` -**表 1** WatchdogMethod成员的回调函数功能说明 - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

成员函数

-

入参

-

出参

-

返回值

-

功能

-

getStatus

-

wdt: 结构体指针,核心层WDG控制器;

-

status: int32_t指针,表示狗的状态（打开或关闭）;

-

HDF_STATUS相关状态

-

获取看门狗所处的状态

-

start

-

wdt: 结构体指针,核心层WDG控制器;

-

无

-

HDF_STATUS相关状态

-

打开开门狗

-

stop

-

wdt: 结构体指针,核心层WDG控制器;

-

无

-

HDF_STATUS相关状态

-

关闭开门狗

-

setTimeout

-

wdt: 结构体指针,核心层WDG控制器;seconds: uint32_t,时间传入值;

-

无

-

HDF_STATUS相关状态

-

设置超时时间值，单位秒，需要保证看门狗实际运行的时间符合该值

-

getTimeout

-

wdt: 结构体指针,核心层WDG控制器;

-

seconds: uint32_t,传出的时间值

-

HDF_STATUS相关状态

-

回读设置的超时时间值

-

feed

-

wdt: 结构体指针,核心层WDG控制器;

-

无

-

HDF_STATUS相关状态

-

喂狗

-
- -## 开发步骤 + **表1** WatchdogMethod成员的回调函数功能说明 + +| 成员函数 | 入参 | 出参 | 返回值 | 功能 | +| -------- | -------- | -------- | -------- | -------- | +| getStatus | wdt：结构体指针，核心层WDG控制器 | status: int32_t指针，表示狗的状态（打开或关闭） | HDF_STATUS相关状态 | 获取看门狗所处的状态 | +| start | wdt：结构体指针，核心层WDG控制器 | 无 | HDF_STATUS相关状态 | 打开开门狗 | +| stop | wdt：结构体指针，核心层WDG控制器 | 无 | HDF_STATUS相关状态 | 关闭开门狗 | +| setTimeout | wdt：结构体指针，核心层WDG控制器 | seconds: uint32_t，时间传入值; | 无 | HDF_STATUS相关状态 | 设置超时时间值，单位秒，需要保证看门狗实际运行的时间符合该值 | +| getTimeout | wdt：结构体指针，核心层WDG控制器 | seconds: uint32_t，传出的时间值 | HDF_STATUS相关状态 | 回读设置的超时时间值 | +| feed | wdt：结构体指针，核心层WDG控制器 | 无 | HDF_STATUS相关状态 | 喂狗 | + + +## 开发步骤 Watchdog模块适配HDF框架的三个环节是配置属性文件，实例化驱动入口，以及实例化核心层接口函数。 -1. **实例化驱动入口：** - - 实例化HdfDriverEntry结构体成员。 - - 调用HDF\_INIT将HdfDriverEntry实例化对象注册到HDF框架中。 - -2. **配置属性文件：** - - 在device\_info.hcs文件中添加deviceNode描述。 - - 【可选】添加watchdog\_config.hcs器件属性文件。 - -3. **实例化Watchdog控制器对象：** - - 初始化WatchdogCntlr成员。 - - 实例化WatchdogCntlr成员WatchdogMethod。 - - >![](../public_sys-resources/icon-note.gif) **说明：** - >实例化WatchdogCntlr成员WatchdogMethod，其定义和成员说明见[接口说明](#section752964871810)。 - - -4. **驱动调试：** - - 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的信息反馈，超时时间设置的成功与否等。 - - -## 开发实例 - -下方将以watchdog\_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。 - -1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf\_device\_desc.h 中定义）类型的全局变量，且moduleName要和device\_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 - - 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 - - Watchdog驱动入口参考： - - ``` - struct HdfDriverEntry g_watchdogDriverEntry = { - .moduleVersion = 1, - .Bind = Hi35xxWatchdogBind, //见Bind参考 - .Init = Hi35xxWatchdogInit, //见Init参考 - .Release = Hi35xxWatchdogRelease, //见Release参考 - .moduleName = "HDF_PLATFORM_WATCHDOG",//【必要且与HCS文件中里面的moduleName匹配】 - }; - HDF_INIT(g_watchdogDriverEntry);//调用HDF_INIT将驱动入口注册到HDF框架中 - ``` - -2. 完成驱动入口注册之后，下一步请在device\_info.hcs文件中添加deviceNode信息，并在 watchdog\_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层WatchdogCntlr 成员的默认值或限制范围有密切关系。 - - 本例只有一个Watchdog控制器，如有多个器件信息，则需要在device\_info文件增加deviceNode信息，以及在watchdog\_config文件中增加对应的器件属性。 - - - device\_info.hcs 配置参考。 - - ``` - root { - device_info { - match_attr = "hdf_manager"; - device_watchdog :: device { // 设备节点 - device0 :: deviceNode { // 驱动的DeviceNode节点 - policy = 1; // policy字段是驱动服务发布的策略,如果需要面向用户态，则为2 - priority = 20; // 驱动启动优先级 - permission = 0644; // 驱动创建设备节点权限 - moduleName = "HDF_PLATFORM_WATCHDOG"; - // 【必要】驱动名称，该字段的值必须和驱动入口结构的moduleName值一致 - serviceName = "HDF_PLATFORM_WATCHDOG_0"; - // 【必要且唯一】驱动对外发布服务的名称 - deviceMatchAttr = "hisilicon_hi35xx_watchdog_0"; - // 【必要】驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值相等 - } - } - } - } - ``` - - - watchdog\_config.hcs 配置参考。 - - ``` - root { - platform { - template watchdog_controller {//【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省 - id = 0; - match_attr = ""; - regBase = 0x12050000; //【必要】地址映射需要 - regStep = 0x1000; //【必要】地址映射需要 - } - controller_0x12050000 :: watchdog_controller {//【必要】是作为设备驱动私有数据匹配的关键字 - match_attr = "hisilicon_hi35xx_watchdog_0"; //【必要】必须和device_info.hcs中的deviceMatchAttr值一致 - } - //存在多个 watchdog 时【必须】添加，否则不用 - ... - } - } - ``` - -3. 完成驱动入口注册之后，最后一步就是以核心层WatchdogCntlr对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化WatchdogCntlr成员WatchdogMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。 - - 自定义结构体参考。 - - 从驱动的角度看，自定义结构体是参数和数据的载体，而且watchdog\_config.hcs文件中的数值会被HDF读入通过DeviceResourceIface来初始化结构体成员，其中一些重要数值也会传递给核心层WatchdogCntlr对象，例如索引、管脚数等。 - - ``` - struct Hi35xxWatchdog { - struct WatchdogCntlr wdt; //【必要】是链接上下层的载体，具体描述见下面 - OsalSpinlock lock; - volatile unsigned char *regBase;//【必要】地址映射需要 - uint32_t phyBase; //【必要】地址映射需要 - uint32_t regStep; //【必要】地址映射需要 - }; - //WatchdogCntlr是核心层控制器结构体，其中的成员在Init函数中会被赋值 - struct WatchdogCntlr { - struct IDeviceIoService service;//驱动服务 - struct HdfDeviceObject *device; //驱动设备 - OsalSpinlock lock; //此变量在HDF核心层被调用来实现自旋锁功能 - struct WatchdogMethod *ops; //接口回调函数 - int16_t wdtId; //WDG设备的识别id - void *priv; //存储指针 - }; - ``` - - - WatchdogCntlr成员回调函数结构体WatchdogMethod的实例化，其他成员在Init和Bind函数中初始化。 - - ``` - static struct WatchdogMethod g_method = { - .getStatus = Hi35xxWatchdogGetStatus, - .start = Hi35xxWatchdogStart, - .stop = Hi35xxWatchdogStop, - .setTimeout = Hi35xxWatchdogSetTimeout, - .getTimeout = Hi35xxWatchdogGetTimeout, - .feed = Hi35xxWatchdogFeed, - }; - ``` - - - Init函数和Bind函数参考 - - 入参： - - HdfDeviceObject :HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。 - - 返回值： - - HDF\_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见//drivers/framework/include/utils/hdf\_base.h中HDF\_STATUS 定义）。 - - **表 2** Init函数和Bind函数入参和返回值 - - - - - - - - - - - - - - - - - - - - - - -

状态(值)

-

问题描述

-

HDF_ERR_INVALID_OBJECT

-

找不到 WDG 设备

-

HDF_ERR_MALLOC_FAIL

-

内存分配失败

-

HDF_ERR_IO

-

I/O 错误

-

HDF_SUCCESS

-

初始化成功

-

HDF_FAILURE

-

初始化失败

-
- - 函数说明： - - 初始化自定义结构体对象，初始化WatchdogCntlr成员，调用核心层WatchdogCntlrAdd函数。 - - ``` - //一般而言，Init函数需要根据入参(HdfDeviceObject对象)的属性值初始化Hi35xxWatchdog结构体的成员， - //但本例中是在bind函数中实现的 - static int32_t Hi35xxWatchdogInit(struct HdfDeviceObject *device) - { - (void)device; - return HDF_SUCCESS; - } +1. **实例化驱动入口：** + - 实例化HdfDriverEntry结构体成员。 + - 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。 + +2. **配置属性文件：** + - 在device_info.hcs文件中添加deviceNode描述。 + - 【可选】添加watchdog_config.hcs器件属性文件。 + +3. **实例化Watchdog控制器对象：** + - 初始化WatchdogCntlr成员。 + - 实例化WatchdogCntlr成员WatchdogMethod。 + > ![](../public_sys-resources/icon-note.gif) **说明：**
+ > 实例化WatchdogCntlr成员WatchdogMethod，其定义和成员说明见[接口说明](#接口说明)。 + +4. **驱动调试：** + 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的信息反馈，超时时间设置的成功与否等。 + + +## 开发实例 + +下方将以watchdog_hi35xx.c为示例，展示需要厂商提供哪些内容来完整实现设备功能。 + +1. 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在 hdf_device_desc.h 中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 + 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 + + Watchdog驱动入口参考： + + ``` + struct HdfDriverEntry g_watchdogDriverEntry = { + .moduleVersion = 1, + .Bind = Hi35xxWatchdogBind, // 见Bind参考 + .Init = Hi35xxWatchdogInit, // 见Init参考 + .Release = Hi35xxWatchdogRelease, // 见Release参考 + .moduleName = "HDF_PLATFORM_WATCHDOG",// 【必要且与HCS文件中里面的moduleName匹配】 + }; + HDF_INIT(g_watchdogDriverEntry);// 调用HDF_INIT将驱动入口注册到HDF框架中 + ``` + +2. 完成驱动入口注册之后，下一步请在device_info.hcs文件中添加deviceNode信息，并在 watchdog_config.hcs 中配置器件属性。deviceNode信息与驱动入口注册相关，器件属性值与核心层WatchdogCntlr 成员的默认值或限制范围有密切关系。 + 本例只有一个Watchdog控制器，如有多个器件信息，则需要在device_info文件增加deviceNode信息，以及在watchdog_config文件中增加对应的器件属性。 + - device_info.hcs 配置参考： + + + ``` + root { + device_info { + match_attr = "hdf_manager"; + device_watchdog :: device { // 设备节点 + device0 :: deviceNode { // 驱动的DeviceNode节点 + policy = 1; // policy字段是驱动服务发布的策略,如果需要面向用户态，则为2 + priority = 20; // 驱动启动优先级 + permission = 0644; // 驱动创建设备节点权限 + moduleName = "HDF_PLATFORM_WATCHDOG"; + // 【必要】驱动名称，该字段的值必须和驱动入口结构的moduleName值一致 + serviceName = "HDF_PLATFORM_WATCHDOG_0"; + // 【必要且唯一】驱动对外发布服务的名称 + deviceMatchAttr = "hisilicon_hi35xx_watchdog_0"; + // 【必要】驱动私有数据匹配的关键字，必须和驱动私有数据配置表中的match_attr值相等 + } + } + } + } + ``` + + - watchdog_config.hcs 配置参考： + + + ``` + root { + platform { + template watchdog_controller {// 【必要】模板配置，继承该模板的节点如果使用模板中的默认值，则节点字段可以缺省 + id = 0; + match_attr = ""; + regBase = 0x12050000; // 【必要】地址映射需要 + regStep = 0x1000; // 【必要】地址映射需要 + } + controller_0x12050000 :: watchdog_controller {// 【必要】是作为设备驱动私有数据匹配的关键字 + match_attr = "hisilicon_hi35xx_watchdog_0"; // 【必要】必须和device_info.hcs中的deviceMatchAttr值一致 + } + // 存在多个 watchdog 时【必须】添加，否则不用 + ... + } + } + ``` + +3. 完成驱动入口注册之后，最后一步就是以核心层WatchdogCntlr对象的初始化为核心，包括厂商自定义结构体（传递参数和数据），实例化WatchdogCntlr成员WatchdogMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。 + - 自定义结构体参考。 + + 从驱动的角度看，自定义结构体是参数和数据的载体，而且watchdog_config.hcs文件中的数值会被HDF读入通过DeviceResourceIface来初始化结构体成员，其中一些重要数值也会传递给核心层WatchdogCntlr对象，例如索引、管脚数等。 + + + ``` + struct Hi35xxWatchdog { + struct WatchdogCntlr wdt; // 【必要】是链接上下层的载体，具体描述见下面 + OsalSpinlock lock; + volatile unsigned char *regBase;// 【必要】地址映射需要 + uint32_t phyBase; // 【必要】地址映射需要 + uint32_t regStep; // 【必要】地址映射需要 + }; + // WatchdogCntlr是核心层控制器结构体，其中的成员在Init函数中会被赋值 + struct WatchdogCntlr { + struct IDeviceIoService service;// 驱动服务 + struct HdfDeviceObject *device; // 驱动设备 + OsalSpinlock lock; // 此变量在HDF核心层被调用来实现自旋锁功能 + struct WatchdogMethod *ops; // 接口回调函数 + int16_t wdtId; // WDG设备的识别id + void *priv; // 存储指针 + }; + ``` + - WatchdogCntlr成员回调函数结构体WatchdogMethod的实例化，其他成员在Init和Bind函数中初始化。 + - static int32_t Hi35xxWatchdogBind(struct HdfDeviceObject *device) - { - int32_t ret; - struct Hi35xxWatchdog *hwdt = NULL; - ... - hwdt = (struct Hi35xxWatchdog *)OsalMemCalloc(sizeof(*hwdt));//Hi35xxWatchdog 结构体的内存申请 - ... - hwdt->regBase = OsalIoRemap(hwdt->phyBase, hwdt->regStep); //地址映射 - ... - hwdt->wdt.priv = (void *)device->property;//【可选】此处是将设备属性的内容赋值给priv成员，但后续没有调用 priv 成员， - // 如果需要用到priv成员，需要额外实例化WatchdogMethod的getPriv和releasePriv成员函数 - hwdt->wdt.ops = &g_method; //【必要】将实例化后的对象赋值给ops成员，就可以实现顶层调用WatchdogMethod成员函数 - hwdt->wdt.device = device; //【必要】这是为了方便HdfDeviceObject与WatchdogcCntlr相互转化 - ret = WatchdogCntlrAdd(&hwdt->wdt); //【必要】调用此函数初始化核心层结构体，返回成功信号后驱动才完全接入平台核心层 - if (ret != HDF_SUCCESS) { //不成功的话，需要释放Init函数申请的资源 - OsalIoUnmap((void *)hwdt->regBase); - OsalMemFree(hwdt); - return ret; - } - return HDF_SUCCESS; - } - ``` - - - Release函数参考 - - 入参： - - HdfDeviceObject :HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。 - - 返回值： - - 无。 - - 函数说明： - - 该函数需要在驱动入口结构体中赋值给Release，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。该函数中需包含释放内存和删除控制器等操作。所有强制转换获取相应对象的操作前提是在Init函数中具备对应赋值的操作。 - - ``` - static void Hi35xxWatchdogRelease(struct HdfDeviceObject *device) - { - struct WatchdogCntlr *wdt = NULL; - struct Hi35xxWatchdog *hwdt = NULL; - ... - wdt = WatchdogCntlrFromDevice(device);//这里会通过service成员将HdfDeviceObject转化为WatchdogCntlr - //return (device == NULL) ? NULL : (struct WatchdogCntlr *)device->service; - if (wdt == NULL) { - return; - } - WatchdogCntlrRemove(wdt); //核心层函数，实际执行wdt->device->service = NULL以及cntlr->lock的释放 - hwdt = (struct Hi35xxWatchdog *)wdt; //这里将WatchdogCntlr转化为HimciHost - if (hwdt->regBase != NULL) { //解除地址映射 - OsalIoUnmap((void *)hwdt->regBase); - hwdt->regBase = NULL; - } - OsalMemFree(hwdt); //释放厂商自定义对象占用的内存 - } - ``` + ``` + static struct WatchdogMethod g_method = { + .getStatus = Hi35xxWatchdogGetStatus, + .start = Hi35xxWatchdogStart, + .stop = Hi35xxWatchdogStop, + .setTimeout = Hi35xxWatchdogSetTimeout, + .getTimeout = Hi35xxWatchdogGetTimeout, + .feed = Hi35xxWatchdogFeed, + }; + ``` + + - Init函数和Bind函数参考： + 入参： + HdfDeviceObject :HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。 + 返回值： + + HDF_STATUS相关状态 （下表为部分展示，如需使用其他状态，可见// drivers/framework/include/utils/hdf_base.h中HDF_STATUS 定义）。 + + **表2** Init函数和Bind函数入参和返回值 + + | 状态(值) | 问题描述 | + | -------- | -------- | + | HDF_ERR_INVALID_OBJECT | 找不到 WDG 设备 | + | HDF_ERR_MALLOC_FAIL | 内存分配失败 | + | HDF_ERR_IO | I/O 错误 | + | HDF_SUCCESS | 初始化成功 | + | HDF_FAILURE | 初始化失败 | + + 函数说明： + + 初始化自定义结构体对象，初始化WatchdogCntlr成员，调用核心层WatchdogCntlrAdd函数。 + + + ``` + // 一般而言，Init函数需要根据入参(HdfDeviceObject对象)的属性值初始化Hi35xxWatchdog结构体的成员， + // 但本例中是在bind函数中实现的 + static int32_t Hi35xxWatchdogInit(struct HdfDeviceObject *device) + { + (void)device; + return HDF_SUCCESS; + } + + static int32_t Hi35xxWatchdogBind(struct HdfDeviceObject *device) + { + int32_t ret; + struct Hi35xxWatchdog *hwdt = NULL; + ... + hwdt = (struct Hi35xxWatchdog *)OsalMemCalloc(sizeof(*hwdt));// Hi35xxWatchdog 结构体的内存申请 + ... + hwdt->regBase = OsalIoRemap(hwdt->phyBase, hwdt->regStep); // 地址映射 + ... + hwdt->wdt.priv = (void *)device->property;// 【可选】此处是将设备属性的内容赋值给priv成员，但后续没有调用 priv 成员， + // 如果需要用到priv成员，需要额外实例化WatchdogMethod的getPriv和releasePriv成员函数 + hwdt->wdt.ops = &g_method; // 【必要】将实例化后的对象赋值给ops成员，就可以实现顶层调用WatchdogMethod成员函数 + hwdt->wdt.device = device; // 【必要】这是为了方便HdfDeviceObject与WatchdogcCntlr相互转化 + ret = WatchdogCntlrAdd(&hwdt->wdt); // 【必要】调用此函数初始化核心层结构体，返回成功信号后驱动才完全接入平台核心层 + if (ret != HDF_SUCCESS) { // 不成功的话，需要释放Init函数申请的资源 + OsalIoUnmap((void *)hwdt->regBase); + OsalMemFree(hwdt); + return ret; + } + return HDF_SUCCESS; + } + ``` + - Release函数参考： + + 入参： + + HdfDeviceObject：HDF框架给每一个驱动创建的设备对象，用来保存设备相关的私有数据和服务接口。 + + 返回值： + + 无。 + + 函数说明： + + 该函数需要在驱动入口结构体中赋值给Release，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。该函数中需包含释放内存和删除控制器等操作。所有强制转换获取相应对象的操作前提是在Init函数中具备对应赋值的操作。 + + + ``` + static void Hi35xxWatchdogRelease(struct HdfDeviceObject *device) + { + struct WatchdogCntlr *wdt = NULL; + struct Hi35xxWatchdog *hwdt = NULL; + ... + wdt = WatchdogCntlrFromDevice(device);// 这里会通过service成员将HdfDeviceObject转化为WatchdogCntlr + // return (device == NULL) ? NULL : (struct WatchdogCntlr *)device->service; + if (wdt == NULL) { + return; + } + WatchdogCntlrRemove(wdt); // 核心层函数，实际执行wdt->device->service = NULL以及cntlr->lock的释放 + hwdt = (struct Hi35xxWatchdog *)wdt; // 这里将WatchdogCntlr转化为HimciHost + if (hwdt->regBase != NULL) { // 解除地址映射 + OsalIoUnmap((void *)hwdt->regBase); + hwdt->regBase = NULL; + } + OsalMemFree(hwdt); // 释放厂商自定义对象占用的内存 + } + ``` \ No newline at end of file