docs: 新增 Watchdog 驱动与 STM32 看门狗代码生成的文档

Author: Jiu-xiao

docs/basic_coding/driver/watchdog.md

@@ -0,0 +1,55 @@
+---
+id: watchdog
+title: 看门狗
+sidebar_position: 11
+---
+
+# Watchdog（看门狗）
+
+`LibXR::Watchdog` 提供通用看门狗（Watchdog）抽象接口，支持配置溢出时间、自动喂狗周期等参数，并提供启动、停止和手动喂狗等控制接口，适配多线程和定时任务等不同运行环境。
+
+## 接口概览
+
+### 配置结构体
+
+```cpp
+struct Configuration {
+  uint32_t timeout_ms;  // 看门狗溢出时间（毫秒）
+  uint32_t feed_ms;     // 自动喂狗周期（毫秒）
+};
+```
+
+### 构造与配置
+
+```cpp
+Watchdog();
+virtual ~Watchdog();
+
+virtual ErrorCode SetConfig(const Configuration& config) = 0;
+```
+
+### 控制接口
+
+```cpp
+virtual ErrorCode Start() = 0;
+virtual ErrorCode Stop() = 0;
+virtual ErrorCode Feed() = 0;
+```
+
+### 自动喂狗辅助函数
+
+```cpp
+static void ThreadFun(Watchdog* wdg);
+static void TaskFun(Watchdog* wdg);
+```
+
+- `ThreadFun`：用于线程环境中的自动喂狗循环；
+- `TaskFun`：适用于定时轮询任务系统中的自动喂狗函数。
+
+## 特性总结
+
+- 支持设置溢出时间与自动喂狗周期；
+- 提供手动 `Feed` 接口与自动喂狗辅助函数；
+- 适用于多种嵌入式运行模型（如 RTOS 线程、定时任务）；
+- 平台无关，便于在不同硬件平台上统一使用；
+- 可扩展，派生类实现具体底层驱动逻辑。

docs/code_gen/stm32/watchdog.md

@@ -0,0 +1,68 @@
+---
+
+id: stm32-code-gen-watchdog
+title: 看门狗
+sidebar_position: 11
+---
+
+
+# 看门狗
+
+LibXR 支持 **STM32 独立看门狗（IWDG）** 的自动管理，包括定时喂狗任务或独立线程。推荐所有产品固件启用硬件看门狗，以提升系统可靠性。
+
+## 基本说明
+
+* 支持 IWDG 实例自动生成代码与配置。
+* 可选自动喂狗方式：**定时任务** 或 **独立线程**，适配裸机/RTOS。
+* 可通过 YAML 配置自定义喂狗周期、线程栈、优先级等参数。
+
+## 看门狗代码示例
+
+```cpp
+// 创建并初始化看门狗实例
+STM32Watchdog iwdg1(&hiwdg1, 1000, 250); // 溢出 1s，喂狗周期 250ms
+
+// 自动喂狗（方式一：作为定时任务，适合裸机或简单轮询）
+auto iwdg1_task = Timer::CreateTask(iwdg1.TaskFun, reinterpret_cast<LibXR::Watchdog *>(&iwdg1), 250);
+Timer::Add(iwdg1_task);
+Timer::Start(iwdg1_task);
+
+// 自动喂狗（方式二：作为线程，适合 RTOS）
+LibXR::Thread iwdg1_thread;
+iwdg1_thread.Create(reinterpret_cast<LibXR::Watchdog *>(&iwdg1), iwdg1.ThreadFun, "iwdg1_wdg", 1024,
+                   static_cast<LibXR::Thread::Priority>(3));
+```
+
+## 配置文件说明
+
+通过配置文件灵活控制看门狗行为：
+
+```yaml
+# IWDG 外设启用与参数
+IWDG:
+  iwdg1:
+    timeout_ms: 1000   # 溢出超时时间（毫秒）
+    feed_ms: 250       # 喂狗周期（毫秒）
+
+# Watchdog 相关全局配置
+Watchdog:
+  RunAsThread: true         # 是否作为线程运行（否则定时任务）
+  ThreadStackDepth: 1024    # 线程栈深度（仅在线程下有效）
+  ThreadPriority: 3         # 线程优先级（仅在线程下有效）
+  FeedInterval: 250         # 定时任务喂狗周期（毫秒，默认250）
+```
+
+> * 若 `RunAsThread: true`，则每个启用的 IWDG 会自动生成线程，线程参数可全局配置。
+> * 若 `RunAsThread: false`，则采用定时任务方式喂狗。
+
+## 生成代码命令
+
+修改 `.config.yaml` 后，重新生成代码：
+
+```bash
+xr_gen_code_stm32 -i ./.config.yaml -o ./User/app_main.cpp
+```
+
+## 注意事项
+
+STM32CubeMX生成的MX_IWDG_Init()会直接使能看门狗，而且除了复位无法关闭和重新配置。可以在CubeMX中的Project Manager->Advanced Settings中关闭此函数的生成和调用

i18n/en/docusaurus-plugin-content-docs/current/basic_coding/driver/watchdog.md

@@ -0,0 +1,55 @@
+---
+id: watchdog
+title: Watchdog
+sidebar_position: 11
+---
+
+# Watchdog
+
+`LibXR::Watchdog` provides a general-purpose abstract interface for watchdog functionality. It supports configuring the overflow timeout, auto-feed interval, and provides control methods like start, stop, and manual feeding. It is suitable for multi-threaded environments or timer-based task scheduling systems.
+
+## Interface Overview
+
+### Configuration Structure
+
+```cpp
+struct Configuration {
+  uint32_t timeout_ms;  // Watchdog overflow time (milliseconds)
+  uint32_t feed_ms;     // Auto-feed interval (milliseconds)
+};
+```
+
+### Constructor and Configuration
+
+```cpp
+Watchdog();
+virtual ~Watchdog();
+
+virtual ErrorCode SetConfig(const Configuration& config) = 0;
+```
+
+### Control Interface
+
+```cpp
+virtual ErrorCode Start() = 0;
+virtual ErrorCode Stop() = 0;
+virtual ErrorCode Feed() = 0;
+```
+
+### Auto-Feed Helper Functions
+
+```cpp
+static void ThreadFun(Watchdog* wdg);
+static void TaskFun(Watchdog* wdg);
+```
+
+- `ThreadFun`: Used in threaded environments for continuous auto-feeding;
+- `TaskFun`: Used in polling/timer task systems for periodic auto-feeding.
+
+## Feature Summary
+
+- Supports configurable overflow timeout and auto-feed interval;
+- Provides manual `Feed` function and auto-feed helpers;
+- Suitable for various embedded execution models such as RTOS threads or timer tasks;
+- Platform-independent, allowing unified usage across different hardware;
+- Easily extendable, with implementation-specific logic in derived classes.

i18n/en/docusaurus-plugin-content-docs/current/code_gen/stm32/watchdog.md

@@ -0,0 +1,66 @@
+---
+id: stm32-code-gen-watchdog
+title: Watchdog
+sidebar_position: 11
+---
+
+# Watchdog
+
+LibXR supports automatic management of **STM32 Independent Watchdog (IWDG)**, including scheduled feed tasks or dedicated threads. It is recommended to enable hardware watchdogs in all production firmware to improve system reliability.
+
+## Overview
+
+* Supports automatic code generation and configuration for IWDG instances.
+* Two auto-feed modes: **timer task** or **dedicated thread**, suitable for bare-metal or RTOS.
+* Behavior can be customized via YAML config (feed period, thread stack, priority, etc).
+
+## Watchdog Code Example
+
+```cpp
+// Create and initialize watchdog instance
+STM32Watchdog iwdg1(&hiwdg1, 1000, 250); // 1s timeout, feed interval 250ms
+
+// Auto-feed (Option 1: as timer task, good for bare-metal or simple polling)
+auto iwdg1_task = Timer::CreateTask(iwdg1.TaskFun, reinterpret_cast<LibXR::Watchdog *>(&iwdg1), 250);
+Timer::Add(iwdg1_task);
+Timer::Start(iwdg1_task);
+
+// Auto-feed (Option 2: as thread, suitable for RTOS)
+LibXR::Thread iwdg1_thread;
+iwdg1_thread.Create(reinterpret_cast<LibXR::Watchdog *>(&iwdg1), iwdg1.ThreadFun, "iwdg1_wdg", 1024,
+                   static_cast<LibXR::Thread::Priority>(3));
+```
+
+## Configuration File
+
+Configure watchdog behavior via `.config.yaml`:
+
+```yaml
+# IWDG instance and parameters
+IWDG:
+  iwdg1:
+    timeout_ms: 1000   # Timeout in milliseconds
+    feed_ms: 250       # Feed interval in milliseconds
+
+# Global watchdog options
+Watchdog:
+  RunAsThread: true         # Whether to run as thread (otherwise uses timer)
+  ThreadStackDepth: 1024    # Stack size for thread (only effective if thread enabled)
+  ThreadPriority: 3         # Thread priority (only effective if thread enabled)
+  FeedInterval: 250         # Feed interval in ms for timer mode (default 250)
+```
+
+> * If `RunAsThread: true`, each enabled IWDG generates a thread; thread parameters are global.
+> * If `RunAsThread: false`, each watchdog uses a periodic timer task.
+
+## Code Generation Command
+
+After editing `.config.yaml`, regenerate the code:
+
+```bash
+xr_gen_code_stm32 -i ./.config.yaml -o ./User/app_main.cpp
+```
+
+## Notes
+
+The `MX_IWDG_Init()` function generated by STM32CubeMX will enable the watchdog immediately, and it cannot be reconfigured or disabled except by reset. You can disable this function's generation and call in CubeMX under **Project Manager → Advanced Settings**.