1 // Copyright 2015-2019 Espressif Systems (Shanghai) PTE LTD
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 //     http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 /*******************************************************************************
16  * NOTICE
17  * The hal is not public api, don't use in application code.
18  * See readme.md in hal/include/hal/readme.md
19  ******************************************************************************/
20 
21 // The HAL layer for GPIO
22 
23 #pragma once
24 
25 #include "soc/gpio_periph.h"
26 #include "soc/soc_caps.h"
27 #include "hal/gpio_ll.h"
28 #include "hal/gpio_types.h"
29 
30 #ifdef CONFIG_LEGACY_INCLUDE_COMMON_HEADERS
31 #include "soc/rtc_io_reg.h"
32 #endif
33 
34 #ifdef __cplusplus
35 extern "C" {
36 #endif
37 
38 // Get GPIO hardware instance with giving gpio num
39 #define GPIO_HAL_GET_HW(num) GPIO_LL_GET_HW(num)
40 
41 /**
42  * Context that should be maintained by both the driver and the HAL
43  */
44 
45 typedef struct {
46     gpio_dev_t *dev;
47     uint32_t version;
48 } gpio_hal_context_t;
49 
50 /**
51   * @brief Enable pull-up on GPIO.
52   *
53   * @param hal Context of the HAL layer
54   * @param gpio_num GPIO number
55   */
56 #define gpio_hal_pullup_en(hal, gpio_num) gpio_ll_pullup_en((hal)->dev, gpio_num)
57 
58 /**
59   * @brief Disable pull-up on GPIO.
60   *
61   * @param hal Context of the HAL layer
62   * @param gpio_num GPIO number
63   */
64 #define gpio_hal_pullup_dis(hal, gpio_num) gpio_ll_pullup_dis((hal)->dev, gpio_num)
65 
66 /**
67   * @brief Enable pull-down on GPIO.
68   *
69   * @param hal Context of the HAL layer
70   * @param gpio_num GPIO number
71   */
72 #define gpio_hal_pulldown_en(hal, gpio_num) gpio_ll_pulldown_en((hal)->dev, gpio_num)
73 
74 /**
75   * @brief Disable pull-down on GPIO.
76   *
77   * @param hal Context of the HAL layer
78   * @param gpio_num GPIO number
79   */
80 #define gpio_hal_pulldown_dis(hal, gpio_num) gpio_ll_pulldown_dis((hal)->dev, gpio_num)
81 
82 /**
83  * @brief  GPIO set interrupt trigger type
84  *
85  * @param  hal Context of the HAL layer
86  * @param  gpio_num GPIO number. If you want to set the trigger type of e.g. of GPIO16, gpio_num should be GPIO_NUM_16 (16);
87  * @param  intr_type Interrupt type, select from gpio_int_type_t
88  */
89 #define gpio_hal_set_intr_type(hal, gpio_num, intr_type) gpio_ll_set_intr_type((hal)->dev, gpio_num, intr_type)
90 
91 /**
92   * @brief Get GPIO interrupt status
93   *
94   * @param hal Context of the HAL layer
95   * @param core_id interrupt core id
96   * @param status interrupt status
97   */
98 #define gpio_hal_get_intr_status(hal, core_id, status) gpio_ll_get_intr_status((hal)->dev, core_id, status)
99 
100 /**
101   * @brief Get GPIO interrupt status high
102   *
103   * @param hal Context of the HAL layer
104   * @param core_id interrupt core id
105   * @param status interrupt status high
106   */
107 #define gpio_hal_get_intr_status_high(hal, core_id, status) gpio_ll_get_intr_status_high((hal)->dev, core_id, status)
108 
109 /**
110   * @brief Clear GPIO interrupt status
111   *
112   * @param hal Context of the HAL layer
113   * @param mask interrupt status clear mask
114   */
115 #define gpio_hal_clear_intr_status(hal, mask) gpio_ll_clear_intr_status((hal)->dev, mask)
116 
117 /**
118   * @brief Clear GPIO interrupt status high
119   *
120   * @param hal Context of the HAL layer
121   * @param mask interrupt status high clear mask
122   */
123 #define gpio_hal_clear_intr_status_high(hal, mask) gpio_ll_clear_intr_status_high((hal)->dev, mask)
124 
125 /**
126  * @brief  Enable GPIO module interrupt signal
127  *
128  * @param  hal Context of the HAL layer
129  * @param  gpio_num GPIO number. If you want to enable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
130  * @param  core_id Interrupt enabled CPU to corresponding ID
131  */
132 void gpio_hal_intr_enable_on_core(gpio_hal_context_t *hal, gpio_num_t gpio_num, uint32_t core_id);
133 
134 /**
135  * @brief  Disable GPIO module interrupt signal
136  *
137  * @param  hal Context of the HAL layer
138  * @param  gpio_num GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
139  */
140 void gpio_hal_intr_disable(gpio_hal_context_t *hal, gpio_num_t gpio_num);
141 
142 /**
143   * @brief Disable input mode on GPIO.
144   *
145   * @param hal Context of the HAL layer
146   * @param gpio_num GPIO number
147   */
148 #define gpio_hal_input_disable(hal, gpio_num) gpio_ll_input_disable((hal)->dev, gpio_num)
149 
150 /**
151   * @brief Enable input mode on GPIO.
152   *
153   * @param hal Context of the HAL layer
154   * @param gpio_num GPIO number
155   */
156 #define gpio_hal_input_enable(hal, gpio_num) gpio_ll_input_enable((hal)->dev, gpio_num)
157 
158 /**
159   * @brief Disable output mode on GPIO.
160   *
161   * @param hal Context of the HAL layer
162   * @param gpio_num GPIO number
163   */
164 #define gpio_hal_output_disable(hal, gpio_num) gpio_ll_output_disable((hal)->dev, gpio_num)
165 
166 /**
167   * @brief Enable output mode on GPIO.
168   *
169   * @param hal Context of the HAL layer
170   * @param gpio_num GPIO number
171   */
172 #define gpio_hal_output_enable(hal, gpio_num) gpio_ll_output_enable((hal)->dev, gpio_num)
173 
174 /**
175   * @brief Disable open-drain mode on GPIO.
176   *
177   * @param hal Context of the HAL layer
178   * @param gpio_num GPIO number
179   */
180 #define gpio_hal_od_disable(hal, gpio_num) gpio_ll_od_disable((hal)->dev, gpio_num)
181 
182 /**
183   * @brief Enable open-drain mode on GPIO.
184   *
185   * @param hal Context of the HAL layer
186   * @param gpio_num GPIO number
187   */
188 #define gpio_hal_od_enable(hal, gpio_num) gpio_ll_od_enable((hal)->dev, gpio_num)
189 
190 /**
191  * @brief  GPIO set output level
192  *
193  * @param  hal Context of the HAL layer
194  * @param  gpio_num GPIO number. If you want to set the output level of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
195  * @param  level Output level. 0: low ; 1: high
196  */
197 #define gpio_hal_set_level(hal, gpio_num, level) gpio_ll_set_level((hal)->dev, gpio_num, level)
198 
199 /**
200  * @brief  GPIO get input level
201  *
202  * @warning If the pad is not configured for input (or input and output) the returned value is always 0.
203  *
204  * @param  hal Context of the HAL layer
205  * @param  gpio_num GPIO number. If you want to get the logic level of e.g. pin GPIO16, gpio_num should be GPIO_NUM_16 (16);
206  *
207  * @return
208  *     - 0 the GPIO input level is 0
209  *     - 1 the GPIO input level is 1
210  */
211 #define gpio_hal_get_level(hal, gpio_num) gpio_ll_get_level((hal)->dev, gpio_num)
212 
213 /**
214  * @brief Enable GPIO wake-up function.
215  *
216  * @param hal Context of the HAL layer
217  * @param gpio_num GPIO number.
218  * @param intr_type GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used.
219  */
220 #define gpio_hal_wakeup_enable(hal, gpio_num, intr_type) gpio_ll_wakeup_enable((hal)->dev, gpio_num, intr_type)
221 
222 /**
223  * @brief Disable GPIO wake-up function.
224  *
225  * @param hal Context of the HAL layer
226  * @param gpio_num GPIO number
227  */
228 #define gpio_hal_wakeup_disable(hal, gpio_num) gpio_ll_wakeup_disable((hal)->dev, gpio_num)
229 
230 /**
231   * @brief Set GPIO pad drive capability
232   *
233   * @param hal Context of the HAL layer
234   * @param gpio_num GPIO number, only support output GPIOs
235   * @param strength Drive capability of the pad
236   */
237 #define gpio_hal_set_drive_capability(hal, gpio_num, strength) gpio_ll_set_drive_capability((hal)->dev, gpio_num, strength)
238 
239 /**
240   * @brief Get GPIO pad drive capability
241   *
242   * @param hal Context of the HAL layer
243   * @param gpio_num GPIO number, only support output GPIOs
244   * @param strength Pointer to accept drive capability of the pad
245   */
246 #define gpio_hal_get_drive_capability(hal, gpio_num, strength) gpio_ll_get_drive_capability((hal)->dev, gpio_num, strength)
247 
248 /**
249   * @brief Enable gpio pad hold function.
250   *
251   * The gpio pad hold function works in both input and output modes, but must be output-capable gpios.
252   * If pad hold enabled:
253   *   in output mode: the output level of the pad will be force locked and can not be changed.
254   *   in input mode: the input value read will not change, regardless the changes of input signal.
255   *
256   * The state of digital gpio cannot be held during Deep-sleep, and it will resume the hold function
257   * when the chip wakes up from Deep-sleep. If the digital gpio also needs to be held during Deep-sleep,
258   * `gpio_deep_sleep_hold_en` should also be called.
259   *
260   * Power down or call gpio_hold_dis will disable this function.
261   *
262   * @param hal Context of the HAL layer
263   * @param gpio_num GPIO number, only support output GPIOs
264   */
265 #define gpio_hal_hold_en(hal, gpio_num) gpio_ll_hold_en((hal)->dev, gpio_num)
266 
267 /**
268   * @brief Disable gpio pad hold function.
269   *
270   * When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output
271   * the default level if this function is called. If you don't want the level changes, the gpio should be configured to
272   * a known state before this function is called.
273   *  e.g.
274   *     If you hold gpio18 high during Deep-sleep, after the chip is woken up and `gpio_hold_dis` is called,
275   *     gpio18 will output low level(because gpio18 is input mode by default). If you don't want this behavior,
276   *     you should configure gpio18 as output mode and set it to hight level before calling `gpio_hold_dis`.
277   *
278   * @param hal Context of the HAL layer
279   * @param gpio_num GPIO number, only support output GPIOs
280   */
281 #define gpio_hal_hold_dis(hal, gpio_num) gpio_ll_hold_dis((hal)->dev, gpio_num)
282 
283 /**
284   * @brief Enable all digital gpio pad hold function during Deep-sleep.
285   *
286   * When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is woken up,
287   * the status of digital gpio will not be held. Note that the pad hold feature only works when the chip is in Deep-sleep mode,
288   * when not in sleep mode, the digital gpio state can be changed even you have called this function.
289   *
290   * Power down or call gpio_hold_dis will disable this function, otherwise, the digital gpio hold feature works as long as the chip enter Deep-sleep.
291   *
292   * @param hal Context of the HAL layer
293   */
294 #define gpio_hal_deep_sleep_hold_en(hal) gpio_ll_deep_sleep_hold_en((hal)->dev)
295 
296 /**
297   * @brief Disable all digital gpio pad hold function during Deep-sleep.
298   *
299   * @param hal Context of the HAL layer
300   */
301 #define gpio_hal_deep_sleep_hold_dis(hal) gpio_ll_deep_sleep_hold_dis((hal)->dev)
302 
303 /**
304   * @brief Set pad input to a peripheral signal through the IOMUX.
305   *
306   * @param hal Context of the HAL layer
307   * @param gpio_num GPIO number of the pad.
308   * @param signal_idx Peripheral signal id to input. One of the ``*_IN_IDX`` signals in ``soc/gpio_sig_map.h``.
309   */
310 #define gpio_hal_iomux_in(hal, gpio_num, signal_idx) gpio_ll_iomux_in((hal)->dev, gpio_num, signal_idx)
311 
312 /**
313   * @brief Set peripheral output to an GPIO pad through the IOMUX.
314   *
315   * @param hal Context of the HAL layer
316   * @param gpio_num gpio_num GPIO number of the pad.
317   * @param func The function number of the peripheral pin to output pin.
318   *        One of the ``FUNC_X_*`` of specified pin (X) in ``soc/io_mux_reg.h``.
319   * @param oen_inv True if the output enable needs to be inverted, otherwise False.
320   */
321 #define gpio_hal_iomux_out(hal, gpio_num, func, oen_inv) gpio_ll_iomux_out((hal)->dev, gpio_num, func, oen_inv)
322 
323 #if SOC_GPIO_SUPPORT_FORCE_HOLD
324 /**
325   * @brief Force hold digital and rtc gpio pad.
326   * @note GPIO force hold, whether the chip in sleep mode or wakeup mode.
327   *
328   * @param hal Context of the HAL layer
329   * */
330 #define gpio_hal_force_hold_all(hal) gpio_ll_force_hold_all((hal)->dev)
331 
332 /**
333   * @brief Force unhold digital and rtc gpio pad.
334   * @note GPIO force unhold, whether the chip in sleep mode or wakeup mode.
335   *
336   * @param hal Context of the HAL layer
337   * */
338 #define gpio_hal_force_unhold_all() gpio_ll_force_unhold_all()
339 #endif
340 
341 #if SOC_GPIO_SUPPORT_SLP_SWITCH
342 /**
343   * @brief Enable pull-up on GPIO when system sleep.
344   *
345   * @param hal Context of the HAL layer
346   * @param gpio_num GPIO number
347   */
348 #define gpio_hal_sleep_pullup_en(hal, gpio_num) gpio_ll_sleep_pullup_en((hal)->dev, gpio_num)
349 
350 /**
351   * @brief Disable pull-up on GPIO when system sleep.
352   *
353   * @param hal Context of the HAL layer
354   * @param gpio_num GPIO number
355   */
356 #define gpio_hal_sleep_pullup_dis(hal, gpio_num) gpio_ll_sleep_pullup_dis((hal)->dev, gpio_num)
357 
358 /**
359   * @brief Enable pull-down on GPIO when system sleep.
360   *
361   * @param hal Context of the HAL layer
362   * @param gpio_num GPIO number
363   */
364 #define gpio_hal_sleep_pulldown_en(hal, gpio_num) gpio_ll_sleep_pulldown_en((hal)->dev, gpio_num)
365 
366 /**
367   * @brief Disable pull-down on GPIO when system sleep.
368   *
369   * @param hal Context of the HAL layer
370   * @param gpio_num GPIO number
371   */
372 #define gpio_hal_sleep_pulldown_dis(hal, gpio_num) gpio_ll_sleep_pulldown_dis((hal)->dev, gpio_num)
373 
374 /**
375   * @brief Enable sleep select on GPIO.
376   *
377   * @param hal Context of the HAL layer
378   * @param gpio_num GPIO number
379   */
380 #define gpio_hal_sleep_sel_en(hal, gpio_num) gpio_ll_sleep_sel_en((hal)->dev, gpio_num)
381 
382 /**
383   * @brief Disable sleep select on GPIO.
384   *
385   * @param hal Context of the HAL layer
386   * @param gpio_num GPIO number
387   */
388 #define gpio_hal_sleep_sel_dis(hal, gpio_num) gpio_ll_sleep_sel_dis((hal)->dev, gpio_num)
389 
390 /**
391   * @brief Disable input mode on GPIO when system sleep.
392   *
393   * @param hal Context of the HAL layer
394   * @param gpio_num GPIO number
395   */
396 #define gpio_hal_sleep_input_disable(hal, gpio_num) gpio_ll_sleep_input_disable((hal)->dev, gpio_num)
397 
398 /**
399   * @brief Enable input mode on GPIO when system sleep.
400   *
401   * @param hal Context of the HAL layer
402   * @param gpio_num GPIO number
403   */
404 #define gpio_hal_sleep_input_enable(hal, gpio_num) gpio_ll_sleep_input_enable((hal)->dev, gpio_num)
405 
406 /**
407   * @brief Disable output mode on GPIO when system sleep.
408   *
409   * @param hal Context of the HAL layer
410   * @param gpio_num GPIO number
411   */
412 #define gpio_hal_sleep_output_disable(hal, gpio_num) gpio_ll_sleep_output_disable((hal)->dev, gpio_num)
413 
414 /**
415   * @brief Enable output mode on GPIO when system sleep.
416   *
417   * @param hal Context of the HAL layer
418   * @param gpio_num GPIO number
419   */
420 #define gpio_hal_sleep_output_enable(hal, gpio_num) gpio_ll_sleep_output_enable((hal)->dev, gpio_num)
421 
422 #if CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL
423 /**
424  * @brief  Apply slp_pu/slp_pd configuration to fun_pu/fun_pd when system sleep.
425  *
426  * @param  hal Context of the HAL layer
427  * @param  gpio_num GPIO number.
428  */
429 void gpio_hal_sleep_pupd_config_apply(gpio_hal_context_t *hal, gpio_num_t gpio_num);
430 
431 /**
432  * @brief  Restore fun_pu/fun_pd configuration when system wakeup.
433  *
434  * @param  hal Context of the HAL layer
435  * @param  gpio_num GPIO number.
436  */
437 void gpio_hal_sleep_pupd_config_unapply(gpio_hal_context_t *hal, gpio_num_t gpio_num);
438 #endif // CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL
439 #endif //SOC_GPIO_SUPPORT_SLP_SWITCH
440 
441 #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
442 
443 /**
444  * @brief Enable GPIO deep-sleep wake-up function.
445  *
446  * @param hal Context of the HAL layer
447  * @param gpio_num GPIO number.
448  * @param intr_type GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used.
449  */
450 #define gpio_hal_deepsleep_wakeup_enable(hal, gpio_num, intr_type) gpio_ll_deepsleep_wakeup_enable((hal)->dev, gpio_num, intr_type)
451 
452 /**
453  * @brief Disable GPIO deep-sleep wake-up function.
454  *
455  * @param hal Context of the HAL layer
456  * @param gpio_num GPIO number
457  */
458 #define gpio_hal_deepsleep_wakeup_disable(hal, gpio_num) gpio_ll_deepsleep_wakeup_disable((hal)->dev, gpio_num)
459 
460 /**
461  * @brief Judge if the gpio is valid for waking up chip from deep-sleep
462  *
463  * @param gpio_num GPIO number
464  */
465 #define gpio_hal_is_valid_deepsleep_wakeup_gpio(gpio_num) (gpio_num <= GPIO_NUM_5)
466 
467 #endif //SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP
468 
469 /**
470  * @brief  Select a function for the pin in the IOMUX
471  *
472  * @param  pin_name Pin name to configure
473  * @param  func Function to assign to the pin
474  */
475 #define gpio_hal_iomux_func_sel(pin_name, func) gpio_ll_iomux_func_sel(pin_name, func)
476 
477 #ifdef __cplusplus
478 }
479 #endif
480