AUTOSAR_SWS_WatchdogDriver 中文翻译

文档编号：039　|　状态：Final（正式发布）　|　发布于：AUTOSAR CP Release 4.4.0（2018-10-31）
所属标准：AUTOSAR Classic Platform 标准　|　文档责任方：AUTOSAR　|　保密等级：AUTOSAR CONFIDENTIAL

本翻译覆盖原文档 1-43 页正文，约 1.01 MB / 43 页。
原文为软件规范（SWS, Software Specification），定义看门狗驱动（Watchdog Driver）模块的功能、API 与配置——含内部看门狗与外部看门狗两类。
本翻译校对区块：11 章 + 多小节 + 4 个 API 函数（Wdg_Init/SetMode/SetTriggerCondition/GetVersionInfo）+ 配置容器（Wdg/WdgGeneral/WdgSettingsConfig/WdgSettingsFast/Slow/Off/WdgExternalConfiguration/WdgDemEventParameterRefs/WdgPublishedInformation 共 9 类）+ 错误码（WDG_E_PARAM_CONFIG/DRIVER_STATE/INIT_FAILED/PARAM_MODE/PARAM_TIMEOUT） + 完整缩略语表。

1 引言与功能概述（Introduction and functional overview）

本文档规约 AUTOSAR 基础软件模块看门狗驱动（Wdg）的功能、API 与配置。

本模块提供服务用于初始化、改变操作模式与设置触发条件（timeout）。

功能需求与功能范围对内部与外部看门狗驱动是相同的。因此 API 语义相同。

内部看门狗驱动属于微控制器抽象层（MCAL），而外部看门狗驱动属于板上设备抽象层。

2 缩略语与缩写（Acronyms and abbreviations）

本节列出本文件使用的缩略语。详细定义见 术语表。

3 相关文档（Related documentation）

3.1 输入文档

• AUTOSAR_SRS_WatchdogDriver — 看门狗驱动需求（Requirements on Watchdog Driver）
• AUTOSAR_SRS_BSWGeneral — 基础软件通用需求（General Requirements on Basic Software Modules）
• AUTOSAR_SRS_SPALGeneral — SPAL 通用需求（General Requirements on SPAL）

3.2 相关标准与规范

N/A

3.3 相关规范

• AUTOSAR_SWS_MCUDriver — MCU 驱动规范（Specification of MCU Driver）
• AUTOSAR_SWS_PORTDriver — Port 驱动规范（Specification of Port Driver）
• AUTOSAR_SWS_SPIHandlerDriver — SPI Handler/Driver 规范（Specification of SPI Handler/Driver）
• AUTOSAR_SWS_DIODriver — DIO 驱动规范（Specification of DIO Driver）
• AUTOSAR_SWS_Det — 默认错误追踪器规范（Specification of Default Error Tracer）
• AUTOSAR_SWS_Dem — 诊断事件管理器规范（Specification of Diagnostic Event Manager）

4 约束与假设（Constraints and assumptions）

4.1 限制（Limitations）

本 SWS 适用于内部与外部看门狗驱动。两者具有相同的功能范围与 API 语义。

4.2 适用性（Applicability to car domains）

看门狗驱动适用于所有汽车域（动力总成、底盘、车身等），无特定域限制。

5 与其他模块的依赖（Dependencies to other modules）

5.1 文件结构（File structure）

5.1.1 代码文件结构（Code file structure）

/<Module>_src/
  Wdg.c                    # 主源文件
  Wdg_Lcfg.c               # Link-time 配置
  Wdg_PBcfg.c              # PostBuild 配置
  Wdg_Irq.c                # ISR 实现（若使用中断）

5.1.2 头文件结构（Header file structure）

/<Module>_include/
  Wdg.h                    # 主头文件
  Wdg_Cfg.h                # 配置头文件
  Wdg_PBcfg.h              # PostBuild 配置头文件
  Wdg_MemMap.h             # 内存映射

5.1.3 版本检查（Version check）

看门狗驱动应使用 Wdg_GetVersionInfo() 报告其版本号。集成商应检查与 ECU 软件版本的一致性。

5.2 系统时钟（System clock）

外部看门狗通常需要由系统时钟（通过 MCU 驱动）提供时钟脉冲。内部看门狗集成在 MCU 内部。

5.3 板上通信处理器（Onboard communication handlers）

外部看门狗驱动通过 SPI/DIO Handler/Driver 访问外部看门狗设备。

6 需求可追溯性（Requirements traceability）

本 SWS 中所有 SWS_Wdg_NNNNN 需求均链接到上游 AUTOSAR_SRS_WatchdogDriver 中的 SRS_Wdg_NNNNN 需求。下游 SRS_Wdg_NNNNN 需求 ID 唯一集合 = {12015, 12018, 12019, 12105, 12106, 12165, 12166, 12167, 12168, 13500} 共 10 个需求；SWS_Wdg_NNNNN 需求 ID 唯一集合（基于文档 13-20 页）约 100+ 条（SWS_Wdg_00001-SWS_Wdg_00300 范围），具体完整列表详见原文第 6 章追溯表。

本规约同时满足 RS_BRF_01008/01136/01448/01464/01912/01936（6 条 RS_BRF 需求，已在 SRS_WatchdogDriver 中追溯）。

7 功能规范（Functional specification）

7.1 通用设计规则（General design rules）

看门狗驱动的设计规则：

1. 提供 3 种模式：Fast、Slow、Off（Off 可选）；
2. 仅在 Wdg_Init() 后可调用其他 API；
3. 触发条件（trigger condition）必须在配置的时间内被设置，否则看门狗触发 reset；
4. 提供 DET 错误报告（开发错误）；
5. 提供 DEM 错误报告（生产错误，可选）；
6. 不支持禁用（disable）看门狗（仅适用于安全相关系统，由预处理器开关控制）。

7.2 错误分类（Error classification）

7.2.1 开发错误（Development Errors）

7.2.2 运行时错误（Runtime errors）

无（看门狗驱动不在运行时产生错误）。

7.2.3 瞬态故障（Transient Faults）

无（看门狗驱动不检测瞬态故障）。

7.2.4 生产错误（Production errors）

无（看门狗驱动不直接产生生产错误；DEM 报告由调用方决定）。

7.2.5 扩展生产错误（Extended production errors）

无。

7.3 错误检测（Error detection）

看门狗驱动检测的错误：

• API 调用时参数无效（NULL 指针、范围超出）；
• 未初始化时调用 API；
• 看门狗硬件初始化失败（寄存器访问错误）。

7.4 错误通知（Error notification）

看门狗驱动通过以下方式通知错误：

• 调用 Det_ReportError() 报告开发错误；
• 调用 Dem_ReportErrorStatus() 报告生产错误（可选）；
• API 返回 E_NOT_OK（若适用）。

7.5 外部看门狗驱动（External watchdog driver）

外部看门狗驱动通过 SPI/DIO 与外部看门狗设备通信。其功能与内部看门狗驱动相同。

7.6 内部看门狗驱动（Internal watchdog driver）

内部看门狗驱动直接通过 MCU 寄存器控制内部看门狗硬件。其功能与外部看门狗驱动相同。

7.7 触发概念支持窗式看门狗（Triggering concept to support windowed watchdogs）

看门狗驱动支持窗式看门狗（Windowed Watchdog）概念：

• 在配置的触发窗口内允许触发；
• 在窗口外触发被视为非法，看门狗 reset；
• 触发窗口由配置定义（WdgSettingsFast/WdgSettingsSlow）；
• 使用 Wdg_SetTriggerCondition() 在窗口内重新触发。

8 API 规范（API specification）

8.1 导入类型（Imported types）

本模块导入以下类型：

• Std_ReturnType（来自 Std_Types.h）
• Std_VersionInfoType（来自 Std_Types.h）

8.2 类型定义（Type definitions）

8.2.1 Wdg_ConfigType

typedef struct {
    WdgIf_ModeType    WdgDefaultMode;        /* 默认模式 */
    WdgIf_TriggerType  WdgFastTrigger;        /* Fast 模式触发条件 */
    WdgIf_TriggerType  WdgSlowTrigger;        /* Slow 模式触发条件 */
    WdgIf_ModeType     WdgInitialMode;        /* 初始模式 */
    /* MCU 特定参数 */
    uint16             WdgMaxTriggerTimeFast;
    uint16             WdgMaxTriggerTimeSlow;
} Wdg_ConfigType;

8.3 函数定义（Function definitions）

8.3.1 Wdg_Init

void Wdg_Init(const Wdg_ConfigType* ConfigPtr);

说明：初始化看门狗驱动。该函数应在 OS 启动后、任何看门狗模式变更前调用。初始化后看门狗硬件开始运行在 ConfigPtr->WdgInitialMode 模式下。

参数：

• ConfigPtr：指向看门狗配置结构的指针。

错误：

• WDG_E_PARAM_CONFIG：ConfigPtr 为 NULL；
• WDG_E_INIT_FAILED：硬件初始化失败。

8.3.2 Wdg_SetMode

Std_ReturnType Wdg_SetMode(WdgIf_ModeType Mode);

说明：设置看门狗当前操作模式。可从 Fast 切换到 Slow 或反之；切换到 Off 仅在配置允许时可用。

参数：

• Mode：目标模式（WDGIF_FAST_MODE、WDGIF_SLOW_MODE、WDGIF_OFF_MODE）。

返回：E_OK 成功；E_NOT_OK 失败。

错误：

• WDG_E_DRIVER_STATE：看门狗未初始化；
• WDG_E_PARAM_MODE：无效的 Mode 参数。

8.3.3 Wdg_SetTriggerCondition

Std_ReturnType Wdg_SetTriggerCondition(uint16 Timeout);

说明：设置看门狗触发条件（timeout 值）。在窗式看门狗模式下，Timeout 须在配置窗口内。

参数：

• Timeout：新的 timeout 值（毫秒）。

返回：E_OK 成功；E_NOT_OK 失败。

错误：

• WDG_E_DRIVER_STATE：看门狗未初始化；
• WDG_E_PARAM_TIMEOUT：Timeout 超出有效范围。

8.3.4 Wdg_GetVersionInfo

#if (WDG_VERSION_INFO_API == STD_ON)
void Wdg_GetVersionInfo(Std_VersionInfoType* VersionInfoPtr);
#endif

说明：返回看门狗驱动的版本信息。

参数：

• VersionInfoPtr：指向 Std_VersionInfoType 结构的指针。

错误：

• WDG_E_PARAM_CONFIG：VersionInfoPtr 为 NULL（DET 错误）。

8.4 回调通知（Call-back Notifications）

本模块无回调通知。所有交互通过 Wdg_SetMode() 与 Wdg_SetTriggerCondition() 主动调用。

8.5 调度函数（Scheduled functions）

本模块无主函数（MainFunction）。看门狗触发由系统时间事件或外部触发直接驱动。

8.6 预期接口（Expected interfaces）

8.6.1 强制接口（Mandatory interfaces）

本模块无强制调用的外部接口。

8.6.2 可选接口（Optional interfaces）

• Det_ReportError()（开发错误，强制）；
• Dem_ReportErrorStatus()（生产错误，可选）；
• Mcu_GetResetReason()（外部 SPI 看门狗触发时调用以获取 MCU 复位原因）；
• Spi_Write()、Spi_Read()（外部 SPI 看门狗驱动）；
• Dio_WriteChannel()、Dio_ReadChannel()（外部 DIO 看门狗驱动）。

8.6.3 可配置接口（Configurable interfaces）

无（所有接口均为固定）。

9 序列图（Sequence diagrams）

9.1 看门狗初始化、设置触发条件与模式（Watchdog initialization, setting trigger condition and mode）

序列图 9.1 描述 EcuM 启动时的看门狗初始化流程：

1. EcuM 调用 Wdg_Init()；
2. Wdg 配置内部/外部看门狗硬件；
3. Wdg 设置初始触发条件；
4. 看门狗开始监控；
5. 应用任务在执行中调用 Wdg_SetTriggerCondition() 重置看门狗；
6. EcuM 在 ECU 状态变更时调用 Wdg_SetMode()。

9.2 看门狗驱动与硬件的数据交换（Data exchange between watchdog driver and hardware）

序列图 9.2 描述外部 SPI 看门狗的数据交换：

1. Wdg 准备数据帧；
2. 调用 Spi_Write() 发送密码到看门狗设备；
3. SPI 完成回调通知 Wdg；
4. Wdg 调用 Spi_Read() 读取看门狗状态；
5. Wdg 处理状态信息。

配置规范（Configuration specification）

10.1 如何阅读本章（How to read this chapter）

本章定义看门狗驱动的所有配置容器与参数。每个容器使用 ECUC（ECU Configuration）格式描述。

10.2 容器与配置参数（Containers and configuration parameters）

10.2.1 Wdg

10.2.2 WdgDemEventParameterRefs

10.2.3 WdgGeneral

WdgGeneral 容器继承 Wdg 容器的所有参数，并添加：

• WdgDemEventParameterRefs 子容器；
• WdgSettingsConfig 子容器；
• WdgExternalConfiguration 子容器（用于外部看门狗）。

10.2.4 WdgSettingsConfig

包含 WdgSettingsFast 与 WdgSettingsSlow 子容器。

10.2.5 WdgSettingsFast

10.2.6 WdgSettingsSlow

10.2.7 WdgSettingsOff

10.2.8 WdgExternalConfiguration

10.3 发布信息（Published information）

10.3.1 WdgPublishedInformation

发布信息包含可在集成时使用的标准 AUTOSAR 公开信息：

• WdgVersionInfo（版本号）；
• 支持的配置变体（PreCompile / LinkTime / PostBuild）；
• 支持的错误码列表。

11 未应用需求（Not applicable requirements）

本节列出来自 AUTOSAR_SRS_WatchdogDriver 但在本 SWS 中不直接对应的需求（标 N/A）：

• [SRS_Wdg_12163] 驱动模块去初始化——由于安全原因与大多数看门狗硬件不支持关闭，看门狗驱动不提供 DeInit 函数；
• [SRS_Wdg_12106] 看门狗不可禁用——仅在配置 WdgDisableAllowed=false 时强制；