1# CLOCK 2 3## 概述 4 5### 功能简介<a name="section1"></a> 6 7CLOCK，时钟是系统各个部件运行的基础，以CPU时钟举例，CPU 时钟是指 CPU 内部的时钟发生器，它以频率的形式工作，用来同步和控制 CPU 内部的各个操作。 8 9### 基本概念<a name="section2"></a> 10 11设备的时钟信号是指在电子设备中用于同步和控制各个模块或组件操作的信号。它是设备内部的一个基本信号源，用于确保设备的正常运行和数据传输的准确性。 12 13### 运作机制 14 15在HDF框架中，同类型设备对象较多时（可能同时存在十几个同类型配置器），若采用独立服务模式，则需要配置更多的设备节点，且相关服务会占据更多的内存资源。相反，采用统一服务模式可以使用一个设备服务作为管理器，统一处理所有同类型对象的外部访问（这会在配置文件中有所体现），实现便捷管理和节约资源的目的。CLOCK模块即采用统一服务模式（如图1所示）。 16 17CLOCK模块各分层的作用为： 18 19- 接口层：提供打开设备，写入数据，关闭设备的能力。 20 21- 核心层：主要负责服务绑定、初始化以及释放管理器，并提供添加、删除以及获取控制器的能力。 22 23- 适配层：由驱动适配者实现与硬件相关的具体功能，如控制器的初始化等。 24 25在统一模式下，所有的控制器都被核心层统一管理，并由核心层统一发布一个服务供接口层，因此这种模式下驱动无需再为每个控制器发布服务。 26 27**图 1** CLOCK统一服务模式结构图<a name="fig1"></a> 28 29 30## 使用指导 31 32### 场景介绍 33 34CLOCK提供芯片级别的时钟管理：时钟功能可用于控制芯片内部的时钟分频、时钟倍频、时钟源选择和时钟门控等操作。通过合理的时钟管理，可以提高芯片的能效，并确保各个功能部件的正确协调和协同工作。 35 36### 接口说明 37 38为了保证上层在调用CLOCK接口时能够正确的操作硬件，核心层在//drivers/hdf_core/framework/support/platform/include/clock/clock_core.h中定义了以下钩子函数。驱动适配者需要在适配层实现这些函数的具体功能，并与这些钩子函数挂接，从而完成接口层与核心层的交互。 39 40ClockMethod和ClockLockMethod定义： 41 42```c 43struct ClockMethod { 44 int32_t (*start)(struct ClockDevice *device); 45 int32_t (*stop)(struct ClockDevice *device); 46 int32_t (*setRate)(struct ClockDevice *device, uint32_t rate); 47 int32_t (*getRate)(struct ClockDevice *device, uint32_t *rate); 48 int32_t (*disable)(struct ClockDevice *device); 49 int32_t (*enable)(struct ClockDevice *device); 50 struct ClockDevice *(*getParent)(struct ClockDevice *device); 51 int32_t (*setParent)(struct ClockDevice *device, struct ClockDevice *parent); 52}; 53 54struct ClockLockMethod { 55 int32_t (*lock)(struct ClockDevice *device); 56 void (*unlock)(struct ClockDevice *device); 57}; 58 59``` 60 61在适配层中，ClockMethod必须被实现，ClockLockMethod可根据实际情况考虑是否实现。核心层提供了默认的ClockLockMethod，其中使用Spinlock作为保护临界区的锁： 62 63```c 64static int32_t ClockDeviceLockDefault(struct ClockDevice *device) 65{ 66 if (device == NULL) { 67 HDF_LOGE("ClockDeviceLockDefault: device is null!"); 68 return HDF_ERR_INVALID_OBJECT; 69 } 70 return OsalSpinLock(&device->spin); 71} 72 73static void ClockDeviceUnlockDefault(struct ClockDevice *device) 74{ 75 if (device == NULL) { 76 HDF_LOGE("ClockDeviceUnlockDefault: device is null!"); 77 return; 78 } 79 (void)OsalSpinUnlock(&device->spin); 80} 81 82static const struct ClockLockMethod g_clockLockOpsDefault = { 83 .lock = ClockDeviceLockDefault, 84 .unlock = ClockDeviceUnlockDefault, 85}; 86 87``` 88 89若实际情况不允许使用Spinlock，驱动适配者可以考虑使用其他类型的锁来实现一个自定义的ClockLockMethod。一旦实现了自定义的ClockLockMethod，默认的ClockLockMethod将被覆盖。 90 91**表 1** ClockMethod结构体成员的钩子函数功能说明 92 93| 函数成员 | 入参 | 出参 | 返回值 | 功能 | 94| -------- | -------- | -------- | -------- | -------- | 95| start | device：结构体指针，核心层CLOCK控制器 | 无| HDF_STATUS相关状态 | 打开CLOCK设备 | 96| stop | device：结构体指针，核心层CLOCK控制器 | 无 | HDF_STATUS相关状态 | 关闭CLOCK设备 | 97| setRate | device：结构体指针，核心层CLOCK控制器 | 无 | HDF_STATUS相关状态 | 设置CLOCK设备的速率 | 98| getRate | device：结构体指针，核心层CLOCK控制器 | 获取的速率 | HDF_STATUS相关状态 | 获取CLOCK设备的速率 | 99| disable | device：结构体指针，核心层CLOCK控制器 | 无 | HDF_STATUS相关状态 | 使能CLOCK设备 | 100| enable | device：结构体指针，核心层CLOCK控制器 | 无 | HDF_STATUS相关状态 | 去使能CLOCK设备 | 101| getParent | device：结构体指针，核心层CLOCK控制器 | 获取的device：结构体指针，核心层CLOCK控制器 | HDF_STATUS相关状态 | 设置CLOCK设备的父设备 | 102| setParent | device：结构体指针，核心层CLOCK控制器 | 无 | HDF_STATUS相关状态 | 设置CLOCK设备的父设备 | 103 104**表 2** ClockLockMethod结构体成员函数功能说明 105 106| 函数成员 | 入参 | 出参 | 返回值 | 功能 | 107| -------- | -------- | -------- | -------- | -------- | 108| lock | device：结构体指针，核心层CLOCK设备对象。 | 无 | HDF_STATUS相关状态 | 获取临界区锁 | 109| unlock | device：结构体指针，核心层CLOCK设备对象。 | 无 | HDF_STATUS相关状态 | 释放临界区锁 | 110 111### 开发步骤 112 113CLOCK模块适配包含以下四个步骤： 114 1151. 实例化驱动入口 116 117 - 实例化HdfDriverEntry结构体成员。 118 119 - 调用HDF_INIT将HdfDriverEntry实例化对象注册到HDF框架中。 120 1212. 配置属性文件 122 123 - 在device_info.hcs文件中添加deviceNode描述。 124 125 - 【可选】添加clock_config.hcs器件属性文件。 126 1273. 实例化核心层接口函数 128 129 - 初始化ClockDevice成员。 130 131 - 实例化ClockDevice成员ClockMethod。 132 133 >  **说明：**<br> 134 > 实例化ClockDevice成员ClockMethod，其定义和成员说明见[接口说明](#接口说明)。 135 1364. 驱动调试 137 138 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的测试用例是否成功等。 139 140### 开发实例 141 142下方将基于RK3568开发板以//drivers/hdf_core/adapter/khdf/linux/platform/clock/clock_adapter.c驱动为示例，展示需要驱动适配者提供哪些内容来完整实现设备功能。 143 1441. 实例化驱动入口 145 146 驱动入口必须为HdfDriverEntry（在//drivers/hdf_core/interfaces/inner_api/host/shared/hdf_device_desc.h中定义）类型的全局变量，且moduleName要和device_info.hcs中保持一致。HDF框架会将所有加载的驱动的HdfDriverEntry对象首地址汇总，形成一个类似数组的段地址空间，方便上层调用。 147 148 一般在加载驱动时HDF会先调用Bind函数，再调用Init函数加载该驱动。当Init调用异常时，HDF框架会调用Release释放驱动资源并退出。 149 150 CLOCK驱动入口参考： 151 152 CLOCK控制器会出现多个设备挂接的情况，因而在HDF框架中首先会为此类型的设备创建一个管理器对象。这样，需要打开某个设备时，管理器对象会根据指定参数查找到指定设备。 153 154 CLOCK管理器的驱动由核心层实现，驱动适配者不需要关注这部分内容的实现，但在实现Init函数的时候需要调用核心层的ClockDeviceAdd函数，它会实现相应功能。 155 156 ```c 157 struct HdfDriverEntry g_clockLinuxDriverEntry = { 158 .moduleVersion = 1, 159 .Bind = NULL, 160 .Init = LinuxClockInit, 161 .Release = LinuxClockRelease, 162 .moduleName = "linux_clock_adapter", // 【必要且与device_info.hcs文件内的模块名匹配】 163 }; 164 HDF_INIT(g_clockLinuxDriverEntry); // 调用HDF_INIT将驱动入口注册到HDF框架中 165 166 // 核心层clock_core.c管理器服务的驱动入口 167 struct HdfDriverEntry g_clockManagerEntry = { 168 .moduleVersion = 1, 169 .Bind = ClockManagerBind, // CLOCK不需要实现Bind，本例是一个空实现，驱动适配者可根据自身需要添加相关操作 170 .Init = ClockManagerInit, // 见Init参考 171 .Release = ClockManagerRelease, // 见Release参考 172 .moduleName = "HDF_PLATFORM_CLOCK_MANAGER", // 这与device_info.hcs文件中device0对应 173 }; 174 HDF_INIT(g_clockManagerEntry); // 调用HDF_INIT将驱动入口注册到HDF框架中 175 ``` 176 1772. 配置属性文件 178 179 完成驱动入口注册之后，下一步请在//vendor/hihope/rk3568/hdf_config/khdf/device_info/device_info.hcs文件中添加deviceNode信息，并在clock_config.hcs中配置器件属性。 180 181 deviceNode信息与驱动入口注册相关，器件属性值对于驱动适配者的驱动实现以及核心层ClockDevice相关成员的默认值或限制范围有密切关系。 182 183 统一服务模式的特点是device_info.hcs文件中第一个设备节点必须为CLOCK管理器，其各项参数如表3所示： 184 185 **表 3** device_info.hcs节点参数说明 186 187 | 成员名 | 值 | 188 | -------- | -------- | 189 | policy | 驱动服务发布的策略，CLOCK管理器具体配置为2，表示驱动对内核态和用户态都发布服务 | 190 | priority | 驱动启动优先级（0-200），值越大优先级越低。CLOCK管理器具体配置为59 | 191 | permission | 驱动创建设备节点权限，CLOCK管理器具体配置为0664 | 192 | moduleName | 驱动名称，CLOCK管理器固定为HDF_PLATFORM_CLOCK_MANAGER | 193 | serviceName | 驱动对外发布服务的名称，CLOCK管理器服务名设置为HDF_PLATFORM_CLOCK_MANAGER | 194 | deviceMatchAttr | 驱动私有数据匹配的关键字，CLOCK管理器没有使用，可忽略 | 195 196 从第二个节点开始配置具体CLOCK控制器信息，第一个节点并不表示某一路CLOCK控制器，而是代表一个资源性质设备，用于描述一类CLOCK控制器的信息。本例只有一个CLOCK设备，如有多个设备，则需要在device_info.hcs文件增加deviceNode信息，以及在clock_config.hcs文件中增加对应的器件属性。 197 198 - device_info.hcs配置参考 199 ``` 200 root { 201 device_info { 202 platform :: host { 203 device_clock :: device { 204 device0 :: deviceNode { 205 policy = 2; 206 priority = 59; 207 permission = 0644; 208 moduleName = "HDF_PLATFORM_CLOCK_MANAGER"; 209 serviceName = "HDF_PLATFORM_CLOCK_MANAGER"; 210 } 211 device1 :: deviceNode { 212 policy = 0; // 等于0，不需要发布服务。 213 priority = 65; // 驱动启动优先级。 214 permission = 0644; // 驱动创建设备节点权限。 215 moduleName = "linux_clock_adapter"; //【必要】用于指定驱动名称，需要与期望的驱动Entry中的moduleName一致。 216 deviceMatchAttr = "linux_clock_adapter_0"; //【必要】用于配置控制器私有数据，要与clock_config.hcs中对应控制器保持一致，具体的控制器信息在clock_config.hcs中。 217 } 218 } 219 } 220 } 221 } 222 ``` 223 224 - clock_config.hcs配置参考 225 226 此处以RK3568为例，给出HCS配置参考。 227 228 ``` 229 root { 230 platform { 231 clock_config { 232 match_attr = "linux_clock_adapter_0"; 233 template clock_device { 234 } 235 device_clock_0x0000 :: clock_device { 236 deviceName = "/cpus/cpu@0"; 237 deviceIndex = 1; 238 } 239 } 240 } 241 } 242 ``` 243 244 需要注意的是，新增clock_config.hcs配置文件后，必须在hdf.hcs文件中将其包含，否则配置文件无法生效。 245 246 例如：本例中clock_config.hcs所在路径为//vendor/hihope/rk3568/hdf_config/ hdf_config/khdf/hdf.hcs，则必须在产品对应的hdf.hcs中添加如下语句： 247 248 ``` 249 #include "platform/clock_config_linux.hcs" // 配置文件相对路径 250 ``` 251 252 本例基于RK3568开发板的标准系统Linux内核运行，对应的hdf.hcs文件路径为//vendor/hihope/rk3568/hdf_config/ hdf_config/khdf/hdf.hcs驱动适配者需根据实际情况选择对应路径下的文件进行修改。 253 2543. 实例化核心层函数 255 256 完成驱动入口注册之后，下一步就是以核心层ClockDevice对象的初始化为核心，包括初始化驱动适配者自定义结构体（传递参数和数据），实例化ClockDevice成员ClockMethod（让用户可以通过接口来调用驱动底层函数），实现HdfDriverEntry成员函数（Bind，Init，Release）。 257 258 - 自定义结构体参考。 259 260 从驱动的角度看，自定义结构体是参数和数据的载体，而且clock_config.hcs文件中的数值会被HDF读入并通过DeviceResourceIface来初始化结构体成员，其中一些重要数值（例如设备号、总线号等）也会传递给核心层ClockDevice对象。 261 ```c 262 // ClockDevice是核心层控制器结构体，其中的成员在Init函数中会被赋值。 263 struct ClockDevice { 264 const struct ClockMethod *ops; 265 OsalSpinlock spin; 266 const char *deviceName; 267 const char *clockName; 268 uint32_t deviceIndex; 269 const struct ClockLockMethod *lockOps; 270 void *clk; 271 void *priv; 272 struct ClockDevice *parent; 273 }; 274 ``` 275 - ClockDevice成员钩子函数结构体ClockMethod的实例化。 276 277 ClockLockMethod钩子函数结构体本例未实现，若要实例化，可参考I2C驱动开发。 278 279 ```c 280 struct ClockMethod { 281 int32_t (*start)(struct ClockDevice *device); 282 int32_t (*stop)(struct ClockDevice *device); 283 int32_t (*setRate)(struct ClockDevice *device, uint32_t rate); 284 int32_t (*getRate)(struct ClockDevice *device, uint32_t *rate); 285 int32_t (*disable)(struct ClockDevice *device); 286 int32_t (*enable)(struct ClockDevice *device); 287 struct ClockDevice *(*getParent)(struct ClockDevice *device); 288 int32_t (*setParent)(struct ClockDevice *device, struct ClockDevice *parent); 289 }; 290 ``` 291 292 - Init函数开发参考 293 294 入参： 295 296 HdfDeviceObject是整个驱动对外提供的接口参数，具备HCS配置文件的信息。 297 298 返回值： 299 300 HDF_STATUS相关状态（表4为部分展示，如需使用其他状态，可参考//drivers/hdf_core/interfaces/inner_api/utils/hdf_base.h中HDF_STATUS定义）。 301 302 **表 4** HDF_STATUS相关状态说明 303 304 | 状态(值) | 问题描述 | 305 | -------- | -------- | 306 | HDF_ERR_INVALID_OBJECT | 控制器对象非法 | 307 | HDF_ERR_INVALID_PARAM | 参数非法 | 308 | HDF_ERR_MALLOC_FAIL | 内存分配失败 | 309 | HDF_ERR_IO | I/O错误 | 310 | HDF_SUCCESS | 传输成功 | 311 | HDF_FAILURE | 传输失败 | 312 313 函数说明： 314 315 初始化自定义结构体对象，初始化ClockDevice成员，并调用核心层ClockDeviceAdd函数。 316 317 ```c 318 static int32_t LinuxClockInit(struct HdfDeviceObject *device) 319 { 320 int32_t ret = HDF_SUCCESS; 321 struct DeviceResourceNode *childNode = NULL; 322 323 if (device == NULL || device->property == NULL) { 324 HDF_LOGE("LinuxClockInit: device or property is null"); 325 return HDF_ERR_INVALID_OBJECT; 326 } 327 328 DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { 329 ret = ClockParseAndDeviceAdd(device, childNode); 330 if (ret != HDF_SUCCESS) { 331 HDF_LOGE("LinuxClockInit: clock init fail!"); 332 return ret; 333 } 334 } 335 HDF_LOGE("LinuxClockInit: clock init success!"); 336 337 return HDF_SUCCESS; 338 } 339 340 static int32_t ClockParseAndDeviceAdd(struct HdfDeviceObject *device, struct DeviceResourceNode *node) 341 { 342 int32_t ret; 343 struct ClockDevice *clockDevice = NULL; 344 345 (void)device; 346 clockDevice = (struct ClockDevice *)OsalMemCalloc(sizeof(*clockDevice)); 347 if (clockDevice == NULL) { 348 HDF_LOGE("ClockParseAndDeviceAdd: alloc clockDevice fail!"); 349 return HDF_ERR_MALLOC_FAIL; 350 } 351 ret = ClockReadDrs(clockDevice, node); 352 if (ret != HDF_SUCCESS) { 353 HDF_LOGE("ClockParseAndDeviceAdd: read drs fail, ret: %d!", ret); 354 OsalMemFree(clockDevice); 355 return ret; 356 } 357 358 clockDevice->priv = (void *)node; 359 clockDevice->ops = &g_method; 360 361 ret = ClockDeviceAdd(clockDevice); 362 if (ret != HDF_SUCCESS) { 363 HDF_LOGE("ClockParseAndDeviceAdd: add clock device:%u fail!", clockDevice->deviceIndex); 364 OsalMemFree(clockDevice); 365 return ret; 366 } 367 368 return HDF_SUCCESS; 369 } 370 371 static int32_t ClockReadDrs(struct ClockDevice *clockDevice, const struct DeviceResourceNode *node) 372 { 373 int32_t ret; 374 struct DeviceResourceIface *drsOps = NULL; 375 376 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 377 if (drsOps == NULL || drsOps->GetUint32 == NULL || drsOps->GetString == NULL) { 378 HDF_LOGE("ClockReadDrs: invalid drs ops!"); 379 return HDF_ERR_NOT_SUPPORT; 380 } 381 ret = drsOps->GetUint32(node, "deviceIndex", &clockDevice->deviceIndex, 0); 382 if (ret != HDF_SUCCESS) { 383 HDF_LOGE("ClockReadDrs: read deviceIndex fail, ret: %d!", ret); 384 return ret; 385 } 386 387 drsOps->GetString(node, "clockName", &clockDevice->clockName, 0); 388 389 ret = drsOps->GetString(node, "deviceName", &clockDevice->deviceName, 0); 390 if (ret != HDF_SUCCESS) { 391 HDF_LOGE("ClockReadDrs: read deviceName fail, ret: %d!", ret); 392 return ret; 393 } 394 return HDF_SUCCESS; 395 } 396 ``` 397 398 - Release函数开发参考 399 400 入参： 401 402 HdfDeviceObject是整个驱动对外提供的接口参数，具备HCS配置文件的信息。 403 404 返回值： 405 406 无。 407 408 函数说明： 409 释放内存和删除控制器，该函数需要在驱动入口结构体中赋值给Release接口，当HDF框架调用Init函数初始化驱动失败时，可以调用Release释放驱动资源。 410 411 ```c 412 static void LinuxClockRelease(struct HdfDeviceObject *device) 413 { 414 const struct DeviceResourceNode *childNode = NULL; 415 if (device == NULL || device->property == NULL) { 416 HDF_LOGE("LinuxClockRelease: device or property is null!"); 417 return; 418 } 419 DEV_RES_NODE_FOR_EACH_CHILD_NODE(device->property, childNode) { 420 ClockRemoveByNode(childNode); 421 } 422 } 423 424 static void ClockRemoveByNode(const struct DeviceResourceNode *node) 425 { 426 int32_t ret; 427 int32_t deviceIndex; 428 struct ClockDevice *device = NULL; 429 struct DeviceResourceIface *drsOps = NULL; 430 431 drsOps = DeviceResourceGetIfaceInstance(HDF_CONFIG_SOURCE); 432 if (drsOps == NULL || drsOps->GetUint32 == NULL) { 433 HDF_LOGE("ClockRemoveByNode: invalid drs ops!"); 434 return; 435 } 436 437 ret = drsOps->GetUint32(node, "deviceIndex", (uint32_t *)&deviceIndex, 0); 438 if (ret != HDF_SUCCESS) { 439 HDF_LOGE("ClockRemoveByNode: read deviceIndex fail, ret: %d!", ret); 440 return; 441 } 442 443 device = ClockDeviceGet(deviceIndex); 444 if (device != NULL && device->priv == node) { 445 ret = ClockStop(device); 446 if (ret != HDF_SUCCESS) { 447 HDF_LOGE("ClockRemoveByNode: close fail, ret: %d!", ret); 448 } 449 if (device->parent && device->parent->deviceName == NULL) { 450 ClockDeviceRemove(device->parent); 451 OsalMemFree(device->parent); 452 } 453 ClockDeviceRemove(device); 454 OsalMemFree(device); 455 } 456 } 457 ``` 458 4594. 驱动调试 460 461 【可选】针对新增驱动程序，建议验证驱动基本功能，例如挂载后的测试用例是否成功等。 462
