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