timer IRQ -> CPU latency -> start ADC -> wait/ADC IRQ -> CPU reads DR -> store sample

TIM2 update
  -> TIM2_TRGO
  -> ADC1 sample/convert
  -> ADC1 DMA request
  -> DMA2 writes one uint16_t sample
  -> HT or TC only at segment boundary
  -> CPU consumes one stable half-buffer

控制流：初始化 -> 武装 ADC/DMA -> 启动 TIM2 -> 停止/恢复
事件流：TIM2 update -> TRGO -> ADC EOC -> DMA request -> HT/TC/error IRQ
数据流：模拟输入 -> ADC1_DR -> DMA2 -> samples[] -> application

T_conv < T_trigger
T_app_worst < T_half
DMA 能在相邻 ADC 请求之间完成一次 half-word 搬运
缓冲区位于 DMA2 可访问且生命周期覆盖整个运行期的内存

HAL_Init
  -> SystemClock_Config
       HSI -> PLL -> SYSCLK/HCLK -> PCLK1/PCLK2
  -> board_adc_gpio_init(actual channel/pin/electrical conditions)
  -> MX_DMA_Init
       DMA2 clock gate + DMA2_Stream0 NVIC
  -> MX_ADC1_Init
       HAL_ADC_Init -> HAL_ADC_MspInit
         ADC1 clock gate
         HAL_DMA_Init(DMA2_Stream0/Channel0)
         __HAL_LINKDMA(hadc1, DMA_Handle, hdma_adc1)
       configure one board-provided channel/rank/sample time
  -> MX_TIM2_Init
       PSC/ARR + master TRGO=update
  -> Pipeline_Start
       clear software diagnostics
       HAL_ADC_Start_DMA(buffer, N)    receiver first
       HAL_TIM_Base_Start(TIM2)        source last

TIM2 counter reaches update
  -> TIM2_CR2.MMS exports update as TIM2_TRGO
  -> ADC1_CR2.EXTSEL/EXTEN accepts TIM2_TRGO rising edge
  -> ADC1 samples selected rank and completes conversion
  -> ADC result reaches ADC1_DR and DMA request is generated
  -> DMA2 Stream0 reads ADC1_DR, writes samples[write_index]
  -> DMA_S0NDTR decrements by one half-word item
  -> index reaches N/2: HTIF0 -> DMA IRQ -> ADC half callback
  -> index reaches N:   TCIF0 -> DMA IRQ -> ADC full callback; circular wrap
  -> callback increments generation/event counter only
  -> main loop snapshots counters and consumes the completed half

HAL_TIM_Base_Stop
  -> no new periodic TRGO
  -> HAL_ADC_Stop_DMA
       disable ADC DMA path and stop owned stream through HAL
  -> snapshot diagnostics
  -> buffer may be reassigned only after stop completes

HSI = 16 MHz
  -> PLLM = 16: PLL input = 1 MHz
  -> PLLN = 336: VCO = 336 MHz
  -> PLLP = 2: SYSCLK = 168 MHz
  -> AHB prescaler /1: HCLK = 168 MHz
       -> AHB1 bus
          -> RCC_AHB1ENR.DMA2EN = 1
          -> DMA2 interface clock available
  -> APB1 prescaler /4: PCLK1 = 42 MHz
       -> F407 rule when APB prescaler != 1: TIM2 kernel = 2 * PCLK1 = 84 MHz
       -> RCC_APB1ENR.TIM2EN = 1
       -> PSC = 83: counter clock = 1 MHz
       -> ARR = 999: update/TRGO = 1 kHz, T_trigger = 1 ms
  -> APB2 prescaler /2: PCLK2 = 84 MHz
       -> RCC_APB2ENR.ADC1EN = 1
       -> ADC common prescaler /4: ADCCLK = 21 MHz
       -> sample time 84 cycles + 12-bit conversion 12 cycles
       -> T_sample+convert = 96 / 21 MHz ~= 4.57 us
       -> 再加 DS8626 规定的外部触发延迟，才得到完整 T_conv
       -> 完整理论裕量 = 1 ms - T_conv

buffer bytes = 128 samples * 2 bytes = 256 bytes
half samples = 64
T_half = 64 * 1 ms = 64 ms
full wrap period = 128 ms

HAL_ADC_Start_DMA(&hadc1, buffer, N)
  -> register ADC-facing DMA callbacks in hdma_adc1
  -> configure/start DMA transfer using ADC1_DR, buffer and N
  -> enable ADC DMA request path and ADC

DMA2_Stream0_IRQHandler
  -> HAL_DMA_IRQHandler(&hdma_adc1)
       -> HT: ADC DMA half callback
          -> HAL_ADC_ConvHalfCpltCallback(&hadc1)
       -> TC: ADC DMA complete callback
          -> HAL_ADC_ConvCpltCallback(&hadc1)
       -> transfer/direct/FIFO error
          -> ADC/DMA error propagation
          -> HAL_ADC_ErrorCallback(&hadc1)

#include <assert.h>
#include <stddef.h>
#include <stdint.h>

#define PIPE_BUFFER_COUNT 8U
#define PIPE_HALF_COUNT   (PIPE_BUFFER_COUNT / 2U)

typedef uint8_t pipe_status_t;
#define PIPE_OK                    ((pipe_status_t)0U)
#define PIPE_ERR_BAD_CONFIG        ((pipe_status_t)1U)
#define PIPE_ERR_NOT_ARMED         ((pipe_status_t)2U)
#define PIPE_ERR_ADC_BUSY          ((pipe_status_t)3U)
#define PIPE_ERR_DMA_STOPPED       ((pipe_status_t)4U)
#define PIPE_ERR_DMA_FAULT         ((pipe_status_t)5U)
#define PIPE_ERR_CONSUMER_LATE     ((pipe_status_t)6U)
#define PIPE_ERR_SEGMENT_NOT_READY ((pipe_status_t)7U)

typedef struct {
    uint32_t period_ticks;
    uint32_t elapsed_ticks;
    uint8_t running;
} fake_timer_t;

typedef struct {
    uint32_t conversion_ticks;
    uint32_t remaining_ticks;
    uint16_t pending_sample;
    uint8_t armed;
    uint8_t busy;
} fake_adc_t;

typedef struct {
    uint16_t *buffer;
    uint32_t count;
    uint32_t write_index;
    uint8_t running;
    uint8_t fault_on_next_request;
} fake_dma_t;

typedef struct {
    fake_timer_t timer;
    fake_adc_t adc;
    fake_dma_t dma;
    uint16_t samples[PIPE_BUFFER_COUNT];
    uint32_t trigger_count;
    uint32_t conversion_count;
    uint32_t dma_write_count;
    uint32_t published_generation[2];
    uint32_t consumed_generation[2];
    uint8_t segment_owned_by_app[2];
    uint16_t next_sample;
    pipe_status_t first_error;
} pipeline_t;

static void pipe_record_first_error(pipeline_t *p, pipe_status_t error)
{
    if (p->first_error == PIPE_OK) {
        p->first_error = error;
    }
}

static void pipe_stop_on_error(pipeline_t *p, pipe_status_t error)
{
    pipe_record_first_error(p, error);
    p->timer.running = 0U;
    p->adc.armed = 0U;
    p->dma.running = 0U;
}

static pipe_status_t pipe_init(pipeline_t *p,
                               uint32_t trigger_period_ticks,
                               uint32_t conversion_ticks,
                               uint32_t buffer_count)
{
    uint32_t i;

    if ((p == NULL) || (trigger_period_ticks == 0U) ||
        (conversion_ticks == 0U) ||
        (buffer_count != PIPE_BUFFER_COUNT) ||
        ((PIPE_BUFFER_COUNT & 1U) != 0U)) {
        return PIPE_ERR_BAD_CONFIG;
    }

    *p = (pipeline_t){0};
    for (i = 0U; i < PIPE_BUFFER_COUNT; ++i) {
        p->samples[i] = 0U;
    }
    p->timer.period_ticks = trigger_period_ticks;
    p->adc.conversion_ticks = conversion_ticks;
    p->dma.buffer = p->samples;
    p->dma.count = buffer_count;
    p->next_sample = 100U;
    p->first_error = PIPE_OK;
    return PIPE_OK;
}

static pipe_status_t pipe_start(pipeline_t *p)
{
    if ((p == NULL) || (p->dma.buffer == NULL) ||
        (p->dma.count != PIPE_BUFFER_COUNT)) {
        return PIPE_ERR_BAD_CONFIG;
    }

    p->timer.elapsed_ticks = 0U;
    p->adc.remaining_ticks = 0U;
    p->adc.busy = 0U;
    p->dma.write_index = 0U;
    p->first_error = PIPE_OK;

    /* Receiver first, source last. */
    p->dma.running = 1U;
    p->adc.armed = 1U;
    p->timer.running = 1U;
    return PIPE_OK;
}

static void pipe_publish_boundary(pipeline_t *p, uint32_t segment)
{
    p->segment_owned_by_app[segment] = 1U;
    p->published_generation[segment]++;
}

static pipe_status_t fake_dma_request(pipeline_t *p, uint16_t sample)
{
    uint32_t segment;

    if (p->dma.running == 0U) {
        pipe_stop_on_error(p, PIPE_ERR_DMA_STOPPED);
        return PIPE_ERR_DMA_STOPPED;
    }
    if (p->dma.fault_on_next_request != 0U) {
        p->dma.fault_on_next_request = 0U;
        pipe_stop_on_error(p, PIPE_ERR_DMA_FAULT);
        return PIPE_ERR_DMA_FAULT;
    }

    segment = (p->dma.write_index < PIPE_HALF_COUNT) ? 0U : 1U;
    if (((p->dma.write_index == 0U) ||
         (p->dma.write_index == PIPE_HALF_COUNT)) &&
        (p->segment_owned_by_app[segment] != 0U)) {
        pipe_stop_on_error(p, PIPE_ERR_CONSUMER_LATE);
        return PIPE_ERR_CONSUMER_LATE;
    }

    p->dma.buffer[p->dma.write_index] = sample;
    p->dma.write_index++;
    p->dma_write_count++;

    if (p->dma.write_index == PIPE_HALF_COUNT) {
        pipe_publish_boundary(p, 0U); /* HT */
    } else if (p->dma.write_index == p->dma.count) {
        pipe_publish_boundary(p, 1U); /* TC */
        p->dma.write_index = 0U;      /* circular reload */
    }
    return PIPE_OK;
}

static pipe_status_t fake_adc_trigger(pipeline_t *p)
{
    if (p->adc.armed == 0U) {
        pipe_stop_on_error(p, PIPE_ERR_NOT_ARMED);
        return PIPE_ERR_NOT_ARMED;
    }
    if (p->adc.busy != 0U) {
        pipe_stop_on_error(p, PIPE_ERR_ADC_BUSY);
        return PIPE_ERR_ADC_BUSY;
    }

    p->adc.pending_sample = p->next_sample;
    p->next_sample++;
    p->adc.remaining_ticks = p->adc.conversion_ticks;
    p->adc.busy = 1U;
    p->trigger_count++;
    return PIPE_OK;
}

static pipe_status_t pipe_tick(pipeline_t *p)
{
    pipe_status_t status;

    if (p == NULL) {
        return PIPE_ERR_BAD_CONFIG;
    }
    if (p->first_error != PIPE_OK) {
        return p->first_error;
    }

    /* Complete an earlier conversion before considering this tick's trigger. */
    if (p->adc.busy != 0U) {
        p->adc.remaining_ticks--;
        if (p->adc.remaining_ticks == 0U) {
            p->adc.busy = 0U;
            p->conversion_count++;
            status = fake_dma_request(p, p->adc.pending_sample);
            if (status != PIPE_OK) {
                return status;
            }
        }
    }

    if (p->timer.running != 0U) {
        p->timer.elapsed_ticks++;
        if (p->timer.elapsed_ticks == p->timer.period_ticks) {
            p->timer.elapsed_ticks = 0U;
            return fake_adc_trigger(p);
        }
    }
    return PIPE_OK;
}

static pipe_status_t pipe_take_segment(pipeline_t *p,
                                       uint32_t segment,
                                       const uint16_t **data,
                                       uint32_t *count,
                                       uint32_t *generation)
{
    if ((p == NULL) || (segment > 1U) || (data == NULL) ||
        (count == NULL) || (generation == NULL)) {
        return PIPE_ERR_BAD_CONFIG;
    }
    if (p->segment_owned_by_app[segment] == 0U) {
        return PIPE_ERR_SEGMENT_NOT_READY;
    }

    *data = &p->samples[segment * PIPE_HALF_COUNT];
    *count = PIPE_HALF_COUNT;
    *generation = p->published_generation[segment];
    p->consumed_generation[segment] = *generation;
    p->segment_owned_by_app[segment] = 0U;
    return PIPE_OK;
}

static void run_ticks_until_writes(pipeline_t *p, uint32_t target_writes)
{
    while ((p->dma_write_count < target_writes) &&
           (p->first_error == PIPE_OK)) {
        (void)pipe_tick(p);
    }
}

static void test_valid_pipeline(void)
{
    pipeline_t p;
    const uint16_t *data;
    uint32_t count;
    uint32_t generation;

    assert(pipe_init(&p, 3U, 1U, PIPE_BUFFER_COUNT) == PIPE_OK);
    assert(pipe_start(&p) == PIPE_OK);

    run_ticks_until_writes(&p, PIPE_HALF_COUNT);
    assert(p.published_generation[0] == 1U);
    assert(pipe_take_segment(&p, 0U, &data, &count, &generation) == PIPE_OK);
    assert(count == PIPE_HALF_COUNT);
    assert(generation == 1U);
    assert(data[0] == 100U);
    assert(data[3] == 103U);

    run_ticks_until_writes(&p, PIPE_BUFFER_COUNT);
    assert(p.published_generation[1] == 1U);
    assert(pipe_take_segment(&p, 1U, &data, &count, &generation) == PIPE_OK);
    assert(data[0] == 104U);
    assert(data[3] == 107U);
    assert(p.trigger_count == p.conversion_count);
    assert(p.conversion_count == p.dma_write_count);
}

static void test_conversion_budget_failure(void)
{
    pipeline_t p;

    assert(pipe_init(&p, 3U, 4U, PIPE_BUFFER_COUNT) == PIPE_OK);
    assert(pipe_start(&p) == PIPE_OK);
    while (p.first_error == PIPE_OK) {
        (void)pipe_tick(&p);
    }
    assert(p.first_error == PIPE_ERR_ADC_BUSY);
    assert(p.timer.running == 0U);
}

static void test_consumer_late(void)
{
    pipeline_t p;

    assert(pipe_init(&p, 2U, 1U, PIPE_BUFFER_COUNT) == PIPE_OK);
    assert(pipe_start(&p) == PIPE_OK);
    run_ticks_until_writes(&p, PIPE_BUFFER_COUNT);
    assert(p.segment_owned_by_app[0] == 1U);
    assert(p.segment_owned_by_app[1] == 1U);

    while (p.first_error == PIPE_OK) {
        (void)pipe_tick(&p);
    }
    assert(p.first_error == PIPE_ERR_CONSUMER_LATE);
    assert(p.dma_write_count == PIPE_BUFFER_COUNT);
}

static void test_dma_fault(void)
{
    pipeline_t p;

    assert(pipe_init(&p, 3U, 1U, PIPE_BUFFER_COUNT) == PIPE_OK);
    assert(pipe_start(&p) == PIPE_OK);
    p.dma.fault_on_next_request = 1U;
    while (p.first_error == PIPE_OK) {
        (void)pipe_tick(&p);
    }
    assert(p.first_error == PIPE_ERR_DMA_FAULT);
    assert(p.dma_write_count == 0U);
}

static void test_inactive_and_invalid_paths(void)
{
    pipeline_t p;
    const uint16_t *data;
    uint32_t count;
    uint32_t generation;
    uint32_t i;

    assert(pipe_init(&p, 2U, 1U, PIPE_BUFFER_COUNT - 1U) ==
           PIPE_ERR_BAD_CONFIG);

    /* A configured but stopped source cannot fabricate a trigger or batch. */
    assert(pipe_init(&p, 2U, 1U, PIPE_BUFFER_COUNT) == PIPE_OK);
    for (i = 0U; i < 8U; ++i) {
        assert(pipe_tick(&p) == PIPE_OK);
    }
    assert(p.trigger_count == 0U);
    assert(p.dma_write_count == 0U);
    assert(p.published_generation[0] == 0U);
    assert(p.published_generation[1] == 0U);
    assert(pipe_take_segment(&p, 0U, &data, &count, &generation) ==
           PIPE_ERR_SEGMENT_NOT_READY);

    assert(pipe_start(&p) == PIPE_OK);
    p.adc.armed = 0U;
    while (p.first_error == PIPE_OK) {
        (void)pipe_tick(&p);
    }
    assert(p.first_error == PIPE_ERR_NOT_ARMED);
    assert(p.dma_write_count == 0U);

    assert(pipe_init(&p, 2U, 1U, PIPE_BUFFER_COUNT) == PIPE_OK);
    assert(pipe_start(&p) == PIPE_OK);
    p.dma.running = 0U;
    while (p.first_error == PIPE_OK) {
        (void)pipe_tick(&p);
    }
    assert(p.first_error == PIPE_ERR_DMA_STOPPED);
    assert(p.dma_write_count == 0U);

    /* A started but unfinished conversion has not produced a DMA request. */
    assert(pipe_init(&p, 3U, 2U, PIPE_BUFFER_COUNT) == PIPE_OK);
    assert(pipe_start(&p) == PIPE_OK);
    assert(pipe_tick(&p) == PIPE_OK);
    assert(pipe_tick(&p) == PIPE_OK);
    assert(pipe_tick(&p) == PIPE_OK);
    assert(p.trigger_count == 1U);
    assert(p.conversion_count == 0U);
    assert(p.dma_write_count == 0U);
    assert(pipe_tick(&p) == PIPE_OK);
    assert(p.conversion_count == 0U);
    assert(p.dma_write_count == 0U);
}

int main(void)
{
    test_valid_pipeline();
    test_conversion_budget_failure();
    test_consumer_late();
    test_dma_fault();
    test_inactive_and_invalid_paths();
    return 0;
}

#include "main.h"

#define PIPE_SAMPLE_COUNT 128U
#define PIPE_HALF_COUNT   (PIPE_SAMPLE_COUNT / 2U)

#define PIPE_EVT_HALF0 (1UL << 0)
#define PIPE_EVT_HALF1 (1UL << 1)
#define PIPE_EVT_ERROR (1UL << 2)

TIM_HandleTypeDef htim2;
ADC_HandleTypeDef hadc1;
DMA_HandleTypeDef hdma_adc1;

_Alignas(uint32_t)
static uint16_t g_samples[PIPE_SAMPLE_COUNT];

typedef struct {
    volatile uint32_t half_generation[2];
    volatile uint32_t events;
    volatile uint32_t first_error;
    volatile uint32_t hal_adc_error;
    volatile uint32_t hal_dma_error;
    volatile uint32_t adc_sr_before_hal;
    volatile uint32_t dma_lisr_before_hal;
    volatile uint32_t adc_sr_at_error;
    volatile uint32_t dma_lisr_at_error;
    volatile uint32_t dma_ndtr_at_error;
} pipeline_diag_t;

static pipeline_diag_t g_diag;

/* 由实际 board/App 层提供；声明在此，避免隐式函数声明。 */
uint8_t board_adc_gpio_init(uint32_t board_adc_channel);
void app_store_pipeline_fault_snapshot(const pipeline_diag_t *diag);

static void SystemClock_Config_Reference(void)
{
    RCC_OscInitTypeDef osc = {0};
    RCC_ClkInitTypeDef clk = {0};

    __HAL_RCC_PWR_CLK_ENABLE();
    __HAL_PWR_VOLTAGESCALING_CONFIG(PWR_REGULATOR_VOLTAGE_SCALE1);

    osc.OscillatorType = RCC_OSCILLATORTYPE_HSI;
    osc.HSIState = RCC_HSI_ON;
    osc.HSICalibrationValue = RCC_HSICALIBRATION_DEFAULT;
    osc.PLL.PLLState = RCC_PLL_ON;
    osc.PLL.PLLSource = RCC_PLLSOURCE_HSI;
    osc.PLL.PLLM = 16U;
    osc.PLL.PLLN = 336U;
    osc.PLL.PLLP = RCC_PLLP_DIV2;
    osc.PLL.PLLQ = 7U;
    if (HAL_RCC_OscConfig(&osc) != HAL_OK) {
        Error_Handler();
    }

    clk.ClockType = RCC_CLOCKTYPE_SYSCLK | RCC_CLOCKTYPE_HCLK |
                    RCC_CLOCKTYPE_PCLK1 | RCC_CLOCKTYPE_PCLK2;
    clk.SYSCLKSource = RCC_SYSCLKSOURCE_PLLCLK;
    clk.AHBCLKDivider = RCC_SYSCLK_DIV1;
    clk.APB1CLKDivider = RCC_HCLK_DIV4;
    clk.APB2CLKDivider = RCC_HCLK_DIV2;
    if (HAL_RCC_ClockConfig(&clk, FLASH_LATENCY_5) != HAL_OK) {
        Error_Handler();
    }
}

static void MX_DMA_Init_Reference(void)
{
    __HAL_RCC_DMA2_CLK_ENABLE();
    HAL_NVIC_SetPriority(DMA2_Stream0_IRQn, 5U, 0U);
    HAL_NVIC_EnableIRQ(DMA2_Stream0_IRQn);
}

void HAL_ADC_MspInit(ADC_HandleTypeDef *hadc)
{
    if ((hadc == NULL) || (hadc->Instance != ADC1)) {
        return;
    }

    __HAL_RCC_ADC1_CLK_ENABLE();

    hdma_adc1.Instance = DMA2_Stream0;
    hdma_adc1.Init.Channel = DMA_CHANNEL_0;
    hdma_adc1.Init.Direction = DMA_PERIPH_TO_MEMORY;
    hdma_adc1.Init.PeriphInc = DMA_PINC_DISABLE;
    hdma_adc1.Init.MemInc = DMA_MINC_ENABLE;
    hdma_adc1.Init.PeriphDataAlignment = DMA_PDATAALIGN_HALFWORD;
    hdma_adc1.Init.MemDataAlignment = DMA_MDATAALIGN_HALFWORD;
    hdma_adc1.Init.Mode = DMA_CIRCULAR;
    hdma_adc1.Init.Priority = DMA_PRIORITY_HIGH;
    hdma_adc1.Init.FIFOMode = DMA_FIFOMODE_DISABLE;
    if (HAL_DMA_Init(&hdma_adc1) != HAL_OK) {
        Error_Handler();
    }

    __HAL_LINKDMA(hadc, DMA_Handle, hdma_adc1);

    HAL_NVIC_SetPriority(ADC_IRQn, 5U, 0U);
    HAL_NVIC_EnableIRQ(ADC_IRQn);
}

static HAL_StatusTypeDef MX_ADC1_Init_Reference(uint32_t board_adc_channel)
{
    ADC_ChannelConfTypeDef channel = {0};

    hadc1.Instance = ADC1;
    hadc1.Init.ClockPrescaler = ADC_CLOCK_SYNC_PCLK_DIV4;
    hadc1.Init.Resolution = ADC_RESOLUTION_12B;
    hadc1.Init.ScanConvMode = DISABLE;
    hadc1.Init.ContinuousConvMode = DISABLE;
    hadc1.Init.DiscontinuousConvMode = DISABLE;
    hadc1.Init.ExternalTrigConvEdge = ADC_EXTERNALTRIGCONVEDGE_RISING;
    hadc1.Init.ExternalTrigConv = ADC_EXTERNALTRIGCONV_T2_TRGO;
    hadc1.Init.DataAlign = ADC_DATAALIGN_RIGHT;
    hadc1.Init.NbrOfConversion = 1U;
    hadc1.Init.DMAContinuousRequests = ENABLE;
    hadc1.Init.EOCSelection = ADC_EOC_SINGLE_CONV;
    if (HAL_ADC_Init(&hadc1) != HAL_OK) {
        return HAL_ERROR;
    }

    channel.Channel = board_adc_channel;
    channel.Rank = 1U;
    channel.SamplingTime = ADC_SAMPLETIME_84CYCLES;
    channel.Offset = 0U;
    return HAL_ADC_ConfigChannel(&hadc1, &channel);
}

static HAL_StatusTypeDef MX_TIM2_Init_Reference(void)
{
    TIM_ClockConfigTypeDef clock_source = {0};
    TIM_MasterConfigTypeDef master = {0};

    __HAL_RCC_TIM2_CLK_ENABLE();

    htim2.Instance = TIM2;
    htim2.Init.Prescaler = 83U;
    htim2.Init.CounterMode = TIM_COUNTERMODE_UP;
    htim2.Init.Period = 999U;
    htim2.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
    htim2.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE;
    if (HAL_TIM_Base_Init(&htim2) != HAL_OK) {
        return HAL_ERROR;
    }

    clock_source.ClockSource = TIM_CLOCKSOURCE_INTERNAL;
    if (HAL_TIM_ConfigClockSource(&htim2, &clock_source) != HAL_OK) {
        return HAL_ERROR;
    }

    master.MasterOutputTrigger = TIM_TRGO_UPDATE;
    master.MasterSlaveMode = TIM_MASTERSLAVEMODE_DISABLE;
    return HAL_TIMEx_MasterConfigSynchronization(&htim2, &master);
}

typedef uint8_t pipeline_status_t;
#define PIPELINE_OK             ((pipeline_status_t)0U)
#define PIPELINE_ERR_BOARD      ((pipeline_status_t)1U)
#define PIPELINE_ERR_ADC_INIT   ((pipeline_status_t)2U)
#define PIPELINE_ERR_TIM_INIT   ((pipeline_status_t)3U)
#define PIPELINE_ERR_ADC_START  ((pipeline_status_t)4U)
#define PIPELINE_ERR_TIM_START  ((pipeline_status_t)5U)
#define PIPELINE_ERR_STOP       ((pipeline_status_t)6U)
#define PIPELINE_ERR_RUNTIME    ((pipeline_status_t)7U)
#define PIPELINE_ERR_SYSTEM_INIT ((pipeline_status_t)8U)

static void pipeline_record_first_error(uint32_t error)
{
    if (g_diag.first_error == 0U) {
        g_diag.first_error = error;
    }
}

static void pipeline_reset_session_diag(void)
{
    uint32_t primask = __get_PRIMASK();

    __disable_irq();
    __DMB();
    g_diag = (pipeline_diag_t){0};
    __DMB();
    if (primask == 0U) {
        __enable_irq();
    }
}

static pipeline_status_t Pipeline_Start(void)
{
    g_diag.events = 0U;

    /* Arm DMA + ADC receiver before starting the periodic source. */
    if (HAL_ADC_Start_DMA(&hadc1,
                          (uint32_t *)g_samples,
                          PIPE_SAMPLE_COUNT) != HAL_OK) {
        pipeline_record_first_error(PIPELINE_ERR_ADC_START);
        return PIPELINE_ERR_ADC_START;
    }

    if (HAL_TIM_Base_Start(&htim2) != HAL_OK) {
        (void)HAL_ADC_Stop_DMA(&hadc1);
        pipeline_record_first_error(PIPELINE_ERR_TIM_START);
        return PIPELINE_ERR_TIM_START;
    }
    return PIPELINE_OK;
}

static pipeline_status_t Pipeline_Stop(void)
{
    HAL_StatusTypeDef tim_status;
    HAL_StatusTypeDef adc_status;

    tim_status = HAL_TIM_Base_Stop(&htim2); /* source first */
    adc_status = HAL_ADC_Stop_DMA(&hadc1);
    if ((tim_status != HAL_OK) || (adc_status != HAL_OK)) {
        pipeline_record_first_error(PIPELINE_ERR_STOP);
        return PIPELINE_ERR_STOP;
    }
    return PIPELINE_OK;
}

static pipeline_status_t Pipeline_InitAndStart(uint32_t board_adc_channel)
{
    pipeline_reset_session_diag();

    /* board_adc_gpio_init() is supplied by the actual board layer. */
    if (board_adc_gpio_init(board_adc_channel) != 0U) {
        pipeline_record_first_error(PIPELINE_ERR_BOARD);
        return PIPELINE_ERR_BOARD;
    }

    MX_DMA_Init_Reference();
    if (MX_ADC1_Init_Reference(board_adc_channel) != HAL_OK) {
        pipeline_record_first_error(PIPELINE_ERR_ADC_INIT);
        return PIPELINE_ERR_ADC_INIT;
    }
    if (MX_TIM2_Init_Reference() != HAL_OK) {
        pipeline_record_first_error(PIPELINE_ERR_TIM_INIT);
        return PIPELINE_ERR_TIM_INIT;
    }
    return Pipeline_Start();
}

static pipeline_status_t App_ComposeAndStart(uint32_t board_adc_channel)
{
    /* The system composition root owns shared HAL and clock setup. */
    if (HAL_Init() != HAL_OK) {
        pipeline_record_first_error(PIPELINE_ERR_SYSTEM_INIT);
        return PIPELINE_ERR_SYSTEM_INIT;
    }
    SystemClock_Config_Reference();
    return Pipeline_InitAndStart(board_adc_channel);
}

static pipeline_status_t Pipeline_Recover(void)
{
    pipeline_status_t stop_status = Pipeline_Stop();

    /* Persist the captured first-fault snapshot before clearing/restarting. */
    app_store_pipeline_fault_snapshot(&g_diag);
    if (stop_status != PIPELINE_OK) {
        return stop_status;
    }

    /* Recovery starts a new session after preserving the old snapshot. */
    pipeline_reset_session_diag();
    return Pipeline_Start();
}

void DMA2_Stream0_IRQHandler(void)
{
    /* HAL may clear serviced flags before invoking the application callback. */
    g_diag.adc_sr_before_hal = ADC1->SR;
    g_diag.dma_lisr_before_hal = DMA2->LISR;
    __DMB();
    HAL_DMA_IRQHandler(&hdma_adc1);
}

void ADC_IRQHandler(void)
{
    g_diag.adc_sr_before_hal = ADC1->SR;
    g_diag.dma_lisr_before_hal = DMA2->LISR;
    __DMB();
    HAL_ADC_IRQHandler(&hadc1);
}

void HAL_ADC_ConvHalfCpltCallback(ADC_HandleTypeDef *hadc)
{
    if ((hadc != NULL) && (hadc->Instance == ADC1)) {
        g_diag.half_generation[0]++;
        g_diag.events |= PIPE_EVT_HALF0;
    }
}

void HAL_ADC_ConvCpltCallback(ADC_HandleTypeDef *hadc)
{
    if ((hadc != NULL) && (hadc->Instance == ADC1)) {
        g_diag.half_generation[1]++;
        g_diag.events |= PIPE_EVT_HALF1;
    }
}

void HAL_ADC_ErrorCallback(ADC_HandleTypeDef *hadc)
{
    if ((hadc != NULL) && (hadc->Instance == ADC1)) {
        g_diag.hal_adc_error = HAL_ADC_GetError(hadc);
        g_diag.adc_sr_at_error = g_diag.adc_sr_before_hal;
        if (hadc->DMA_Handle != NULL) {
            g_diag.hal_dma_error = HAL_DMA_GetError(hadc->DMA_Handle);
            g_diag.dma_lisr_at_error = g_diag.dma_lisr_before_hal;
            g_diag.dma_ndtr_at_error = hadc->DMA_Handle->Instance->NDTR;
        }
        pipeline_record_first_error(PIPELINE_ERR_RUNTIME);
        g_diag.events |= PIPE_EVT_ERROR;
    }
}

typedef struct {
    uint32_t events;
    uint32_t generation[2];
} pipeline_events_t;

static pipeline_events_t Pipeline_TakeEvents(void)
{
    pipeline_events_t snapshot;
    uint32_t primask = __get_PRIMASK();

    __disable_irq();
    __DMB();
    snapshot.events = g_diag.events;
    snapshot.generation[0] = g_diag.half_generation[0];
    snapshot.generation[1] = g_diag.half_generation[1];
    g_diag.events = 0U;
    __DMB();
    if (primask == 0U) {
        __enable_irq();
    }
    return snapshot;
}

static void app_process_half(const uint16_t *samples,
                             uint32_t count,
                             uint32_t generation)
{
    /* App context only: finish before the same half is written again. */
    (void)samples;
    (void)count;
    (void)generation;
}

static void App_RunPipeline(void)
{
    uint32_t consumed_generation[2] = {0U, 0U};

    for (;;) {
        pipeline_events_t event = Pipeline_TakeEvents();
        uint32_t ready_halves = event.events &
                                (PIPE_EVT_HALF0 | PIPE_EVT_HALF1);

        if ((event.events & PIPE_EVT_ERROR) != 0U) {
            if (Pipeline_Recover() != PIPELINE_OK) {
                Error_Handler();
            }
            consumed_generation[0] = 0U;
            consumed_generation[1] = 0U;
            continue;
        }

        /* HT and TC pending together means half 0 has reached reuse risk. */
        if (ready_halves == (PIPE_EVT_HALF0 | PIPE_EVT_HALF1)) {
            pipeline_record_first_error(PIPELINE_ERR_RUNTIME);
            if (Pipeline_Recover() != PIPELINE_OK) {
                Error_Handler();
            }
            consumed_generation[0] = 0U;
            consumed_generation[1] = 0U;
            continue;
        }

        if ((event.events & PIPE_EVT_HALF0) != 0U) {
            if (event.generation[0] != (consumed_generation[0] + 1U)) {
                pipeline_record_first_error(PIPELINE_ERR_RUNTIME);
                if (Pipeline_Recover() != PIPELINE_OK) {
                    Error_Handler();
                }
                consumed_generation[0] = 0U;
                consumed_generation[1] = 0U;
                continue;
            }
            app_process_half(&g_samples[0], PIPE_HALF_COUNT,
                             event.generation[0]);
            consumed_generation[0] = event.generation[0];
        }

        if ((event.events & PIPE_EVT_HALF1) != 0U) {
            if (event.generation[1] != (consumed_generation[1] + 1U)) {
                pipeline_record_first_error(PIPELINE_ERR_RUNTIME);
                if (Pipeline_Recover() != PIPELINE_OK) {
                    Error_Handler();
                }
                consumed_generation[0] = 0U;
                consumed_generation[1] = 0U;
                continue;
            }
            app_process_half(&g_samples[PIPE_HALF_COUNT], PIPE_HALF_COUNT,
                             event.generation[1]);
            consumed_generation[1] = event.generation[1];
        }
    }
}

TIM2 CNT 不动
  -> 查 HSI/PLL/switch/APB1、TIM2EN、复位释放、CEN

CNT/UIF 正常，ADC 无转换
  -> 查 MMS、EXTSEL/EXTEN、ADC enable、初始化 UG 和启动顺序

ADC EOC/DR 变化，NDTR 不动
  -> 查 ADC DMA/DDS、DMA2 clock、Stream0/Channel0、EN、PAR/M0AR

NDTR 递减，无 HT/TC callback
  -> 查 HTIE/TCIE、LISR、NVIC enable/pending、向量入口和句柄

callback 增长，App 无批次
  -> 查事件快照、generation、主循环阻塞和中断临界区

出现 TE/DME/FE
  -> 保存 LISR/NDTR/PAR/M0AR/CR/FCR，核对地址、宽度、可达内存和 FIFO 配置

出现 ADC OVR
  -> 保存 ADC_SR/HAL errors，核对转换间隔、DMA request、断点影响和总线服务

generation 跳变
  -> 消费者超过 T_half 或中断长期屏蔽；先停源，不能继续使用已覆盖批次

TIM2 update/TRGO defines when
  -> ADC1 converts one sample
  -> DMA2 moves one half-word without per-sample CPU work
  -> HT/TC transfers one stable half-buffer to software ownership
  -> App consumes before that half is reused
  -> errors stop the source, preserve evidence, then recover explicitly