F´（F Prime）飞行软件框架中的 Svc::WatchDog 端口：原理、FPP 定义与在健康检查（Health）组件中的应用

F´（F Prime）飞行软件框架中的 Svc::WatchDog 端口：原理、FPP 定义与在健康检查（Health）组件中的应用

【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime

Svc::WatchDog 是 F´（F Prime）飞行软件与嵌入式系统框架中用于“喂狗”（stroking a watchdog timer）的核心端口：健康检查组件（Svc::Health）在每个调度周期通过它向系统看门狗定时器发送喂狗码，以此表明系统仍然响应、未发生挂死（hang）。本文基于 Svc/WatchDog/docs/sdd.md 展开，结合 WatchDog.fpp 的端口定义与 Health 组件的实现，完整讲解该端口的接口契约、设计动机、参数语义及其在真实拓扑中的调用链，帮助你理解并正确使用这一看门狗机制。

Svc::WatchDog 端口框图

1. 端口概述（Introduction）

Svc::WatchDog端口用于向激活组件（active components）发送“心跳”信号，从而验证系统内的激活组件仍然可响应、没有挂起。其端口注释在源码中写得很直白：Port for stroking a watchdog timer（用于刷新看门狗定时器的端口），见 Svc/WatchDog/WatchDog.fpp。

在实际飞行软件中，“组件未响应”往往是灾难性的：某个激活组件因死锁、无限循环或任务栈溢出而挂死，会导致整个任务链停止推进。Svc::WatchDog端口就是这类健康监控体系的出口——它负责把“我还活着”的信号送给外部的看门狗硬件或监控实体，一旦信号缺失，外部看门狗可以复位系统或触发安全处置。

需要特别指出的是：Svc::WatchDog端口本身并不承担故障检测逻辑，它只是一个单向的喂狗输出接口；真正判断“谁还活着、谁已挂死”的是配套的 Svc::Ping 端口与Svc::Health健康检查组件。两者配合构成了 F´ 中的“Ping + 喂狗”健康监控闭环，这一点在下一节展开。

2. 设计（Design）

2.1 工作机制：Ping 应答 + 周期喂狗

根据 Svc/WatchDog/docs/sdd.md 的设计说明，系统中的健康检查组件（Health）持有一组 Ping 输出端口，向各激活组件周期发送 Ping 消息；激活组件必须在一个超时窗口内，把端口参数key中携带的值原样应答回来。Health 组件据此判断每个目标是否仍然响应。

而Svc::WatchDog端口承担的角色是“看门狗刷新”：Health 组件在完成一轮 Ping 检查之后，通过WdogStroke输出端口向外发送一次喂狗码（watchdog stroke code）。只要健康检查逻辑仍在按周期运行，喂狗信号就会持续产生；反之，若 Health 组件自身也挂死或调度中断，喂狗停止，外部看门狗便会被触发。

这一机制可以从 Svc/Health/Health.fpp 的端口声明中看到：

@ Ping output port output port PingSend: [HealthPingPorts] Svc.Ping @ Ping return port async input port PingReturn: [HealthPingPorts] Svc.Ping @ Run port sync input port Run: Svc.Sched @ Run port output port WdogStroke: Svc.WatchDog

其中WdogStroke: Svc.WatchDog即Svc::WatchDog端口在 Health 组件中的实例化名称，match PingSend with PingReturn声明了 Ping 发送与返回端口的配对关系。

2.2 端口参数

Svc::WatchDog端口只有一个参数：

该参数在 WatchDog.fpp 中的完整定义与注释为：

@ Port for stroking a watchdog timer port WatchDog( code: U32 @< Watchdog stroke code )

其中code是一个 32 位无符号整数的喂狗码。从实际实现看，Health 组件内部维护一个喂狗码成员m_watchDogCode，每次喂狗时将该值原样传给端口；对于外部看门狗而言，这个码既可以用于校验喂狗序列的正确性（防止误触发），也可以被忽略、仅当作固定占位值使用，具体取决于系统接入的看门狗实现。

2.3 串行化（Serializables）

Svc::WatchDog端口不定义任何序列化类型（Serializables），文档中明确标注 “There are no serializables defined in the port”。其唯一的U32参数直接通过 FPP 自动生成的端口调用机制传递，无需额外的数据结构定义。

3. 在 Health 组件中的真实调用链

要真正理解Svc::WatchDog端口如何使用，最直接的方式是阅读它的消费方——Svc::Health组件实现 Svc/Health/HealthComponentImpl.cpp。

在每个调度周期（Run端口被触发）中，Health 组件会依次执行 Ping 检查逻辑，然后在周期末尾执行喂狗：

// health check for each ping entry ... // (遍历各 Ping 目标，判断是否超时、是否应答错误 key) // stroke watchdog. if (this->isConnected_WdogStroke_OutputPort(0)) { this->WdogStroke_out(0, this->m_watchDogCode); }

见 Svc/Health/HealthComponentImpl.cpp#L131-L134。这段实现透露了三个关键点：

1. 喂狗发生在健康检查周期末尾：只要Run周期持续驱动 Health 组件，喂狗信号就会随之持续产生，因此喂狗本身也间接验证了 Health 组件与整个调度链的健康状态。
2. 端口连接检查：调用前通过isConnected_WdogStroke_OutputPort(0)判断端口是否已连接，未连接时静默跳过，避免在未装配看门狗的系统上产生无效调用。
3. 喂狗码来源：喂狗码为成员变量m_watchDogCode（U32），在每轮喂狗中原样发出，体现 “stroke code” 的语义。

同时注意，Ping 检查自身的超时判定（如warnCycles警告阈值、fatalCycles致命阈值，见 Svc/Health/Health.fpp 中HLTH_PING_WARN、HLTH_PING_LATE、HLTH_PING_WRONG_KEY等事件）与喂狗是相互独立的两条路径：Ping 负责“发现”挂死的组件，WatchDog 负责“报告”整体心跳。

3.1 Health 组件中的完整端口角色分工

从 Health.fpp 可以梳理出 WatchDog 端口在健康监控体系中的位置：

• PingSend（输出，Svc.Ping）：向被监控的激活组件发起 Ping，携带递增的key；
• PingReturn（输入，Svc.Ping）：接收激活组件应答的key，用于校验其是否仍响应；
• WdogStroke（输出，Svc.WatchDog）：周期喂狗，通知外部看门狗系统仍健康。

Health 组件还提供命令HLTH_ENABLE、HLTH_PING_ENABLE、HLTH_CHNG_PING用于动态启停健康检查、启停单个 Ping 条目、调整警告/致命超时阈值，配合事件与遥测（如PingLateWarnings）形成一套完整的可运维健康监控能力。这些命令与事件均定义于 Svc/Health/Health.fpp。

Health 健康检查组件端口关系图

3.2 典型的系统拓扑接线方式

在实际 F´ 拓扑中（例如参考部署 TestDeploymentsProject/Ref 中的健康监控接线），Svc::WatchDog端口通常由以下方式之一消费：

• 连接到一个看门狗驱动组件（如外部硬件看门狗定时器的驱动），将code值写入硬件寄存器完成喂狗；
• 连接到一个监控/遥测组件，把喂狗事件作为系统存活指示上报；
• 在未装配看门狗硬件的开发/测试平台上，可以保持该端口悬空——Health 组件已通过isConnected_WdogStroke_OutputPort做了容错处理。

由于Svc::WatchDog与 Svc::Ping 都是单向简单端口，接线时只需将 Health 的WdogStroke输出端口与目标组件的 WatchDog 输入端口一一对应即可，端口名WatchDog即作为连接标识。

4. 构建集成（CMake）

Svc::WatchDog端口作为一个独立的 F´ 模块随源码树分发，其构建配置见 Svc/WatchDog/CMakeLists.txt：

register_fprime_module( AUTOCODER_INPUTS "${CMAKE_CURRENT_LIST_DIR}/WatchDog.fpp" DEPENDS Fw_Port )

要点说明：

• AUTOCODER_INPUTS指向 WatchDog.fpp，由 FPP 自动代码生成器（autocoder）在构建时生成端口的 C++ 调用接口（如WatchDog_out、isConnected_WatchDog_OutputPort等）；
• DEPENDS声明对Fw_Port的依赖，即端口基础设施（Fw::Port基类体系，见 Fw/Port）；
• 在使用该端口时，只需在组件 FPP 中声明output port或input port并正确接线，随后将相关模块加入 CMake 构建即可，无需手写任何端口胶水代码。

5. 变更日志（Change Log）

原文档记录的修订历史如下：

Svc::WatchDog端口的接口自初始版本以来保持稳定：单个U32 code参数、无序列化类型的契约一直延续至今，这保证了基于该端口的拓扑设计与驱动实现具有良好的向后兼容性。

6. 小结：何时使用 Svc::WatchDog

• 使用场景：系统需要向外部看门狗（硬件或软件监控实体）周期上报“系统存活”信号，且该信号应由健康检查逻辑统一驱动；
• 搭配使用：与Svc::Ping、Svc::Health组件配合，形成“Ping 检测组件响应 + WatchDog 上报整体心跳”的双层健康监控；
• 参数语义：code为喂狗码，由调用方（如 Health 的m_watchDogCode）决定具体取值，外部看门狗可据此校验喂狗序列；
• 实现成本：端口仅含一个 U32 参数，无序列化类型，接线与使用极为轻量，且 Health 组件对未连接端口做了容错，即使暂未接入真实看门狗也不会影响系统运行。

如需进一步阅读，可参考端口定义源码 Svc/WatchDog/WatchDog.fpp、消费方实现 Svc/Health/HealthComponentImpl.cpp 及其组件定义 Svc/Health/Health.fpp，以及配套的 Svc::Ping 端口文档。

【免费下载链接】fprimeF´ - A flight software and embedded systems framework项目地址: https://gitcode.com/GitHub_Trending/fpr/fprime