1 /* 2 * SPDX-FileCopyrightText: 2015-2023 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 GPIO 14 15 #pragma once 16 17 #include "soc/gpio_periph.h" 18 #include "soc/soc_caps.h" 19 #include "hal/gpio_ll.h" 20 #include "hal/gpio_types.h" 21 22 #ifdef __cplusplus 23 extern "C" { 24 #endif 25 26 // Get GPIO hardware instance with giving gpio num 27 #define GPIO_HAL_GET_HW(num) GPIO_LL_GET_HW(num) 28 29 /** 30 * Context that should be maintained by both the driver and the HAL 31 */ 32 33 typedef struct { 34 gpio_dev_t *dev; 35 } gpio_hal_context_t; 36 37 /** 38 * @brief Get the configuration for an IO 39 * 40 * @param hal Context of the HAL layer 41 * @param gpio_num GPIO number 42 * @param pu Pointer to accept the status of pull-up enabled or not 43 * @param pd Pointer to accept the status of pull-down enabled or not 44 * @param ie Pointer to accept the status of input enabled or not 45 * @param oe Pointer to accept the status of output enabled or not 46 * @param od Pointer to accept the status of open-drain enabled or not 47 * @param drv Pointer to accept the value of drive strength 48 * @param fun_sel Pointer to accept the value of IOMUX function selection 49 * @param sig_out Pointer to accept the index of outputting peripheral signal 50 * @param slp_sel Pointer to accept the status of pin sleep mode enabled or not 51 */ 52 #define gpio_hal_get_io_config(hal, gpio_num, pu, pd, ie, oe, od, drv, fun_sel, sig_out, slp_sel) \ 53 gpio_ll_get_io_config((hal)->dev, gpio_num, pu, pd, ie, oe, od, drv, fun_sel, sig_out, slp_sel) 54 55 /** 56 * @brief Enable pull-up on GPIO. 57 * 58 * @param hal Context of the HAL layer 59 * @param gpio_num GPIO number 60 */ 61 #define gpio_hal_pullup_en(hal, gpio_num) gpio_ll_pullup_en((hal)->dev, gpio_num) 62 63 /** 64 * @brief Disable pull-up on GPIO. 65 * 66 * @param hal Context of the HAL layer 67 * @param gpio_num GPIO number 68 */ 69 #define gpio_hal_pullup_dis(hal, gpio_num) gpio_ll_pullup_dis((hal)->dev, gpio_num) 70 71 /** 72 * @brief Enable pull-down on GPIO. 73 * 74 * @param hal Context of the HAL layer 75 * @param gpio_num GPIO number 76 */ 77 #define gpio_hal_pulldown_en(hal, gpio_num) gpio_ll_pulldown_en((hal)->dev, gpio_num) 78 79 /** 80 * @brief Disable pull-down on GPIO. 81 * 82 * @param hal Context of the HAL layer 83 * @param gpio_num GPIO number 84 */ 85 #define gpio_hal_pulldown_dis(hal, gpio_num) gpio_ll_pulldown_dis((hal)->dev, gpio_num) 86 87 /** 88 * @brief GPIO set interrupt trigger type 89 * 90 * @param hal Context of the HAL layer 91 * @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); 92 * @param intr_type Interrupt type, select from gpio_int_type_t 93 */ 94 #define gpio_hal_set_intr_type(hal, gpio_num, intr_type) gpio_ll_set_intr_type((hal)->dev, gpio_num, intr_type) 95 96 /** 97 * @brief Get GPIO interrupt status 98 * 99 * @param hal Context of the HAL layer 100 * @param core_id interrupt core id 101 * @param status interrupt status 102 */ 103 #define gpio_hal_get_intr_status(hal, core_id, status) gpio_ll_get_intr_status((hal)->dev, core_id, status) 104 105 /** 106 * @brief Get GPIO interrupt status high 107 * 108 * @param hal Context of the HAL layer 109 * @param core_id interrupt core id 110 * @param status interrupt status high 111 */ 112 #define gpio_hal_get_intr_status_high(hal, core_id, status) gpio_ll_get_intr_status_high((hal)->dev, core_id, status) 113 114 /** 115 * @brief Clear GPIO interrupt status bit 116 * 117 * @param hal Context of the HAL layer 118 * @param gpio_num GPIO number. If you want to clear the interrupt status bit of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 119 */ 120 #define gpio_hal_clear_intr_status_bit(hal, gpio_num) (((gpio_num) < 32) ? gpio_ll_clear_intr_status((hal)->dev, 1 << gpio_num) \ 121 : gpio_ll_clear_intr_status_high((hal)->dev, 1 << (gpio_num - 32))) 122 123 /** 124 * @brief Enable GPIO module interrupt signal 125 * 126 * @param hal Context of the HAL layer 127 * @param gpio_num GPIO number. If you want to enable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 128 * @param core_id Interrupt enabled CPU to corresponding ID 129 */ 130 void gpio_hal_intr_enable_on_core(gpio_hal_context_t *hal, uint32_t gpio_num, uint32_t core_id); 131 132 /** 133 * @brief Disable GPIO module interrupt signal 134 * 135 * @param hal Context of the HAL layer 136 * @param gpio_num GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 137 */ 138 void gpio_hal_intr_disable(gpio_hal_context_t *hal, uint32_t gpio_num); 139 140 /** 141 * @brief Disable input mode on GPIO. 142 * 143 * @param hal Context of the HAL layer 144 * @param gpio_num GPIO number 145 */ 146 #define gpio_hal_input_disable(hal, gpio_num) gpio_ll_input_disable((hal)->dev, gpio_num) 147 148 /** 149 * @brief Enable input mode on GPIO. 150 * 151 * @param hal Context of the HAL layer 152 * @param gpio_num GPIO number 153 */ 154 #define gpio_hal_input_enable(hal, gpio_num) gpio_ll_input_enable((hal)->dev, gpio_num) 155 156 /** 157 * @brief Disable output mode on GPIO. 158 * 159 * @param hal Context of the HAL layer 160 * @param gpio_num GPIO number 161 */ 162 #define gpio_hal_output_disable(hal, gpio_num) gpio_ll_output_disable((hal)->dev, gpio_num) 163 164 /** 165 * @brief Enable output mode on GPIO. 166 * 167 * @param hal Context of the HAL layer 168 * @param gpio_num GPIO number 169 */ 170 #define gpio_hal_output_enable(hal, gpio_num) gpio_ll_output_enable((hal)->dev, gpio_num) 171 172 /** 173 * @brief Disable open-drain mode on GPIO. 174 * 175 * @param hal Context of the HAL layer 176 * @param gpio_num GPIO number 177 */ 178 #define gpio_hal_od_disable(hal, gpio_num) gpio_ll_od_disable((hal)->dev, gpio_num) 179 180 /** 181 * @brief Enable open-drain mode on GPIO. 182 * 183 * @param hal Context of the HAL layer 184 * @param gpio_num GPIO number 185 */ 186 #define gpio_hal_od_enable(hal, gpio_num) gpio_ll_od_enable((hal)->dev, gpio_num) 187 188 /** 189 * @brief Select a function for the pin in the IOMUX 190 * 191 * @param hal Context of the HAL layer 192 * @param gpio_num GPIO number 193 * @param func Function to assign to the pin 194 */ 195 #define gpio_hal_func_sel(hal, gpio_num, func) gpio_ll_func_sel((hal)->dev, gpio_num, func) 196 197 /** 198 * @brief Get the GPIO number that is routed to the input peripheral signal through GPIO matrix 199 * 200 * @param hal Context of the HAL layer 201 * @param in_sig_idx Peripheral signal index (tagged as input attribute) 202 * 203 * @return 204 * - -1 Signal bypassed GPIO matrix 205 * - Others GPIO number 206 */ 207 #define gpio_hal_get_in_signal_connected_io(hal, in_sig_idx) gpio_ll_get_in_signal_connected_io((hal)->dev, in_sig_idx) 208 209 /** 210 * @brief GPIO set output level 211 * 212 * @param hal Context of the HAL layer 213 * @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); 214 * @param level Output level. 0: low ; 1: high 215 */ 216 #define gpio_hal_set_level(hal, gpio_num, level) gpio_ll_set_level((hal)->dev, gpio_num, level) 217 218 /** 219 * @brief GPIO get input level 220 * 221 * @warning If the pad is not configured for input (or input and output) the returned value is always 0. 222 * 223 * @param hal Context of the HAL layer 224 * @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); 225 * 226 * @return 227 * - 0 the GPIO input level is 0 228 * - 1 the GPIO input level is 1 229 */ 230 #define gpio_hal_get_level(hal, gpio_num) gpio_ll_get_level((hal)->dev, gpio_num) 231 232 /** 233 * @brief Enable GPIO wake-up function. 234 * 235 * @param hal Context of the HAL layer 236 * @param gpio_num GPIO number. 237 */ 238 #define gpio_hal_wakeup_enable(hal, gpio_num) gpio_ll_wakeup_enable((hal)->dev, gpio_num) 239 240 /** 241 * @brief Disable GPIO wake-up function. 242 * 243 * @param hal Context of the HAL layer 244 * @param gpio_num GPIO number 245 */ 246 #define gpio_hal_wakeup_disable(hal, gpio_num) gpio_ll_wakeup_disable((hal)->dev, gpio_num) 247 248 /** 249 * @brief Set GPIO pad drive capability 250 * 251 * @param hal Context of the HAL layer 252 * @param gpio_num GPIO number, only support output GPIOs 253 * @param strength Drive capability of the pad 254 */ 255 #define gpio_hal_set_drive_capability(hal, gpio_num, strength) gpio_ll_set_drive_capability((hal)->dev, gpio_num, strength) 256 257 /** 258 * @brief Get GPIO pad drive capability 259 * 260 * @param hal Context of the HAL layer 261 * @param gpio_num GPIO number, only support output GPIOs 262 * @param strength Pointer to accept drive capability of the pad 263 */ 264 #define gpio_hal_get_drive_capability(hal, gpio_num, strength) gpio_ll_get_drive_capability((hal)->dev, gpio_num, strength) 265 266 /** 267 * @brief Enable gpio pad hold function. 268 * 269 * The gpio pad hold function works in both input and output modes, but must be output-capable gpios. 270 * If pad hold enabled: 271 * in output mode: the output level of the pad will be force locked and can not be changed. 272 * in input mode: the input value read will not change, regardless the changes of input signal. 273 * 274 * On ESP32/S2/C3/S3/C2, the state of digital gpio cannot be held during Deep-sleep, and it will resume the hold 275 * function when the chip wakes up from Deep-sleep. If the digital gpio also needs to be held during Deep-sleep, 276 * `gpio_deep_sleep_hold_en` should also be called. 277 * 278 * Power down or call gpio_hold_dis will disable this function. 279 * 280 * @param hal Context of the HAL layer 281 * @param gpio_num GPIO number, only support output GPIOs 282 */ 283 #define gpio_hal_hold_en(hal, gpio_num) gpio_ll_hold_en((hal)->dev, gpio_num) 284 285 /** 286 * @brief Disable gpio pad hold function. 287 * 288 * When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output 289 * the default level if this function is called. If you don't want the level changes, the gpio should be configured to 290 * a known state before this function is called. 291 * e.g. 292 * If you hold gpio18 high during Deep-sleep, after the chip is woken up and `gpio_hold_dis` is called, 293 * gpio18 will output low level(because gpio18 is input mode by default). If you don't want this behavior, 294 * you should configure gpio18 as output mode and set it to hight level before calling `gpio_hold_dis`. 295 * 296 * @param hal Context of the HAL layer 297 * @param gpio_num GPIO number, only support output GPIOs 298 */ 299 #define gpio_hal_hold_dis(hal, gpio_num) gpio_ll_hold_dis((hal)->dev, gpio_num) 300 301 /** 302 * @brief Get wether digital gpio pad is held 303 * 304 * @param hal Context of the HAL layer 305 * @param gpio_num GPIO number, only support output GPIOs 306 * 307 * @note digital io means io pad powered by VDD3P3_CPU or VDD_SPI 308 * rtc io means io pad powered by VDD3P3_RTC 309 * caller must ensure that gpio_num is a digital io pad 310 * 311 * @return 312 * - true digital gpio pad is held 313 * - false digital gpio pad is unheld 314 */ 315 #define gpio_hal_is_digital_io_hold(hal, gpio_num) gpio_ll_is_digital_io_hold((hal)->dev, gpio_num) 316 317 #if !SOC_GPIO_SUPPORT_HOLD_SINGLE_IO_IN_DSLP 318 /** 319 * @brief Enable all digital gpio pad hold function during Deep-sleep. 320 * 321 * When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is woken up, 322 * 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, 323 * when not in sleep mode, the digital gpio state can be changed even you have called this function. 324 * 325 * 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. 326 * 327 * @param hal Context of the HAL layer 328 */ 329 #define gpio_hal_deep_sleep_hold_en(hal) gpio_ll_deep_sleep_hold_en((hal)->dev) 330 331 /** 332 * @brief Disable all digital gpio pad hold function during Deep-sleep. 333 * 334 * @param hal Context of the HAL layer 335 */ 336 #define gpio_hal_deep_sleep_hold_dis(hal) gpio_ll_deep_sleep_hold_dis((hal)->dev) 337 338 /** 339 * @brief Get whether all digital gpio pad hold function during Deep-sleep is enabled. 340 * 341 * @param hal Context of the HAL layer 342 * 343 * @return 344 * - true deep sleep hold is enabled 345 * - false deep sleep hold is disabled 346 */ 347 #define gpio_hal_deep_sleep_hold_is_en(hal) gpio_ll_deep_sleep_hold_is_en((hal)->dev) 348 #endif //!SOC_GPIO_SUPPORT_HOLD_SINGLE_IO_IN_DSLP 349 350 /** 351 * @brief Set pad input to a peripheral signal through the IOMUX. 352 * 353 * @param hal Context of the HAL layer 354 * @param gpio_num GPIO number of the pad. 355 * @param signal_idx Peripheral signal id to input. One of the ``*_IN_IDX`` signals in ``soc/gpio_sig_map.h``. 356 */ 357 #define gpio_hal_iomux_in(hal, gpio_num, signal_idx) gpio_ll_iomux_in((hal)->dev, gpio_num, signal_idx) 358 359 /** 360 * @brief Set peripheral output to an GPIO pad through the IOMUX. 361 * 362 * @param hal Context of the HAL layer 363 * @param gpio_num gpio_num GPIO number of the pad. 364 * @param func The function number of the peripheral pin to output pin. 365 * One of the ``FUNC_X_*`` of specified pin (X) in ``soc/io_mux_reg.h``. 366 * @param oen_inv True if the output enable needs to be inverted, otherwise False. 367 */ 368 #define gpio_hal_iomux_out(hal, gpio_num, func, oen_inv) gpio_ll_iomux_out((hal)->dev, gpio_num, func, oen_inv) 369 370 #if SOC_GPIO_SUPPORT_FORCE_HOLD 371 /** 372 * @brief Force hold all digital gpio pads (including those powered by VDD3P3_RTC power domain). 373 * @note GPIO force hold, whether the chip in sleep mode or wakeup mode. 374 */ 375 #define gpio_hal_force_hold_all() gpio_ll_force_hold_all() 376 377 /** 378 * @brief Force unhold all digital gpio pads (including those powered by VDD3P3_RTC power domain). 379 * @note GPIO force unhold, whether the chip in sleep mode or wakeup mode. 380 */ 381 #define gpio_hal_force_unhold_all() gpio_ll_force_unhold_all() 382 #endif 383 384 /** 385 * @brief Enable pull-up on GPIO when system sleep. 386 * 387 * @param hal Context of the HAL layer 388 * @param gpio_num GPIO number 389 */ 390 #define gpio_hal_sleep_pullup_en(hal, gpio_num) gpio_ll_sleep_pullup_en((hal)->dev, gpio_num) 391 392 /** 393 * @brief Disable pull-up on GPIO when system sleep. 394 * 395 * @param hal Context of the HAL layer 396 * @param gpio_num GPIO number 397 */ 398 #define gpio_hal_sleep_pullup_dis(hal, gpio_num) gpio_ll_sleep_pullup_dis((hal)->dev, gpio_num) 399 400 /** 401 * @brief Enable pull-down on GPIO when system sleep. 402 * 403 * @param hal Context of the HAL layer 404 * @param gpio_num GPIO number 405 */ 406 #define gpio_hal_sleep_pulldown_en(hal, gpio_num) gpio_ll_sleep_pulldown_en((hal)->dev, gpio_num) 407 408 /** 409 * @brief Disable pull-down on GPIO when system sleep. 410 * 411 * @param hal Context of the HAL layer 412 * @param gpio_num GPIO number 413 */ 414 #define gpio_hal_sleep_pulldown_dis(hal, gpio_num) gpio_ll_sleep_pulldown_dis((hal)->dev, gpio_num) 415 416 /** 417 * @brief Enable sleep select on GPIO. 418 * 419 * @param hal Context of the HAL layer 420 * @param gpio_num GPIO number 421 */ 422 #define gpio_hal_sleep_sel_en(hal, gpio_num) gpio_ll_sleep_sel_en((hal)->dev, gpio_num) 423 424 /** 425 * @brief Disable sleep select on GPIO. 426 * 427 * @param hal Context of the HAL layer 428 * @param gpio_num GPIO number 429 */ 430 #define gpio_hal_sleep_sel_dis(hal, gpio_num) gpio_ll_sleep_sel_dis((hal)->dev, gpio_num) 431 432 /** 433 * @brief Disable input mode on GPIO when system sleep. 434 * 435 * @param hal Context of the HAL layer 436 * @param gpio_num GPIO number 437 */ 438 #define gpio_hal_sleep_input_disable(hal, gpio_num) gpio_ll_sleep_input_disable((hal)->dev, gpio_num) 439 440 /** 441 * @brief Enable input mode on GPIO when system sleep. 442 * 443 * @param hal Context of the HAL layer 444 * @param gpio_num GPIO number 445 */ 446 #define gpio_hal_sleep_input_enable(hal, gpio_num) gpio_ll_sleep_input_enable((hal)->dev, gpio_num) 447 448 /** 449 * @brief Disable output mode on GPIO when system sleep. 450 * 451 * @param hal Context of the HAL layer 452 * @param gpio_num GPIO number 453 */ 454 #define gpio_hal_sleep_output_disable(hal, gpio_num) gpio_ll_sleep_output_disable((hal)->dev, gpio_num) 455 456 /** 457 * @brief Enable output mode on GPIO when system sleep. 458 * 459 * @param hal Context of the HAL layer 460 * @param gpio_num GPIO number 461 */ 462 #define gpio_hal_sleep_output_enable(hal, gpio_num) gpio_ll_sleep_output_enable((hal)->dev, gpio_num) 463 464 #if CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL 465 /** 466 * @brief Apply slp_pu/slp_pd configuration to fun_pu/fun_pd when system sleep. 467 * 468 * @param hal Context of the HAL layer 469 * @param gpio_num GPIO number. 470 */ 471 void gpio_hal_sleep_pupd_config_apply(gpio_hal_context_t *hal, uint32_t gpio_num); 472 473 /** 474 * @brief Restore fun_pu/fun_pd configuration when system wakeup. 475 * 476 * @param hal Context of the HAL layer 477 * @param gpio_num GPIO number. 478 */ 479 void gpio_hal_sleep_pupd_config_unapply(gpio_hal_context_t *hal, uint32_t gpio_num); 480 #endif // CONFIG_GPIO_ESP32_SUPPORT_SWITCH_SLP_PULL 481 482 #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP && (SOC_RTCIO_PIN_COUNT == 0) 483 /** 484 * @brief Enable GPIO deep-sleep wake-up function. 485 * 486 * @param hal Context of the HAL layer 487 * @param gpio_num GPIO number. 488 * @param intr_type GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used. 489 */ 490 #define gpio_hal_deepsleep_wakeup_enable(hal, gpio_num, intr_type) gpio_ll_deepsleep_wakeup_enable((hal)->dev, gpio_num, intr_type) 491 492 /** 493 * @brief Disable GPIO deep-sleep wake-up function. 494 * 495 * @param hal Context of the HAL layer 496 * @param gpio_num GPIO number 497 */ 498 #define gpio_hal_deepsleep_wakeup_disable(hal, gpio_num) gpio_ll_deepsleep_wakeup_disable((hal)->dev, gpio_num) 499 500 /** 501 * @brief Get the status of whether an IO is used for deep-sleep wake-up. 502 * 503 * @param hal Context of the HAL layer 504 * @param gpio_num GPIO number 505 * 506 * @return True if the pin is enabled to wake up from deep-sleep 507 */ 508 #define gpio_hal_deepsleep_wakeup_is_enabled(hal, gpio_num) gpio_ll_deepsleep_wakeup_is_enabled((hal)->dev, gpio_num) 509 #endif //SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP 510 511 /** 512 * @brief Select a function for the pin in the IOMUX 513 * 514 * @param pin_name Pin name to configure 515 * @param func Function to assign to the pin 516 */ 517 #define gpio_hal_iomux_func_sel(pin_name, func) gpio_ll_iomux_func_sel(pin_name, func) 518 519 #if SOC_GPIO_SUPPORT_PIN_HYS_FILTER 520 /** 521 * @brief Control gpio hysteresis enable/disable by software. 522 * 523 * @param hal Context of the HAL layer 524 * @param gpio_num GPIO number 525 * @param enable enable or disable the hysteresis 526 */ 527 void gpio_hal_hysteresis_soft_enable(gpio_hal_context_t *hal, uint32_t gpio_num, bool enable); 528 529 /** 530 * @brief Set gpio hysteresis enable/disable by efuse. 531 * 532 * @param hal Context of the HAL layer 533 * @param gpio_num GPIO number 534 */ 535 #define gpio_hal_hysteresis_from_efuse(hal, gpio_num) gpio_ll_pin_input_hysteresis_ctrl_sel_efuse((hal)->dev, gpio_num) 536 #endif // SOC_GPIO_SUPPORT_PIN_HYS_FILTER 537 538 #ifdef __cplusplus 539 } 540 #endif 541
