STM32F4-Base/App/algo/adc_health.c

/*
 * 模块名称：ADC 采样有效性校验（L1 采集与预处理，规划项 L1-6）
 * 模块功能：见 adc_health.h 文件头。本文件为**纯逻辑实现**：输入计数快照、
 *          输出故障位/事件位，零平台依赖（仅 stdint.h/string.h 标准 C）→
 *          主机侧免桩单测。
 * 适用平台：STM32F407ZGTx + TPAFE5160
 * 作者：王建锋
 * 创建日期：2026-10-11
 * 修改记录：
 *   v1.0  2026-10-11  王建锋  创建：L1-6 采样有效性校验
 *   v1.1  2026-10-21  王建锋  新增 adc_health_age_stale()：无模块状态的帧年龄
 *                             纯判据（参照系由调用方自存），供 protectTask 的
 *                             兜底新鲜度门使用，见 adc_health.h 同名声明
 *   v1.2  2026-10-25  DTU 项目组  新增 L5-2 残余：码值越界（贴轨）观察器
 *                             （rail_watch/rail_sticky/rail_init），判据与释放
 *                             沿理由见 adc_health.h L5-2 段注释
 */

#include "adc_health.h"

#include <string.h>   /* memset（L5-2 贴轨观察器数组复位） */

/* ===================== 内部状态 ===================== */

/* 基线是否已建立：首次 check() 只记基线、不判定（开机首拍无参照系） */
static uint8_t s_primed;

/* 上次看到的计数（差值法判"有无前进"，回绕安全） */
static uint32_t s_tpafe_seq;
static uint32_t s_tpafe_frst;
static uint32_t s_stm32_seq;
static uint32_t s_stm32_errs;
static uint32_t s_stm32_gaps;
static uint32_t s_stm32_hw;

/* 两侧"最后一次看到序号前进"的时刻（判静默） */
static uint32_t s_tpafe_adv_ms;
static uint32_t s_stm32_adv_ms;

/* 故障位 */
static uint32_t s_flags;    /* 电平位（stall 可自愈；backward 锁存在此） */
static uint32_t s_sticky;   /* 锁存位（含电平位历史并集） */
static uint32_t s_tpafe_gaps;

/* L5-2 贴轨观察器（每通道独立小状态机，单写者 = adcTask） */
typedef struct {
    uint16_t run_hi;    /* 连续贴上轨计数（饱和 0xFFFF） */
    uint16_t run_lo;    /* 连续贴下轨计数 */
    uint8_t  seen_mid;  /* 见过中带样本（释放沿）——锁存的必要前提 */
    uint8_t  latched;   /* 已报过边沿（不重复报） */
} adc_rail_t;

static adc_rail_t s_rail[ADC_RAIL_CH_NUM];
static uint32_t   s_rail_sticky;

/* ===================== 对外接口 ===================== */

/*
 * 函数功能：采样有效性校验初始化（幂等）
 * 入口参数：无
 * 返 回 值：无
 * 限定条件：无（内核启动前可调）
 * 函数说明：清全部内部状态；判定从下一次 check() 的首拍基线重新开始。
 */
void adc_health_init(void) {
    adc_health_rail_init();
    s_primed = 0u;
    s_tpafe_seq = 0u;
    s_tpafe_frst = 0u;
    s_stm32_seq = 0u;
    s_stm32_errs = 0u;
    s_stm32_gaps = 0u;
    s_stm32_hw = 0u;
    s_tpafe_adv_ms = 0u;
    s_stm32_adv_ms = 0u;
    s_flags = 0u;
    s_sticky = 0u;
    s_tpafe_gaps = 0u;
}

/*
 * 函数功能：按计数快照做一次有效性判定
 * 入口参数：in  - 计数快照；NULL 则本次跳过（out 不动）
 *           out - 判定结果；NULL 则仅更新内部状态
 * 返 回 值：无
 * 限定条件：仅任务上下文（与 adc_input_poll() 同节奏，每拍一次）
 * 函数说明：判定顺序 = 建基线 → 序号差值（倒退/丢帧/前进）→ 静默时长 →
 *          错误计数增量。events 仅本次有效；flags/sticky 为持续状态。
 */
void adc_health_check(const adc_health_in_t *in, adc_health_status_t *out) {
    uint32_t events = 0u;

    if (in == 0) {
        return;
    }

    /* 1) 首拍基线：只记录，不判定（开机时序号已非 0，无"上一拍"参照） */
    if (s_primed == 0u) {
        s_primed = 1u;
        s_tpafe_seq = in->tpafe_seq;
        s_tpafe_frst = in->tpafe_frst_err;
        s_stm32_seq = in->stm32_seq;
        s_stm32_errs = in->stm32_errs;
        s_stm32_gaps = in->stm32_gaps;
        s_stm32_hw = in->stm32_hw_errs;
        s_tpafe_adv_ms = in->now_ms;
        s_stm32_adv_ms = in->now_ms;
    } else {
        uint32_t d;   /* 序号差值（两侧共用，cppcheck：作用域收在本块） */

        /* 2) TPAFE 序号差值：倒退 = 单调性破坏（锁存）；>1 = 丢帧（事件 + 计数） */
        d = in->tpafe_seq - s_tpafe_seq;
        if ((int32_t)d < 0) {
            s_flags |= ADC_HF_SEQ_BACKWARD;
            s_sticky |= ADC_HF_SEQ_BACKWARD;
            s_tpafe_seq = in->tpafe_seq;   /* 重新对齐，避免持续误判 */
            s_tpafe_adv_ms = in->now_ms;
        } else {
            if (d > 1u) {
                s_tpafe_gaps += (d - 1u);
                events |= ADC_HE_TPAFE_GAP;
            }
            if (d >= 1u) {
                s_tpafe_seq = in->tpafe_seq;
                s_tpafe_adv_ms = in->now_ms;
            }
        }

        /* 3) STM32 序号差值：同一口径（gap 计数在 adc_input 侧另有细账，
         *    这里只取"前进/倒退/静默"三态，避免两处判据打架） */
        d = in->stm32_seq - s_stm32_seq;
        if ((int32_t)d < 0) {
            s_flags |= ADC_HF_SEQ_BACKWARD;
            s_sticky |= ADC_HF_SEQ_BACKWARD;
            s_stm32_seq = in->stm32_seq;
            s_stm32_adv_ms = in->now_ms;
        } else if (d >= 1u) {
            s_stm32_seq = in->stm32_seq;
            s_stm32_adv_ms = in->now_ms;
        }

        /* 4) 静默判定（电平位，可自愈）：距最后一次前进 >= 门限 */
        if ((uint32_t)(int32_t)(in->now_ms - s_tpafe_adv_ms) >= ADC_HEALTH_STALL_MS) {
            s_flags |= ADC_HF_TPAFE_STALL;
            s_sticky |= ADC_HF_TPAFE_STALL;
        } else {
            s_flags &= ~ADC_HF_TPAFE_STALL;
        }
        if ((uint32_t)(int32_t)(in->now_ms - s_stm32_adv_ms) >= ADC_HEALTH_STALL_MS) {
            s_flags |= ADC_HF_STM32_STALL;
            s_sticky |= ADC_HF_STM32_STALL;
        } else {
            s_flags &= ~ADC_HF_STM32_STALL;
        }

        /* 5) 错误计数增量（事件 + 锁存）：三类计数正常应恒为 0 增量 */
        if (in->tpafe_frst_err != s_tpafe_frst) {
            events |= ADC_HE_FRSTDATA;
            s_sticky |= ADC_HF_FRSTDATA;
            s_tpafe_frst = in->tpafe_frst_err;
        }
        if (in->stm32_errs != s_stm32_errs) {
            events |= ADC_HE_STM32_ERR;
            s_sticky |= ADC_HF_STM32_ERR;
            s_stm32_errs = in->stm32_errs;
        }
        if (in->stm32_gaps != s_stm32_gaps) {
            events |= ADC_HE_STM32_GAP;
            s_stm32_gaps = in->stm32_gaps;
        }
        if (in->stm32_hw_errs != s_stm32_hw) {
            events |= ADC_HE_HW_ERR;
            s_sticky |= ADC_HF_HW_ERR;
            s_stm32_hw = in->stm32_hw_errs;
        }
    }

    if (out != 0) {
        out->flags = s_flags;
        out->events = events;
        out->sticky = s_sticky;
        out->tpafe_gaps = s_tpafe_gaps;
        out->tpafe_stall_ms =
            ((s_flags & ADC_HF_TPAFE_STALL) != 0u)
                ? (uint32_t)(int32_t)(in->now_ms - s_tpafe_adv_ms)
                : 0u;
    }
}

/*
 * 函数功能：帧年龄判定（无模块状态，保护侧兜底门专用）
 * 入口参数：见 adc_health.h 同名声明
 * 返 回 值：1 - 已陈旧；0 - 新鲜或仍在建立基线
 * 限定条件：任意任务上下文；不读写本模块任何 static（与 check() 的关键区别）
 * 函数说明：三步——建基线 → 有前进即刷新参照系 → 原地不动才量"距最后一次前进"。
 *          倒退也按"有变化"处理（本函数不判单调性，那归 ADC_HF_SEQ_BACKWARD）。
 */
uint8_t adc_health_age_stale(adc_health_age_t *a_p_age, uint32_t a_cur_seq,
                             uint32_t a_now_ms, uint32_t a_age_ms) {
    if (a_p_age == 0) {
        return 0u;
    }

    /* 1) 首拍建基线：此刻序号往往已非 0（TIM3 比调度器早约 100 ms 就在生产帧），
     *    没有"上一拍"就没有参照系——开机窗口内绝不允许把保护锁掉 */
    if (a_p_age->primed == 0u) {
        a_p_age->primed = 1u;
        a_p_age->seq    = a_cur_seq;
        a_p_age->adv_ms = a_now_ms;
        return 0u;
    }

    /* 2) 有任何前进（含跨多帧、含跨回绕、含倒退）即算新鲜，并刷新参照系 */
    if (a_cur_seq != a_p_age->seq) {
        a_p_age->seq    = a_cur_seq;
        a_p_age->adv_ms = a_now_ms;
        return 0u;
    }

    /* 3) 序号原地不动：只看"距最后一次前进多久"，含等号（与 stall 判据同边界） */
    if ((uint32_t)(int32_t)(a_now_ms - a_p_age->adv_ms) >= a_age_ms) {
        return 1u;
    }
    return 0u;
}

/*
 * 函数功能：读当前电平故障位
 * 入口参数：无
 * 返 回 值：见 adc_health.h ADC_HF_TPAFE_STALL/STM32_STALL/SEQ_BACKWARD
 * 限定条件：无
 * 函数说明：与 check() 出参 flags 同源。
 */
uint32_t adc_health_flags(void) {
    return s_flags;
}

/*
 * 函数功能：读锁存故障位
 * 入口参数：无
 * 返 回 值：电平位 + FRSTDATA/STM32_ERR/HW_ERR 的并集
 * 限定条件：无
 * 函数说明：出现过即留痕，直到 adc_health_init() 才清。
 */
uint32_t adc_health_sticky(void) {
    return s_sticky;
}

/*
 * 函数功能：读 TPAFE 累计丢帧点数
 * 入口参数：无
 * 返 回 值：序号前进 >1 的超出部分累计
 * 限定条件：无
 * 函数说明：与 STM32 侧 adc_input_stm32_gaps() 对称的 TPAFE 侧细账。
 */
uint32_t adc_health_tpafe_gaps(void) {
    return s_tpafe_gaps;
}

/* ===================== L5-2 贴轨观察器实现 ===================== */

/*
 * 函数功能：贴轨观察器复位（幂等；adc_health_init() 已内含）
 * 入口参数：无
 * 返 回 值：无
 * 限定条件：与 check() 同为单写者任务上下文
 */
void adc_health_rail_init(void) {
    (void)memset(s_rail, 0, sizeof(s_rail));
    s_rail_sticky = 0u;
}

/*
 * 函数功能：单通道单拍贴轨观察（判据与释放沿前提见 adc_health.h 同名声明）
 * 入口参数：ch / code / lo_th / hi_th - 见 adc_health.h
 * 返 回 值：1 - 本拍新锁存（边沿）；0 - 无新事件（含 ch 越界忽略）  uint32_t
 * 限定条件：每拍每通道至多一次；纯算术、零平台依赖
 */
uint32_t adc_health_rail_watch(uint8_t ch, int32_t code, int32_t lo_th, int32_t hi_th) {
    adc_rail_t *p;

    if (ch >= (uint8_t)ADC_RAIL_CH_NUM) {
        return 0u;
    }
    p = &s_rail[ch];

    if (code >= hi_th) {                    /* 贴上轨带：清对侧计数 */
        p->run_lo = 0u;
        if (p->run_hi < 0xFFFFu) {
            p->run_hi++;
        }
        if ((p->run_hi >= (uint16_t)ADC_RAIL_N_RUN) && (p->seen_mid != 0u)
                && (p->latched == 0u)) {
            p->latched = 1u;
            s_rail_sticky |= (1uL << ch);
            return 1u;
        }
        return 0u;
    }
    if (code <= lo_th) {                    /* 贴下轨带（对称） */
        p->run_hi = 0u;
        if (p->run_lo < 0xFFFFu) {
            p->run_lo++;
        }
        if ((p->run_lo >= (uint16_t)ADC_RAIL_N_RUN) && (p->seen_mid != 0u)
                && (p->latched == 0u)) {
            p->latched = 1u;
            s_rail_sticky |= (1uL << ch);
            return 1u;
        }
        return 0u;
    }
    /* 中带：记释放沿（锁存的必要前提），并清两侧连续计数 */
    p->seen_mid = 1u;
    p->run_hi = 0u;
    p->run_lo = 0u;
    return 0u;
}

/*
 * 函数功能：读贴轨锁存位图
 * 入口参数：无
 * 返 回 值：bit ch = 曾检出贴轨（低 9 位有效）  uint32_t
 * 限定条件：无
 */
uint32_t adc_health_rail_sticky(void) {
    return s_rail_sticky;
}