1 /*
2  * SPDX-FileCopyrightText: 2019-2022 Espressif Systems (Shanghai) CO LTD
3  *
4  * SPDX-License-Identifier: Apache-2.0
5  */
6 
7 /*******************************************************************************
8  * NOTICE
9  * The hal is not public api, don't use in application code.
10  * See readme.md in hal/include/hal/readme.md
11  ******************************************************************************/
12 
13 // The HAL layer for LEDC.
14 // There is no parameter check in the hal layer, so the caller must ensure the correctness of the parameters.
15 
16 #pragma once
17 
18 #include "hal/ledc_ll.h"
19 #include "hal/ledc_types.h"
20 #include "soc/soc_caps.h"
21 
22 /**
23  * Context that should be maintained by both the driver and the HAL
24  */
25 typedef struct {
26     ledc_dev_t *dev;
27     ledc_mode_t speed_mode;
28 } ledc_hal_context_t;
29 
30 /**
31  * @brief Set LEDC low speed timer clock
32  *
33  * @param hal Context of the HAL layer
34  * @param slow_clk_sel LEDC low speed timer clock source
35  *
36  * @return None
37  */
38 #define ledc_hal_set_slow_clk_sel(hal, slow_clk_sel)  ledc_ll_set_slow_clk_sel((hal)->dev, slow_clk_sel)
39 
40 /**
41  * @brief Get LEDC low speed timer clock
42  *
43  * @param hal Context of the HAL layer
44  * @param slow_clk_sel LEDC low speed timer clock source
45  *
46  * @return None
47  */
48 #define ledc_hal_get_slow_clk_sel(hal, slow_clk_sel)  ledc_ll_get_slow_clk_sel((hal)->dev, slow_clk_sel)
49 
50 /**
51  * @brief Update LEDC low speed timer
52  *
53  * @param hal Context of the HAL layer
54  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
55  *
56  * @return None
57  */
58 #define ledc_hal_ls_timer_update(hal, timer_sel)  ledc_ll_ls_timer_update((hal)->dev, (hal)->speed_mode, timer_sel)
59 
60 /**
61  * @brief Reset LEDC timer
62  *
63  * @param hal Context of the HAL layer
64  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
65  *
66  * @return None
67  */
68 #define ledc_hal_timer_rst(hal, timer_sel)  ledc_ll_timer_rst((hal)->dev, (hal)->speed_mode, timer_sel)
69 
70 /**
71  * @brief Pause LEDC timer
72  *
73  * @param hal Context of the HAL layer
74  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
75  *
76  * @return None
77  */
78 #define ledc_hal_timer_pause(hal, timer_sel)  ledc_ll_timer_pause((hal)->dev, (hal)->speed_mode, timer_sel)
79 
80 /**
81  * @brief Resume LEDC timer
82  *
83  * @param hal Context of the HAL layer
84  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
85  *
86  * @return None
87  */
88 #define ledc_hal_timer_resume(hal, timer_sel)  ledc_ll_timer_resume((hal)->dev, (hal)->speed_mode, timer_sel)
89 
90 /**
91  * @brief Set LEDC timer clock divider
92  *
93  * @param hal Context of the HAL layer
94  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
95  * @param clock_divider Timer clock divide value, the timer clock is divided from the selected clock source
96  *
97  * @return None
98  */
99 #define ledc_hal_set_clock_divider(hal, timer_sel, clock_divider)  ledc_ll_set_clock_divider((hal)->dev, (hal)->speed_mode, timer_sel, clock_divider)
100 
101 /**
102  * @brief Get LEDC timer clock divider
103  *
104  * @param hal Context of the HAL layer
105  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
106  * @param clock_divider Timer clock divide value, the timer clock is divided from the selected clock source
107  *
108  * @return None
109  */
110 #define ledc_hal_get_clock_divider(hal, timer_sel, clock_divider)  ledc_ll_get_clock_divider((hal)->dev, (hal)->speed_mode, timer_sel, clock_divider)
111 
112 /**
113  * @brief Set LEDC timer clock source
114  *
115  * @param hal Context of the HAL layer
116  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
117  * @param clk_src Timer clock source
118  *
119  * @return None
120  */
121 #define ledc_hal_set_clock_source(hal, timer_sel, clk_src)  ledc_ll_set_clock_source((hal)->dev, (hal)->speed_mode, timer_sel, clk_src)
122 
123 /**
124  * @brief Get LEDC timer clock source
125  *
126  * @param hal Context of the HAL layer
127  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
128  * @param clk_src Pointer to accept the timer clock source
129  *
130  * @return None
131  */
132 #define ledc_hal_get_clock_source(hal, timer_sel, clk_src)  ledc_ll_get_clock_source((hal)->dev, (hal)->speed_mode, timer_sel, clk_src)
133 
134 /**
135  * @brief Set LEDC duty resolution
136  *
137  * @param hal Context of the HAL layer
138  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
139  * @param duty_resolution Resolution of duty setting in number of bits. The range of duty values is [0, (2**duty_resolution)]
140  *
141  * @return None
142  */
143 #define ledc_hal_set_duty_resolution(hal, timer_sel, duty_resolution)  ledc_ll_set_duty_resolution((hal)->dev, (hal)->speed_mode, timer_sel, duty_resolution)
144 
145 /**
146  * @brief Get LEDC duty resolution
147  *
148  * @param hal Context of the HAL layer
149  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
150  * @param duty_resolution Pointer to accept the resolution of duty setting in number of bits.
151  *
152  * @return None
153  */
154 #define ledc_hal_get_duty_resolution(hal, timer_sel, duty_resolution)  ledc_ll_get_duty_resolution((hal)->dev, (hal)->speed_mode, timer_sel, duty_resolution)
155 
156 /**
157  * @brief Get LEDC max duty
158  *
159  * @param hal Context of the HAL layer
160  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
161  * @param max_duty Pointer to accept the max duty
162  *
163  * @return None
164  */
165 #define ledc_hal_get_max_duty(hal, channel_num, max_duty)  ledc_ll_get_max_duty((hal)->dev, (hal)->speed_mode, channel_num, max_duty)
166 
167 /**
168  * @brief Get LEDC hpoint value
169  *
170  * @param hal Context of the HAL layer
171  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
172  * @param hpoint_val Pointer to accept the LEDC hpoint value(max: 0xfffff)
173  *
174  * @return None
175  */
176 #define ledc_hal_get_hpoint(hal, channel_num, hpoint_val)  ledc_ll_get_hpoint((hal)->dev, (hal)->speed_mode, channel_num, hpoint_val)
177 
178 /**
179  * @brief Set the output enable
180  *
181  * @param hal Context of the HAL layer
182  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
183  * @param sig_out_en The output enable status
184  *
185  * @return None
186  */
187 #define ledc_hal_set_sig_out_en(hal, channel_num, sig_out_en)  ledc_ll_set_sig_out_en((hal)->dev, (hal)->speed_mode, channel_num, sig_out_en)
188 
189 /**
190  * @brief Set output idle level
191  *
192  * @param hal Context of the HAL layer
193  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
194  * @param idle_level The output idle level
195  *
196  * @return None
197  */
198 #define ledc_hal_set_idle_level(hal, channel_num, idle_level)  ledc_ll_set_idle_level((hal)->dev, (hal)->speed_mode, channel_num, idle_level)
199 
200 /**
201  * @brief Set fade end interrupt enable
202  *
203  * @param hal Context of the HAL layer
204  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
205  * @param fade_end_intr_en The fade end interrupt enable status
206  *
207  * @return None
208  */
209 #define ledc_hal_set_fade_end_intr(hal, channel_num, fade_end_intr_en)  ledc_ll_set_fade_end_intr((hal)->dev, (hal)->speed_mode, channel_num, fade_end_intr_en)
210 
211 /**
212  * @brief Set timer index of the specified channel
213  *
214  * @param hal Context of the HAL layer
215  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
216  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
217  *
218  * @return None
219  */
220 #define ledc_hal_bind_channel_timer(hal, channel_num, timer_sel)  ledc_ll_bind_channel_timer((hal)->dev, (hal)->speed_mode, channel_num, timer_sel)
221 
222 /**
223  * @brief Get timer index of the specified channel
224  *
225  * @param hal Context of the HAL layer
226  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
227  * @param timer_sel Pointer to accept the LEDC timer index
228  *
229  * @return None
230  */
231 #define ledc_hal_get_channel_timer(hal, channel_num, timer_sel)  ledc_ll_get_channel_timer((hal)->dev, (hal)->speed_mode, channel_num, timer_sel)
232 
233 /**
234  * @brief Init the LEDC hal. This function should be called first before other hal layer function is called
235  *
236  * @param hal Context of the HAL layer
237  * @param speed_mode speed_mode Select the LEDC speed_mode, high-speed mode and low-speed mod
238  *
239  * @return None
240  */
241 void ledc_hal_init(ledc_hal_context_t *hal, ledc_mode_t speed_mode);
242 
243 /**
244  * @brief Update channel configure when select low speed mode
245  *
246  * @param hal Context of the HAL layer
247  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
248  *
249  * @return None
250  */
251 void ledc_hal_ls_channel_update(ledc_hal_context_t *hal, ledc_channel_t channel_num);
252 
253 /**
254  * @brief Set the duty start
255  *
256  * @param hal Context of the HAL layer
257  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
258  * @param duty_start The duty start
259  *
260  * @return None
261  */
262 void ledc_hal_set_duty_start(ledc_hal_context_t *hal, ledc_channel_t channel_num, bool duty_start);
263 
264 /**
265  * @brief Set LEDC the integer part of duty value
266  *
267  * @param hal Context of the HAL layer
268  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
269  * @param duty_val LEDC duty value, the range of duty setting is [0, (2**duty_resolution)]
270  *
271  * @return None
272  */
273 void ledc_hal_set_duty_int_part(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t duty_val);
274 
275 /**
276  * @brief Set LEDC hpoint value
277  *
278  * @param hal Context of the HAL layer
279  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
280  * @param hpoint_val LEDC hpoint value(max: 0xfffff)
281  *
282  * @return None
283  */
284 void ledc_hal_set_hpoint(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t hpoint_val);
285 
286 /**
287  * @brief Get LEDC duty value
288  *
289  * @param hal Context of the HAL layer
290  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
291  * @param duty_val Pointer to accept the LEDC duty value
292  *
293  * @return None
294  */
295 void ledc_hal_get_duty(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t *duty_val);
296 
297 /**
298  * @brief Set LEDC duty change direction
299  *
300  * @param hal Context of the HAL layer
301  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
302  * @param duty_direction LEDC duty change direction, increase or decrease
303  *
304  * @return None
305  */
306 void ledc_hal_set_duty_direction(ledc_hal_context_t *hal, ledc_channel_t channel_num, ledc_duty_direction_t duty_direction);
307 
308 /**
309  * @brief Set the number of increased or decreased times
310  *
311  * @param hal Context of the HAL layer
312  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
313  * @param duty_num The number of increased or decreased times
314  *
315  * @return None
316  */
317 void ledc_hal_set_duty_num(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t duty_num);
318 
319 /**
320  * @brief Set the duty cycles of increase or decrease
321  *
322  * @param hal Context of the HAL layer
323  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
324  * @param duty_cycle The duty cycles
325  *
326  * @return None
327  */
328 void ledc_hal_set_duty_cycle(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t duty_cycle);
329 
330 /**
331  * @brief Set the step scale of increase or decrease
332  *
333  * @param hal Context of the HAL layer
334  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
335  * @param duty_scale The step scale
336  *
337  * @return None
338  */
339 void ledc_hal_set_duty_scale(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t duty_scale);
340 
341 #if SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED
342 /**
343  * @brief Set the range number of the specified duty configurations to be written from gamma_wr register to gamma ram
344  *
345  * @param hal Context of the HAL layer
346  * @param channel_num LEDC channel index, select from ledc_channel_t
347  * @param duty_range Range index (0 - (SOC_LEDC_GAMMA_CURVE_FADE_RANGE_MAX-1)), it specifies to which range in gamma ram to write
348  *
349  * @return None
350  */
351 void ledc_hal_set_duty_range_wr_addr(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t duty_range);
352 
353 /**
354  * @brief Set the total number of ranges in one fading
355  *
356  * @param hal Context of the HAL layer
357  * @param channel_num LEDC channel index, select from ledc_channel_t
358  * @param range_num Total number of ranges (1-16) of the fading configured
359  *
360  * @return None
361  */
362 void ledc_hal_set_range_number(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t range_num);
363 
364 /**
365  * @brief Get the total number of ranges in one fading
366  *
367  * @param hal Context of the HAL layer
368  * @param channel_num LEDC channel index, select from ledc_channel_t
369  * @param range_num Pointer to accept fade range number
370  *
371  * @return None
372  */
373 void ledc_hal_get_range_number(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t *range_num);
374 
375 /**
376  * @brief Read the fade parameters that are stored in gamma ram for a certain fade range
377  *
378  * @param hal Context of the HAL layer
379  * @param channel_num LEDC channel index, select from ledc_channel_t
380  * @param range Range index (0 - (SOC_LEDC_GAMMA_CURVE_FADE_RANGE_MAX-1)), it specifies to which range in gamma ram to read
381  * @param dir Pointer to accept fade direction value
382  * @param cycle Pointer to accept fade cycle value
383  * @param scale Pointer to accept fade scale value
384  * @param step Pointer to accept fade step value
385  *
386  * @return None
387  */
388 void ledc_hal_get_fade_param(ledc_hal_context_t *hal, ledc_channel_t channel_num, uint32_t range, uint32_t *dir, uint32_t *cycle, uint32_t *scale, uint32_t *step);
389 #endif //SOC_LEDC_GAMMA_CURVE_FADE_SUPPORTED
390 
391 /**
392  * @brief Get interrupt status of the specified channel
393  *
394  * @param hal Context of the HAL layer
395  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
396  * @param intr_status Pointer to accept the interrupt status
397  *
398  * @return None
399  */
400 void ledc_hal_get_fade_end_intr_status(ledc_hal_context_t *hal, uint32_t *intr_status);
401 
402 /**
403  * @brief Clear interrupt status of the specified channel
404  *
405  * @param hal Context of the HAL layer
406  * @param channel_num LEDC channel index (0-7), select from ledc_channel_t
407  *
408  * @return None
409  */
410 void ledc_hal_clear_fade_end_intr_status(ledc_hal_context_t *hal, ledc_channel_t channel_num);
411 
412 /**
413  * @brief Get clock config of LEDC timer
414  *
415  * @param hal Context of the HAL layer
416  * @param timer_sel LEDC timer index (0-3), select from ledc_timer_t
417  * @param clk_cfg Pointer to accept clock config
418  *
419  * @return None
420  */
421 void ledc_hal_get_clk_cfg(ledc_hal_context_t *hal, ledc_timer_t timer_sel, ledc_clk_cfg_t *clk_cfg);
422