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 __SUNXI_HAL_CLK_H__
33 #define __SUNXI_HAL_CLK_H__
34 
35 
36 #include <stdio.h>
37 #include <string.h>
38 #include <sunxi_hal_common.h>
39 #include <common_ccmu.h>
40 #include <platform_ccmu.h>
41 
42 #define hal_clk_api_version "hal_clk_api_version_1_1_0"
43 
44 /************************************************************************************************
45 * Macro definition readl 、writel hal_read_xxx and hal_write_xxx
46 * @Description:  These definitions used to CCMU Drivers to read and write Physical I/O register
47 *************************************************************************************************/
48 #define hal_write_reg8(addr ,data)     ((*(volatile u8 *)(addr)) = (u8)(data))
49 #define hal_write_reg16(addr ,data)     ((*(volatile u16 *)(addr)) = (u16)(data))
50 #define hal_write_reg32(addr ,data)     ((*(volatile u32 *)(addr)) = (u32)(data))
51 #define hal_read_reg8(x)                (*(volatile u8 *)(x))
52 #define hal_read_reg16(x)                (*(volatile u16 *)(x))
53 #define hal_read_reg32(x)                (*(volatile u32 *)(x))
54 
55 #undef readl
56 #undef writel
57 #define readl(x) hal_read_reg32(x)
58 #define writel(val, reg) hal_write_reg32(reg, val)
59 /************************************************************************************************
60 * Macro definition CCMU_XXX
61 * @Description: These definitions used to CCMU HAL-API and Drivers source code debug
62 *************************************************************************************************/
63 //#define CCMU_DBG_EN 1
64 
65 #if defined(CCMU_DBG_LEAVE_TINY) || defined(CCMU_DBG_LEAVE_HIGH)
66 #define CCMU_DBG(fmt,args...)       printf("[CCMU:dbg..] %-*s:%d "fmt ,30, __func__, __LINE__, ##args)
67 #define CCMU_ERR(fmt,args...)       printf("[CCMU:err**] %-*s:%d "fmt ,30, __func__, __LINE__, ##args)
68 #else
69 #define CCMU_DBG(fmt,args...)   do{} while(0)
70 #define CCMU_ERR(fmt,args...)   do{} while(0)
71 #endif
72 #if defined(CCMU_DBG_LEAVE_HIGH)
73 #define CCMU_TRACE()                printf("[CCMU:trace] %-*s:%d \n",30, __func__, __LINE__)
74 #define CCMU_TRACE_CLK(tpye, clk)   printf("CCMU:trace %s:%d CLK "#tpye" id %d\n",__func__, __LINE__, clk)
75 #else
76 #define CCMU_TRACE()            do{} while(0)
77 #define CCMU_TRACE_CLK(clk, rate)   do{} while(0)
78 #endif
79 
80 /************************************************************************************************
81 * @Function: hal_clock_init
82 * @Description: provide HAL API for initialize soc clocks during the system power-on startup phase
83 * @Parameters:
84 * # void: No parameters required
85 * @Return values:
86 * # HAL_CLK_STATUS_OK: soc clocks initialize successed
87 * # others : soc clocks initialization may have some abnormal problems
88 * @Attention: clock initialize timing depands on specific soc platform clock design
89 *************************************************************************************************/
90 void hal_clock_init(void);
91 
92 /************************************************************************************************
93 * @Function: hal_clock_init
94 * @Description: provide HAL API for initialize soc clocks during the system power-on startup phase
95 * @Parameters:
96 * # void: No parameters required
97 * @Return values:
98 * # HAL_CLK_STATUS_OK: soc clocks initialize successed
99 * # others : soc clocks initialization may have some abnormal problems
100 * @Attention: clock initialize timing depands on specific soc platform clock design
101 *************************************************************************************************/
102 hal_clk_t hal_clock_get(hal_clk_type_t type, hal_clk_id_t id);
103 
104 
105 hal_clk_status_t hal_clock_put(hal_clk_t clk);
106 
107 /************************************************************************************************
108 * @Function: hal_clock_is_enabled
109 * @Description: provide HAL API for bus-clk and periph-clk to get clock enabled statue
110 * @Parameters:
111 * # clk: clock-id of soc specific clock
112 * @Return values:
113 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
114 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
115 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
116 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
117 * # HAL_CLK_STATUS_ENABLED: clock current status is enabled
118 * # HAL_CLK_STATUS_DISABLED: clock current status is disabled
119 * @Attention: .etc
120 *************************************************************************************************/
121 hal_clk_status_t hal_clock_is_enabled(hal_clk_t clk);
122 
123 /************************************************************************************************
124 * @Function: hal_clock_enable
125 * @Description: provide HAL API for bus-clk and periph-clk to enable clock
126 * @Parameters:
127 * # clk: clock-id of soc specific clock
128 * @Return values:
129 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
130 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
131 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
132 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
133 * # HAL_CLK_STATUS_ENABLED: clock current status is enabled
134 * # HAL_CLK_STATUS_DISABLED: clock current status is disabled
135 * @Attention: .etc
136 *************************************************************************************************/
137 hal_clk_status_t hal_clock_enable(hal_clk_t clk);
138 
139 
140 /************************************************************************************************
141 * @Function: hal_clock_disable
142 * @Description: provide HAL API for bus-clk and periph-clk to disable clock
143 * @Parameters:
144 * # clk: clock-id of soc specific clock
145 * @Return values:
146 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
147 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
148 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
149 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
150 * # HAL_CLK_STATUS_OK: clock current status disabled successed
151 * @Attention: .etc
152 *************************************************************************************************/
153 hal_clk_status_t hal_clock_disable(hal_clk_t clk);
154 
155 
156 /************************************************************************************************
157 * @Function: hal_clk_recalc_rate
158 * @Description: provide HAL API for factor-clk, bus-clk and periph-clk to recalculate current Runtime rate
159 * @Parameters:
160 * # clk: clock-id of soc specific clock
161 * @Return values:
162 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal
163 * # HAL_CLK_RATE_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver or clock disbaled
164 * # others: return current clock rate successed
165 * @Attention: .etc
166 *************************************************************************************************/
167 u32 hal_clk_recalc_rate(hal_clk_t clk);
168 
169 
170 /************************************************************************************************
171 * @Function: hal_clk_round_rate
172 * @Description: provide HAL API for factor-clk, bus-clk and periph-clk round target rate to the most suitable rate
173 * @Parameters:
174 * # clk: clock-id of soc specific clock
175 * # rate: the target rate form API-User
176 * @Return values:
177 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
178 * # HAL_CLK_RATE_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver or clock disbaled
179 * # others: return round rate successed
180 * @Attention: .etc
181 *************************************************************************************************/
182 u32 hal_clk_round_rate(hal_clk_t clk, u32 rate);
183 
184 
185 /************************************************************************************************
186 * @Function: hal_clk_get_rate
187 * @Description: provide HAL API for factor-clk, bus-clk and periph-clk get current rate cached witch may not current Runtime rate
188 * @Parameters:
189 * # clk: clock-id of soc specific clock
190 * @Return values:
191 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
192 * # HAL_CLK_RATE_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver or clock disbaled
193 * # others: return rate cached successed
194 * @Attention: .etc
195 *************************************************************************************************/
196 u32  hal_clk_get_rate(hal_clk_t clk);
197 
198 
199 /************************************************************************************************
200 * @Function: hal_clk_set_rate
201 * @Description: provide HAL API for bus-clk and periph-clk to set new rate
202 * @Parameters:
203 * # clk: clock-id of soc specific clock
204 * # rate: the new rate value
205 * @Return values:
206 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal ot rate value is invalid
207 * # HAL_CLK_STATUS_ERROR_CLK_SET_RATE_REFUSED: fixed-clk and factor clk not allowed User to change rate because of stability
208 * # HAL_CLK_STATUS_ERROT_CLK_UNDEFINED: input parameter of clock-id defined in hal but not defined by soc clock driver
209 * # HAL_CLK_STATUS_ERROR_CLK_NOT_FOUND: input parameter of clock-id defined in hal but not defined by soc clock driver
210 * # HAL_CLK_STATUS_OK: set new rate successed
211 * @Attention: .etc
212 *************************************************************************************************/
213 hal_clk_status_t hal_clk_set_rate(hal_clk_t clk,  u32 rate);
214 
215 
216 /************************************************************************************************
217 * @Function: hal_clk_set_parent
218 * @Description: provide HAL API for factor-clk, bus-clk and periph-clk to select parent clock
219 * @Parameters:
220 * # clk: clock-id of soc specific clock witch nedds to adjust parent clock
221 * # parent: clock-id of soc specific clock's parent clock
222 * @Return values:
223 * # HAL_CLK_STATUS_OK: soc specific clock select and siwtch parent clock successed
224 * # others : soc specific clock select and siwtch parent clock may have some abnormal problems
225 * @Attention: soc specific clock and parent clock must be according to the SOC_User_Manual definition
226 *************************************************************************************************/
227 hal_clk_status_t hal_clk_set_parent(hal_clk_t clk, hal_clk_t parent);
228 
229 
230 /************************************************************************************************
231 * @Function: hal_clk_get_parent
232 * @Description: provide HAL API for factor-clk, bus-clk and periph-clk to get current parent clock
233 * @Parameters:
234 * # clk: clock-id of soc specific clock
235 * @Return values:
236 * # HAL_CLK_STATUS_INVALID_PARAMETER: input parameter of clock-id undefined in hal
237 * # HAL_CLK_UNINITIALIZED : input parameter of clock-id defined in hal but not defined by soc clock driver
238 * # others: return current parent clock-id successed
239 * @Attention: soc specific clock and parent clock must be according to the SOC_User_Manual definition
240 *************************************************************************************************/
241 hal_clk_t hal_clk_get_parent(hal_clk_t clk);
242 
243 
244 #endif /* __HAL_CLOCK_H__ */
245 
246