/**
 * bq25756_hal.h — BQ25756 Hardware Abstraction Layer
 *
 * 平台无关的 BQ25756 寄存器读写 + 参数换算函数。
 * 依赖 soft_i2c.c 提供 I2C 通信基础。
 * 调用者提供平台相关的延时函数（delay_ms callback）。
 *
 * 分层：
 *   soft_i2c.c     ← GPIO 位操作（纯硬件无关）
 *   bq25756_hal.c  ← 寄存器读写 + 物理量换算（本模块）
 *   bq25756_ai4_init.c ← AI-4 专用初始化序列
 *   charge_sm.c    ← 状态机（纯算法，不接触寄存器）
 *   app_charge_task.c ← RTOS 任务集成
 */

#ifndef __BQ25756_HAL_H
#define __BQ25756_HAL_H

#include <stdint.h>
#include "bq25756_regs.h"

/* ──────────────── I2C 地址 ──────────────── */

#ifndef BQ25756_HAL_I2C_ADDR
#define BQ25756_HAL_I2C_ADDR   BQ25756_I2C_ADDR
#endif

/* ──────────────── ADC 读数 ──────────────── */

/** @brief 电池电压 (REG0x33 VBAT_ADC), 2mV/LSB */
int32_t bq_read_vbat_mv(void);

/** @brief 充电电流 (REG0x2F IBAT_ADC), 2mA/LSB, 有符号 */
int32_t bq_read_ibat_ma(void);

/** @brief 输入电压 (REG0x31 VAC_ADC), 2mV/LSB */
int32_t bq_read_vin_mv(void);

/** @brief 输入电流 (REG0x2D IAC_ADC), 2mA/LSB, 有符号 */
int32_t bq_read_iin_ma(void);

/* ──────────────── 寄存器写入 ──────────────── */

/** @brief 充电电流 REG0x02, clamp 400-20000mA */
int bq_write_charge_current(uint32_t mA);

/** @brief 预充电流 REG0x10, clamp 250-10000mA */
int bq_write_precharge_current(uint32_t mA);

/** @brief 充电使能/禁用 REG0x17 bit0 (读改写) */
int bq_set_en_chg(uint8_t enable);

/** @brief 复位 I2C 看门狗 REG0x17 bit5 */
int bq_reset_wd(void);

/** @brief PFM 模式开关 REG0x19 bit5 (读改写) */
int bq_set_en_pfm(uint8_t enable);

/* ──────────────── MPPT ──────────────── */

/** @brief 启动 MPPT (P&O=1s, FS=20min) */
int bq_mppt_start(void);

/** @brief 停止 MPPT */
int bq_mppt_stop(void);

/** @brief 强制全面板扫描一次 */
int bq_mppt_force_sweep(void);

/* ──────────────── 充电控制 ──────────────── */

/**
 * @brief 充电电流软启动 ramp
 * @param target_ma  目标充电电流
 * @param delay_ms   平台延时函数 (RTOS: OSTimeDlyHMSM, 裸机: SysTick)
 * @return 0=成功, -1=I2C 失败
 */
int bq_soft_start(uint32_t target_ma, void (*delay_ms)(uint32_t ms));

/* ──────────────── 诊断/校验 ──────────────── */

/**
 * @brief VFB_ADC POST 自检 — 验证 FB 电阻分压比
 * @param expected_divider_ratio  期望分压比 (如 19.34)
 * @param tolerance_mv            容许偏差 mV
 * @param delay_ms                平台延时函数
 * @return 0=通过, -1=I2C 失败, -2=偏差超限
 */
int bq_vfb_post_check(float expected_divider_ratio, int32_t tolerance_mv,
                      void (*delay_ms)(uint32_t ms));

/**
 * @brief TS_ADC 交叉校验 — BQ 内部 TS vs MCU 独立 NTC
 * @param mcu_temp_c  MCU 侧 NTC 读数
 */
void bq_ts_cross_check(int8_t mcu_temp_c);

/** @brief PFM/FSW_SYNC 一致性检测 */
void bq_pfm_sync_check(void);

/* ──────────────── 中断 ──────────────── */

/** @brief INT 引脚下降沿中断初始化 (GD32 平台, 实现在 app_charge_task.c) */
void bq_int_init(void);

/** @brief 重配 INT 屏蔽 — 仅开故障类中断 */
void bq_int_mask_only_fault(void);

/** @brief INT 外部全局故障标记 (ISR 写, 任务读) */
extern volatile uint8_t g_bq_fault;
extern volatile uint8_t g_bq_fault_status;

/* ──────────────── 快速初始化（从 soft_i2c.c 迁移） ──────────────── */

uint8_t bq_watchdog_off(void);
uint8_t bq_ntc_off(void);
uint8_t bq_adc_continuous(void);

#endif /* __BQ25756_HAL_H */