外设产生一个数据就绪事件
  -> CPU 进入轮询或中断处理
  -> CPU 读取外设数据寄存器
  -> CPU 写入内存并递增软件索引
  -> CPU 再等待下一个数据

CPU 提交契约
  -> 外设发出 request（请求）
  -> DMA 搬运一个 transfer unit（传输单元）
  -> 剩余计数递减
  -> 半传输/全传输/错误状态可观察

应用/BSP 组装契约
  -> DMA 对象保存端点、宽度、计数和模式
  -> 外设产生 request
  -> fake_dma_step(request)
       -> 检查请求/状态/边界
       -> 复制一个 transfer unit
       -> 更新 offset 与 remaining_units
       -> 记录 HALF 或 FULL
  -> 应用读取状态并按所有权边界消费数据

ADC1_IN0（板级模拟输入，封装相关）
  -> ADC1 采样/转换
  -> ADC1_DR 保存 12 位右对齐结果
  -> ADC1 产生 DMA request
  -> DMA2 Stream0 / Channel0
       PAR  = &ADC1->DR             固定外设地址
       M0AR = adc_dma_samples       递增内存地址
       NDTR = 128                   128 个半字传输单元
  -> HTIF0：前 64 个样本交给应用
  -> TCIF0：后 64 个样本交给应用，循环模式自动重装 NDTR
  -> TEIF0/DMEIF0/FEIF0 或 ADC OVR：进入错误路径

HSI = 16 MHz
  -> PLLM = 16：PLL 输入 = 16 / 16 = 1 MHz
  -> PLLN = 336：VCO = 1 * 336 = 336 MHz
  -> PLLP = 2：SYSCLK = 336 / 2 = 168 MHz
  -> AHB HPRE = 1：HCLK/AHB1 = 168 MHz
       -> RCC_AHB1ENR.DMA2EN = 1：DMA2 AHB1 接口可工作
  -> APB2 PPRE2 = 2：PCLK2 = 84 MHz
       -> RCC_APB2ENR.ADC1EN = 1：ADC1 接口时钟开启
       -> ADC prescaler = 4：ADC clock = 84 / 4 = 21 MHz

main
  -> HAL_Init
  -> SystemClock_Config
  -> MX_DMA_Init                     开 DMA2 时钟和 DMA2_Stream0_IRQn
  -> MX_ADC1_Init
       -> HAL_ADC_Init
            -> HAL_ADC_MspInit
                 -> GPIO/ADC1 时钟
                 -> HAL_DMA_Init(&hdma_adc1)
                 -> __HAL_LINKDMA(&hadc1, DMA_Handle, hdma_adc1)
  -> HAL_ADC_Start_DMA(&hadc1, buffer, 128)
       -> 配置 PAR/M0AR/NDTR 与中断回调
       -> 使能 DMA stream、ADC DMA request 和 ADC

DMA2_Stream0_IRQHandler
  -> HAL_DMA_IRQHandler(&hdma_adc1)
       -> HT：HAL_ADC_ConvHalfCpltCallback
       -> TC：HAL_ADC_ConvCpltCallback
       -> TE/DME/FE：ADC/DMA 错误状态与 HAL_ADC_ErrorCallback

ADC_IRQHandler
  -> HAL_ADC_IRQHandler(&hadc1)
       -> OVR 等 ADC 错误：HAL_ADC_ErrorCallback

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

#define DMA_ENDPOINT_CAPACITY 16U
#define DMA_EVENT_CAPACITY 32U

typedef uint8_t dma_status_t;
#define DMA_OK ((dma_status_t)0U)
#define DMA_ERR_BAD_CONFIG ((dma_status_t)1U)
#define DMA_ERR_BAD_REQUEST ((dma_status_t)2U)
#define DMA_ERR_BOUNDS ((dma_status_t)3U)
#define DMA_ERR_STOPPED ((dma_status_t)4U)

typedef uint8_t dma_mode_t;
#define DMA_MODE_NORMAL ((dma_mode_t)0U)
#define DMA_MODE_CIRCULAR ((dma_mode_t)1U)

typedef uint8_t dma_state_t;
#define DMA_STATE_READY ((dma_state_t)0U)
#define DMA_STATE_RUNNING ((dma_state_t)1U)
#define DMA_STATE_COMPLETE ((dma_state_t)2U)
#define DMA_STATE_ERROR ((dma_state_t)3U)

typedef uint8_t dma_event_t;
#define DMA_EVT_TRANSFER ((dma_event_t)0U)
#define DMA_EVT_HALF ((dma_event_t)1U)
#define DMA_EVT_FULL ((dma_event_t)2U)
#define DMA_EVT_WAIT ((dma_event_t)3U)
#define DMA_EVT_ERROR ((dma_event_t)4U)

typedef struct {
    uint8_t *buffer;
    uint32_t capacity;
    uint32_t offset;
} dma_endpoint_t;

typedef struct {
    dma_endpoint_t source;
    dma_endpoint_t destination;
    uint32_t width_bytes;
    uint32_t transfer_units;
    dma_mode_t mode;
} dma_config_t;

typedef struct {
    dma_config_t config;
    uint32_t remaining_units;
    uint32_t completed_units;
    dma_state_t state;
    dma_status_t last_status;
    dma_event_t events[DMA_EVENT_CAPACITY];
    uint32_t event_count;
} dma_fake_t;

static void dma_log(dma_fake_t *dma, dma_event_t event)
{
    if (dma->event_count < DMA_EVENT_CAPACITY) {
        dma->events[dma->event_count] = event;
        dma->event_count += 1U;
    }
}

static uint8_t dma_width_is_valid(uint32_t width_bytes)
{
    return (uint8_t)(width_bytes == 1U || width_bytes == 2U || width_bytes == 4U);
}

static uint8_t dma_endpoint_can_transfer(const dma_endpoint_t *endpoint,
                                         uint32_t offset,
                                         uint32_t width_bytes)
{
    if (endpoint == NULL || endpoint->buffer == NULL) {
        return 0U;
    }
    if (offset > endpoint->capacity || width_bytes > endpoint->capacity - offset) {
        return 0U;
    }
    return 1U;
}

static dma_status_t dma_config_is_valid(const dma_config_t *config)
{
    if (config == NULL || config->source.buffer == NULL ||
        config->destination.buffer == NULL) {
        return DMA_ERR_BAD_CONFIG;
    }
    if (dma_width_is_valid(config->width_bytes) == 0U ||
        config->transfer_units == 0U ||
        (config->mode != DMA_MODE_NORMAL && config->mode != DMA_MODE_CIRCULAR)) {
        return DMA_ERR_BAD_CONFIG;
    }
    if (config->source.offset > config->source.capacity ||
        config->destination.offset > config->destination.capacity) {
        return DMA_ERR_BAD_CONFIG;
    }
    if (config->transfer_units >
            (config->source.capacity - config->source.offset) / config->width_bytes ||
        config->transfer_units >
            (config->destination.capacity - config->destination.offset) / config->width_bytes) {
        return DMA_ERR_BOUNDS;
    }
    return DMA_OK;
}

dma_status_t dma_fake_init(dma_fake_t *dma, const dma_config_t *config)
{
    dma_status_t status;

    if (dma == NULL) {
        return DMA_ERR_BAD_CONFIG;
    }
    status = dma_config_is_valid(config);
    if (status != DMA_OK) {
        dma->state = DMA_STATE_ERROR;
        dma->last_status = status;
        return status;
    }
    dma->config = *config;
    dma->remaining_units = config->transfer_units;
    dma->completed_units = 0U;
    dma->state = DMA_STATE_RUNNING;
    dma->last_status = DMA_OK;
    dma->event_count = 0U;
    return DMA_OK;
}

dma_status_t fake_dma_step(dma_fake_t *dma, uint8_t request)
{
    uint32_t width_bytes;
    uint32_t source_offset;
    uint32_t destination_offset;

    if (dma == NULL) {
        return DMA_ERR_BAD_CONFIG;
    }
    if (request == 0U) {
        dma_log(dma, DMA_EVT_WAIT);
        return DMA_OK;
    }
    if (request != 1U) {
        dma->state = DMA_STATE_ERROR;
        dma->last_status = DMA_ERR_BAD_REQUEST;
        dma_log(dma, DMA_EVT_ERROR);
        return DMA_ERR_BAD_REQUEST;
    }
    if (dma->state == DMA_STATE_COMPLETE) {
        dma->last_status = DMA_ERR_STOPPED;
        dma_log(dma, DMA_EVT_ERROR);
        return DMA_ERR_STOPPED;
    }
    if (dma->state != DMA_STATE_RUNNING) {
        dma->last_status = DMA_ERR_BAD_CONFIG;
        dma_log(dma, DMA_EVT_ERROR);
        return DMA_ERR_BAD_CONFIG;
    }

    width_bytes = dma->config.width_bytes;
    source_offset = dma->config.source.offset;
    destination_offset = dma->config.destination.offset;
    if (dma_endpoint_can_transfer(&dma->config.source, source_offset, width_bytes) == 0U ||
        dma_endpoint_can_transfer(&dma->config.destination, destination_offset, width_bytes) == 0U) {
        dma->state = DMA_STATE_ERROR;
        dma->last_status = DMA_ERR_BOUNDS;
        dma_log(dma, DMA_EVT_ERROR);
        return DMA_ERR_BOUNDS;
    }

    for (uint32_t i = 0U; i < width_bytes; ++i) {
        dma->config.destination.buffer[destination_offset + i] =
            dma->config.source.buffer[source_offset + i];
    }
    dma->config.source.offset += width_bytes;
    dma->config.destination.offset += width_bytes;
    dma->remaining_units -= 1U;
    dma->completed_units += 1U;
    dma_log(dma, DMA_EVT_TRANSFER);

    if (dma->completed_units * 2U == dma->config.transfer_units) {
        dma_log(dma, DMA_EVT_HALF);
    }
    if (dma->remaining_units == 0U) {
        dma_log(dma, DMA_EVT_FULL);
        if (dma->config.mode == DMA_MODE_CIRCULAR) {
            dma->config.source.offset -= dma->config.transfer_units * width_bytes;
            dma->config.destination.offset -= dma->config.transfer_units * width_bytes;
            dma->remaining_units = dma->config.transfer_units;
            dma->completed_units = 0U;
        } else {
            dma->state = DMA_STATE_COMPLETE;
        }
    }
    return DMA_OK;
}

static void assert_event(const dma_fake_t *dma, uint32_t index, dma_event_t event)
{
    assert(index < dma->event_count);
    assert(dma->events[index] == event);
}

static void test_normal_mode(void)
{
    uint8_t source[DMA_ENDPOINT_CAPACITY] = { 10U, 11U, 12U, 13U };
    uint8_t destination[DMA_ENDPOINT_CAPACITY] = { 0U };
    dma_fake_t dma;
    dma_config_t config = {
        { source, DMA_ENDPOINT_CAPACITY, 0U },
        { destination, DMA_ENDPOINT_CAPACITY, 0U },
        1U, 4U, DMA_MODE_NORMAL
    };

    assert(dma_fake_init(&dma, &config) == DMA_OK);
    assert(fake_dma_step(&dma, 0U) == DMA_OK);
    assert(destination[0] == 0U);
    assert(fake_dma_step(&dma, 1U) == DMA_OK);
    assert(fake_dma_step(&dma, 1U) == DMA_OK);
    assert(fake_dma_step(&dma, 1U) == DMA_OK);
    assert(fake_dma_step(&dma, 1U) == DMA_OK);
    assert(dma.state == DMA_STATE_COMPLETE);
    assert(destination[0] == 10U && destination[3] == 13U);
    assert_event(&dma, 0U, DMA_EVT_WAIT);
    assert_event(&dma, 1U, DMA_EVT_TRANSFER);
    assert_event(&dma, 3U, DMA_EVT_HALF);
    assert_event(&dma, 6U, DMA_EVT_FULL);
    assert(fake_dma_step(&dma, 1U) == DMA_ERR_STOPPED);
}

static void test_circular_mode(void)
{
    uint8_t source[DMA_ENDPOINT_CAPACITY] = { 1U, 2U, 3U, 4U };
    uint8_t destination[DMA_ENDPOINT_CAPACITY] = { 0U };
    dma_fake_t dma;
    dma_config_t config = {
        { source, DMA_ENDPOINT_CAPACITY, 0U },
        { destination, DMA_ENDPOINT_CAPACITY, 0U },
        1U, 4U, DMA_MODE_CIRCULAR
    };

    assert(dma_fake_init(&dma, &config) == DMA_OK);
    for (uint32_t i = 0U; i < 8U; ++i) {
        assert(fake_dma_step(&dma, 1U) == DMA_OK);
    }
    assert(dma.state == DMA_STATE_RUNNING);
    assert(dma.remaining_units == 4U);
    assert(destination[0] == 1U && destination[3] == 4U);
}

static void test_error_paths(void)
{
    uint8_t source[DMA_ENDPOINT_CAPACITY] = { 1U, 2U };
    uint8_t destination[DMA_ENDPOINT_CAPACITY] = { 0U };
    dma_fake_t dma;
    dma_config_t bad_width = {
        { source, DMA_ENDPOINT_CAPACITY, 0U },
        { destination, DMA_ENDPOINT_CAPACITY, 0U },
        3U, 1U, DMA_MODE_NORMAL
    };
    dma_config_t bad_bounds = {
        { source, 1U, 0U },
        { destination, DMA_ENDPOINT_CAPACITY, 0U },
        2U, 1U, DMA_MODE_NORMAL
    };

    assert(dma_fake_init(&dma, &bad_width) == DMA_ERR_BAD_CONFIG);
    assert(dma_fake_init(&dma, &bad_bounds) == DMA_ERR_BOUNDS);
    {
        dma_config_t valid = {
            { source, DMA_ENDPOINT_CAPACITY, 0U },
            { destination, DMA_ENDPOINT_CAPACITY, 0U },
            1U, 2U, DMA_MODE_NORMAL
        };
        assert(dma_fake_init(&dma, &valid) == DMA_OK);
        assert(fake_dma_step(&dma, 1U) == DMA_OK);
        dma.config.destination.capacity = 1U;
        assert(fake_dma_step(&dma, 1U) == DMA_ERR_BOUNDS);
    }
    assert(fake_dma_step(&dma, 2U) == DMA_ERR_BAD_REQUEST);
}

int main(void)
{
    test_normal_mode();
    test_circular_mode();
    test_error_paths();
    return 0;
}

static void SystemClock_Config(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();
    }
}

#include "main.h"

#define ADC_DMA_SAMPLE_COUNT 128U
#define ADC_DMA_HALF_COUNT   (ADC_DMA_SAMPLE_COUNT / 2U)

ADC_HandleTypeDef hadc1;
DMA_HandleTypeDef hdma_adc1;

_Alignas(uint32_t)
static uint16_t g_adc_dma_samples[ADC_DMA_SAMPLE_COUNT];

static void MX_DMA_Init(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)
{
    GPIO_InitTypeDef gpio = {0};

    if (hadc->Instance != ADC1) {
        return;
    }

    __HAL_RCC_ADC1_CLK_ENABLE();
    __HAL_RCC_GPIOA_CLK_ENABLE();

    gpio.Pin = GPIO_PIN_0;
    gpio.Mode = GPIO_MODE_ANALOG;
    gpio.Pull = GPIO_NOPULL;
    HAL_GPIO_Init(GPIOA, &gpio);

    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 void MX_ADC1_Init(void)
{
    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 = ENABLE;
    hadc1.Init.DiscontinuousConvMode = DISABLE;
    hadc1.Init.ExternalTrigConvEdge = ADC_EXTERNALTRIGCONVEDGE_NONE;
    hadc1.Init.ExternalTrigConv = ADC_SOFTWARE_START;
    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) {
        Error_Handler();
    }

    channel.Channel = ADC_CHANNEL_0;
    channel.Rank = 1U;
    channel.SamplingTime = ADC_SAMPLETIME_84CYCLES;
    if (HAL_ADC_ConfigChannel(&hadc1, &channel) != HAL_OK) {
        Error_Handler();
    }
}

#define ADC_DMA_EVT_FIRST_HALF  (1UL << 0)
#define ADC_DMA_EVT_SECOND_HALF (1UL << 1)
#define ADC_DMA_EVT_ERROR       (1UL << 2)

static volatile uint32_t g_adc_dma_events;
static volatile uint32_t g_adc_error_code;
static volatile uint32_t g_dma_error_code;

static HAL_StatusTypeDef adc_dma_start(void)
{
    g_adc_dma_events = 0U;
    g_adc_error_code = HAL_ADC_ERROR_NONE;
    g_dma_error_code = HAL_DMA_ERROR_NONE;

    return HAL_ADC_Start_DMA(&hadc1,
                             (uint32_t *)g_adc_dma_samples,
                             ADC_DMA_SAMPLE_COUNT);
}

void DMA2_Stream0_IRQHandler(void)
{
    HAL_DMA_IRQHandler(&hdma_adc1);
}

void ADC_IRQHandler(void)
{
    HAL_ADC_IRQHandler(&hadc1);
}

void HAL_ADC_ConvHalfCpltCallback(ADC_HandleTypeDef *hadc)
{
    if (hadc->Instance == ADC1) {
        g_adc_dma_events |= ADC_DMA_EVT_FIRST_HALF;
    }
}

void HAL_ADC_ConvCpltCallback(ADC_HandleTypeDef *hadc)
{
    if (hadc->Instance == ADC1) {
        g_adc_dma_events |= ADC_DMA_EVT_SECOND_HALF;
    }
}

void HAL_ADC_ErrorCallback(ADC_HandleTypeDef *hadc)
{
    if (hadc->Instance == ADC1) {
        g_adc_error_code = HAL_ADC_GetError(hadc);
        if (hadc->DMA_Handle != NULL) {
            g_dma_error_code = HAL_DMA_GetError(hadc->DMA_Handle);
        }
        g_adc_dma_events |= ADC_DMA_EVT_ERROR;
    }
}

static uint32_t adc_dma_take_events(void)
{
    uint32_t events;
    uint32_t primask = __get_PRIMASK();

    __disable_irq();
    __DMB();
    events = g_adc_dma_events;
    g_adc_dma_events = 0U;
    __DMB();
    if (primask == 0U) {
        __enable_irq();
    }
    return events;
}

static void adc_process_block(const uint16_t *samples, uint32_t count)
{
    /* 应用处理入口：必须在 DMA 下一次覆盖该半区前完成。 */
    (void)samples;
    (void)count;
}

static HAL_StatusTypeDef adc_dma_recover(void)
{
    HAL_StatusTypeDef status = HAL_ADC_Stop_DMA(&hadc1);
    if (status != HAL_OK) {
        return status;
    }

    /* 先把 g_adc_error_code/g_dma_error_code 记入诊断，再清状态重启。 */
    return adc_dma_start();
}

int main(void)
{
    HAL_Init();
    SystemClock_Config();
    MX_GPIO_Init();
    MX_DMA_Init();
    MX_ADC1_Init();

    if (adc_dma_start() != HAL_OK) {
        Error_Handler();
    }

    for (;;) {
        uint32_t events = adc_dma_take_events();

        if ((events & ADC_DMA_EVT_FIRST_HALF) != 0U) {
            adc_process_block(&g_adc_dma_samples[0], ADC_DMA_HALF_COUNT);
        }
        if ((events & ADC_DMA_EVT_SECOND_HALF) != 0U) {
            adc_process_block(&g_adc_dma_samples[ADC_DMA_HALF_COUNT],
                              ADC_DMA_HALF_COUNT);
        }
        if ((events & ADC_DMA_EVT_ERROR) != 0U) {
            if (adc_dma_recover() != HAL_OK) {
                Error_Handler();
            }
        }
    }
}