1# DAC 2 3## 概述 4 5### 功能简介 6 7DAC（Digital to Analog Converter）是一种通过电流、电压或电荷的形式将数字信号转换为模拟信号的设备。 8 9DAC模块支持数模转换的开发。它主要用于： 10 11- 作为过程控制计算机系统的输出通道，与执行器相连，实现对生产过程的自动控制。 12- 在利用反馈技术的模数转换器设计中，作为重要的功能模块呈现。 13 14### 基本概念 15 16- 分辨率 17 18 分辨率指的是D/A转换器能够转换的二进制位数，位数越多分辨率越高。 19 20- 转换精度 21 22 精度是指输入端加有最大数值时，DAC的实际输出值和理论计算值之差，DAC转换器的转换精度与DAC转换器的集成芯片结构和接口电路配置有关。理想情况下，DAC的转换精度越小越好，因此为了获得更高精度的DAC转换结果，首先要保证选择的DAC转换器具备足够高的分辨率。其次，要保证接口电路的器件或电源误差最小或者不存在误差，否则会造成DAC转换的误差，若这些误差超过一定程度，就会导致DAC转换错误。 23 24- 转换速度 25 26 转换速度一般由建立时间决定。从输入由全0突变为全1时开始，到输出电压稳定在FSR±½LSB范围（或以FSR±x%FSR指明范围）内为止，这段时间称为建立时间，它是DAC的最大响应时间，所以用它衡量转换速度的快慢。 27 28 - 满量程范围FSR（Full Scale Range），是指DAC输出信号幅度的最大范围，不同的DAC有不同的满量程范围，该范围可以用正、负电流或者正、负电压来限制。 29 30 - 最低有效位LSB（Least Significant Byte），指的是一个二进制数字中的第0位（即最低位）。 31 32### 运作机制 33 34在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），若采用独立服务模式，则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现），实现便捷管理和节约资源的目的。DAC模块即采用统一服务模式（如图1）。 35 36DAC模块各分层的作用为： 37- 接口层：提供打开设备、写入数据和关闭设备接口的能力。 38- 核心层：主要提供绑定设备、初始化设备以及释放设备的能力。 39- 适配层：由驱动适配者实现与硬件相关的具体功能，如控制器的初始化等。 40 41在统一模式下，所有的控制器都被核心层统一管理，并由核心层统一发布一个服务供接口层，因此这种模式下驱动无需再为每个控制器发布服务。 42 43 说明：<br>核心层可以调用接口层的函数，也可以通过钩子函数调用适配层函数，从而使得适配层间接的可以调用接口层函数，但是不可逆转接口层调用适配层函数。 44 45**图 1** 统一服务模式结构图<a name="fig1"></a> 46 47 48 49### 约束与限制 50 51DAC模块当前仅支持轻量和小型系统内核（LiteOS-A）。 52 53## 开发指导 54 55### 场景介绍 56 57DAC模块主要在设备中数模转换、音频输出和电机控制等设备使用，设置将DAC模块传入的数字信号转换为输出模拟信号时需要用到DAC数模转换驱动。当驱动开发者需要将DAC设备适配到OpenHarmony时，需要进行DAC驱动适配，下文将介绍如何进行DAC驱动适配。 58 59### 接口说明 60 61为了保证上层在调用DAC接口时能够正确的操作硬件，核心层在//drivers/hdf_core/framework/support/platform/include/dac/dac_core.h中定义了以下钩子函数。驱动适配者需要在适配层实现这些函数的具体功能，并与这些钩子函数挂接，从而完成接口层与核心层的交互。 62 63DacMethod和DacLockMethod定义： 64 65```c++ 66struct DacMethod { 67 /* 写入数据的钩子函数 */ 68 int32_t (*write)(struct DacDevice *device, uint32_t channel, uint32_t val); 69 /* 启动DAC设备的钩子函数 */ 70 int32_t (*start)(struct DacDevice *device); 71 /* 停止DAC设备的钩子函数 */ 72 int32_t (*stop)(struct DacDevice *device); 73}; 74 75struct DacLockMethod { 76 int32_t (*lock)(struct DacDevice *device); 77 void (*unlock)(struct DacDevice *device); 78}; 79``` 80在适配层中，DacMethod必须被实现，DacLockMethod可根据实际情况考虑是否实现。核心层提供了默认的DacLockMethod，其中使用Spinlock作为保护临界区的锁： 81 82```c 83static int32_t DacDeviceLockDefault(struct DacDevice *device) 84{ 85 if (device == NULL) { 86 HDF_LOGE("%s: device is null", __func__); 87 return HDF_ERR_INVALID_OBJECT; 88 } 89 return OsalSpinLock(&device->spin); 90} 91 92static void DacDeviceUnlockDefault(struct DacDevice *device) 93{ 94 if (device == NULL) { 95 HDF_LOGE("%s: device is null", __func__); 96 return; 97 } 98 (void)OsalSpinUnlock(&device->spin); 99} 100 101static const struct DacLockMethod g_dacLockOpsDefault = { 102 .lock = DacDeviceLockDefault, 103 .unlock = DacDeviceUnlockDefault, 104}; 105``` 106 107若实际情况不允许使用Spinlock，驱动适配者可以考虑使用其他类型的锁来实现一个自定义的DacLockMethod。一旦实现了自定义的DacLockMethod，默认的DacLockMethod将被覆盖。 108 109**表 1** DacMethod结构体成员的钩子函数功能说明 110 111| 函数成员 | 入参 | 出参 | 返回值 | 功能 | 112| -------- | ------------------------------------------------------------ | ---- | ------------------ | -------------- | 113| write | device：结构体指针，核心层DAC控制器<br>channel：uint32_t，传入的通道号<br>val：uint32_t，要传入的数据 | 无 | HDF_STATUS相关状态 | 写入DA的目标值 | 114| start | device：结构体指针，核心层DAC控制器 | 无 | HDF_STATUS相关状态 | 开启DAC设备 | 115| stop | device：结构体指针，核心层DAC控制器 | 无 | HDF_STATUS相关状态 | 关闭DAC设备 | 116 117**表2** DacLockMethod结构体成员函数功能说明 118 119| 函数成员 | 入参 | 出参 | 返回值 | 功能 | 120| -------- | -------- | -------- | -------- | -------- | 121| lock | device：结构体指针，核心层DAC设备对象。 | 无 | HDF_STATUS相关状态 | 获取临界区锁 | 122| unlock | devicie：结构体指针，核心层DAC设备对象。 | 无 | HDF_STATUS相关状态 | 释放临界区锁 | 123 124 125### 开发步骤 126 127DAC模块适配包含以下四个步骤： 128 1291. 实例化驱动入口。 1302. 配置属性文件。 1313. 实例化核心层接口函数。 1324. 驱动调试。 133 134### 开发实例 135 136下方将Hi3516DV300的驱动//device/soc/hisilicon/common/platform/dac/dac_hi35xx.c为例，展示驱动适配者需要提供哪些内容来完整实现设备功能。 137 1381. 实例化驱动入口： 139 140 驱动开发首先需要实例化驱动入口，驱动入口必须为HdfDriverEntry（在hdf_device_desc.h中定义）类型的全局变量，且moduleName要和//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs中保持一致。HDF框架会汇总所有加载的驱动的HdfDriverEntry对象入口，形成一个类似数组的段地址空间，方便上层调用。 141 142 一般在加载驱动时HDF会先调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 143 144 ```c++ 145 static struct HdfDriverEntry g_dacDriverEntry = { 146 .moduleVersion = 1, 147 .Init = VirtualDacInit, 148 .Release = VirtualDacRelease, 149 .moduleName = "virtual_dac_driver", //【必要且与HCS里面的名字匹配】 150 }; 151 HDF_INIT(g_dacDriverEntry); // 调用HDF_INIT将驱动入口注册到HDF框架中 152 ``` 153 1542. 配置属性文件： 155 156 - 添加//vendor/hisilicon/hispark_taurus/hdf_config/device_info/device_info.hcs器件属性文件。 157 158 器件属性值对于驱动适配者的驱动实现以及核心层DacDevice相关成员的默认值或限制范围有密切关系，比如设备通道的个数以及传输速率的最大值，会影响DacDevice相关成员的默认值。 159 160 由于采用了统一服务模式，device_info.hcs文件中第一个设备节点必须为DAC管理器，其各项参数必须如下设置： 161 162 | 成员名 | 值 | 163 | --------------- | ------------------------------------------------------------------- | 164 | policy | 具体配置为0，不发布服务 | 165 | priority | 驱动启动优先级（0-200），值越大优先级越低，优先级相同则不保证device的加载顺序。| 166 | permission | 驱动权限 | 167 | moduleName | 固定为HDF_PLATFORM_DAC_MANAGER | 168 | serviceName | 固定为HDF_PLATFORM_DAC_MANAGER | 169 | deviceMatchAttr | 没有使用，可忽略 | 170 171 从第二个节点开始配置具体DAC控制器信息，此节点并不表示某一路DAC控制器，而是代表一个资源性质设备，用于描述一类DAC控制器的信息。本例只有一个DAC设备，如有多个设备，则需要在device_info.hcs文件增加deviceNode信息，以及在dac_config.hcs文件中增加对应的器件属性。 172 173 device_info.hcs配置参考： 174 175 ```hcs 176 root { 177 device_dac :: device { 178 /* device0是DAC管理器 */ 179 device0 :: deviceNode { 180 policy = 0; 181 priority = 52; 182 permission = 0644; 183 serviceName = "HDF_PLATFORM_DAC_MANAGER"; 184 moduleName = "HDF_PLATFORM_DAC_MANAGER"; 185 } 186 } 187 /* dac_virtual是DAC控制器 */ 188 dac_virtual :: deviceNode { 189 policy = 0; 190 priority = 56; 191 permission = 0644; 192 moduleName = "virtual_dac_driver"; //【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致。 193 serviceName = "VIRTUAL_DAC_DRIVER"; //【必要】驱动对外发布服务的名称，必须唯一。 194 deviceMatchAttr = "virtual_dac"; //【必要】用于配置控制器私有数据，要与dac_config.hcs中对应控制器保持一致。 195 } 196 } 197 ``` 198 199 - 添加dac_test_config.hcs器件属性文件。 200 201 在具体产品对应目录下新增文件用于驱动配置参数（例如hispark_taurus开发板：vendor/hisilicon/hispark_taurus/hdf_config/hdf_test/dac_test_config.hcs），其中配置参数如下： 202 203 ```hcs 204 root { 205 platform { 206 dac_config { 207 match_attr = "virtual_dac"; //【必要】需要和device_info.hcs中的deviceMatchAttr值一致 208 template dac_device { 209 deviceNum = 0; // 设备号 210 validChannel = 0x1; // 有效通道1 211 rate = 20000; // 速率 212 } 213 device_0 :: dac_device { 214 deviceNum = 0; // 设备号 215 validChannel = 0x2; // 有效通道2 216 } 217 } 218 } 219 } 220 ``` 221 222 需要注意的是，新增dac_config.hcs配置文件后，必须在hdf.hcs文件中将其包含，否则配置文件无法生效。 223 224 例如：本例中dac_config.hcs所在路径为device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/dac/dac_config.hcs，则必须在产品对应的hdf.hcs中添加如下语句： 225 226 ```c 227 #include "../../../../device/soc/hisilicon/hi3516dv300/sdk_liteos/hdf_config/dac/dac_config.hcs" // 配置文件相对路径 228 ``` 229 2303. 实例化核心层接口函数： 231 232 - 初始化DacDevice成员。 233 234 在VirtualDacParseAndInit函数中对DacDevice成员进行初始化操作。 235 236 ```c++ 237 /* 虚拟驱动自定义结构体 */ 238 struct VirtualDacDevice { 239 /*DAC设备结构体 */ 240 struct DacDevice device; 241 /* DAC设备号 */ 242 uint32_t deviceNum; 243 /* 有效通道 */ 244 uint32_t validChannel; 245 /* DAC速率 */ 246 uint32_t rate; 247 }; 248 /* 解析并且初始化核心层DacDevice对象 */ 249 static int32_t VirtualDacParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) 250 { 251 /* 定义返回值 */ 252 int32_t ret; 253 /* DAC设备虚拟指针 */ 254 struct VirtualDacDevice *virtual = NULL; 255 (void)device; 256 /* 给virtual指针开辟空间 */ 257 virtual = (struct VirtualDacDevice *)OsalMemCalloc(sizeof(*virtual)); 258 if (virtual == NULL) { 259 /*为空则返回错误参数 */ 260 HDF_LOGE("%s: Malloc virtual fail!", __func__); 261 return HDF_ERR_MALLOC_FAIL; 262 } 263 /* 读取属性文件配置参数 */ 264 ret = VirtualDacReadDrs(virtual, node); 265 if (ret != HDF_SUCCESS) { 266 /* 读取失败 */ 267 HDF_LOGE("%s: Read drs fail! ret:%d", __func__, ret); 268 /* 释放virtual空间 */ 269 OsalMemFree(virtual); 270 /* 指针置为0 */ 271 virtual = NULL; 272 return ret; 273 } 274 /* 初始化虚拟指针 */ 275 VirtualDacDeviceInit(virtual); 276 /* 对DacDevice中priv对象初始化 */ 277 virtual->device.priv = (void *)node; 278 /* 对DacDevice中devNum对象初始化 */ 279 virtual->device.devNum = virtual->deviceNum; 280 /* 对DacDevice中ops对象初始化 */ 281 virtual->device.ops = &g_method; 282 /* 添加DAC设备 */ 283 ret = DacDeviceAdd(&virtual->device); 284 if (ret != HDF_SUCCESS) { 285 /* 添加设备失败 */ 286 HDF_LOGE("%s: add Dac controller failed! ret = %d", __func__, ret); 287 /* 释放virtual空间 */ 288 OsalMemFree(virtual); 289 /* 虚拟指针置空 */ 290 virtual = NULL; 291 return ret; 292 } 293 294 return HDF_SUCCESS; 295 } 296 ``` 297 298 - 自定义结构体参考。 299 300 通过自定义结构体定义DAC数模转换必要的参数，在定义结构体时需要根据设备的功能参数来实现自定义结构体，从驱动的角度看，自定义结构体是参数和数据的载体，dac_config.hcs文件中传递的参数和数据会被HDF驱动模块的DacTestReadConfig函数读入，通过DeviceResourceIface来初始化结构体成员，其中一些重要数值也会传递给核心层DacDevice对象，例如设备号、总线号等。 301 302 ```c++ 303 struct VirtualDacDevice { 304 struct DacDevice device; //【必要】是核心层控制对象，具体描述见下面 305 uint32_t deviceNum; //【必要】设备号 306 uint32_t validChannel; //【必要】有效通道 307 uint32_t rate; //【必要】采样率 308 }; 309 310 /* DacDevice是核心层控制器结构体，其中的成员在Init函数中会被赋值。 */ 311 struct DacDevice { 312 const struct DacMethod *ops; 313 OsalSpinlock spin; // 自旋锁 314 uint32_t devNum; // 设备号 315 uint32_t chanNum; // 设备通道号 316 const struct DacLockMethod *lockOps; 317 void *priv; 318 }; 319 ``` 320 321 - 实例化DacDevice成员DacMethod。 322 323 VirtualDacWrite、VirtualDacStop、VirtualDacStart函数会在dac_virtual.c文件中进行模块功能的实例化。 324 325 ```c++ 326 static const struct DacMethod g_method = { 327 .write = VirtualDacWrite, // DAC设备写入值 328 .stop = VirtualDacStop, // 停止DAC设备 329 .start = VirtualDacStart, // 开始启动DAC设备 330 }; 331 ``` 332 333  **说明：**<br> 334 DacDevice成员DacMethod的定义和成员说明见[接口说明](#接口说明)。 335 336 - Init函数开发参考 337 338 入参： 339 340 HdfDeviceObject这个是整个驱动对外提供的接口参数，具备HCS配置文件的信息。 341 342 返回值： 343 344 HDF_STATUS相关状态（下表为部分展示，如需使用其他状态，可见//drivers/hdf_core/framework/include/utils/hdf_base.h中HDF_STATUS定义）。 345 346 | 状态(值) | 问题描述 | 347 | ---------------------- | ------------- | 348 | HDF_ERR_INVALID_OBJECT | 控制器对象非法。 | 349 | HDF_ERR_INVALID_PARAM | 参数非法。 | 350 | HDF_ERR_MALLOC_FAIL | 内存分配失败。 | 351 | HDF_ERR_IO | I/O 错误。 | 352 | HDF_SUCCESS | 传输成功。 | 353 | HDF_FAILURE | 传输失败。 | 354 355 函数说明： 356 357 初始化自定义结构体对象，初始化DacDevice成员，并调用核心层DacDeviceAdd函数。 358 359 ```c++ 360 static int32_t VirtualDacParseAndInit(struct HdfDeviceObject *device, const struct DeviceResourceNode *node) 361 { 362 /* 定义返回值参数 */ 363 int32_t ret; 364 /* DAC设备的结构体指针 */ 365 struct VirtualDacDevice *virtual = NULL; 366 (void)device; 367 /* 分配指定大小的内存 */ 368 virtual = (struct VirtualDacDevice *)OsalMemCalloc(sizeof(*virtual)); 369 if (virtual == NULL) { 370 /* 分配内存失败 */ 371 HDF_LOGE("%s: Malloc virtual fail!", __func__); 372 return HDF_ERR_MALLOC_FAIL; 373 } 374 /* 读取hcs中的node节点参数，函数定义见下方 */ 375 ret = VirtualDacReadDrs(virtual, node); 376 if (ret != HDF_SUCCESS) { 377 /* 读取节点失败 */ 378 HDF_LOGE("%s: Read drs fail! ret:%d", __func__, ret); 379 goto __ERR__; 380 } 381 /* 初始化DAC设备指针 */ 382 VirtualDacDeviceInit(virtual); 383 /* 节点数据传入私有数据 */ 384 virtual->device.priv = (void *)node; 385 /* 传入设备号 */ 386 virtual->device.devNum = virtual->deviceNum; 387 /* 传入方法 */ 388 virtual->device.ops = &g_method; 389 /* 添加DAC设备 */ 390 ret = DacDeviceAdd(&virtual->device); 391 if (ret != HDF_SUCCESS) { 392 /* 添加DAC设备失败 */ 393 HDF_LOGE("%s: add Dac controller failed! ret = %d", __func__, ret); 394 goto __ERR__; 395 } 396 /* 成功添加DAC设备 */ 397 return HDF_SUCCESS; 398 __ERR__: 399 /* 如果指针为空 */ 400 if (virtual != NULL) { 401 /* 释放内存 */ 402 OsalMemFree(virtual); 403 /* 指针置空 */ 404 virtual = NULL; 405 } 406 407 return ret; 408 } 409 410 static int32_t VirtualDacInit(struct HdfDeviceObject *device) 411 { 412 /* 定义返回值参数 */ 413 int32_t ret; 414 /* 设备结构体子节点 */ 415 const struct DeviceResourceNode *childNode = NULL; 416 /* 入参指针进行判断 */ 417 if (device == NULL || device->property == NULL) { 418 /* 入参指针为空 */ 419 HDF_LOGE("%s: device or property is NULL", __func__); 420 return HDF_ERR_INVALID_OBJECT; 421 } 422 /* 入参指针不为空 */ 423 ret = HDF_SUCCESS; 424 DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { 425 /* 解析子节点 */ 426 ret = VirtualDacParseAndInit(device, childNode); 427 if (ret != HDF_SUCCESS) { 428 /* 解析失败 */ 429 break; 430 } 431 } 432 /* 解析成功 */ 433 return ret; 434 } 435 436 static int32_t VirtualDacReadDrs(struct VirtualDacDevice *virtual, const struct DeviceResourceNode *node) 437 { 438 struct DeviceResourceIface *drsOps = NULL; 439 440 /* 获取drsOps方法 */ 441 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 442 if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetUint16 == NULL) { 443 HDF_LOGE("%s: Invalid drs ops fail!", __func__); 444 return HDF_FAILURE; 445 } 446 /* 将配置参数依次读出，并填充至结构体中 */ 447 if (drsOps->GetUint32(node, "deviceNum", &virtual->deviceNum, 0) != HDF_SUCCESS) { 448 HDF_LOGE("%s: Read deviceNum fail!", __func__); 449 return HDF_ERR_IO; 450 } 451 if (drsOps->GetUint32(node, "validChannel", &virtual->validChannel, 0) != HDF_SUCCESS) { 452 HDF_LOGE("%s: Read validChannel fail!", __func__); 453 return HDF_ERR_IO; 454 } 455 if (drsOps->GetUint32(node, "rate", &virtual->rate, 0) != HDF_SUCCESS) { 456 HDF_LOGE("%s: Read rate fail!", __func__); 457 return HDF_ERR_IO; 458 } 459 return HDF_SUCCESS; 460 } 461 ``` 462 463 - Release函数开发参考 464 465 入参： 466 467 HdfDeviceObject是整个驱动对外提供的接口参数，具备HCS配置文件的信息。 468 469 返回值： 470 471 无。 472 473 函数说明： 474 475 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。 476 477  **说明：**<br> 478 所有强制转换获取相应对象的操作前提是在Init函数中具备对应赋值的操作。 479 480 ```c++ 481 static void VirtualDacRemoveByNode(const struct DeviceResourceNode *node) 482 { 483 /* 定义返回值参数 */ 484 int32_t ret; 485 /* 定义DAC设备号 */ 486 int16_t devNum; 487 /* DAC设备结构体指针 */ 488 struct DacDevice *device = NULL; 489 /* DAC虚拟结构体指针 */ 490 struct VirtualDacDevice *virtual = NULL; 491 /* 设备资源接口结构体指针 */ 492 struct DeviceResourceIface *drsOps = NULL; 493 /* 通过实例入口获取设备资源 */ 494 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 495 /* 入参指判空 */ 496 if (drsOps == NULL || drsOps->GetUint32 == NULL) { 497 /* 指针为空 */ 498 HDF_LOGE("%s: invalid drs ops fail!", __func__); 499 return; 500 } 501 /* 获取devNum节点的数据 */ 502 ret = drsOps->GetUint16(node, "devNum", (uint16_t *)&devNum, 0); 503 if (ret != HDF_SUCCESS) { 504 /* 获取失败 */ 505 HDF_LOGE("%s: read devNum fail!", __func__); 506 return; 507 } 508 /* 获取DAC设备号 */ 509 device = DacDeviceGet(devNum); 510 /* 判断DAC设备号以及数据是否为空 */ 511 if (device != NULL && device->priv == node) { 512 /* 为空释放DAC设备号 */ 513 DacDevicePut(device); 514 /* 移除DAC设备号 */ 515 DacDeviceRemove(device); 516 virtual = (struct VirtualDacDevice *)device; 517 /* 释放虚拟指针 */ 518 OsalMemFree(virtual); 519 } 520 return; 521 } 522 523 static void VirtualDacRelease(struct HdfDeviceObject *device) 524 { 525 /* 定义设备资源子节点结构体指针 */ 526 const struct DeviceResourceNode *childNode = NULL; 527 /* 入参指针判空 */ 528 if (device == NULL || device->property == NULL) { 529 /* 入参指针为空 */ 530 HDF_LOGE("%s: device or property is NULL", __func__); 531 return; 532 } 533 534 DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { 535 /* 通过节点移除DAC */ 536 VirtualDacRemoveByNode(childNode); 537 } 538 } 539 ``` 540 5414. 驱动调试： 542 543 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的测试用例是否成功等。
