/**
 * @file canfd.h
 * @brief CANFD 通信接口、状态载荷与诊断信息定义。
 */
#ifndef DEVICE_CANFD_H
#define DEVICE_CANFD_H

#include <stdint.h>

/** @brief CANFD 状态报文的数据长度，单位字节。 */
#define CANFD_STATUS_DLEN 12U

/**
 * @brief CANFD 运行诊断统计信息。
 * @note 记录发送、接收、错误计数以及最近一次收发报文的关键信息。
 */
typedef struct {
    uint32_t tx_count;            /**< @brief 成功发送的报文计数。 */
    uint32_t rx_count;            /**< @brief 成功接收的报文计数。 */
    uint32_t error_count;         /**< @brief 发送失败或检测到的错误计数。 */
    uint32_t last_rx_id;          /**< @brief 最近一次接收报文的标识符。 */
    uint32_t last_tx_id;          /**< @brief 最近一次发送报文的标识符。 */
    uint8_t last_payload_length;  /**< @brief 最近一次收发报文的数据长度。 */
    uint8_t last_rx_fd_flag;      /**< @brief 最近一次接收报文的 FD 帧标志。 */
    uint8_t last_rx_brs;          /**< @brief 最近一次接收报文的波特率切换标志。 */
    uint8_t last_rx_esi;          /**< @brief 最近一次接收报文的错误状态指示位。 */
} canfd_diag_t;

/**
 * @brief CANFD 状态发送载荷。
 * @note 用于封装温度与供电电压相关的状态数据，供状态帧打包发送。
 */
typedef struct {
    uint16_t temp_raw;    /**< @brief 内部温度通道原始 ADC 数值。 */
    uint16_t vref_raw;    /**< @brief 内部参考电压通道原始 ADC 数值。 */
    float vdda;           /**< @brief 根据内部参考电压换算得到的 MCU 供电电压，单位 V。 */
    float temperature;    /**< @brief 根据温度通道换算得到的芯片温度，单位 ℃。 */
} canfd_status_payload_t;

/**
 * @brief 初始化 CANFD 外设、GPIO、波特率参数与接收过滤器。
 * @param[in] 无。
 * @param[out] 无。
 * @retval 无返回值。
 */
void canfd_init(void);

/**
 * @brief 轮询 CANFD 接收 FIFO，并缓存最近收到的一帧数据。
 * @param[in] 无。
 * @param[out] 无。
 * @retval 无返回值。
 * @note 若当前没有待接收报文，函数直接返回。
 */
void canfd_poll(void);

/**
 * @brief 根据状态载荷准备一帧待发送的 CANFD 状态报文。
 * @param[in] status 指向状态载荷的指针；为空时将清除待发送标志。
 * @param[out] 无。
 * @retval 无返回值。
 */
void canfd_prepare_status(const canfd_status_payload_t *status);

/**
 * @brief 发送已准备好的 CANFD 状态报文。
 * @param[in] 无。
 * @param[out] 无。
 * @retval 无返回值。
 * @note 若当前没有有效待发送报文，函数直接返回。
 */
void canfd_send_prepared(void);

/**
 * @brief 查询是否存在尚未消费的接收报文。
 * @param[in] 无。
 * @param[out] 无。
 * @retval uint8_t 返回非 0 表示存在待消费报文，返回 0 表示没有待消费报文。
 */
uint8_t canfd_has_rx_frame(void);

/**
 * @brief 读取并消费最近一次缓存的接收报文。
 * @param[out] id 输出报文标识符的指针；允许为空。
 * @param[out] data 输出报文数据缓存区指针；允许为空。
 * @param[out] length 输出报文数据长度的指针；允许为空。
 * @retval uint8_t 返回 1 表示成功消费一帧报文，返回 0 表示当前无有效缓存报文。
 */
uint8_t canfd_consume_rx_frame(uint32_t *id, uint8_t *data, uint8_t *length);

/**
 * @brief 获取 CANFD 诊断统计信息只读指针。
 * @param[in] 无。
 * @param[out] 无。
 * @retval const canfd_diag_t* 指向内部诊断统计结构体的只读指针。
 */
const canfd_diag_t *canfd_get_diag(void);

#endif /* DEVICE_CANFD_H */