1 /* Copyright (c) 2019-2025 Allwinner Technology Co., Ltd. ALL rights reserved.
2  *
3  * Allwinner is a trademark of Allwinner Technology Co.,Ltd., registered in
4  *the the People's Republic of China and other countries.
5  * All Allwinner Technology Co.,Ltd. trademarks are used with permission.
6  *
7  * DISCLAIMER
8  * THIRD PARTY LICENCES MAY BE REQUIRED TO IMPLEMENT THE SOLUTION/PRODUCT.
9  * IF YOU NEED TO INTEGRATE THIRD PARTY’S TECHNOLOGY (SONY, DTS, DOLBY, AVS OR MPEGLA, ETC.)
10  * IN ALLWINNERS’SDK OR PRODUCTS, YOU SHALL BE SOLELY RESPONSIBLE TO OBTAIN
11  * ALL APPROPRIATELY REQUIRED THIRD PARTY LICENCES.
12  * ALLWINNER SHALL HAVE NO WARRANTY, INDEMNITY OR OTHER OBLIGATIONS WITH RESPECT TO MATTERS
13  * COVERED UNDER ANY REQUIRED THIRD PARTY LICENSE.
14  * YOU ARE SOLELY RESPONSIBLE FOR YOUR USAGE OF THIRD PARTY’S TECHNOLOGY.
15  *
16  *
17  * THIS SOFTWARE IS PROVIDED BY ALLWINNER"AS IS" AND TO THE MAXIMUM EXTENT
18  * PERMITTED BY LAW, ALLWINNER EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND,
19  * WHETHER EXPRESS, IMPLIED OR STATUTORY, INCLUDING WITHOUT LIMITATION REGARDING
20  * THE TITLE, NON-INFRINGEMENT, ACCURACY, CONDITION, COMPLETENESS, PERFORMANCE
21  * OR MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
22  * IN NO EVENT SHALL ALLWINNER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
23  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
25  * LOSS OF USE, DATA, OR PROFITS, OR BUSINESS INTERRUPTION)
26  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27  * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
29  * OF THE POSSIBILITY OF SUCH DAMAGE.
30  */
31 
32 #ifndef __CLK_H__
33 #define __CLK_H__
34 
35 #include "ccu.h"
36 #include "../common_ccmu.h"
37 
38 /************************************************************************************************
39 * @Function: clk_init
40 * @Description: implement for initialize soc clocks during the system power-on startup phase
41 * @Parameters:
42 * # void: No parameters required
43 * @Return values:
44 * # HAL_CLK_STATUS_OK: soc clocks initialize successed
45 * # others : soc clocks initialization may have some abnormal problems
46 * @Attention: clock initialize timing depands on specific soc platform clock design
47 *************************************************************************************************/
48 
49 hal_clk_status_t clk_init(void);
50 
51 struct clk *clk_get(hal_clk_type_t type, hal_clk_id_t id);
52 
53 hal_clk_status_t clk_put(struct clk *clk);
54 
55 /************************************************************************************************
56 * @Function: clk_get_rate
57 * @Description: implement for factor-clk, bus-clk and periph-clk get current rate cached witch may not current Runtime rate
58 * @Parameters:
59 * # clk: clock-id of soc specific clock
60 * @Return values:
61 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
62 * # HAL_CLK_RATE_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver or clock disbaled
63 * # others: return rate cached successed
64 * @Attention: .etc
65 *************************************************************************************************/
66 hal_clk_status_t clk_get_rate(struct clk *clk, u32 *rate);
67 
68 /************************************************************************************************
69 * @Function: clk_set_rate
70 * @Description: implement for bus-clk and periph-clk to set new rate
71 * @Parameters:
72 * # clk: clock-id of soc specific clock
73 * # rate: the new rate value
74 * @Return values:
75 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
76 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
77 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
78 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
79 * # HAL_CLK_STATUS_OK: set new rate successed
80 * @Attention: .etc
81 *************************************************************************************************/
82 hal_clk_status_t clk_set_rate(struct clk *clk, u32 rate);
83 
84 
85 /************************************************************************************************
86 * @Function: clk_recalc_rate
87 * @Description: implement for factor-clk, bus-clk and periph-clk to recalculate current Runtime rate
88 * @Parameters:
89 * # clk: clock-id of soc specific clock
90 * @Return values:
91 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal
92 * # HAL_CLK_RATE_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver or clock disbaled
93 * # others: return current clock rate successed
94 * @Attention: .etc
95 *************************************************************************************************/
96 hal_clk_status_t clk_recalc_rate(struct clk *clk, u32 *prate);
97 
98 
99 /************************************************************************************************
100 * @Function: clk_round_rate
101 * @Description: implement for for factor-clk, bus-clk and periph-clk round target rate to the most suitable rate
102 * @Parameters:
103 * # clk: clock-id of soc specific clock
104 * # rate: the target rate form API-User
105 * @Return values:
106 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
107 * # HAL_CLK_RATE_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver or clock disbaled
108 * # others: return round rate successed
109 * @Attention: .etc
110 *************************************************************************************************/
111 hal_clk_status_t clk_round_rate(struct clk *clk, u32 rate, u32 *prate);
112 
113 /************************************************************************************************
114 * @Function: clk_is_enabled
115 * @Description: implement for bus-clk and periph-clk to get clock enabled statue
116 * @Parameters:
117 * # clk: clock-id of soc specific clock
118 * @Return values:
119 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
120 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
121 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
122 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
123 * # HAL_CLK_STATUS_ENABLED: clock current status is enabled
124 * # HAL_CLK_STATUS_DISABLED: clock current status is disabled
125 * @Attention: .etc
126 *************************************************************************************************/
127 hal_clk_status_t clk_is_enabled(struct clk *clk);
128 
129 
130 /************************************************************************************************
131 * @Function: clk_prepare_enable
132 * @Description: implement for bus-clk and periph-clk to enable clock
133 * @Parameters:
134 * # clk: clock-id of soc specific clock
135 * @Return values:
136 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
137 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
138 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
139 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
140 * # HAL_CLK_STATUS_ENABLED: clock current status is enabled
141 * # HAL_CLK_STATUS_DISABLED: clock current status is disabled
142 * @Attention: .etc
143 *************************************************************************************************/
144 hal_clk_status_t clk_prepare_enable(struct clk *clk);
145 
146 /************************************************************************************************
147 * @Function: clk_disable_unprepare
148 * @Description: implement for bus-clk and periph-clk to disable clock
149 * @Parameters:
150 * # clk: clock-id of soc specific clock
151 * @Return values:
152 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
153 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
154 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
155 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
156 * # HAL_CLK_STATUS_OK: clock current status disabled successed
157 * @Attention: .etc
158 *************************************************************************************************/
159 hal_clk_status_t clk_disable_unprepare(struct clk *clk);
160 
161 /************************************************************************************************
162 * @Function: clk_get_parent
163 * @Description: implement for factor-clk, bus-clk and periph-clk to select parent clock
164 * @Parameters:
165 * # clk: clock-id of soc specific clock witch nedds to adjust parent clock
166 * # parent: clock-id of soc specific clock's parent clock
167 * @Return values:
168 * # HAL_CLK_STATUS_OK: soc specific clock select and siwtch parent clock successed
169 * # others : soc specific clock select and siwtch parent clock may have some abnormal problems
170 * @Attention: soc specific clock and parent clock must be according to the SOC_User_Manual definition
171 *************************************************************************************************/
172 struct clk  *clk_get_parent(struct clk *clk);
173 
174 /************************************************************************************************
175 * @Function: clk_set_parent
176 * @Description: implement for factor-clk, bus-clk and periph-clk to select parent clock
177 * @Parameters:
178 * # clk: clock-id of soc specific clock witch nedds to adjust parent clock
179 * # parent: clock-id of soc specific clock's parent clock
180 * @Return values:
181 * # HAL_CLK_STATUS_OK: soc specific clock select and siwtch parent clock successed
182 * # others : soc specific clock select and siwtch parent clock may have some abnormal problems
183 * @Attention: soc specific clock and parent clock must be according to the SOC_User_Manual definition
184 *************************************************************************************************/
185 
186 hal_clk_status_t clk_set_parent(struct clk *clk, struct clk *p_clk);
187 
188 #endif /* __HAL_CLOCK_H__ */
189 
190