1# Clock
2
3## Overview
4
5### Function
6
7The clock regulates the timing and speed of all functions in a device. For example, the CPU clock is an internal time generator of the CPU. It operates in frequency and used to synchronize and control the operations within the CPU.
8
9The **Clock** module provides APIs for clock operations, including:
10
11-  Clock device management: enabling or disabling a clock device.
12-  Clock rate modulation: obtaining or setting the clock speed.
13-  Clock gating: enabling or disabling a clock.
14-  Parent-clock management: obtaining or setting the parent clock.
15
16### Basic Concepts
17
18The clock signal is used to synchronize and control the operations of the modules or components of an electronic device. It serves as a fundamental signal reference source to ensure proper functioning and accurate data transmission.
19
20### Working Principles
21
22In the Hardware Driver Foundation (HDF), the **Clock** module uses the unified service mode for API adaptation. In this mode, a service is used as the clock manager to handle external access requests in a unified manner. The unified service mode applies when the system has multiple device objects of the same type. If the independent service mode is used in this case, more device nodes need to be configured and more memory resources will be consumed. The **Clock** module uses the unified service mode.
23
24## Usage Guidelines
25
26### When to Use
27
28The **Clock** module provides chip-level clock management, including frequency division, frequency multiplication, clock source selection, and clock gating within the chip. Proper clock management can enhance chip efficiency while streamlining coordination and synergy among all functional components.
29
30### Available APIs
31
32The following table describes the common APIs of the **Clock** module. For more information, see **//drivers/hdf_core/framework/include/platform/clock_if.h**.
33
34**Table 1** APIs of the Clock driver
35
36| API | Description  | Return Value                          | Remarks                     |
37| ---------------------------------------------------------- | ------------- | ----------------------------------- | --------------------------------------- |
38| DevHandle ClockOpen(uint32_t number);                      | Opens a clock device. | NULL: The operation fails.<br/>Device handle: The operation is successful. |                                         |
39| int32_t ClockClose(DevHandle handle);                      | Closes a clock device. | **0**: The operation is successful.<br>Other value: The operation fails. |                                         |
40| int32_t ClockEnable(DevHandle handle);                     | Enables clock.    | **0**: The operation is successful.<br>Other value: The operation fails. |                                         |
41| int32_t ClockDisable(DevHandle handle);                    | Disables clock.  | **0**: The operation is successful.<br>Other value: The operation fails. |                                         |
42| int32_t ClockSetRate(DevHandle handle, uint32_t rate);     | Sets the clock rate. | **0**: The operation is successful.<br>Other value: The operation fails. | If the operation fails, check whether the specified clock rate is supported. |
43| int32_t ClockGetRate(DevHandle handle, uint32_t *rate);    | Obtains the clock rate. | **0**: The operation is successful.<br>Other value: The operation fails. |                                         |
44| int32_t ClockSetParent(DevHandle child, DevHandle parent); | Sets the parent clock. | **0**: The operation is successful.<br>Other value: The operation fails. | When the parent clock is set repeatedly, no error will be returned. |
45| DevHandle ClockGetParent(DevHandle handle);                | Obtains the parent clock. | **0**: The operation is successful.<br>Other value: The operation fails. |                                         |
46
47### How to Develop
48
49The following figure illustrates how to use the APIs provided by the **Clock** module.
50
51**Figure 2** Process of using Clock APIs
52
53![Process of using Clock APIs](figures/using-CLOCK-process.png)
54
55### Example
56
57The following example shows how to implement read operations on a clock device of the RK3568 development board. The hardware information is as follows:
58
59-   SOC: RK3568
60
61Example:
62
63```c
64#include "clock_if.h"          // Header file of clock APIs
65#include "hdf_log.h"           // Header file of log APIs
66#define CLOCK_NUM 1
67
68static int32_t TestCaseClock(void)
69{
70    int ret = 0;
71    DevHandle handle = NULL;
72    DevHandle parent = NULL;
73    uint32_t rate = 0;
74
75    handle = ClockOpen(CLOCK_NUM);
76    if (handle == NULL) {
77        HDF_LOGE("Failed to open CLOCK_NUM %d \n", CLOCK_NUM);
78        return HDF_FAILURE;
79    }
80
81    ret = ClockEnable(handle);
82    if (ret != HDF_SUCCESS) {
83        HDF_LOGE("Failed to ClockEnable ret = %d \n",ret);
84        return ret;
85    }
86
87
88    ret = ClockGetRate(handle, &rate);
89    if (ret != HDF_SUCCESS) {
90        HDF_LOGE("Failed to ClockGetRate ret = %d \n",ret);
91        return ret;
92    }
93
94    ret = ClockSetRate(handle, set_rate);
95    if (ret != HDF_SUCCESS) {
96        HDF_LOGE("Failed to ClockSetRate ret = %d \n",ret);
97        return ret;
98    }
99
100    ret = ClockDisable(handle);
101    if (ret != HDF_SUCCESS) {
102        HDF_LOGE("Failed to ClockDisable ret = %d \n",ret);
103        return ret;
104    }
105
106    parent = ClockGetParent(handle);
107    if (parent != NULL) {
108        ret = ClockSetParent(handle, parent);
109        ClockClose(parent);
110    } else {
111        HDF_LOGE("Failed to ClockGetParent ret = %d \n",ret);
112    }
113
114    ret = ClockClose(handle);
115    return ret;
116}
117```