1 /*
2 * Copyright (c) 2006-2025 RT-Thread Development Team
3 *
4 * SPDX-License-Identifier: Apache-2.0
5 *
6 * Change Logs:
7 * Date Author Notes
8 * 2022-11-26 GuEe-GUI first version
9 * 2025-01-24 wumingzi add doxygen comment
10 */
11
12 #ifndef __CLK_H__
13 #define __CLK_H__
14
15 #include <rthw.h>
16
17 #include <ref.h>
18 #include <drivers/ofw.h>
19
20 /**
21 * @defgroup group_driver_clock Clock
22 * @brief Clock driver API
23 * @ingroup group_device_driver
24 */
25
26 /**
27 * @addtogroup group_driver_clock
28 * @{
29 */
30
31 #define RT_CLK_NODE_OBJ_NAME "CLKNP"
32
33 struct rt_clk_ops;
34 struct rt_reset_control_node;
35
36 /**
37 * @brief Clk node, it is a pat of clk source or controller
38 * @note Defined as the array like this if the CLK have multi out clocks:
39 * @code{.c}
40 * struct XYZ_single_clk
41 * {
42 * struct rt_clk_node parent;
43 * ...
44 * };
45 *
46 * struct XYZ_multi_clk
47 * {
48 * struct rt_clk_node parent[N];
49 * ...
50 * };
51 * @endcode
52 * We assume the 'N' is the max value of element in 'clock-indices' if OFW.
53 */
54 struct rt_clk_node
55 {
56 struct rt_object rt_parent;
57
58 rt_list_t list;
59 rt_list_t children_nodes;
60
61 const char *name;
62 const struct rt_clk_ops *ops;
63
64 struct rt_clk_node *parent;
65 struct rt_ref ref;
66
67 rt_ubase_t rate;
68 rt_ubase_t min_rate;
69 rt_ubase_t max_rate;
70
71 rt_size_t notifier_count;
72
73 void *priv;
74
75 struct rt_clk *clk;
76 rt_size_t multi_clk;
77 };
78
79 /**
80 * @brief Constant rate clk
81 */
82 struct rt_clk_fixed_rate
83 {
84 struct rt_clk_node clk;
85
86 rt_ubase_t fixed_rate;
87 rt_ubase_t fixed_accuracy;
88 };
89
90 /**
91 * @brief Clk object, it can be clk source or controller
92 */
93 struct rt_clk
94 {
95 struct rt_clk_node *clk_np;
96
97 const char *dev_id;
98 const char *con_id;
99
100 rt_ubase_t rate;
101 int prepare_count;
102 int enable_count;
103
104 void *fw_node;
105 void *priv;
106 };
107
108 /**
109 * @brief Clk array
110 */
111 struct rt_clk_array
112 {
113 rt_size_t count;
114 struct rt_clk *clks[];
115 };
116
117 struct rt_clk_ops
118 {
119 rt_err_t (*init)(struct rt_clk *, void *fw_data);
120 rt_err_t (*finit)(struct rt_clk *);
121 /* API */
122 rt_err_t (*prepare)(struct rt_clk *);
123 void (*unprepare)(struct rt_clk *);
124 rt_bool_t (*is_prepared)(struct rt_clk *);
125 rt_err_t (*enable)(struct rt_clk *);
126 void (*disable)(struct rt_clk *);
127 rt_bool_t (*is_enabled)(struct rt_clk *);
128 rt_err_t (*set_rate)(struct rt_clk *, rt_ubase_t rate, rt_ubase_t parent_rate);
129 rt_err_t (*set_parent)(struct rt_clk *, struct rt_clk *parent);
130 rt_err_t (*set_phase)(struct rt_clk *, int degrees);
131 rt_base_t (*get_phase)(struct rt_clk *);
132 rt_base_t (*round_rate)(struct rt_clk *, rt_ubase_t drate, rt_ubase_t *prate);
133 };
134
135 struct rt_clk_notifier;
136
137 #define RT_CLK_MSG_PRE_RATE_CHANGE RT_BIT(0)
138 #define RT_CLK_MSG_POST_RATE_CHANGE RT_BIT(1)
139 #define RT_CLK_MSG_ABORT_RATE_CHANGE RT_BIT(2)
140
141 typedef rt_err_t (*rt_clk_notifier_callback)(struct rt_clk_notifier *notifier,
142 rt_ubase_t msg, rt_ubase_t old_rate, rt_ubase_t new_rate);
143
144 /**
145 * @brief Clock notifier, it containers of clock list and callback function
146 */
147 struct rt_clk_notifier
148 {
149 rt_list_t list;
150
151 struct rt_clk *clk;
152 rt_clk_notifier_callback callback;
153 void *priv;
154 };
155
156 rt_err_t rt_clk_register(struct rt_clk_node *clk_np, struct rt_clk_node *parent_np);
157 rt_err_t rt_clk_unregister(struct rt_clk_node *clk_np);
158
159 rt_err_t rt_clk_notifier_register(struct rt_clk *clk, struct rt_clk_notifier *notifier);
160 rt_err_t rt_clk_notifier_unregister(struct rt_clk *clk, struct rt_clk_notifier *notifier);
161
162 rt_err_t rt_clk_set_parent(struct rt_clk *clk, struct rt_clk *clk_parent);
163
164 rt_err_t rt_clk_prepare(struct rt_clk *clk);
165 rt_err_t rt_clk_unprepare(struct rt_clk *clk);
166
167 rt_err_t rt_clk_enable(struct rt_clk *clk);
168 void rt_clk_disable(struct rt_clk *clk);
169
170 rt_err_t rt_clk_prepare_enable(struct rt_clk *clk);
171 void rt_clk_disable_unprepare(struct rt_clk *clk);
172
173 rt_err_t rt_clk_array_prepare(struct rt_clk_array *clk_arr);
174 rt_err_t rt_clk_array_unprepare(struct rt_clk_array *clk_arr);
175
176 rt_err_t rt_clk_array_enable(struct rt_clk_array *clk_arr);
177 void rt_clk_array_disable(struct rt_clk_array *clk_arr);
178
179 rt_err_t rt_clk_array_prepare_enable(struct rt_clk_array *clk_arr);
180 void rt_clk_array_disable_unprepare(struct rt_clk_array *clk_arr);
181
182 rt_err_t rt_clk_set_rate_range(struct rt_clk *clk, rt_ubase_t min, rt_ubase_t max);
183 rt_err_t rt_clk_set_min_rate(struct rt_clk *clk, rt_ubase_t rate);
184 rt_err_t rt_clk_set_max_rate(struct rt_clk *clk, rt_ubase_t rate);
185 rt_err_t rt_clk_set_rate(struct rt_clk *clk, rt_ubase_t rate);
186 rt_ubase_t rt_clk_get_rate(struct rt_clk *clk);
187
188 rt_err_t rt_clk_set_phase(struct rt_clk *clk, int degrees);
189 rt_base_t rt_clk_get_phase(struct rt_clk *clk);
190
191 rt_base_t rt_clk_round_rate(struct rt_clk *clk, rt_ubase_t rate);
192
193 struct rt_clk *rt_clk_get_parent(struct rt_clk *clk);
194
195 struct rt_clk_array *rt_clk_get_array(struct rt_device *dev);
196 struct rt_clk *rt_clk_get_by_index(struct rt_device *dev, int index);
197 struct rt_clk *rt_clk_get_by_name(struct rt_device *dev, const char *name);
198 void rt_clk_array_put(struct rt_clk_array *clk_arr);
199 void rt_clk_put(struct rt_clk *clk);
200
201 #ifdef RT_USING_OFW
202 struct rt_clk_array *rt_ofw_get_clk_array(struct rt_ofw_node *np);
203 struct rt_clk *rt_ofw_get_clk(struct rt_ofw_node *np, int index);
204 struct rt_clk *rt_ofw_get_clk_by_name(struct rt_ofw_node *np, const char *name);
205 rt_ssize_t rt_ofw_count_of_clk(struct rt_ofw_node *clk_ofw_np);
206 #else
rt_ofw_get_clk(struct rt_ofw_node * np,int index)207 rt_inline struct rt_clk *rt_ofw_get_clk(struct rt_ofw_node *np, int index)
208 {
209 return RT_NULL;
210 }
rt_ofw_get_clk_by_name(struct rt_ofw_node * np,const char * name)211 rt_inline struct rt_clk *rt_ofw_get_clk_by_name(struct rt_ofw_node *np, const char *name)
212 {
213 return RT_NULL;
214 }
rt_ofw_count_of_clk(struct rt_ofw_node * clk_ofw_np)215 rt_inline rt_ssize_t rt_ofw_count_of_clk(struct rt_ofw_node *clk_ofw_np)
216 {
217 return 0;
218 }
219 #endif /* RT_USING_OFW */
220
221 /*! @}*/
222
223 #endif /* __CLK_H__ */