Doxygen 在嵌入式软件开发中的深度应用(下)：从基础到无人机电调 / 汽车 FOC 控制器实战

6. 初始化软件看门狗（独立于系统看门狗）；

• 1. 设置初始安全模式为正常模式
• @note 1. 初始化必须在系统启动后优先执行，确保安全监控覆盖所有模块；
• 1. 配置参数需通过功能安全验证，不可随意修改（如 core_check_timeout 需≤100μs）；
• 1. 若 Flash 故障存储区初始化失败，故障存储功能禁用，但安全监控仍正常工作*/int32_t safe_smu_init (SafeSmuHandleType *smu, const SafeSmuConfigType *config);

/*!

• @brief 双核心互检数据同步
• @param [in,out] smu 安全监控句柄指针
• @param [in] core_id 核心 ID（0 - 主核心，1 - 从核心）
• @param [in] data 互检数据数组（8 个 32 位数据，包含核心状态、关键算法参数）
• @return 同步结果
• @retval 0：同步成功
• @retval -1：参数错误（smu 为 NULL、core_id 非法、data 为 NULL）
• @retval -2：未初始化
• @safety 双核心互检是 ASIL-B 等级的关键安全机制，确保核心间数据一致性：
• 1. 主核心同步电机转矩指令、电流环参数；
• 1. 从核心同步故障诊断结果、硬件状态；
• 1. 互检数据采用 CRC32 校验，避免数据传输错误
• @note 1. 该函数需由两个核心周期性调用（周期≤core_check_timeout）；
• 1. 若超过 core_check_timeout 未收到对方数据，触发核心互检超时故障；
• 1. 数据不一致时，触发核心互检失败故障，进入跛行模式*/int32_t safe_smu_core_sync (SafeSmuHandleType *smu, uint8_t core_id, const uint32_t data [8]);

/*!

• @brief 硬件自校验（指定诊断类型）
• @param [in,out] smu 安全监控句柄指针
• @param [in] diag_type 硬件诊断类型
• @return 校验结果
• @retval 0：校验通过
• @retval -1：参数错误（smu 为 NULL 或 diag_type 非法）
• @retval -2：未初始化
• @retval -3：校验失败（硬件故障）
• @details 各诊断类型的校验逻辑：
• 1. ADC 自校验：通过内部参考电压校准，检查采样精度误差≤±1%；
• 1. GPIO 故障检测：检测 IGBT 驱动使能引脚、安全关断引脚的电平状态合法性；
• 1. CAN FD 通信诊断：发送测试帧并接收响应，检查通信延迟≤100μs；
• 1. IGBT 驱动诊断：读取 IGBT 温度、过流反馈信号，检查信号有效性；
• 1. 电源监控诊断：检测 3.3V、5V、12V 电源轨电压，偏差≤±5%
• @safety 硬件自校验覆盖率≥90%，符合 ASIL-B 对故障诊断的要求
• @note 1. 关键诊断类型（如 IGBT 驱动、电源监控）需在电机启动前执行一次；
• 1. 非关键诊断类型（如 ADC 自校验）可周期性执行（频率由 adc_self_check_freq 配置）；
• 1. 校验失败时，自动触发对应故障码，根据故障等级进入跛行或安全关断模式*/int32_t safe_smu_hw_self_diag (SafeSmuHandleType *smu, SafeSmuHwDiagType diag_type);

/*!

• @brief 软件看门狗喂狗
• @param [in,out] smu 安全监控句柄指针
• @return 喂狗结果
• @retval 0：喂狗成功
• @retval -1：参数错误（smu 为 NULL）
• @retval -2：未初始化
• @safety 软件看门狗用于监控核心程序运行状态，避免程序卡死导致安全风险：
• 1. 主核心喂狗周期≤sw_watchdog_timeout/2；
• 1. 喂狗失败时，触发软件超时故障，10ms 内未恢复则执行安全关断
• @note 1. 喂狗函数需在主循环或核心任务中周期性调用；
• 1. 禁止在中断服务函数中喂狗，避免掩盖主程序卡死问题；
• 1. 软件看门狗与硬件看门狗独立，双重保障程序运行可靠性*/int32_t safe_smu_sw_watchdog_feed (SafeSmuHandleType *smu);

/*!

• @brief 安全关断控制（最高优先级）
• @param [in,out] smu 安全监控句柄指针
• @param [in] fault_code 触发关断的故障码
• @details 安全关断流程（硬件级 + 软件级双重保障）：
• 1. 立即拉低 IGBT 驱动使能引脚（硬件级关断，响应时间≤10μs）；
• 1. 关闭 PWM 输出，设置转矩指令为 0；
• 1. 存储故障码和故障发生时的关键数据（母线电压、电机电流、核心状态）到 Flash；
• 1. 上报故障信息到 VCU（通过 CAN FD 紧急帧）；
• 1. 进入安全关断模式，仅保留故障诊断和通信模块运行
• @safety 安全关断是 ASIL-B 等级的最终安全机制，确保故障时电机无转矩输出
• @note 1. 该函数可由故障中断、安全监控定时器中断直接调用；
• 1. 安全关断后，需通过上位机清除故障码并重启控制器才能恢复；
• 1. 关断延迟时间（safe_shutdown_delay）需根据 IGBT 特性配置，避免电压尖峰*/void safe_smu_safe_shutdown (SafeSmuHandleType *smu, SafeFaultCodeType fault_code);

/*!

• @brief 安全监控主函数（周期调用）
• @param [in,out] smu 安全监控句柄指针
• @return 执行结果
• @retval 0：执行成功
• @retval -1：参数错误（smu 为 NULL）
• @retval -2：未初始化
• @details 安全监控主流程（100μs 周期）：
• 1. 双核心互检状态检查：判断是否超时或数据不一致；
• 1. 硬件诊断调度：根据配置频率触发指定类型的硬件自校验；
• 1. 软件看门狗状态检查：判断是否超时；
• 1. 故障状态评估：根据当前故障码确定安全模式（正常 / 跛行 / 关断）；
• 1. 状态同步：更新安全状态并同步到其他模块
• @safety 主函数采用时间触发机制，确保监控的实时性和可靠性，符合 ASIL-B 对安全机制的要求
• @warning 该函数必须通过独立定时器中断调用，禁止在主循环中调用，避免被其他任务阻塞*/int32_t safe_smu_main (SafeSmuHandleType *smu);

/*!

• @brief 获取安全监控状态
• @param [in] smu 安全监控句柄指针
• @param [out] status 安全监控状态结构体指针
• @return 获取结果
• @retval 0：获取成功
• @retval -1：参数错误（smu 为 NULL 或 status 为 NULL）
• @retval -2：未初始化
• @note 1. 该函数可由 VCU 通信模块调用，用于上报安全状态；
• 1. 状态数据包含故障码、故障次数、安全模式等关键信息，支持整车故障追溯*/int32_t safe_smu_get_status (const SafeSmuHandleType *smu, SafeSmuStatusType *status);

/*!

• @brief 清除故障记录
• @param [in,out] smu 安全监控句柄指针
• @param [in] fault_code 要清除的故障码（SAFE_FAULT_MAX 表示清除所有）
• @return 清除结果
• @retval 0：清除成功
• @retval -1：参数错误（smu 为 NULL）
• @retval -2：未初始化
• @retval -3：Flash 写入失败
• @safety 故障记录清除需满足功能安全要求：
• 1. 仅允许在上位机校准模式下清除；
• 1. 清除前需记录清除日志（包含清除时间、操作人）；
• 1. 致命故障记录（如 IGBT 过流）不可清除，仅可读取
• @note 1. 清除故障记录后，故障发生次数清零，但历史故障日志仍保留；
• 1. 建议仅在故障排查完成后执行清除操作*/int32_t safe_smu_clear_fault (SafeSmuHandleType *smu, SafeFaultCodeType fault_code);

/*! @} */ // 结束 SAFE_SMU 模块

#endif // SAFE_SMU_H

plaintext

#### 5.2.2 驱动层（DRV）核心模块：IGBT驱动与旋转变压器采样
```c
/*!
 * @file drv_igbt.h
 * @brief IGBT驱动模块（汽车FOC控制器核心驱动）
 * @author Li Ming
 * @date 2025-12-04
 * @version V1.0.0
 * @details 实现高压IGBT模块的驱动控制、状态采样、故障保护功能，支持最大100kW电机驱动，
 *          适配英飞凌FS820R08A1E3 IGBT模块，包含栅极驱动、过流保护、温度采样、欠压锁定等功能
 * @note 1. IGBT驱动采用隔离式设计（光耦+隔离电源），耐压≥2500V；
 *       2. 过流保护响应时间≤1μs，温度采样精度±2℃；
 *       3. 驱动模块支持热插拔诊断，故障时自动切断栅极驱动信号
 * @safety 符合ISO 26262 ASIL-B等级要求，故障诊断覆盖率≥95%，支持硬件级故障关断
 */

#ifndef DRV_IGBT_H
#define DRV_IGBT_H

#include "hal_common.h"
#include "safe_fault.h"

/*!
 * @defgroup DRV_IGBT IGBT驱动模块
 * @brief 高压IGBT驱动控制与故障诊断，适配100kW永磁同步电机
 * @ingroup DRV
 * @safety 硬件级过流/过温/欠压保护，响应时间≤1μs，符合ASIL-B要求
 * @{
 */

/*!
 * @brief IGBT驱动模式枚举
 */
typedef enum {
    DRV_IGBT_MODE_STOP,      /*!< 停止模式（栅极关断） */
    DRV_IGBT_MODE_READY,     /*!< 就绪模式（栅极使能，无PWM输入） */
    DRV_IGBT_MODE_DRIVE,     /*!< 驱动模式（栅极使能，接收PWM输入） */
    DRV_IGBT_MODE_FAULT      /*!< 故障模式（栅极关断，故障锁定） */
} DrvIgbtModeType;

/*!
 * @brief IGBT故障类型枚举
 */
typedef enum {
    DRV_IGBT_ERR_NONE = 0,       /*!< 无故障 */
    DRV_IGBT_ERR_OVER_CURRENT,   /*!< 过流故障（相电流超过800A） */
    DRV_IGBT_ERR_OVER_TEMP,      /*!< 过温故障（IGBT结温超过150℃） */
    DRV_IGBT_ERR_UNDER_VOLTAGE,  /*!< 欠压故障（栅极驱动电压低于12V） */
    DRV_IGBT_ERR_OPEN_CIRCUIT,   /*!< 开路故障（IGBT模块未连接） */
    DRV_IGBT_ERR_SHORT_CIRCUIT,  /*!< 短路故障（IGBT桥臂短路） */
    DRV_IGBT_ERR_MAX             /*!< 故障类型数量 */
} DrvIgbtErrType;

/*!
 * @brief IGBT相序枚举（对应电机三相桥）
 */
typedef enum {
    DRV_IGBT_PHASE_A,  /*!< A相桥臂 */
    DRV_IGBT_PHASE_B,  /*!< B相桥臂 */
    DRV_IGBT_PHASE_C,  /*!< C相桥臂 */
    DRV_IGBT_PHASE_MAX /*!< 相序数量 */
} DrvIgbtPhaseType;

/*!
 * @brief IGBT驱动配置结构体
 */
typedef struct {
    uint16_t over_current_thr;    /*!< 过流阈值（A），默认800A（峰值） */
    uint16_t over_temp_thr;       /*!< 过温阈值（℃），默认150℃（结温） */
    uint16_t undervolt_thr;       /*!< 欠压阈值（V），默认12V（栅极驱动电压） */
    uint8_t dead_time;            /*!< 死区时间（ns），默认1000ns */
    uint8_t gate_drive_voltage;   /*!< 栅极驱动电压（V），默认15V（开通）/-8V（关断） */
    uint32_t pwm_freq;            /*!< PWM驱动频率（Hz），默认10kHz */
    void (*fault_cb)(DrvIgbtErrType err); /*!< 故障回调函数（上报故障到安全监控模块） */
} DrvIgbtConfigType;

/*!
 * @brief IGBT驱动状态结构体
 */
typedef struct {
    DrvIgbtModeType curr_mode;    /*!< 当前驱动模式 */
    DrvIgbtErrType active_err;    /*!< 当前激活的故障 */
    float phase_current[3];       /*!< 三相相电流（A）- A/B/C相 */
    float igbt_temp[3];           /*!< 三相IGBT结温（℃）- A/B/C相 */
    float gate_voltage;           /*!< 栅极驱动电压（V） */
    uint32_t pwm_duty[3];         /*!< 三相PWM占空比（‰）- A/B/C相 */
    uint8_t fault_lock;           /*!< 故障锁定标志：1-锁定（需复位解锁），0-未锁定 */
} DrvIgbtStatusType;

/*!
 * @brief IGBT驱动句柄结构体
 */
typedef struct {
    DrvIgbtConfigType config;     /*!< 驱动配置 */
    DrvIgbtStatusType status;     /*!< 驱动状态 */
    HalPwmHandleType pwm_handle[3]; /*!< 三相PWM驱动句柄 */
    HalAdcHandleType adc_current[3]; /*!< 三相电流采样ADC句柄 */
    HalAdcHandleType adc_temp[3]; /*!< 三相温度采样ADC句柄 */
    HalGpioHandleType gpio_enable; /*!< 栅极使能GPIO句柄 */
    HalGpioHandleType gpio_fault; /*!< 故障反馈GPIO句柄 */
} DrvIgbtHandleType;

/*!
 * @brief IGBT驱动初始化
 * @param[in,out] igbt IGBT驱动句柄指针
 * @param[in] config IGBT驱动配置结构体指针
 * @return 初始化结果
 * @retval 0：初始化成功
 * @retval -1：参数错误（igbt为NULL或config参数非法）
 * @retval -2：PWM初始化失败
 * @retval -3：ADC初始化失败
 * @retval -4：GPIO初始化失败
 * @safety 初始化流程符合ASIL-B安全要求：
 *         1. 初始化前执行IGBT模块存在性诊断；
 *         2. 初始化栅极驱动使能引脚为低电平（关断状态）；
 *         3. 配置故障反馈引脚为中断触发模式（上升沿触发）；
 *         4. 校准电流采样ADC的零点偏移
 * @note 1. 三相PWM驱动默认使用定时器1、定时器8（高级定时器，支持互补输出）；
 *       2. 电流采样采用分流电阻+ADC差分采样，采样频率10kHz；
 *       3. 故障回调函数需关联安全监控模块，故障时触发安全关断
 */
int32_t drv_igbt_init(DrvIgbtHandleType *igbt, const DrvIgbtConfigType *config);

/*!
 * @brief 设置IGBT驱动模式
 * @param[in,out] igbt IGBT驱动句柄指针
 * @param[in] mode 目标驱动模式
 * @return 设置结果
 * @retval 0：设置成功
 * @retval -1：参数错误（igbt为NULL或mode非法）
 * @retval -2：未初始化
 * @retval -3：故障锁定（需复位解锁）
 * @details 模式切换逻辑：
 *          1. STOP→READY：使能栅极驱动电压，关闭PWM输出；
 *          2. READY→DRIVE：启用PWM输入，开始驱动IGBT；
 *          3. 任意模式→STOP：关断栅极驱动电压，关闭PWM输出；
 *          4. 任意模式→FAULT：关断栅极驱动，锁定故障状态
 * @safety 模式切换过程中加入硬件互锁，避免上下桥臂同时导通：
 *         1. 模式切换延迟≥2×死区时间；
 *         2. 驱动模式下，PWM占空比初始值为50%（无转矩输出）
 * @note 1. 启动电机前需先切换至READY模式，预热IGBT驱动模块；
 *       2. 故障模式下，需复位控制器才能解锁，禁止直接切换至驱动模式
 */
int32_t drv_igbt_set_mode(DrvIgbtHandleType *igbt, DrvIgbtModeType mode);

/*!
 * @brief 设置三相PWM占空比
 * @param[in,out] igbt IGBT驱动句柄指针
 * @param[in] duty 三相占空比数组（‰），索引0-A相，1-B相，2-C相
 * @return 设置结果
 * @retval 0：设置成功
 * @retval -1：参数错误（igbt为NULL或duty值超出0-1000范围）
 * @retval -2：未初始化
 * @retval -3：非驱动模式（仅DRIVE模式支持占空比设置）
 * @safety 占空比设置加入硬件级限幅和死区保护：
 *         1. 占空比限制在100-900‰（避免过调制导致电压畸变）；
 *         2. 上下桥臂占空比差值≥死区时间对应的占空比；
 *         3. 占空比突变率限制≤50‰/μs（避免电流冲击）
 * @note 1. 占空比由FOC算法计算得出（SVPWM调制结果）；
 *       2. 三相占空比需满足A+B+C=1500‰（中点钳位），否则自动校准
 */
int32_t drv_igbt_set_pwm_duty(DrvIgbtHandleType *igbt, const uint32_t duty[3]);

/*!
 * @brief IGBT故障检测与处理（中断回调函数）
 * @param[in,out] igbt IGBT驱动句柄指针
 * @details 故障检测流程：
 *          1. 读取故障反馈GPIO电平，判断故障类型（过流/过温/欠压）；
 *          2. 采样故障发生时的相电流、IGBT温度、栅极电压；
 *          3. 更新故障状态和故障锁定标志；
 *          4. 调用故障回调函数，上报故障到安全监控模块；
 *          5. 关断栅极驱动，切换至故障模式
 * @safety 故障处理响应时间≤1μs，符合ASIL-B对故障响应的要求：
 *         1. 过流故障采用硬件比较器触发，无需软件干预；
 *         2. 故障状态采用双缓冲存储，避免数据丢失；
 *         3. 故障锁定后，仅复位可解锁，防止故障反复触发
 * @note 该函数由故障反馈GPIO中断触发，禁止手动调用
 */
void drv_igbt_fault_handler(DrvIgbtHandleType *igbt);

/*!
 * @brief 获取IGBT驱动状态
 * @param[in] igbt IGBT驱动句柄指针
 * @param[out] status IGBT驱动状态结构体指针
 * @return 获取结果
 * @retval 0：获取成功
 * @retval -1：参数错误（igbt为NULL或status为NULL）
 * @retval -2：未初始化
 * @note 1. 状态数据包含相电流、IGBT温度、故障状态等，用于FOC算法调整和整车监控；
 *       2. 建议100μs调用一次，确保状态数据实时性
 */
int32_t drv_igbt_get_status(const DrvIgbtHandleType *igbt, DrvIgbtStatusType *status);

/*!
 * @brief 解锁IGBT故障状态
 * @param[in,out] igbt IGBT驱动句柄指针
 * @return 解锁结果
 * @retval 0：解锁成功
 * @retval -1：参数错误（igbt为NULL）
 * @retval -2：未初始化
 * @retval -3：硬件故障未解除（需检查IGBT模块）
 * @safety 故障解锁需满足安全要求：
 *         1. 解锁前检测IGBT模块状态，确认故障已解除；
 *         2. 解锁后自动执行一次IGBT自校验；
 *         3. 同一故障1分钟内解锁次数≤3次，避免故障反复
 * @note 故障解锁仅适用于非致命故障（如暂时欠压），致命故障（如桥臂短路）需更换IGBT模块
 */
int32_t drv_igbt_unlock_fault(DrvIgbtHandleType *igbt);

/*! @} */  // 结束DRV_IGBT模块

#endif  // DRV_IGBT_H

c

运行

/*!
 * @file drv_resolver.h
 * @brief 旋转变压器采样模块（电机转子位置检测）
 * @author Zhang Hong
 * @date 2025-12-04
 * @version V1.0.0
 * @details 实现旋转变压器（Resolver）的信号解码、转子位置和转速计算，适配100kW永磁同步电机，
 *          支持14位位置分辨率，转速测量范围0-10000rpm，位置更新频率10kHz，
 *          采用STM32G474内置的Resolver接口（TIM1/TIM8）实现解码
 * @note 1. 旋转变压器与电机转子机械耦合，位置信号无接触、抗干扰能力强；
 *       2. 支持正反转检测，转速计算采用一阶低通滤波（截止频率100Hz）；
 *       3. 位置信号丢失时，自动切换至反电动势估算模式（降级控制）
 * @safety 符合ISO 26262 ASIL-B等级要求，位置信号故障诊断覆盖率≥98%，支持降级控制
 */

#ifndef DRV_RESOLVER_H
#define DRV_RESOLVER_H

#include "hal_common.h"
#include "safe_fault.h"

/*!
 * @defgroup DRV_RESOLVER 旋转变压器采样模块
 * @brief 电机转子位置/转速检测，支持14位分辨率，适配100kW永磁同步电机
 * @ingroup DRV
 * @safety 位置信号故障时自动降级，符合ASIL-B对容错的要求
 * @{
 */

/*!
 * @brief 旋转变压器解码模式枚举
 */
typedef enum {
    DRV_RESOLVER_MODE_NORMAL,    /*!< 正常模式（旋转变压器解码） */
    DRV_RESOLVER_MODE_FALLBACK,  /*!< 降级模式（反电动势估算） */
    DRV_RESOLVER_MODE_FAULT      /*!< 故障模式（位置信号无效） */
} DrvResolverModeType;

/*!
 * @brief 旋转变压器故障类型枚举
 */
typedef enum {
    DRV_RESOLVER_ERR_NONE = 0,       /*!< 无故障 */
    DRV_RESOLVER_ERR_SIGNAL_LOSS,    /*!< 信号丢失故障（正弦/余弦信号幅值≤0.5V） */
    DRV_RESOLVER_ERR_SIGNAL_DISTORT, /*!< 信号畸变故障（正弦/余弦信号相位差≠90°） */
    DRV_RESOLVER_ERR_NOISE,          /*!< 噪声故障（位置抖动≥5°） */
    DRV_RESOLVER_ERR_TIMEOUT,        /*!< 超时故障（10ms未更新位置） */
    DRV_RESOLVER_ERR_MAX             /*!< 故障类型数量 */
} DrvResolverErrType;

/*!
 * @brief 旋转变压器配置结构体
 */
typedef struct {
    uint32_t excitation_freq;    /*!< 激励信号频率（kHz），默认10kHz */
    uint16_t excitation_amplitude; /*!< 激励信号幅值（Vpp），默认7Vpp */
    uint16_t pole_pairs;         /*!< 电机极对数，默认4对极 */
    uint16_t resolution;         /*!< 位置分辨率（位），默认14位 */
    float speed_filter_alpha;    /*!< 转速滤波系数（0-1），默认0.1 */
    uint32_t fallback_threshold; /*!< 降级模式切换阈值（位置抖动°），默认5° */
    void (*fault_cb)(DrvResolverErrType err); /*!< 故障回调函数 */
} DrvResolverConfigType;

/*!
 * @brief 旋转变压器采样结果结构体
 */
typedef struct {
    float mechanical_angle;      /*!< 机械角度（°），范围0-360° */
    float electrical_angle;      /*!< 电角度（°），范围0-360°，=机械角度×极对数 */
    float speed_rpm;             /*!< 转速（rpm），正转为正，反转为负 */
    float speed_rad_s;           /*!< 转速（rad/s），=speed_rpm×2π/60 */
    uint32_t update_time;        /*!< 上次更新时间（μs） */
} DrvResolverResultType;

/*!
 * @brief 旋转变压器句柄结构体
 */
typedef struct {
    DrvResolverConfigType config; /*!< 旋转变压器配置 */
    DrvResolverModeType curr_mode; /*!< 当前工作模式 */
    DrvResolverErrType active_err; /*!< 当前激活的故障 */
    DrvResolverResultType result;  /*!< 采样结果 */
    HalTimHandleType excite_tim;   /*!< 激励信号定时器句柄 */
    HalTimHandleType decode_tim;   /*!< 解码定时器句柄（TIM1/TIM8） */
    HalAdcHandleType monitor_adc;  /*!< 信号监控ADC句柄 */
    float sin_signal;             /*!< 正弦信号采样值（V） */
    float cos_signal;             /*!< 余弦信号采样值（V） */
    float angle_prev;             /*!< 上一次机械角度（°） */
    uint32_t timeout_tick;        /*!< 超时计数器（μs） */
} DrvResolverHandleType;

/*!
 * @brief 旋转变压器初始化
 * @param[in,out] resolver 旋转变压器句柄指针
 * @param[in] config 旋转变压器配置结构体指针
 * @return 初始化结果
 * @retval 0：初始化成功
 * @retval -1：参数错误（resolver为NULL或config参数非法）
 * @retval -2：激励定时器初始化失败
 * @retval -3：解码定时器初始化失败
 * @retval -4：ADC监控初始化失败
 * @safety 初始化流程符合ASIL-B安全要求：
 *         1. 初始化后执行信号自检，检查正弦/余弦信号幅值和相位；
 *         2. 校准位置零点偏移（机械零点与电零点对齐）；
 *         3. 配置解码定时器中断优先级为最高（避免位置更新延迟）
 * @note 1. 激励信号由定时器生成PWM，通过功率放大后输出至旋转变压器；
 *       2. 解码定时器采用STM32G4内置的Resolver接口，支持硬件解码，无需软件计算；
 *       3. ADC监控用于检测正弦/余弦信号状态，判断是否发生信号丢失或畸变
 */
int32_t drv_resolver_init(DrvResolverHandleType *resolver, const DrvResolverConfigType *config);

/*!
 * @brief 旋转变压器位置/转速采样（周期调用）
 * @param[in,out] resolver 旋转变压器句柄指针
 * @return 采样结果
 * @retval 0：采样成功
 * @retval -1：参数错误（resolver为NULL）
 * @retval -2：未初始化
 * @retval -3：采样故障（当前为故障模式）
 * @details 采样流程：
 *          1. 读取解码定时器的硬件解码结果（机械角度）；
 *          2. 计算电角度（机械角度×极对数）；
 *          3. 基于相邻两次角度差计算转速，应用一阶低通滤波；
 *          4. 读取ADC监控值，检查正弦/余弦信号状态；
 *          5. 故障诊断：判断是否发生信号丢失、畸变或超时；
 *          6. 模式切换：故障时切换至降级或故障模式
 * @safety 采样过程加入多重故障诊断：
 *         1. 信号幅值检测：正弦/余弦信号幅值需在0.5V-10V之间；
 *         2. 相位检测：正弦/余弦信号相位差需在85°-95°之间；
 *         3. 抖动检测：相邻两次位置差≤fallback_threshold；
 *         4. 超时检测：位置更新周期≤100μs（采样频率10kHz）
 * @note 1. 该函数需100μs周期调用（与FOC算法执行周期同步）；
 *       2. 降级模式下，位置由反电动势估算得出，精度≤±3°，仅适用于中高速（≥1000rpm）
 */
int32_t drv_resolver_sample(DrvResolverHandleType *resolver);

/*!
 * @brief 获取旋转变压器采样结果
 * @param[in] resolver 旋转变压器句柄指针
 * @param[out] result 采样结果结构体指针
 * @return 获取结果
 * @retval 0：获取成功
 * @retval -1：参数错误（resolver为NULL或result为NULL）
 * @retval -2：未初始化
 * @note 1. 采样结果为最新一次采样数据，支持FOC算法的dq轴坐标变换；
 *       2. 转速数据已滤波，可直接用于转速环PID控制；
 *       3. 建议在FOC算法主函数中调用，确保位置数据与算法执行同步
 */
int32_t drv_resolver_get_result(const DrvResolverHandleType *resolver, DrvResolverResultType *result);

/*!
 * @brief 旋转变压器零点校准
 * @param[in,out] resolver 旋转变压器句柄指针
 * @return 校准结果
 * @retval 0：校准成功
 * @retval -1：参数错误（resolver为NULL）
 * @retval -2：未初始化
 * @retval -3：校准超时（超过5秒未完成）
 * @retval -4：信号异常（无法完成校准）
 * @details 零点校准流程（电机静止时执行）：
 *          1. 控制电机转子转动至机械零点位置；
 *          2. 采样此时的旋转变压器解码角度；
 *          3. 计算零点偏移量并存储至Flash；
 *          4. 校准后，采样角度自动减去偏移量，确保电零点与机械零点对齐
 * @safety 校准过程加入安全保护：
 *         1. 校准期间电机转矩限制≤5N·m，避免机械冲击；
 *         2. 校准失败时，使用默认零点偏移量（0°），并上报校准故障；
 *         3. 校准结果存储在片内Flash，掉电不丢失
 * @note 1. 每次安装或更换旋转变压器后需执行一次校准；
 *       2. 校准需在电机静止、无负载状态下进行；
 *       3. 校准结果可通过上位机读取，用于故障排查
 */
int32_t drv_resolver_zero_calibrate(DrvResolverHandleType *resolver);

/*!
 * @brief 旋转变压器故障处理函数
 * @param[in,out] resolver 旋转变压器句柄指针
 * @param[in] err 故障类型
 * @details 故障处理流程：
 *          1. 更新故障状态和工作模式；
 *          2. 调用故障回调函数，上报故障到安全监控模块；
 *          3. 若为信号丢失/畸变故障，切换至降级模式（反电动势估算）；
 *          4. 若为超时/严重故障，切换至故障模式，禁止电机驱动
 * @safety 故障处理符合ASIL-B容错要求：
 *         1. 降级模式下仍能维持电机基本控制，确保车辆跛行回家；
 *         2. 故障状态采用双缓冲存储，避免数据丢失；
 *         3. 故障恢复后，自动切换回正常模式，无需手动干预
 * @note 该函数由采样函数或中断自动调用，也可手动调用上报故障
 */
void drv_resolver_fault_handler(DrvResolverHandleType *resolver, DrvResolverErrType err);

/*! @} */  // 结束DRV_RESOLVER模块

#endif  // DRV_RESOLVER_H

5.2.3 算法层（ALG）核心模块：FOC 矢量控制与能量回收

c

运行

/*!
 * @file alg_foc_pmsm.h
 * @brief 永磁同步电机（PMSM）FOC矢量控制算法模块
 * @author Wang Jun
 * @date 2025-12-04
 * @version V1.0.0
 * @details 实现适用于汽车级永磁同步电机的FOC矢量控制算法，包含Clark变换、Park变换、
 *          逆Park变换、SVPWM调制、MTPA（最大转矩电流比）控制、弱磁控制等核心功能，
 *          支持转矩/转速双闭环控制，转矩响应时间≤10ms，转速控制精度±1rpm
 * @note 1. 算法执行频率10kHz（与电流采样、位置采样周期同步）；
 *       2. 支持id=0控制和MTPA控制两种模式，根据转速自动切换；
 *       3. 弱磁控制用于高速区扩展转速范围，最大弱磁电流≤-20A
 * @safety 符合ISO 26262 ASIL-B等级要求，算法容错机制包括：位置信号降级、电流环饱和保护、
 *         转矩限制等，确保故障时电机控制稳定
 */

#ifndef ALG_FOC_PMSM_H
#define ALG_FOC_PMSM_H

#include "stdint.h"
#include "math.h"
#include "pid_ctrl.h"
#include "drv_resolver.h"
#include "drv_igbt.h"

/*!
 * @defgroup ALG_FOC_PMSM PMSM FOC矢量控制算法模块
 * @brief 汽车级永磁同步电机FOC控制，支持MTPA、弱磁控制，转矩响应≤10ms
 * @ingroup ALG
 * @safety 算法容错机制完善，符合ISO 26262 ASIL-B要求
 * @{
 */

/*!
 * @brief FOC控制模式枚举
 */
typedef enum {
    ALG_FOC_PMSM_MODE_TORQUE,    /*!< 转矩控制模式（接收转矩指令） */
    ALG_FOC_PMSM_MODE_SPEED,     /*!< 转速控制模式（接收转速指令） */
    ALG_FOC_PMSM_MODE_IDLE,      /*!< 怠速模式（转矩指令为0） */
    ALG_FOC_PMSM_MODE_FAULT      /*!< 故障模式（停止控制） */
} AlgFocPmsmModeType;

/*!
 * @brief 电流控制策略枚举
 */
typedef enum {
    ALG_FOC_PMSM_CURRENT_STRATEGY_ID0,  /*!< id=0控制（表面贴装式PMSM） */
    ALG_FOC_PMSM_CURRENT_STRATEGY_MTPA  /*!< MTPA控制（内置式PMSM，提高转矩密度） */
} AlgFocPmsmCurrentStrategyType;

/*!
 * @brief 弱磁控制模式枚举
 */
typedef enum {
    ALG_FOC_PMSM_WEAK_MAGNET_DISABLE,  /*!< 禁用弱磁控制 */
    ALG_FOC_PMSM_WEAK_MAGNET_ENABLE,   /*!< 启用弱磁控制 */
    ALG_FOC_PMSM_WEAK_MAGNET_AUTO      /*!< 自动弱磁控制（根据转速自动切换） */
} AlgFocPmsmWeakMagnetModeType;

/*!
 * @brief PMSM电机参数结构体
 */
typedef struct {
    float rated_power;           /*!< 额定功率（kW），默认100kW */
    float rated_torque;          /*!< 额定转矩（N·m），默认318N·m（100kW/1000rpm） */
    float rated_speed;           /*!< 额定转速（rpm），默认3000rpm */
    float max_speed;             /*!< 最大转速（rpm），默认10000rpm */
    float pole_pairs;            /*!< 极对数，默认4对极 */
    float phase_resistance;      /*!< 相电阻（Ω），默认0.015Ω */
    float d_axis_inductance;     /*!< d轴电感（mH），默认0.5mH */
    float q_axis_inductance;     /*!< q轴电感（mH），默认1.5mH（内置式PMSM，Lq>Ld） */
    float flux_linkage;          /*!< 永磁体磁链（Wb），默认0.175Wb */
} AlgFocPmsmMotorParamType;

/*!
 * @brief FOC控制配置结构体
 */
typedef struct {
    AlgFocPmsmModeType ctrl_mode;          /*!< 控制模式 */
    AlgFocPmsmCurrentStrategyType current_strategy; /*!< 电流控制策略 */
    AlgFocPmsmWeakMagnetModeType weak_magnet_mode; /*!< 弱磁控制模式 */
    float max_torque;                      /*!< 最大转矩限制（N·m），默认400N·m */
    float max_d_axis_current;              /*!< d轴最大电流（A），默认±50A */
    float max_q_axis_current;              /*!< q轴最大电流（A），默认200A */
    float weak_magnet_speed_threshold;     /*!< 弱磁启动转速（rpm），默认2500rpm */
    float weak_magnet_max_d_current;       /*!< 弱磁最大d轴电流（A），默认-20A（负电流削弱磁链） */
    PidParamType speed_pid_param;          /*!< 转速环PID参数 */
    PidParamType d_axis_current_pid_param; /*!< d轴电流环PID参数 */
    PidParamType q_axis_current_pid_param; /*!< q轴电流环PID参数 */
} AlgFocPmsmConfigType;

/*!
 * @brief FOC控制状态结构体
 */
typedef struct {
    AlgFocPmsmModeType curr_mode;          /*!< 当前控制模式 */
    float target_torque;                   /*!< 目标转矩（N·m） */
    float actual_torque;                   /*!< 实际转矩（N·m） */
    float target_speed;                    /*!< 目标转速（rpm） */
    float actual_speed;                    /*!< 实际转速（rpm） */
    float d_axis_current_ref;              /*!< d轴参考电流（A） */
    float d_axis_current_actual;           /*!< d轴实际电流（A） */
    float q_axis_current_ref;              /*!< q轴参考电流（A） */
    float q_axis_current_actual;           /*!< q轴实际电流（A） */
    float d_axis_voltage_ref;              /*!< d轴参考电压（V） */
    float q_axis_voltage_ref;              /*!< q轴参考电压（V） */
    float dc_bus_voltage;                  /*!< 直流母线电压（V） */
    uint8_t weak_magnet_active;            /*!< 弱磁控制激活标志：1-激活，0-未激活 */
    uint32_t ctrl_tick;                    /*!< 控制周期计数器（μs） */
} AlgFocPmsmStatusType;

/*!
 * @brief FOC控制句柄结构体
 */
typedef struct {
    AlgFocPmsmConfigType config;           /*!< 控制配置 */
    AlgFocPmsmStatusType status;           /*!< 控制状态 */
    AlgFocAbcCurrType abc_current;         /*!< ABC坐标系三相电流 */
    AlgFocAlphaBetaCurrType alpha_beta_current; /*!< αβ坐标系电流 */
    AlgFocDqCurrType dq_current;           /*!< dq坐标系电流 */
    AlgFocDqVoltType dq_voltage;           /*!< dq坐标系电压 */
    AlgFocSvpwmDutyType svpwm_duty;        /*!< SVPWM占空比 */
    PidHandleType speed_pid;               /*!< 转速环PID控制器 */
    PidHandleType d_axis_current_pid;      /*!< d轴电流环PID控制器 */
    PidHandleType q_axis_current_pid;      /*!< q轴电流环PID控制器 */
    DrvResolverResultType resolver_result; /*!< 旋转变压器采样结果 */
    float electrical_angle;                /*!< 电角度（rad） */
    float speed_filtered;                  /*!< 滤波后转速（rpm） */
} AlgFocPmsmHandleType;

/*!
 * @brief FOC控制初始化
 * @param[in,out] foc FOC控制句柄指针
 * @param[in] motor_param 电机参数结构体指针
 * @param[in] config 控制配置结构体指针
 * @return 初始化结果
 * @retval 0：初始化成功
 * @retval -1：参数错误（foc为NULL或参数非法）
 * @retval -2：PID控制器初始化失败
 * @retval -3：电机参数配置错误（如Ld≥Lq时选择MTPA策略）
 * @safety 初始化流程符合ASIL-B安全要求：
 *         1. 初始化前检查电机参数合法性（如功率、转矩、转速匹配）；
 *         2. PID参数范围限制（kp>0，ki≥0，kd≥0）；
 *         3. 初始控制模式为怠速模式，转矩指令为0；
 *         4. 初始化电流环和转速环限幅，避免启动冲击
 * @note 1. 内置式PMSM（Lq>Ld）推荐使用MTPA策略，表面贴装式（Lq≈Ld）推荐id=0策略；
 *       2. 直流母线电压需通过ADC实时采样更新（建议1ms更新一次）；
 *       3. 初始化后需执行一次电机辨识，校准相电阻、电感等参数（可选）
 */
int32_t alg_foc_pmsm_init(AlgFocPmsmHandleType *foc, const AlgFocPmsmMotorParamType *motor_param, const AlgFocPmsmConfigType *config);

/*!
 * @brief 设置FOC控制模式
 * @param[in,out] foc FOC控制句柄指针
 * @param[in] mode 目标控制模式
 * @return 设置结果
 * @retval 0：设置成功
 * @retval -1：参数错误（foc为NULL或mode非法）
 * @retval -2：未初始化
 * @retval -3：故障模式下无法切换（需先清除故障）
 * @details 模式切换逻辑：
 *          1. 任意模式→故障模式：立即停止控制，转矩指令置0，关闭PWM输出；
 *          2. 故障模式→其他模式：需先清除故障，且电机参数正常；
 *          3. 转速/转矩模式→怠速模式：转矩指令平滑降至0（斜率0.5N·m/ms）；
 *          4. 怠速模式→转速/转矩模式：转矩指令平滑升至目标值（斜率0.5N·m/ms）
 * @safety 模式切换加入平滑过渡机制，避免转矩突变导致的电流冲击：
 *         1. 转矩指令变化率限制≤0.5N·m/ms；
 *         2. 模式切换期间，电流环PID参数保持不变；
 *         3. 切换失败时，自动回退到原模式，避免控制失效
 * @note 1. 车辆行驶时切换模式需通过VCU授权，禁止直接切换；
 *       2. 模式切换结果需反馈给VCU，用于整车控制策略调整
 */
int32_t alg_foc_pmsm_set_mode(AlgFocPmsmHandleType *foc, AlgFocPmsmModeType mode);

/*!
 * @brief 设置目标转矩（转矩控制模式）
 * @param[in,out] foc FOC控制句柄指针
 * @param[in] target_torque 目标转矩（N·m）
 * @return 设置结果
 * @retval 0：设置成功
 * @retval -1：参数错误（foc为NULL或target_torque超出±max_torque）
 * @retval -2：未初始化
 * @retval -3：非转矩控制模式（需先切换至ALG_FOC_PMSM_MODE_TORQUE）
 * @safety 转矩指令加入多重限制，符合汽车安全要求：
 *         1. 幅值限制：|target_torque|≤max_torque；
 *         2. 变化率限制：|Δtarget_torque/Δt|≤0.5N·m/ms；
 *         3. 转速关联限制：高速区（>8000rpm）转矩线性衰减至0；
 *         4. 故障关联限制：检测到故障时，转矩指令强制置0
 * @note 1. 目标转矩由VCU根据驾驶员意图（油门踏板）生成；
 *       2. 再生制动时，目标转矩为负值（能量回收）；
 *       3. 转矩指令需经过滤波处理（一阶低通，截止频率10Hz），避免噪声干扰
 */
int32_t alg_foc_pmsm_set_target_torque(AlgFocPmsmHandleType *foc, float target_torque);

/*!
 * @brief 设置目标转速（转速控制模式）
 * @param[in,out] foc FOC控制句柄指针
 * @param[in] target_speed 目标转速（rpm）
 * @return 设置结果
 * @retval 0：设置成功
 * @retval -1：参数错误（foc为NULL或target_speed超出0-max_speed）
 * @retval -2：未初始化
 * @retval -3：非转速控制模式（需先切换至ALG_FOC_PMSM_MODE_SPEED）
 * @safety 转速指令加入多重限制，确保控制稳定：
 *         1. 幅值限制：0≤target_speed≤max_speed；
 *         2. 变化率限制：|Δtarget_speed/Δt|≤500rpm/s；
 *         3. 转矩限制：转速环输出转矩≤max_torque；
 *         4. 弱磁关联：高速区自动启用弱磁控制，扩展转速范围
 * @note 1. 转速控制模式适用于定速巡航、怠速控制等场景；
 *       2. 目标转速由VCU根据整车控制策略生成；
 *       3. 转速环PID参数可根据转速自适应调整（低速时增大ki，高速时增大kd）
 */
int32_t alg_foc_pmsm_set_target_speed(AlgFocPmsmHandleType *foc, float target_speed);

/*!
 * @brief MTPA控制（最大转矩电流比）
 * @param[in,out] foc FOC控制句柄指针
 * @param[in] target_torque 目标转矩（N·m）
 * @param[out] d_axis_current_ref d轴参考电流（A）
 * @param[out] q_axis_current_ref q轴参考电流（A）
 * @details MTPA控制原理：在相同电流幅值下，通过优化d/q轴电流分配，获得最大转矩输出，
 *          适用于内置式PMSM（Lq>Ld），可提高转矩密度和效率，核心公式如下：
 *          T_e = (3/2)×p×[ψ_f×i_q + (L_d - L_q)×i_d×i_q]
 *          约束条件：i_d² + i_q² = i_s²（定子电流幅值恒定）
 *          求导得最优电流分配：i_d = [ -ψ_f ± √(ψ_f² + 8×(L_d - L_q)²×i_q²) ] / [4×(L_d - L_q) ]
 * @safety MTPA控制加入边界保护：
 *         1. 电流幅值限制：i_d² + i_q² ≤ (max_q_axis_current)²；
 *         2. 弱磁兼容：高速区自动调整电流分配，兼容弱磁控制；
 *         3. 参数容错：电机参数偏差≤20%时，仍能维持控制性能
 * @note 1. 该函数由FOC主函数自动调用，无需手动调用；
 *       2. 电机参数（ψ_f、L_d、L_q）需通过实验精确校准，否则影响MTPA效果；
 *       3. 低速区（<1000rpm）MTPA效果显著，高速区自动切换至弱磁控制
 */
void alg_foc_pmsm_mtpa_control(AlgFocPmsmHandleType *foc, float target_torque, float *d_axis_current_ref, float *q_axis_current_ref);

/*!
 * @brief 弱磁控制（高速区扩展）
 * @param[in,out] foc FOC控制句柄指针
 * @details 弱磁控制原理：当电机转速超过额定转速时，定子反电动势增大，接近直流母线电压，
 *          通过注入负的d轴电流（去磁电流），削弱永磁体磁链，从而降低反电动势，扩展转速范围，
 *          核心公式如下：
 *          E_0 = ψ_f×ω_e（反电动势幅值）
 *          U_dc ≥ √3×E_0（电压约束）
 *          弱磁控制通过调节i_d，使E_0 ≤ U_dc/√3
 * @safety 弱磁控制加入多重保护：
 *         1. d轴电流限制：i_d ≥ weak_magnet_max_d_current（避免过度去磁导致电机退磁）；
 *         2. 转矩限制：弱磁期间转矩线性衰减，避免功率过载；
 *         3. 电压裕量保护：保留10%的电压裕量，避免过调制；
 *         4. 故障退出：检测到电流、电压异常时，立即退出弱磁控制
 * @note 1. 弱磁控制仅适用于高速区（≥weak_magnet_speed_threshold）；
 *       2. 弱磁电流大小与转速正相关，转速越高，弱磁电流越大；
 *       3. 过度弱磁会降低电机效率，需平衡转速和效率需求
 */
void alg_foc_pmsm_weak_magnet_control(AlgFocPmsmHandleType *foc);

/*!
 * @brief FOC控制主函数（周期调用）
 * @param[in,out] foc FOC控制句柄指针
 * @param[in] abc_current 三相相电流（A）
 * @param[in] resolver_result 旋转变压器采样结果
 * @param[in] dc_bus_voltage 直流母线电压（V）
 * @param[out] svpwm_duty SVPWM占空比（‰）
 * @return 执行结果
 * @retval 0：执行成功
 * @retval -1：参数错误（foc为NULL或输入参数无效）
 * @retval -2：未初始化
 * @retval -3：故障模式（停止输出）
 * @details FOC主控制流程（100μs周期）：
 *          1. 输入数据预处理：电流、电压、位置信号滤波，异常检测；
 *          2. 模式状态检查：判断当前控制模式，若为故障模式则停止控制；
 *          3. 指令处理：根据控制模式，处理目标转矩/转速指令，加入限制；
 *          4. 坐标变换：Clark变换（ABC→αβ）→Park变换（αβ→dq）；
 *          5. 电流分配：根据电流策略（id=0/MTPA）计算d/q轴参考电流；
 *          6. 弱磁控制：高速区执行弱磁控制，调整d轴参考电流；
 *          7. 电流环控制：d/q轴电流环PID计算，得到d/q轴参考电压；
 *          8. 电压限制：根据直流母线电压，限制d/q轴参考电压幅值；
 *          9. 逆坐标变换：逆Park变换（dq→αβ）；
 *          10. SVPWM调制：αβ电压→三相PWM占空比；
 *          11. 输出：更新SVPWM占空比，反馈控制状态
 * @safety 主函数符合ASIL-B对控制算法的要求：
 *         1. 输入数据异常检测：电流、电压、位置信号超出合理范围时，触发故障；
 *         2. 算法容错：位置信号丢失时，切换至降级模式（反电动势估算）；
 *         3. 输出限制：占空比限制在100-900‰，避免IGBT过压；
 *         4. 周期监控：执行周期超出120μs时，触发超时故障
 * @warning 该函数必须100μs周期严格调用，与电流采样、位置采样同步，否则会导致控制不稳定；
 *          建议通过定时器中断调用，中断优先级高于其他任务
 */
int32_t alg_foc_pmsm_main(AlgFocPmsmHandleType *foc, const AlgFocAbcCurrType *abc_current, const DrvResolverResultType *resolver_result, float dc_bus_voltage, AlgFocSvpwmDutyType *svpwm_duty);

/*!
 * @brief 获取FOC控制状态
 * @param[in] foc FOC控制句柄指针
 * @param[out] status 控制状态结构体指针
 * @return 获取结果
 * @retval 0：获取成功
 * @retval -1：参数错误（foc为NULL或status为NULL）
 * @retval -2：未初始化
 * @note 1. 状态数据包含目标/实际转矩、目标/实际转速、d/q轴电流/电压等，用于整车监控；
 *       2. 建议1ms调用一次，反馈给VCU和上位机；
 *       3. 状态数据采用双缓冲存储，避免读取时被更新覆盖
 */
int32_t alg_foc_pmsm_get_status(const AlgFocPmsmHandleType *foc, AlgFocPmsmStatusType *status);

/*! @} */  // 结束ALG_FOC_PMSM模块

#endif  // ALG_FOC_PMSM_H

c

运行

/*!
 * @file alg_regen_brake.h
 * @brief 再生制动（能量回收）算法模块
 * @author Liu Tao
 * @date 2025-12-04
 * @version V1.0.0
 * @details 实现新能源汽车的再生制动能量回收算法，配合FOC控制模块，将车辆减速时的动能
 *          转换为电能存储到动力电池，支持最大回收功率50kW，回收效率≥75%，
 *          支持驾驶员踏板意图识别、电池SOC状态适配、整车稳定性控制
 * @note 1. 再生制动与机械制动协同工作，根据车速、SOC、踏板深度分配制动力；
 *       2. 回收转矩可通过VCU配置，支持三级回收强度调节；
 *       3. 低SOC（<20%）或高SOC（>95%）时自动降低回收强度，保护电池
 * @safety 符合ISO 26262 ASIL-B等级要求，再生制动故障时自动切换至机械制动，
 *         确保制动性能不下降，符合汽车制动安全标准
 */

#ifndef ALG_REGEN_BRAKE_H
#define ALG_REGEN_BRAKE_H

#include "stdint.h"
#include "alg_foc_pmsm.h"
#include "drv_bms.h"  // 电池管理系统驱动

/*!
 * @defgroup ALG_REGEN_BRAKE 再生制动算法模块
 * @brief 新能源汽车能量回收，最大回收功率50kW，效率≥75%
 * @ingroup ALG
 * @safety 与机械制动协同，故障时自动降级，符合ASIL-B要求
 * @{
 */

/*!
 * @brief 再生制动强度枚举
 */
typedef enum {
    ALG_REGEN_BRAKE_STRENGTH_LOW,    /*!< 弱回收（最大回收转矩50N·m） */
    ALG_REGEN_BRAKE_STRENGTH_MEDIUM, /*!< 中回收（最大回收转矩150N·m） */
    ALG_REGEN_BRAKE_STRENGTH_HIGH,   /*!< 强回收（最大回收转矩300N·m） */
    ALG_REGEN_BRAKE_STRENGTH_AUTO    /*!< 自动回收（根据车速、SOC自动调整） */
} AlgRegenBrakeStrengthType;

/*!
 * @brief 驾驶员踏板意图枚举
 */
typedef enum {
    ALG_REGEN_BRAKE_PEDAL_INTENT_NONE,    /*!< 无制动意图（踏板未踩下） */
    ALG_REGEN_BRAKE_PEDAL_INTENT_LIGHT,   /*!< 轻度制动（踏板行程0-30%） */
    ALG_REGEN_BRAKE_PEDAL_INTENT_MEDIUM,  /*!< 中度制动（踏板行程30%-70%） */
    ALG_REGEN_BRAKE_PEDAL_INTENT_STRONG   /*!< 重度制动（踏板行程70%-100%） */
} AlgRegenBrakePedalIntentType;

/*!
 * @brief 再生制动配置结构体
 */
typedef struct {
    AlgRegenBrakeStrengthType default_strength; /*!< 默认回收强度 */
    float max_regen_power;                      /*!< 最大回收功率（kW），默认50kW */
    float max_regen_torque_low;                /*!< 弱回收最大转矩（N·m），默认50N·m */
    float max_regen_torque_medium;             /*!< 中回收最大转矩（N·m），默认150N·m */
    float max_regen_torque_high;               /*!< 强回收最大转矩（N·m），默认300N·m */
    float soc_low_threshold;                   /*!< 低SOC阈值（%），默认20%（低于此值降低回收） */
    float soc_high_threshold;                  /*!< 高SOC阈值（%），默认95%（高于此值停止回收） */
    float speed_low_threshold;                 /*!< 低速阈值（km/h），默认5km/h（低于此值停止回收） */
    float speed_high_threshold;                /*!< 高速阈值（km/h），默认120km/h（高于此值降低回收） */
    uint8_t brake_cooperation_en;              /*!< 机械制动协同使能：1-使能，0-禁用 */
} AlgRegenBrakeConfigType;

/*!
 * @brief 再生制动状态结构体
 */
typedef struct {
    AlgRegenBrakeStrengthType curr_strength;   /*!< 当前回收强度 */
    AlgRegenBrakePedalIntentType pedal_intent; /*!< 驾驶员踏板意图 */
    float req_regen_torque;                    /*!< 请求回收转矩（N·m，负值） */
    float actual_regen_torque;                 /*!< 实际回收转矩（N·m，负值） */
    float regen_power;                         /*!< 实时回收功率（kW） */
    float regen_energy_total;                  /*!< 累计回收能量（kWh） */
    float battery_soc;                         /*!< 电池SOC（%） */
    float vehicle_speed;                       /*!< 车速（km/h） */
    uint8_t regen_active;                      /*!< 回收激活标志：1-激活，0-未激活 */
    uint8_t fault_flag;                        /*!< 故障标志：1-故障，0-正常 */
} AlgRegenBrakeStatusType;

/*!
 * @brief 再生制动句柄结构体
 */
typedef struct {
    AlgRegenBrakeConfigType config;           /*!< 再生制动配置 */
    AlgRegenBrakeStatusType status;           /*!< 再生制动状态 */
    DrvBmsStatusType bms_status;              /*!< 电池管理系统状态 */
    float pedal_travel;                       /*!< 制动踏板行程（%） */
    float pedal_travel_rate;                  /*!< 制动踏板行程变化率（%/ms） */
    float regen_torque_filtered;              /*!< 滤波后回收转矩（N·m） */
    uint32_t regen_tick;                      /*!< 回收时间计数器（ms） */
} AlgRegenBrakeHandleType;

/*!
 * @brief 再生制动初始化
 * @param[in,out] regen 再生制动句柄指针
 * @param[in] config 再生制动配置结构体指针
 * @return 初始化结果
 * @retval 0：初始化成功
 * @retval -1：参数错误（regen为NULL或config参数非法）
 * @retval -2：BMS驱动初始化失败
 * @safety 初始化流程符合ASIL-B安全要求：
 *         1. 初始化前检查BMS通信状态，确保电池状态可获取；
 *         2. 配置参数合法性检查（如SOC阈值、回收转矩范围）；
 *         3. 初始回收强度为默认值，回收转矩为0；
 *         4. 初始化累计回收能量为0，存储在Flash中（掉电不丢失）
 * @note 1. 再生制动依赖BMS提供的SOC、电压、温度等数据，需确保BMS工作正常；
 *       2. 最大回收功率需与电池充电能力匹配，避免电池过流；
 *       3. 累计回收能量存储在片内Flash，每1分钟更新一次，避免频繁写入
 */
int32_t alg_regen_brake_init(AlgRegenBrakeHandleType *regen, const AlgRegenBrakeConfigType *config);

/*!
 * @brief 驾驶员踏板意图识别
 * @param[in,out] regen 再生制动句柄指针
 * @param[in] pedal_travel 制动踏板行程（%）
 * @param[in] pedal_travel_rate 制动踏板行程变化率（%/ms）
 * @details 踏板意图识别逻辑：
 *          1. 踏板行程0%且变化率为0：无制动意图；
 *          2. 踏板行程0-30%且变化率≤0.5%/ms：轻度制动意图；
 *          3. 踏板行程30%-70%或变化率0.5%-1%/ms：中度制动意图；
 *          4. 踏板行程70%-100%或变化率≥1%/ms：重度制动意图
 * @safety 意图识别加入滤波和防抖处理：
 *         1. 踏板行程采用一阶低通滤波（截止频率5Hz）；
 *         2. 意图切换加入滞回特性（避免频繁切换）；
 *         3. 踏板信号异常（超出0-100%）时，默认无制动意图
 * @note 该函数由主函数自动调用，无需手动调用，识别结果用于回收转矩计算
 */
void alg_regen_brake_pedal_intent_recognize(AlgRegenBrakeHandleType *regen, float pedal_travel, float pedal_travel_rate);

/*!
 * @brief 再生制动转矩计算
 * @param[in,out] regen 再生制动句柄指针
 * @param[in] vehicle_speed 车速（km/h）
 * @param[in] bms_status 电池管理系统状态（SOC、电压、温度）
 * @return 计算得到的回收转矩（N·m，负值）
 * @details 回收转矩计算流程：
 *          1. 状态判断：检查车速、SOC、电池温度是否满足回收条件；
 *          2. 回收强度确定：根据当前回收强度模式，确定最大回收转矩；
 *          3. 踏板意图适配：根据踏板意图调整回收转矩（轻度制动→全回收，重度制动→部分回收）；
 *          4. 边界限制：根据车速、SOC、电池电流限制回收转矩；
 *          5. 平滑处理：回收转矩变化率限制≤0.3N·m/ms，避免冲击
 * @safety 回收转矩计算加入多重安全限制：
 *         1. 电池电流限制：回收电流≤电池最大充电电流（默认200A）；
 *         2. 电池温度限制：电池温度<-10℃或>55℃时，停止回收；
 *         3. 车速限制：车速<speed_low_threshold时，停止回收；
 *         4. SOC限制：SOC<soc_low_threshold或>SOC_high_threshold时，降低或停止回收；
 *         5. 故障限制：BMS故障或电机故障时，停止回收
 * @note 1. 回收转矩为负值，与驱动转矩（正值）区分；
 *       2. 轻度制动时，优先使用再生制动（机械制动不介入）；
 *       3. 重度制动时，再生制动与机械制动协同工作，回收转矩占比≤50%
 */
float alg_regen_brake_calc_torque(AlgRegenBrakeHandleType *regen, float vehicle_speed, const DrvBmsStatusType *bms_status);

/*!
 * @brief 再生制动主函数（周期调用）
 * @param[in,out] regen 再生制动句柄指针
 * @param[in] pedal_travel 制动踏板行程（%）
 * @param[in] pedal_travel_rate 制动踏板行程变化率（%/ms）
 * @param[in] vehicle_speed 车速（km/h）
 * @param[in] bms_status 电池管理系统状态
 * @param[out] regen_torque 再生制动转矩（N·m，负值）
 * @return 执行结果
 * @retval 0：执行成功
 * @retval -1：参数错误（regen为NULL或输入参数无效）
 * @retval -2：未初始化
 * @retval -3：故障模式（停止回收）
 * @details 再生制动主流程（10ms周期）：
 *          1. 输入数据

5.2.4 应用层（APP）核心模块：FOC 控制器整车交互与管理

c

运行

/*!
 * @file app_foc_ctrl.h
 * @brief 汽车FOC控制器应用层核心模块
 * @author Zhou Yang
 * @date 2025-12-04
 * @version V1.0.0
 * @details 实现汽车FOC控制器的整车交互、驾驶模式管理、转矩协调、故障管理等核心逻辑，
 *          作为控制器与VCU（整车控制器）、BMS（电池管理系统）的交互枢纽，
 *          符合ISO 26262 ASIL-B功能安全要求，支持转矩控制、能量回收、跛行模式等功能
 * @note 1. 应用层采用状态机设计，包含初始化、就绪、运行、故障、跛行5种状态；
 *       2. 所有整车交互信号通过CAN FD通信，波特率500kbps，信号周期10ms；
 *       3. 故障处理采用分级机制，致命故障触发安全关断，非致命故障进入跛行模式
 * @safety 安全目标：避免控制器故障导致电机非预期转矩输出或制动失效，保障车辆行驶安全；
 *         安全机制：双核心监控、故障分级处理、安全关断、跛行回家
 */

#ifndef APP_FOC_CTRL_H
#define APP_FOC_CTRL_H

#include "safe_smu.h"
#include "drv_igbt.h"
#include "drv_resolver.h"
#include "alg_foc_pmsm.h"
#include "alg_regen_brake.h"
#include "comm_canfd.h"

/*!
 * @defgroup APP_FOC_CTRL FOC控制器应用层模块
 * @brief 整车交互与核心逻辑管理，符合ISO 26262 ASIL-B要求
 * @ingroup APP
 * @safety 状态机管理、故障分级处理、安全关断机制，确保整车安全
 * @{
 */

/*!
 * @brief FOC控制器状态机枚举
 */
typedef enum {
    APP_FOC_STATE_INIT,      /*!< 初始化状态（系统启动后执行） */
    APP_FOC_STATE_READY,     /*!< 就绪状态（初始化完成，等待VCU指令） */
    APP_FOC_STATE_RUNNING,   /*!< 运行状态（正常转矩/转速控制） */
    APP_FOC_STATE_LIMP,      /*!< 跛行状态（非致命故障，降级运行） */
    APP_FOC_STATE_FAULT      /*!< 故障状态（致命故障，安全关断） */
} AppFocStateType;

/*!
 * @brief 驾驶模式枚举（适配整车控制策略）
 */
typedef enum {
    APP_FOC_DRIVE_MODE_ECO,      /*!< 经济模式（优先节能，限制最大转矩） */
    APP_FOC_DRIVE_MODE_NORMAL,   /*!< 标准模式（平衡动力与节能） */
    APP_FOC_DRIVE_MODE_SPORT,    /*!< 运动模式（优先动力，最大转矩输出） */
    APP_FOC_DRIVE_MODE_BRAKE,    /*!< 制动模式（能量回收+机械制动） */
    APP_FOC_DRIVE_MODE_PARK      /*!< 驻车模式（转矩指令为0，IGBT关断） */
} AppFocDriveModeType;

/*!
 * @brief VCU指令结构体（整车控制指令）
 */
typedef struct {
    AppFocDriveModeType drive_mode;  /*!< 驾驶模式指令 */
    float target_torque;             /*!< 目标转矩（N·m），正-驱动，负-制动回收 */
    float target_speed;              /*!< 目标转速（rpm），仅定速巡航时有效 */
    uint8_t enable_ctrl;             /*!< 控制使能：1-使能，0-禁用 */
    uint8_t regen_strength;          /*!< 再生制动强度（0-3级，对应弱/中/强/自动） */
    uint8_t limp_request;            /*!< 跛行请求：1-请求进入跛行，0-正常 */
} AppFocVcuCmdType;

/*!
 * @brief 控制器反馈结构体（向VCU上报状态）
 */
typedef struct {
    AppFocStateType curr_state;      /*!< 当前控制器状态 */
    AppFocDriveModeType curr_mode;   /*!< 当前驾驶模式 */
    float actual_torque;             /*!< 实际输出转矩（N·m） */
    float actual_speed;              /*!< 实际电机转速（rpm） */
    float motor_temp;                /*!< 电机绕组温度（℃） */
    float igbt_temp;                 /*!< IGBT结温（℃） */
    float dc_bus_voltage;            /*!< 直流母线电压（V） */
    float regen_power;               /*!< 再生制动功率（kW） */
    SafeFaultCodeType active_fault;  /*!< 当前激活的故障码 */
    uint8_t ctrl_ready;              /*!< 控制就绪标志：1-就绪，0-未就绪 */
} AppFocFeedbackType;

/*!
 * @brief FOC控制器配置结构体
 */
typedef struct {
    float eco_mode_max_torque;       /*!< 经济模式最大转矩（N·m），默认200N·m */
    float sport_mode_max_torque;     /*!< 运动模式最大转矩（N·m），默认400N·m */
    float limp_mode_max_torque;      /*!< 跛行模式最大转矩（N·m），默认50N·m */
    float limp_mode_max_speed;       /*!< 跛行模式最大转速（rpm），默认1000rpm */
    uint32_t can_comm_timeout;       /*!< CAN通信超时时间（ms），默认100ms */
    uint8_t auto_limp_en;            /*!< 自动跛行使能：1-故障时自动进入，0-需VCU请求 */
} AppFocConfigType;

/*!
 * @brief FOC控制器句柄结构体
 */
typedef struct {
    AppFocStateType curr_state;      /*!< 当前状态机状态 */
    AppFocConfigType config;         /*!< 控制器配置 */
    AppFocVcuCmdType vcu_cmd;        /*!< 最新VCU指令 */
    AppFocFeedbackType feedback;     /*!< 控制器反馈数据 */
    SafeSmuHandleType smu;           /*!< 安全监控单元句柄 */
    DrvIgbtHandleType igbt;          /*!< IGBT驱动句柄 */
    DrvResolverHandleType resolver;  /*!< 旋转变压器句柄 */
    AlgFocPmsmHandleType foc;        /*!< FOC控制算法句柄 */
    AlgRegenBrakeHandleType regen;   /*!< 再生制动句柄 */
    CommCanfdHandleType canfd;       /*!< CAN FD通信句柄 */
    AlgFocPmsmMotorParamType motor_param; /*!< 电机参数 */
    uint32_t comm_tick;              /*!< 通信超时计数器（ms） */
    uint32_t state_tick;             /*!< 状态机计数器（ms） */
} AppFocCtrlHandleType;

/*!
 * @brief FOC控制器初始化（核心初始化函数）
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @param[in] motor_param 电机参数结构体指针
 * @param[in] config 控制器配置结构体指针
 * @return 初始化结果
 * @retval 0：初始化成功
 * @retval -1：参数错误（foc_ctrl为NULL或参数非法）
 * @retval -2：安全监控单元初始化失败
 * @retval -3：IGBT驱动初始化失败
 * @retval -4：旋转变压器初始化失败
 * @retval -5：FOC算法初始化失败
 * @retval -6：再生制动初始化失败
 * @retval -7：CAN FD通信初始化失败
 * @safety 初始化流程符合ASIL-B安全要求，采用“分层初始化+故障回滚”机制：
 *         1. 按安全优先级初始化模块（安全监控→驱动→算法→通信）；
 *         2. 某模块初始化失败时，回滚已初始化模块（关闭外设、清除状态）；
 *         3. 初始化完成后执行全局自校验（硬件+软件）；
 *         4. 自校验通过后切换至就绪状态，否则进入故障状态
 * @note 1. 初始化需在系统启动后优先执行，耗时约500ms；
 *       2. 电机参数需根据实际电机型号精确配置，直接影响控制性能；
 *       3. 初始化结果通过CAN FD上报给VCU，支持整车上电自检
 */
int32_t app_foc_ctrl_init(AppFocCtrlHandleType *foc_ctrl, const AlgFocPmsmMotorParamType *motor_param, const AppFocConfigType *config);

/*!
 * @brief 状态机处理函数（核心逻辑调度）
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @details 状态机调度流程：
 *          1. 状态输入：获取当前状态、VCU指令、故障状态；
 *          2. 状态判断：根据输入条件确定目标状态；
 *          3. 状态切换：执行状态切换动作（初始化→就绪→运行→跛行/故障）；
 *          4. 状态输出：更新控制器状态，上报给VCU
 * @safety 状态机采用“状态互锁+超时保护”机制：
 *         1. 状态切换需满足前置条件（如就绪状态需初始化完成+无故障）；
 *         2. 状态切换超时保护（如运行→跛行切换超时≤100ms）；
 *         3. 故障状态优先级最高，任何状态下检测到致命故障立即切换至故障状态
 * @note 1. 该函数需10ms周期调用，与CAN通信周期同步；
 *       2. 状态切换动作需原子执行，避免被中断打断；
 *       3. 状态机状态通过反馈结构体实时上报VCU，支持整车状态监控
 */
void app_foc_ctrl_state_machine(AppFocCtrlHandleType *foc_ctrl);

/*!
 * @brief VCU指令解析（CAN FD接收回调）
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @param[in] vcu_cmd VCU指令结构体指针
 * @return 解析结果
 * @retval 0：解析成功
 * @retval -1：参数错误（foc_ctrl为NULL或vcu_cmd为NULL）
 * @retval -2：指令非法（如目标转矩超出当前模式限制）
 * @details 指令解析逻辑：
 *          1. 指令合法性检查：目标转矩/转速需在当前模式允许范围内；
 *          2. 驾驶模式解析：根据VCU指令切换驾驶模式，更新最大转矩限制；
 *          3. 再生制动强度解析：将VCU指令映射为再生制动强度模式；
 *          4. 控制使能解析：使能/禁用控制器，禁用时转矩指令置0
 * @safety 指令解析加入多重安全限制：
 *         1. 转矩限制：根据驾驶模式限制目标转矩（经济<标准<运动）；
 *         2. 转速限制：目标转速≤电机最大转速；
 *         3. 指令防抖：连续3次接收相同指令才执行切换，避免误触发；
 *         4. 超时处理：超过can_comm_timeout未接收指令，触发通信超时故障
 * @note 该函数由CAN FD接收中断触发，禁止手动调用；
 *       指令解析后存储在vcu_cmd成员，供状态机和控制算法调用
 */
int32_t app_foc_ctrl_parse_vcu_cmd(AppFocCtrlHandleType *foc_ctrl, const AppFocVcuCmdType *vcu_cmd);

/*!
 * @brief 转矩协调与控制（核心控制逻辑）
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @return 执行结果
 * @retval 0：执行成功
 * @retval -1：参数错误（foc_ctrl为NULL）
 * @retval -2：非运行状态（无法执行控制）
 * @retval -3：控制失败（如FOC算法执行失败）
 * @details 转矩协调流程：
 *          1. 指令预处理：根据驾驶模式和故障状态，调整目标转矩；
 *          2. 再生制动协调：制动模式下，融合再生制动转矩与VCU制动指令；
 *          3. 限制处理：转矩变化率限制、温度补偿（高温降额）；
 *          4. 算法调用：将目标转矩发送给FOC算法，执行矢量控制；
 *          5. 输出执行：将FOC算法生成的PWM占空比发送给IGBT驱动模块
 * @safety 转矩控制加入多重安全机制：
 *         1. 温度降额：电机温度>120℃或IGBT温度>140℃时，转矩线性降额；
 *         2. 电压补偿：直流母线电压波动时，动态调整转矩指令，避免过压；
 *         3. 故障熔断：检测到故障时，立即将目标转矩置0，关闭IGBT；
 *         4. 双核心校验：主从核心同时计算目标转矩，结果不一致时触发故障
 * @note 1. 该函数需100μs周期调用，与FOC算法执行周期同步；
 *       2. 再生制动转矩与驱动转矩互斥，制动时优先执行再生制动；
 *       3. 温度降额系数=1 - (当前温度-阈值温度)/(极限温度-阈值温度)，最低降额至50%
 */
int32_t app_foc_ctrl_torque_control(AppFocCtrlHandleType *foc_ctrl);

/*!
 * @brief 故障管理与处理
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @param[in] fault_code 故障码
 * @param[in] fault_level 故障等级（1-轻微，2-中等，3-致命）
 * @details 故障处理流程：
 *          1. 故障记录：存储故障码、故障发生时间、故障时的关键参数（转矩、转速、温度）；
 *          2. 故障上报：通过CAN FD紧急帧将故障信息上报给VCU和BMS；
 *          3. 状态切换：根据故障等级切换状态机状态（轻微→正常，中等→跛行，致命→故障）；
 *          4. 安全动作：致命故障时触发安全关断（关闭IGBT、转矩置0），中等故障时进入跛行模式
 * @safety 故障处理符合ISO 26262 ASIL-B要求：
 *         1. 故障诊断覆盖率≥95%，支持故障自诊断和外部诊断；
 *         2. 故障存储采用非易失性存储，可存储最近100条故障记录；
 *         3. 故障恢复：轻微故障自动恢复，中等故障需VCU确认恢复，致命故障需复位控制器；
 *         4. 跛行模式：限制转矩和转速，确保车辆能安全行驶至维修站
 * @note 1. 故障等级由安全监控模块确定，1-轻微（如通信超时），2-中等（如轻度过温），3-致命（如IGBT短路）；
 *       2. 故障记录包含时间戳、控制器状态、关键电参数，支持故障追溯；
 *       3. 跛行模式下，仅保留核心控制功能，禁用能量回收和运动模式
 */
void app_foc_ctrl_fault_handler(AppFocCtrlHandleType *foc_ctrl, SafeFaultCodeType fault_code, uint8_t fault_level);

/*!
 * @brief 控制器反馈上报（CAN FD发送）
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @return 上报结果
 * @retval 0：上报成功
 * @retval -1：参数错误（foc_ctrl为NULL）
 * @retval -2：CAN FD发送失败
 * @details 反馈上报流程：
 *          1. 数据更新：采集控制器状态、转矩、转速、温度、故障等数据；
 *          2. 数据打包：按整车通信协议打包反馈数据，加入CRC32校验；
 *          3. CAN发送：通过CAN FD发送反馈帧，周期10ms；
 *          4. 发送确认：检查发送状态，发送失败时重试3次，仍失败则触发通信故障
 * @safety 反馈上报符合汽车行业通信标准：
 *         1. 数据校验：所有反馈数据加入CRC32校验，避免数据传输错误；
 *         2. 超时重传：发送失败时自动重试，确保数据可靠性；
 *         3. 冗余设计：关键信号（故障码、控制器状态）采用双帧发送，提高容错性；
 *         4. 通信监控：监控CAN总线状态，总线故障时触发通信故障
 * @note 1. 反馈数据按整车协议定义的信号格式打包，字节序为大端序；
 *       2. 关键参数（如故障码、实际转矩）的分辨率需满足VCU要求（转矩分辨率0.1N·m）；
 *       3. 建议10ms周期调用，与VCU指令接收周期同步
 */
int32_t app_foc_ctrl_feedback_report(AppFocCtrlHandleType *foc_ctrl);

/*!
 * @brief FOC控制器主循环（顶层调度）
 * @param[in,out] foc_ctrl FOC控制器句柄指针
 * @return 循环执行结果
 * @retval 0：正常执行
 * @retval -1：参数错误（foc_ctrl为NULL）
 * @retval -2：未初始化
 * @details 主循环调度流程（10ms周期，由RTOS任务调用）：
 *          1. 状态机处理：调用app_foc_ctrl_state_machine()，更新状态机状态；
 *          2. 故障检测：调用safe_smu_main()，检测硬件和软件故障；
 *          3. 指令处理：解析最新VCU指令，更新控制参数；
 *          4. 转矩控制：根据状态机状态，调用app_foc_ctrl_torque_control()执行控制；
 *          5. 反馈上报：调用app_foc_ctrl_feedback_report()，向VCU上报状态；
 *          6. 超时监控：监控通信超时、控制周期超时等异常
 * @safety 主循环采用“时间触发+事件驱动”混合机制，符合ASIL-B要求：
 *         1. 周期监控：主循环周期超出12ms时，触发超时故障；
 *         2. 任务优先级：主循环任务优先级最高（RTOS优先级1），避免被其他任务阻塞；
 *         3. Watchdog喂狗：主循环中周期性喂硬件看门狗和软件看门狗；
 *         4. 双核心同步：主从核心主循环同步执行，状态不一致时触发故障
 * @warning 该函数是控制器的顶层调度函数，必须由RTOS任务独立调用，禁止在中断中执行；
 *          主循环执行周期需严格控制在10ms±2ms内，否则会影响控制性能和通信同步
 */
int32_t app_foc_ctrl_main_loop(AppFocCtrlHandleType *foc_ctrl);

/*! @} */  // 结束APP_FOC_CTRL模块

#endif  // APP_FOC_CTRL_H

5.3 汽车 FOC 控制器项目 Doxygen 配置文件（安全合规优化版）

plaintext

# 汽车FOC控制器项目Doxygen配置文件
# 配置文件版本：Doxyfile 1.11.0
# 生成日期：2025-12-04
# 项目名称（符合汽车行业命名规范）
PROJECT_NAME           = "汽车FOC控制器（100kW PMSM）"
PROJECT_NUMBER         = "V1.0.0"
PROJECT_BRIEF          = "ISO 26262 ASIL-B等级，适配100kW永磁同步电机，支持矢量控制+能量回收"
PROJECT_LOGO           = doc/automotive_logo.png
OUTPUT_DIRECTORY       = doc/
CREATE_SUBDIRS         = NO
OUTPUT_LANGUAGE        = Chinese
BRIEF_MEMBER_DESC      = YES
REPEAT_BRIEF           = YES
ABBREVIATE_BRIEF       = "The $name class" \
                         "The $name module" \
                         "The $name driver" \
                         is \
                         provides \
                         specifies \
                         contains
ALWAYS_DETAILED_SEC    = YES  # 强制显示详细描述（符合功能安全文档要求）
INLINE_INHERITED_MEMB  = NO
FULL_PATH_NAMES        = YES
STRIP_FROM_PATH        = src/ inc/ safe/ drv/ alg/ app/ comm/
STRIP_FROM_INC_PATH    = inc/
SHORT_NAMES            = NO
JAVADOC_AUTOBRIEF      = NO
QT_AUTOBRIEF           = NO
MULTILINE_CPP_IS_BRIEF = NO
INHERIT_DOCS           = YES
SEPARATE_MEMBER_PAGES  = NO
TAB_SIZE               = 4
ALIASES                = "safety{1}=@safety \1"  # 自定义功能安全标签
OPTIMIZE_OUTPUT_FOR_C  = YES
EXTENSION_MAPPING      = .s=C .asm=C .hpp=C++
MARKDOWN_SUPPORT       = YES
TOC_INCLUDE_HEADINGS   = 6  # 支持6级标题（适配复杂层级文档）
AUTOLINK_SUPPORT       = YES
BUILTIN_STL_SUPPORT    = NO
CPP_CLI_SUPPORT        = NO
SIP_SUPPORT            = NO
IDL_PROPERTY_SUPPORT   = YES
DISTRIBUTE_GROUP_DOC   = YES
GROUP_NESTED_COMPOUNDS = YES
SUBGROUPING            = YES
INLINE_GROUPED_CLASSES = NO
INLINE_SIMPLE_STRUCTS  = NO
TYPEDEF_HIDES_STRUCT   = NO
LOOKUP_CACHE_SIZE      = 0

# 源码路径配置（覆盖所有功能模块）
INPUT                  = src/ inc/ safe/ drv/ alg/ app/ comm/ doc/README.md doc/Safety_Plan.md
INPUT_ENCODING         = UTF-8
FILE_PATTERNS          = *.c *.h *.cpp *.hpp *.s *.asm *.md *.txt
RECURSIVE              = YES
EXCLUDE                = src/test/ inc/test/ build/ obj/ bin/ doc/template/
EXCLUDE_SYMLINKS       = YES
EXCLUDE_PATTERNS       = *test* *mock* *demo* *sim*  # 排除测试、仿真文件
EXAMPLE_PATH           = example/ doc/examples/
EXAMPLE_PATTERNS       = *.c *.h *.cpp *.hpp *.md
EXAMPLE_RECURSIVE      = YES
IMAGE_PATH             = doc/images/ doc/safety_images/
INPUT_FILTER           =
FILTER_PATHS           =
FILTER_PATTERNS        =
FILTER_SOURCE_FILES    = NO
FILTER_SOURCE_PATHS    = NO

# 文档输出配置（侧重功能安全合规）
GENERATE_HTML          = YES
HTML_OUTPUT            = html
HTML_FILE_EXTENSION    = .html
HTML_HEADER            = doc/template/safety_header.html  # 包含功能安全声明
HTML_FOOTER            = doc/template/safety_footer.html  # 包含文档版本和修订记录
HTML_STYLESHEET        = doc/template/automotive.css  # 汽车行业风格CSS
HTML_EXTRA_STYLESHEET  =
HTML_EXTRA_FILES       = doc/Safety_Plan.md  # 功能安全计划文件
HTML_COLORSTYLE_HUE    = 200
HTML_COLORSTYLE_SAT    = 100
HTML_COLORSTYLE_GAMMA  = 90
HTML_TIMESTAMP         = YES
HTML_DYNAMIC_SECTIONS  = NO
HTML_CODE_HIGHLIGHTING = YES
HTML_BRIEF_LINK_TEXT   = "详细说明"
GENERATE_HTMLHELP      = NO
GENERATE_CHM           = NO
GENERATE_QHP           = NO
GENERATE_ECLIPSEHELP   = NO
GENERATE_JAVADOC_TAGFILE=
JAVADOC_BASENAME       =
GENERATE_LATEX         = YES  # 生成LaTeX文档（用于功能安全合规报告）
LATEX_OUTPUT           = latex
LATEX_CMD_NAME         = latex
MAKEINDEX_CMD_NAME     = makeindex
COMPACT_LATEX          = NO
PAPER_TYPE             = a4
EXTRA_PACKAGES         = geometry hyperref xcolor
LATEX_HEADER           = doc/template/safety_latex_header.tex
LATEX_FOOTER           = doc/template/safety_latex_footer.tex
PDF_HYPERLINKS         = YES
USE_PDFLATEX           = YES
LATEX_BATCHMODE        = NO
GENERATE_RTF           = YES  # 生成RTF文档（用于客户交付）
RTF_OUTPUT             = rtf
COMPACT_RTF            = NO
RTF_HYPERLINKS         = YES
RTF_STYLESHEET_FILE    = doc/template/safety_rtf.sty
GENERATE_MAN           = YES
MAN_OUTPUT             = man
MAN_EXTENSION          = .3
MAN_LINKS              = YES
GENERATE_XML           = YES  # 生成XML文档（用于自动化合规检查）
XML_OUTPUT             = xml
XML_PROGRAMLISTING     = YES
GENERATE_DOCSET        = NO
GENERATE_HTMLINDEX     = YES
GENERATE_SEARCHINDEX   = YES
SEARCHENGINE           = YES
SERVER_BASED_SEARCH    = NO
SEARCHDATA_FILE        = searchdata.xml
EXTRA_SEARCH_MAPPINGS  =

# 代码提取配置（功能安全相关增强）
EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = NO
EXTRACT_PRIV_VIRTUAL   = NO
EXTRACT_PACKAGE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = NO
EXTRACT_LOCAL_METHODS  = NO
EXTRACT_ANON_NSPACES   = NO
HIDE_UNDOC_MEMBERS     = YES
HIDE_UNDOC_CLASSES     = YES
HIDE_FRIEND_COMPOUNDS  = NO
HIDE_IN_BODY_DOCS      = NO
INTERNAL_DOCS          = NO  # 不显示内部文档（仅暴露对外接口）
CASE_SENSE_NAMES       = YES
HIDE_SCOPE_NAMES       = NO
HIDE_COMPOUND_REFERENCE= NO
SHOW_INCLUDE_FILES     = YES
SHOW_GROUPED_MEMB_INC  = YES
FORCE_LOCAL_INCLUDES   = NO
INLINE_INFO            = YES
SORT_MEMBER_DOCS       = YES
SORT_BRIEF_DOCS        = YES
SORT_MEMBERS_CTORS_1ST = NO
SORT_GROUP_NAMES       = YES
SORT_BY_SCOPE_NAME     = NO
STRICT_PROTO_MATCHING  = YES  # 严格匹配函数原型（避免接口歧义）
GENERATE_TODOLIST      = YES
GENERATE_TESTLIST      = YES
GENERATE_BUGLIST       = YES
GENERATE_DEPRECATEDLIST= YES
ENABLED_SECTIONS       = safety  # 启用功能安全相关章节
MAX_INITIALIZER_LINES  = 50  # 显示完整的初始化代码（便于安全审查）
SHOW_USED_FILES        = YES
SHOW_FILES             = YES
SHOW_NAMESPACES        = YES
FILE_VERSION_FILTER    =
LAYOUT_FILE            = doc/template/safety_layout.xml  # 自定义功能安全文档布局
CITE_BIB_FILES         = doc/references.bib  # 引用功能安全相关标准文档

# 图表配置（增强安全相关图表）
CLASS_DIAGRAMS         = YES
MSCGEN_PATH            =
DIA_PATH               =
HIDE_UNDOC_RELATIONS   = YES
HAVE_DOT               = YES
DOT_NUM_THREADS        = 1
DOT_FONTNAME           = Arial
DOT_FONTSIZE           = 10
DOT_FONTPATH           =
CLASS_GRAPH            = YES
COLLABORATION_GRAPH    = YES
GROUP_GRAPHS           = YES
UML_LOOK               = YES  # 采用UML风格图表（便于安全分析）
UML_LIMIT_NUM_FIELDS   = 15
TEMPLATE_RELATIONS     = YES
MULTI_IMAGE_PER_TAG    = NO
DOT_GRAPH_MAX_NODES    = 100
MAX_DOT_GRAPH_DEPTH    = 8  # 增加图表深度（适配复杂安全机制）
DOT_TRANSPARENT        = NO
DOT_MULTI_TARGETS      = NO
GENERATE_LEGEND        = YES
DOT_CLEANUP            = YES
CALL_GRAPH             = YES
CALLER_GRAPH           = YES
GRAPHICAL_HIERARCHY    = YES
DIRECTORY_GRAPH        = YES
DOT_IMAGE_FORMAT       = svg
INTERACTIVE_SVG        = YES  # 交互式SVG图表（便于查看复杂安全流程）
DOT_PATH               = /usr/bin/dot  # Linux路径
# DOT_PATH               = C:/Program Files/Graphviz/bin/dot.exe  # Windows路径

# 警告配置（严格模式，确保文档完整性）
WARN_IF_UNDOCUMENTED   = YES
WARN_IF_DOC_ERROR      = YES
WARN_IF_INCOMPLETE_DOC = YES
WARN_NO_PARAMDOC       = YES
WARN_NO_RETURN         = YES
WARN_NO_THROWS         = NO
WARN_NO_INLINE         = NO
WARN_NO_RELATED        = NO
WARN_NO_FUNCTION_RETURN= YES
WARN_FORMAT            = "$file:$line: 文档警告: $text"
WARN_DEPRECATED        = YES
WARN_UNUSED_PARAM      = YES
WARN_UNUSED_WARNING    = NO
WARN_MISSING_PROTO     = YES
WARN_MISSING_INCLUDE_DIRS = YES
WARN_DOC_REFERENCES    = YES
WARN_UNDOC_REFERENCES  = NO
WARN_EXIT_CODE         = 1  # 文档警告时返回非0退出码（阻断CI流程）
WARN_LOGFILE           = doc/doxygen_safety_warn.log  # 功能安全相关警告日志

5.4 汽车 FOC 控制器项目文档生成效果与合规应用

5.4.1 文档目录结构（安全合规导向）

plaintext

doc/
├── html/                  # HTML文档主目录（核心交付物）
│   ├── index.html         # 首页（包含项目概述、功能安全声明）
│   ├── modules.html       # 模块列表页（按SAFE/DRV/ALG/APP/COMM划分）
│   ├── classes.html       # 结构体/枚举列表页（含安全相关类型）
│   ├── functions.html     # 函数列表页（支持按安全等级筛选）
│   ├── safety.html        # 功能安全专题页（安全目标、机制、合规性）
│   ├── faults.html        # 故障码列表页（含故障处理流程）
│   ├── todo.html          # 待完成事项（含安全优化项）
│   ├── bugs.html          # 已知问题（含安全风险等级）
│   ├── search/            # 搜索功能目录
│   ├── graphs/            # 安全相关图表（状态机图、故障流程图）
│   │   ├── state_machine.svg  # 控制器状态机图
│   │   ├── fault_handler.svg  # 故障处理流程图
│   │   └── safety_mechanism.svg  # 功能安全机制图
│   └── Safety_Plan.md     # 功能安全计划（直接嵌入HTML）
├── latex/                 # LaTeX文档（用于生成PDF合规报告）
│   ├── refman.tex         # 主TeX文件
│   └── ...                # 辅助文件
├── rtf/                   # RTF文档（客户交付用）
│   ├── refman.rtf         # 完整RTF文档
├── xml/                   # XML文档（自动化合规检查用）
│   ├── index.xml          # XML索引文件
├── man/                   # Man Page文档（Linux环境调试用）
├── doxygen_safety_warn.log  # 安全相关警告日志
├── references.bib         # 功能安全标准引用文献
└── template/              # 自定义模板目录

5.4.2 核心文档页面（功能安全特色）

页面名称	核心功能	合规应用场景
功能安全专题页（safety.html）	汇总安全目标、安全机制、合规性证据、安全分析结果	ISO 26262 合规审查时，提供集中的安全相关文档
故障码列表页（faults.html）	按故障等级分类展示所有故障码、触发条件、处理流程、安全动作	故障排查、维修手册编写、安全风险评估
状态机图（state_machine.svg）	可视化控制器状态切换逻辑，标注状态切换的安全条件	安全分析（如失效模式与影响分析 FMEA）
故障处理流程图（fault_handler.svg）	展示故障检测→记录→上报→处理→恢复的完整流程	功能安全审计时，验证故障处理的合规性
功能安全机制图（safety_mechanism.svg）	展示双核心监控、安全关断、跛行模式等安全机制的关联关系	安全目标达成验证，证明安全机制的有效性

5.4.3 文档合规应用场景

应用场景	文档使用方式	合规价值
ISO 26262 ASIL-B 认证	提交 LaTeX 生成的 PDF 合规报告、XML 自动化检查文件、安全专题页	满足认证对 “文档可追溯性”“安全机制文档化” 的要求
整车厂供应商审核	提供 HTML 文档（侧重接口和安全）、RTF 文档（客户定制格式）	展示控制器的安全设计、接口标准化、故障处理能力
内部安全评审	参考安全专题页、故障处理流程图、状态机图	识别安全设计漏洞，优化安全机制
维修与售后	使用故障码列表页、故障处理流程	快速定位故障原因，执行规范的故障处理步骤
软件迭代	查看 TODO 页的安全优化项、bugs 页的安全风险	确保迭代过程中不引入新的安全风险，持续优化安全性能

5.5 汽车 FOC 控制器文档维护与合规保障

1. 文档与安全计划同步：功能安全计划（Safety Plan.md）更新后，自动同步至 HTML 文档，确保合规性证据实时更新；
2. 安全相关警告强制处理：doxygen_safety_warn.log中所有警告（如安全相关注释缺失）需在代码提交前修复，CI 流程阻断未修复警告的提交；
3. 合规报告自动生成：通过 LaTeX 模板自动生成 PDF 合规报告，包含安全目标、机制、故障分析、测试结果等内容，支持一键导出；
4. 版本化管理：文档与代码版本绑定，每个代码版本对应唯一的文档版本，通过 Git 标签管理，支持合规审查时的版本追溯；
5. 跨团队协作支持：HTML 文档部署到内部安全服务器，设置访问权限（如安全团队、审核团队、客户），支持在线评论和反馈。

六、总结：Doxygen 在嵌入式开发中的核心价值与实践建议

6.1 核心价值回顾

Doxygen 作为嵌入式开发的 “文档自动化利器”，其价值远不止 “代码转文档”，而是贯穿项目全生命周期的 “效率提升 + 合规保障 + 风险降低” 工具：

价值维度	具体体现	无人机电调 / 汽车 FOC 案例印证
效率提升	1. 自动化生成结构化文档，减少手动编写成本；2. 可视化代码架构和调用关系，降低团队协作门槛；3. 集成到 CI/CD 流程，实现文档实时更新	无人机电调团队新成员 1-2 天掌握架构；汽车 FOC 控制器文档随代码自动更新，无需专人维护
合规保障	1. 强制规范注释，确保接口、算法、故障逻辑可追溯；2. 支持生成多格式文档，满足行业合规要求（如 ISO 26262）；3. 故障码、安全机制结构化呈现，提供合规证据	汽车 FOC 控制器通过 Doxygen 文档满足 ASIL-B 合规审查；无人机电调文档满足无人机行业产品认证要求
风险降低	1. 接口文档清晰，减少模块调用错误；2. 算法逻辑文档化，降低维护和迭代风险；3. 故障处理流程可视化，减少故障排查时间	无人机电调通过文档快速定位通信超时故障；汽车 FOC 控制器故障处理流程标准化，降低维修风险

6.2 嵌入式开发实践建议

6.2.1 团队落地流程

1. 前期准备：

   • 制定团队注释规范（参考本文嵌入式注释规则），明确必填命令（如 @file、@brief、@param）；
   • 生成项目专属 Doxyfile 配置文件（基于本文案例模板修改），固化核心配置；
   • 安装 Graphviz 工具，启用图表生成功能（调用关系图、状态机图等）。

2. 编码阶段：

   • 遵循 “代码即文档” 原则，编写代码时同步编写注释，避免 “事后补注释”；
   • 关键模块（驱动、算法、安全相关）优先完成注释，确保核心逻辑可追溯；
   • 定期运行doxygen生成文档，查看警告日志，补全无注释或注释错误的内容。

3. 集成与维护：

   • 将文档生成加入 Makefile/CMake 构建流程，执行make doc即可生成最新文档；
   • 配置 CI/CD 流程，代码合并到主分支后自动生成并部署文档；
   • 每季度进行一次文档审计，优化注释质量和配置合理性。

6.2.2 避坑指南

1. 注释常见问题：

   • 避免 “注释与代码不一致”：代码修改后，同步更新注释，可通过 Git 提交钩子检查；
   • 避免 “过度注释”：内部实现细节用 // 注释（不被 Doxygen 识别），仅对外接口和核心逻辑用 Doxygen 注释；
   • 避免 “中文乱码”：统一编码为 UTF-8，配置文件中设置INPUT_ENCODING = UTF-8。

2. 配置常见问题：

   • 图表生成失败：确保安装 Graphviz，并在配置文件中正确设置DOT_PATH；
   • 文档缺失模块：检查INPUT参数是否包含目标目录，RECURSIVE是否设置为 YES；
   • 警告过多：优先处理WARN_NO_PARAMDOC（参数无注释）、WARN_NO_RETURN（返回值无注释）等关键警告。

3. 合规相关问题：

   • 功能安全项目：启用ENABLED_SECTIONS = safety，自定义 @safety 标签，集中展示安全相关内容；
   • 多团队协作：通过EXTRACT_PRIVATE = NO隐藏内部实现，仅暴露对外接口文档；
   • 客户交付：生成 RTF/LaTeX 格式文档，按客户要求定制模板（如添加客户 Logo、合规声明）。

6.3 未来扩展方向

1. AI 辅助注释：结合 AI 工具（如 ChatGPT、CodeLlama），自动生成符合 Doxygen 规范的注释初稿，提高注释效率；
2. 文档自动化校验：开发自定义脚本，校验注释完整性和合规性（如是否包含安全相关标签），集成到 CI 流程；
3. 跨工具链集成：与需求管理工具（如 Jira）、测试工具（如 TestStand）联动，实现需求 - 代码 - 文档 - 测试用例的全链路追溯；
4. 移动端适配：优化 HTML 文档的移动端展示，支持现场调试时通过手机查看接口和故障文档。