xt_hal_dac - DAC 数字模拟转换驱动

版本：0.1 | 日期：2026-07-03 | 路径： platforms/components/xtiny/xt_hal/

---

一、概述

xt_hal_dac 是 xtiny 平台的 DAC（数模转换器）驱动模块，提供 DAC 初始化、电压输出、原始值输出和关闭四个接口。

设计理念： 简洁通用 。仅抽象了 DAC 最核心的配置参数（分辨率、参考电压）和两种输出方式（原始值 / 毫伏值），不限定具体的 DAC 型号。

1.1 设计原则

• 两种输出粒度 ： set_raw 提供按原始寄存器值输出（高精度控制）， set_mv 提供按目标电压输出（应用层友好）
• 分辨率 + 参考电压组合 ：平台实现根据这两个参数计算内部寄存器配置，无需用户关心底层细节
• 无回调 ：DAC 输出是同步操作，不需要异步通知

1.2 依赖

仅依赖 xt_hal_internal.h （ xt_error.h ）。

---

二、核心概念

2.1 输出模式对比

模式	接口	参数含义	适用场景
原始值	xt_hal_dac_set_raw	0 ~ (2^res_bits - 1)	需要精确控制 DAC 寄存器值
毫伏值	xt_hal_dac_set_mv	0 ~ vref_mv	应用层直接指定目标电压

2.2 参数回绕

平台实现可能无法精确支持任意 res_bits 和 vref_mv 组合，具体行为（舍入、裁剪、拒绝）由平台决定。

---

三、API 参考

以下为函数签名大纲，完整的参数说明、返回值、注意事项请查看 xt_hal_dac（DAC 驱动） 。

3.1 生命周期

函数签名	说明
xt_err_t xt_hal_dac_setup(uint8_t dac_id, uint8_t res_bits, uint16_t vref_mv)	初始化 DAC，设置分辨率和参考电压（mV）
xt_err_t xt_hal_dac_close(uint8_t dac_id)	关闭 DAC

3.2 输出控制

函数签名	说明
xt_err_t xt_hal_dac_set_raw(uint8_t dac_id, uint32_t raw)	按原始值输出，有效位取决于 res_bits
xt_err_t xt_hal_dac_set_mv(uint8_t dac_id, uint32_t mv)	按目标电压输出，单位 mV

3.3 常量

常量	值	说明
XT_HAL_DAC_INVALID_ID	0xFF	无效 DAC ID

---

四、常见模式

4.1 基本使用流程

#include "xt_hal_dac.h"
 
uint8_t dac_id = 0;
 
xt_hal_dac_setup(dac_id, 12, 3300);
 
xt_hal_dac_set_mv(dac_id, 1650);
 
xt_hal_dac_close(dac_id);

---

五、已知行为与限制

• 不支持多通道同时操作，每个调用仅操作单个 DAC
• setup 的分辨率和参考电压参数能否精确匹配取决于平台硬件能力
• set_mv 内部基于 vref_mv 和 res_bits 计算原始值，受分辨率精度限制