/*
 * 模块名称：Task Watchdog（IWDG + 任务心跳位图）
 * 模块功能：独立看门狗与"全部任务存活"绑定的对外接口
 * 适用平台：STM32F407ZGTx + FreeRTOS（CMSIS-RTOS V2）
 * 作者：王建锋
 * 创建日期：2026-09-29
 * 修改记录：
 *   v1.0  2026-09-29  王建锋  创建
 *
 * 设计依据：docs/子系统设计/看门狗设计说明.md
 */

#ifndef TASK_WATCHDOG_H
#define TASK_WATCHDOG_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * 任务 ID（位序号 = 心跳位图上的位置，与必需掩码一一对应）
 * 顺序一旦确定不要插空/改动，掩码是编译期常量
 */
typedef enum {
    TASK_WD_DEFAULT  = 0,
    TASK_WD_NET      = 1,
    TASK_WD_FTP      = 2,
    TASK_WD_TEST     = 3,
    TASK_WD_UI       = 4,
    TASK_WD_TIMESYNC = 5,
    TASK_WD_ID_MAX
} task_wd_id_t;

/*
 * 函数功能：任务心跳置位（各任务在自己主循环里调用）
 * 入口参数：id - 任务 ID
 * 返回值：无
 * 限定条件：任意上下文可调（单字原子写、无内核对象依赖）
 * 函数说明：仅 1~2 条指令，无锁、无阻塞，可放在中断外任意位置。
 */
void task_wd_beat(task_wd_id_t id);

/*
 * 函数功能：启动 IWDG（**延后启动**）
 * 入口参数：无
 * 返回值：无
 * 限定条件：仅 defaultTask 在存储 bring-up 完成后调用一次
 * 函数说明：MX_IWDG_Init() 只填参数不启动（原因见 Src/iwdg.c 的
 *          IWDG_DEFER_START 注释：HAL_IWDG_Init 内部会立即启动，而它被
 *          CubeMX 插在 app_main_init 之前，那段无喂狗点且耗时可达数秒）。
 *          本函数才真正启动，使"启动段不喂狗、主循环段才喂"成立。
 */
void task_wd_start(void);

/*
 * 函数功能：心跳抽样与喂狗判定
 * 入口参数：无
 * 返回值：无
 * 限定条件：仅 defaultTask 主循环调用（唯一喂狗者）
 * 函数说明：内部节流至 100ms 一次。全员到位才喂狗；连续 800ms 有任务
 *          缺席则停止喂狗，由 IWDG 自然溢出复位（保留 IWDGRSTF 权威归因）。
 */
void task_wd_poll(void);

/* 观测接口（自检 / 串口报告用） */
uint32_t task_wd_last_mask(void);      /* 上次抽样到的位图（0 位 = 缺席任务） */
uint32_t task_wd_miss_count(void);     /* 累计未达标轮数 */
uint32_t task_wd_is_armed(void);       /* 1 = IWDG 已启动 */

#ifdef __cplusplus
}
#endif

#endif /* TASK_WATCHDOG_H */