AD/DA HAL库API

前面我们通过实例了解了 AD/DA 转换的几种常用方法。这些方法的实现都离不开 STMicroelectronics 提供的 HAL (Hardware Abstraction Layer) 库。HAL 库封装了底层的寄存器操作，提供了统一、易用的 API 接口。理解这些核心 API 对于灵活运用 AD/DA 功能至关重要。本节将深入探讨我们在之前章节中使用到的关键 HAL 函数和宏。

一，ADC 相关 API

1，ADC_HandleTypeDef (句柄)

这是 ADC 外设的"身份证"和"控制器"。它是一个结构体，包含了：
ADC 的配置信息（如分辨率、模式、触发源等）、
运行时状态、
错误代码以及指向 DMA 通道句柄的指针（如果使用了 DMA）
所有 ADC 相关的 HAL 函数都需要传递一个指向该类型结构体的指针作为第一个参数（例如 &hadc1）。该结构体通常由 CubeMX 自动生成和初始化。

2，HAL_StatusTypeDef HAL_ADC_Start(ADC_HandleTypeDef* hadc)

用途:
启动 ADC 转换。在轮询法或中断法中用于启动单次或连续转换（取决于 CubeMX 配置）

注意：启动ADC转换不一定就开始ADC转换，还要检查触发源

参数:
hadc - 指向 ADC 句柄的指针
返回:
HAL_OK (成功), HAL_ERROR, HAL_BUSY

3，HAL_StatusTypeDef HAL_ADC_Stop(ADC_HandleTypeDef* hadc)

用途:
停止 ADC 转换。主要用于停止连续转换模式下的 ADC。
参数:
hadc - 指向 ADC 句柄的指针。
返回:
HAL_OK, HAL_ERROR, HAL_BUSY。

4，HAL_StatusTypeDef HAL_ADC_PollForConversion(ADC_HandleTypeDef* hadc, uint32_t Timeout)

用途:
以阻塞方式等待 ADC 转换完成。它会不断检查 ADC 状态寄存器中的 EOC (End of Conversion) 标志位。
参数:
hadc: 指向 ADC 句柄的指针。
Timeout: 等待超时时间（毫秒）。如果超时仍未完成，则返回 HAL_TIMEOUT。
返回:
HAL_OK (转换完成), HAL_TIMEOUT, HAL_ERROR。
说明:
用于"守株待兔"式地等待转换结果，但会阻塞 CPU

5，uint32_t HAL_ADC_GetValue(ADC_HandleTypeDef* hadc)

用途:
读取 ADC 转换的结果。
参数:
hadc - 指向 ADC 句柄的指针。
返回:
ADC 数据寄存器中的转换结果（通常是 0 到 4095 对于 12 位 ADC）。
说明:
当 HAL_ADC_PollForConversion 返回 HAL_OK 后，调用此函数获取数字值。

6，HAL_StatusTypeDef HAL_ADC_Start_DMA(ADC_HandleTypeDef* hadc, uint32_t* pData, uint32_t Length)

用途:
以 DMA 模式启动 ADC 转换。ADC 转换的结果将由 DMA 控制器自动传输到指定的内存缓冲区。
参数:
hadc: 指向 ADC 句柄的指针。
pData: 指向存储转换结果的内存缓冲区的指针。

注意： HAL 库通常要求此指针为 uint32_t* 类型，即使你定义的缓冲区是 uint16_t 类型，也需要进行强制类型转换 (uint32_t*)your_buffer。这与 DMA 配置为 Word 传输有关

Length: DMA 单次传输的数据量（对于循环模式，这是缓冲区的大小）

返回:
HAL_OK, HAL_ERROR, HAL_BUSY
说明:
这是 (DMA 轮询) 和(TIM+DMA+IT) 实现 ADC 数据自动搬运的核心函数。一旦启动（且 DMA 配置为循环模式），数据传输会自动进行。

7，HAL_StatusTypeDef HAL_ADC_Stop_DMA(ADC_HandleTypeDef* hadc)

用途:
停止以 DMA 模式运行的 ADC 转换和相应的 DMA 传输
参数:
hadc - 指向 ADC 句柄的指针
返回:
HAL_OK, HAL_ERROR, HAL_BUSY
说明:
在需要停止 DMA 驱动的 ADC 采集时使用此函数

8，void HAL_ADC_ConvCpltCallback(ADC_HandleTypeDef* hadc) (回调函数)

用途:
这是一个弱定义 (weak) 的回调函数，当 ADC 转换完成（在中断模式下）或 DMA 传输完成（在 DMA 模式下，完成整个缓冲区传输）时，由 HAL 库的中断处理程序调用。
参数:
hadc - 触发回调的 ADC 句柄指针
说明:
在 (TIM+DMA+IT) 中，我们在用户代码中重新实现了这个函数。当 DMA 完成将 adc_dma_buffer 填满时，此回调被触发，我们在其中将数据拷贝到处理缓冲区 adc_processing_buffer 并设置标志位 adc_data_ready_flag。这是实现采样与处理解耦的关键。

9，__HAL_DMA_DISABLE_IT(&hdma_adc1, DMA_IT_HT) (宏)

用途:
禁用指定的 DMA 中断。这是一个宏，直接操作 DMA 控制器的寄存器。
参数:
&hdma_adc1: 指向与 ADC 关联的 DMA 通道句柄的指针 (需要根据实际项目中的 DMA 句柄名称修改)。
DMA_IT_HT: 指定要禁用的中断类型，这里是半传输 (Half Transfer) 中断。其他常用类型包括 DMA_IT_TC (全传输完成), DMA_IT_TE (传输错误)。
说明:
我们只关心全传输完成中断 (TC)，所以显式调用此宏来禁用半传输中断 (HT)，防止它意外触发回调函数或中断。

二，DAC 相关 API

1，DAC_HandleTypeDef (句柄)

与 ADC 类似，这是 DAC 外设的句柄结构体，包含了 DAC 的配置信息、状态等。所有 DAC 相关的 HAL 函数都需要传递指向该类型结构体的指针（例如 &hdac）。同样通常由 CubeMX 生成和初始化。

2，HAL_StatusTypeDef HAL_DAC_Start(DAC_HandleTypeDef* hdac, uint32_t Channel)

用途:
启动指定的 DAC 通道。
参数:
hdac: 指向 DAC 句柄的指针。
Channel: 要启动的 DAC 通道，例如 DAC_CHANNEL_1 或 DAC_CHANNEL_2 (取决于具体型号)。
返回:
HAL_OK, HAL_ERROR。
说明:
在非 DMA 模式下控制 DAC 时使用。

3，HAL_StatusTypeDef HAL_DAC_Stop(DAC_HandleTypeDef* hdac, uint32_t Channel)

用途:
停止指定的 DAC 通道。
参数:
hdac: 指向 DAC 句柄的指针。
Channel: 要停止的 DAC 通道。
返回:
HAL_OK, HAL_ERROR。
说明:
在非 DMA 模式下停止 DAC 输出时使用。

4，HAL_StatusTypeDef HAL_DAC_SetValue(DAC_HandleTypeDef* hdac, uint32_t Channel, uint32_t Alignment, uint32_t Data)

用途:
手动设置 DAC 通道的输出值。DAC 会将 Data 转换为对应的模拟电压。
参数:
hdac: 指向 DAC 句柄的指针。
Channel: 要设置的 DAC 通道。
Alignment: 数据对齐方式。对于 12 位 DAC，常用 DAC_ALIGN_12B_R (右对齐) 或 DAC_ALIGN_12B_L (左对齐)。对于 8 位 DAC，使用 DAC_ALIGN_8B_R。这必须与 CubeMX 中的配置一致。
Data: 要写入 DAC 数据保持寄存器的数字值 (例如 0-4095)。

返回:
HAL_OK, HAL_ERROR。
说明:
这是手动控制 DAC 输出最基本的方式。DMA 模式实际上是硬件自动调用类似此操作的过程。

5，HAL_StatusTypeDef HAL_DAC_Start_DMA(DAC_HandleTypeDef* hdac, uint32_t Channel, uint32_t* pData, uint32_t Length, uint32_t Alignment)

用途:
以 DMA 模式启动 DAC 通道输出。DMA 会自动从指定的内存缓冲区读取数据，并根据触发信号（通常来自定时器）写入 DAC 数据寄存器。

参数:
hdac: 指向 DAC 句柄的指针。
Channel: 要使用的 DAC 通道。
pData: 指向包含波形数据的内存缓冲区的指针（查找表）。注意： 同样，HAL 库常要求此指针为 uint32_t* 类型，即使数据是 uint16_t，如 (uint32_t *)SineWave。
Length: 查找表中的数据点数量（DMA 传输单元数）。
Alignment: 数据对齐方式，必须与 HAL_DAC_SetValue 和 CubeMX 配置一致，例如 DAC_ALIGN_12B_R。

返回:
HAL_OK, HAL_ERROR, HAL_BUSY。
说明:
输出正弦波的核心函数。它启动了从 SineWave 数组到 DAC 的自动数据流。

6，HAL_StatusTypeDef HAL_DAC_Stop_DMA(DAC_HandleTypeDef* hdac, uint32_t Channel)

用途:
停止以 DMA 模式运行的 DAC 通道和相应的 DMA 传输。

参数:
hdac: 指向 DAC 句柄的指针。
Channel: 要停止的 DAC 通道。

返回:
HAL_OK, HAL_ERROR, HAL_BUSY。
说明:
用于停止由 DMA 驱动的 DAC 波形输出。

三，TIM (定时器) 相关 API

1，TIM_HandleTypeDef (句柄)

定时器外设的句柄结构体，包含了定时器的配置信息（如预分频器 PSC、周期 ARR、时钟源、触发输出 TRGO 设置等）和状态。操作定时器的 HAL 函数需要传递指向该结构体的指针（例如 &htim3, &htim6）。由 CubeMX 生成和初始化。

2，HAL_StatusTypeDef HAL_TIM_Base_Start(TIM_HandleTypeDef *htim)

用途:
以基本模式（向上或向下计数）启动定时器。
参数:
htim - 指向要启动的定时器句柄的指针。
返回:
HAL_OK, HAL_ERROR。
说明: 在(ADC 的 TIM+DMA+IT) 和(DAC 的 DMA 正弦波) 中，我们使用此函数启动作为 ADC 或 DAC 触发源 (TRGO) 的定时器（如 TIM3 或 TIM6）。定时器启动后，会按照配置的频率产生更新事件，进而触发 ADC 转换或 DMA 传输到 DAC。

四， DMA 相关

DMA_HandleTypeDef (句柄)

DMA 通道的句柄结构体。它包含了特定 DMA 通道的配置（如传输方向、外设/内存地址、数据宽度、模式 - 循环/普通、优先级等）和状态。
虽然在我们的 ADC/DAC 应用代码中可能不直接声明或操作独立的 DMA 句柄变量（因为它通常被链接在 ADC 或 DAC 句柄内部，由 CubeMX 配置），但理解它的存在和配置对于排查 DMA 问题至关重要。例如，__HAL_DMA_DISABLE_IT 宏就需要传递 DMA 句柄的地址。

HAL 库提供了丰富的功能，远不止这些。查阅 ST 官方提供的对应系列 MCU 的 HAL 库用户手册是深入学习和掌握更多高级功能的最佳途径。