DCU_APP/GD32E508_DCU_APP/device/ADC.cpp

/**
 * @file adc.cpp
 * @brief ADC 采样模块实现。
 */

#include "main.h"
#include "device/adc.h"
#include "sys/systick.h"
#include "sys/config.h"
#include <math.h>

namespace {
constexpr float kMinValidVdda = 2.7f;
constexpr float kMaxValidVdda = 3.6f;
constexpr float kMinValidTemperature = -40.0f;
constexpr float kMaxValidTemperature = 125.0f;

static bool isValidAdcRaw(uint16_t raw)
{
    return (raw > 0U) && (raw < static_cast<uint16_t>(CONFIG_ADC_MAX_VALUE));
}

static bool isFiniteFloat(float value)
{
    return isfinite(value) != 0;
}
} // namespace

namespace {
constexpr uint32_t kDmaPeriph = DMA0;
constexpr dma_channel_enum kDmaChannel = DMA_CH0;
constexpr uint32_t kChannelCount = 3U;
constexpr uint32_t kVinGpio = GPIOA;
constexpr uint32_t kVinPin = GPIO_PIN_6;
volatile uint16_t s_dmaBuffer[kChannelCount] = {0U, 0U, 0U};
volatile uint8_t s_dmaReady = 0U;
} // namespace

/**
 * @brief 初始化 ADC DMA 循环搬运。
 * @param[in]  无。
 * @param[out] 无。
 * @retval    无返回值。
 * @note      配置 DMA0 Channel0，将 ADC 规则组结果连续搬运到 `s_dmaBuffer`。
 */
void Adc::initDma()
{
    dma_parameter_struct dma_initpara{};

    rcu_periph_clock_enable(RCU_DMA0);
    dma_deinit(kDmaPeriph, kDmaChannel);
    dma_struct_para_init(&dma_initpara);

    dma_initpara.periph_addr = (uint32_t)(&ADC_RDATA(CONFIG_ADC_INSTANCE));
    dma_initpara.memory_addr = (uint32_t)s_dmaBuffer;
    dma_initpara.direction = DMA_PERIPHERAL_TO_MEMORY;
    dma_initpara.periph_width = DMA_PERIPHERAL_WIDTH_16BIT;
    dma_initpara.memory_width = DMA_MEMORY_WIDTH_16BIT;
    dma_initpara.periph_inc = DMA_PERIPH_INCREASE_DISABLE;
    dma_initpara.memory_inc = DMA_MEMORY_INCREASE_ENABLE;
    dma_initpara.number = kChannelCount;
    dma_initpara.priority = DMA_PRIORITY_HIGH;
    dma_init(kDmaPeriph, kDmaChannel, &dma_initpara);
    dma_circulation_enable(kDmaPeriph, kDmaChannel);
    dma_channel_enable(kDmaPeriph, kDmaChannel);
}

/**
 * @brief 初始化 ADC、DMA 与规则通道扫描配置。
 * @param[in]  无。
 * @param[out] 无。
 * @retval    无返回值。
 * @note      按 `VIN_ADC / TEMP / VREFINT` 三通道顺序启用连续扫描与 DMA 采样。
 *            参考 GD32E508 文档要求，内部温度与 VREFINT 通道使用长采样时间，以满足 ts_temp 要求。
 */
void Adc::init()
{
    rcu_periph_clock_enable(RCU_ADC0);
    rcu_periph_clock_enable(RCU_GPIOA);
    rcu_adc_clock_config(RCU_CKADC_CKAPB2_DIV8);

    /* 原理图：PA6 -> VIN_ADC，为外部电源分压检测输入 */
    gpio_init(kVinGpio, GPIO_MODE_AIN, GPIO_OSPEED_50MHZ, kVinPin);

    initDma();
    adc_deinit(CONFIG_ADC_INSTANCE);
    adc_mode_config(ADC_MODE_FREE);
    adc_special_function_config(CONFIG_ADC_INSTANCE, ADC_SCAN_MODE, ENABLE);
    adc_special_function_config(CONFIG_ADC_INSTANCE, ADC_CONTINUOUS_MODE, ENABLE);
    adc_data_alignment_config(CONFIG_ADC_INSTANCE, ADC_DATAALIGN_RIGHT);
    adc_channel_length_config(CONFIG_ADC_INSTANCE, ADC_REGULAR_CHANNEL, kChannelCount);

    /* 内部温度传感器和 VREFINT 使用长采样时间，确保满足文档要求。 */
    adc_regular_channel_config(CONFIG_ADC_INSTANCE, 0U, CONFIG_ADC_VIN_CHANNEL, ADC_SAMPLETIME_239POINT5);
    adc_regular_channel_config(CONFIG_ADC_INSTANCE, 1U, CONFIG_ADC_TEMP_CHANNEL, ADC_SAMPLETIME_239POINT5);
    adc_regular_channel_config(CONFIG_ADC_INSTANCE, 2U, CONFIG_ADC_VREFINT_CHANNEL, ADC_SAMPLETIME_239POINT5);

    adc_external_trigger_source_config(CONFIG_ADC_INSTANCE, ADC_REGULAR_CHANNEL, ADC0_1_2_EXTTRIG_REGULAR_NONE);
    adc_external_trigger_config(CONFIG_ADC_INSTANCE, ADC_REGULAR_CHANNEL, ENABLE);
    adc_dma_mode_enable(CONFIG_ADC_INSTANCE);

    adc_tempsensor_vrefint_enable();
    SysTickTimer::delayMs(CONFIG_ADC_STABILIZE_DELAY_MS);

    adc_enable(CONFIG_ADC_INSTANCE);
    SysTickTimer::delayMs(CONFIG_ADC_STABILIZE_DELAY_MS);
    adc_calibration_enable(CONFIG_ADC_INSTANCE);
    SysTickTimer::delayMs(CONFIG_ADC_STABILIZE_DELAY_MS);
    adc_software_trigger_enable(CONFIG_ADC_INSTANCE, ADC_REGULAR_CHANNEL);
    SysTickTimer::delayMs(1U);
    s_dmaReady = 1U;
}

/**
 * @brief 查询 ADC DMA 采样是否已经就绪。
 * @param[in]  无。
 * @param[out] 无。
 * @retval bool true 表示 DMA 已启动并完成初始稳定等待，false 表示尚未就绪。
 */
bool Adc::dmaReady()
{
    return s_dmaReady != 0U;
}

/**
 * @brief 获取 ADC DMA 原始缓冲区首地址。
 * @param[in]  无。
 * @param[out] 无。
 * @retval const uint16_t* 返回 DMA 原始缓冲区首地址。
 * @note      缓冲顺序固定为 `VIN_ADC / TEMP / VREFINT`。
 */
const uint16_t *Adc::dmaBuffer()
{
    return (const uint16_t *)s_dmaBuffer;
}

/**
 * @brief 按逻辑通道号读取一个原始 ADC 数值。
 * @param[in]  channel 逻辑 ADC 通道号。
 * @param[out] 无。
 * @retval uint16_t 返回对应通道的原始采样值；若通道不受支持则返回 0。
 */
uint16_t Adc::readRaw(uint8_t channel)
{
    if(channel == CONFIG_ADC_VIN_CHANNEL) return s_dmaBuffer[0];
    if(channel == CONFIG_ADC_TEMP_CHANNEL) return s_dmaBuffer[1];
    if(channel == CONFIG_ADC_VREFINT_CHANNEL) return s_dmaBuffer[2];
    return 0U;
}

/**
 * @brief 读取 VIN_ADC 原始采样值。
 * @param[in]  无。
 * @param[out] 无。
 * @retval uint16_t 返回 VIN_ADC 通道原始值。
 */
uint16_t Adc::readVinRaw()     { return readRaw(CONFIG_ADC_VIN_CHANNEL); }

/**
 * @brief 读取内部参考电压原始采样值。
 * @param[in]  无。
 * @param[out] 无。
 * @retval uint16_t 返回 VREFINT 通道原始值。
 */
uint16_t Adc::readVrefRaw()    { return readRaw(CONFIG_ADC_VREFINT_CHANNEL); }

/**
 * @brief 读取内部温度通道原始采样值。
 * @param[in]  无。
 * @param[out] 无。
 * @retval uint16_t 返回内部温度通道原始值。
 */
uint16_t Adc::readTempRaw()    { return readRaw(CONFIG_ADC_TEMP_CHANNEL); }

/**
 * @brief 将 VIN_ADC 原始值换算为 ADC 引脚电压。
 * @param[in]  vinRaw VIN_ADC 原始采样值。
 * @param[in]  vdda   当前 ADC 供电电压。
 * @param[out] 无。
 * @retval float 返回 ADC 引脚电压，单位 V。
 */
float Adc::calculateVinAdcVoltage(uint16_t vinRaw, float vdda)
{
    return (static_cast<float>(vinRaw) * vdda) / CONFIG_ADC_MAX_VALUE;
}

/**
 * @brief 根据内部参考电压原始值换算当前 VDDA。
 * @param[in]  vrefRaw 内部参考电压通道原始值。
 * @param[out] 无。
 * @retval float 返回换算得到的 VDDA，单位 V；若原始值为 0，则返回默认值。
 */
float Adc::calculateVdda(uint16_t vrefRaw)
{
    if(!isValidAdcRaw(vrefRaw)) return 0.0f;

    const float vdda = (CONFIG_ADC_VREFINT_TYPICAL_VOLTAGE * CONFIG_ADC_MAX_VALUE) /
                       static_cast<float>(vrefRaw);
    if(!isFiniteFloat(vdda) || vdda < kMinValidVdda || vdda > kMaxValidVdda) {
        return 0.0f;
    }
    return vdda;
}

/**
 * @brief 根据温度通道原始值换算芯片温度。
 * @param[in]  tempRaw 温度通道原始值。
 * @param[in]  vdda    当前 ADC 供电电压。
 * @param[out] 无。
 * @retval float 返回换算得到的芯片温度，单位 ℃。
 * @note      按 GD32E508 文档推荐公式处理：
 *            Temperature = (V25 - Vtemperature) / Avg_Slope + 25
 */
float Adc::calculateTemperature(uint16_t tempRaw, float vdda)
{
    if(!isValidAdcRaw(tempRaw)) return 0.0f;
    if(!isFiniteFloat(vdda) || vdda < kMinValidVdda || vdda > kMaxValidVdda) return 0.0f;

    const float sensorVoltage = (static_cast<float>(tempRaw) * vdda) / CONFIG_ADC_MAX_VALUE;
    const float temperature = ((CONFIG_ADC_TEMP_V25 - sensorVoltage) / CONFIG_ADC_TEMP_AVG_SLOPE) + 25.0f;
    if(!isFiniteFloat(temperature) ||
       temperature < kMinValidTemperature ||
       temperature > kMaxValidTemperature) {
        return 0.0f;
    }
    return temperature;
}

/**
 * @brief 收集一组完整 ADC 采样结果。
 * @param[in]  sample 指向输出采样结构体的指针。
 * @param[out] sample 输出原始值与工程值结果；允许为空。
 * @retval    无返回值。
 * @note      若 `sample == nullptr`，函数直接返回。
 */
void Adc::collectSample(Sample *sample)
{
    if(sample == nullptr) return;

    sample->vin_raw = readVinRaw();
    sample->temp_raw = readTempRaw();
    sample->vref_raw = readVrefRaw();
    sample->vdda = calculateVdda(sample->vref_raw);
    sample->vin_adc_v = calculateVinAdcVoltage(sample->vin_raw, sample->vdda);
    sample->temperature = calculateTemperature(sample->temp_raw, sample->vdda);
    sample->valid = (isValidAdcRaw(sample->temp_raw) &&
                     isValidAdcRaw(sample->vref_raw) &&
                     (sample->vdda >= kMinValidVdda) && (sample->vdda <= kMaxValidVdda) &&
                     (sample->temperature >= kMinValidTemperature) &&
                     (sample->temperature <= kMaxValidTemperature)) ? 1U : 0U;
}