1 /* 2 * SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include "sdkconfig.h" 10 #include "esp_err.h" 11 #include <stdbool.h> 12 #include "esp_intr_alloc.h" 13 #if !CONFIG_IDF_TARGET_LINUX 14 #include <esp_types.h> 15 #include <esp_bit_defs.h> 16 #include "esp_attr.h" 17 #include "soc/soc_caps.h" 18 #include "soc/gpio_periph.h" 19 #endif // !CONFIG_IDF_TARGET_LINUX 20 #include "hal/gpio_types.h" 21 22 // |================================= WARNING ====================================================== | 23 // | Including ROM header file in a PUBLIC API file will be REMOVED in the next major release (5.x). | 24 // | User should include "esp_rom_gpio.h" in their code if they have to use those ROM API. | 25 // |================================================================================================ | 26 #if CONFIG_IDF_TARGET_ESP32 27 #include "esp32/rom/gpio.h" 28 #elif CONFIG_IDF_TARGET_ESP32S2 29 #include "esp32s2/rom/gpio.h" 30 #elif CONFIG_IDF_TARGET_ESP32S3 31 #include "esp32s3/rom/gpio.h" 32 #elif CONFIG_IDF_TARGET_ESP32C3 33 #include "esp32c3/rom/gpio.h" 34 #elif CONFIG_IDF_TARGET_ESP32S3 35 #include "esp32s3/rom/gpio.h" 36 #elif CONFIG_IDF_TARGET_ESP32H2 37 #include "esp32h2/rom/gpio.h" 38 #endif 39 40 #ifdef CONFIG_LEGACY_INCLUDE_COMMON_HEADERS 41 #include "soc/rtc_io_reg.h" 42 #endif 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 #define GPIO_PIN_COUNT (SOC_GPIO_PIN_COUNT) 49 /// Check whether it is a valid GPIO number 50 #define GPIO_IS_VALID_GPIO(gpio_num) (((1ULL << (gpio_num)) & SOC_GPIO_VALID_GPIO_MASK) != 0) 51 /// Check whether it can be a valid GPIO number of output mode 52 #define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num) (((1ULL << (gpio_num)) & SOC_GPIO_VALID_OUTPUT_GPIO_MASK) != 0) 53 54 55 typedef intr_handle_t gpio_isr_handle_t; 56 57 /** 58 * @brief GPIO common configuration 59 * 60 * Configure GPIO's Mode,pull-up,PullDown,IntrType 61 * 62 * @param pGPIOConfig Pointer to GPIO configure struct 63 * 64 * @return 65 * - ESP_OK success 66 * - ESP_ERR_INVALID_ARG Parameter error 67 * 68 */ 69 esp_err_t gpio_config(const gpio_config_t *pGPIOConfig); 70 71 /** 72 * @brief Reset an gpio to default state (select gpio function, enable pullup and disable input and output). 73 * 74 * @param gpio_num GPIO number. 75 * 76 * @note This function also configures the IOMUX for this pin to the GPIO 77 * function, and disconnects any other peripheral output configured via GPIO 78 * Matrix. 79 * 80 * @return Always return ESP_OK. 81 */ 82 esp_err_t gpio_reset_pin(gpio_num_t gpio_num); 83 84 /** 85 * @brief GPIO set interrupt trigger type 86 * 87 * @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); 88 * @param intr_type Interrupt type, select from gpio_int_type_t 89 * 90 * @return 91 * - ESP_OK Success 92 * - ESP_ERR_INVALID_ARG Parameter error 93 * 94 */ 95 esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type); 96 97 /** 98 * @brief Enable GPIO module interrupt signal 99 * 100 * @note Please do not use the interrupt of GPIO36 and GPIO39 when using ADC or Wi-Fi with sleep mode enabled. 101 * Please refer to the comments of `adc1_get_raw`. 102 * Please refer to section 3.11 of 'ECO_and_Workarounds_for_Bugs_in_ESP32' for the description of this issue. 103 * As a workaround, call adc_power_acquire() in the app. This will result in higher power consumption (by ~1mA), 104 * but will remove the glitches on GPIO36 and GPIO39. 105 * 106 * @param gpio_num GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 107 * 108 * @return 109 * - ESP_OK Success 110 * - ESP_ERR_INVALID_ARG Parameter error 111 * 112 */ 113 esp_err_t gpio_intr_enable(gpio_num_t gpio_num); 114 115 /** 116 * @brief Disable GPIO module interrupt signal 117 * 118 * @param gpio_num GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 119 * 120 * @return 121 * - ESP_OK success 122 * - ESP_ERR_INVALID_ARG Parameter error 123 * 124 */ 125 esp_err_t gpio_intr_disable(gpio_num_t gpio_num); 126 127 /** 128 * @brief GPIO set output level 129 * 130 * @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); 131 * @param level Output level. 0: low ; 1: high 132 * 133 * @return 134 * - ESP_OK Success 135 * - ESP_ERR_INVALID_ARG GPIO number error 136 * 137 */ 138 esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level); 139 140 /** 141 * @brief GPIO get input level 142 * 143 * @warning If the pad is not configured for input (or input and output) the returned value is always 0. 144 * 145 * @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); 146 * 147 * @return 148 * - 0 the GPIO input level is 0 149 * - 1 the GPIO input level is 1 150 * 151 */ 152 int gpio_get_level(gpio_num_t gpio_num); 153 154 /** 155 * @brief GPIO set direction 156 * 157 * Configure GPIO direction,such as output_only,input_only,output_and_input 158 * 159 * @param gpio_num Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 160 * @param mode GPIO direction 161 * 162 * @return 163 * - ESP_OK Success 164 * - ESP_ERR_INVALID_ARG GPIO error 165 * 166 */ 167 esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode); 168 169 /** 170 * @brief Configure GPIO pull-up/pull-down resistors 171 * 172 * Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not. 173 * 174 * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 175 * @param pull GPIO pull up/down mode. 176 * 177 * @return 178 * - ESP_OK Success 179 * - ESP_ERR_INVALID_ARG : Parameter error 180 * 181 */ 182 esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull); 183 184 /** 185 * @brief Enable GPIO wake-up function. 186 * 187 * @param gpio_num GPIO number. 188 * 189 * @param intr_type GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used. 190 * 191 * @return 192 * - ESP_OK Success 193 * - ESP_ERR_INVALID_ARG Parameter error 194 */ 195 esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type); 196 197 #if defined(__ZEPHYR__) && defined(CONFIG_PM) 198 /* 199 * This interface is a wrapper around gpio_wakeup_enable, whose only purpose is to provide a consistent 200 * API naming convention to Zephyr users. 201 */ 202 esp_err_t esp_gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type); 203 #endif 204 205 /** 206 * @brief Disable GPIO wake-up function. 207 * 208 * @param gpio_num GPIO number 209 * 210 * @return 211 * - ESP_OK Success 212 * - ESP_ERR_INVALID_ARG Parameter error 213 */ 214 esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num); 215 216 /** 217 * @brief Register GPIO interrupt handler, the handler is an ISR. 218 * The handler will be attached to the same CPU core that this function is running on. 219 * 220 * This ISR function is called whenever any GPIO interrupt occurs. See 221 * the alternative gpio_install_isr_service() and 222 * gpio_isr_handler_add() API in order to have the driver support 223 * per-GPIO ISRs. 224 * 225 * @param fn Interrupt handler function. 226 * @param arg Parameter for handler function 227 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 228 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. 229 * @param handle Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here. 230 * 231 * \verbatim embed:rst:leading-asterisk 232 * To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api-reference/system/intr_alloc>`. 233 * \endverbatim 234 * 235 * @return 236 * - ESP_OK Success ; 237 * - ESP_ERR_INVALID_ARG GPIO error 238 * - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags 239 */ 240 esp_err_t gpio_isr_register(void (*fn)(void *), void *arg, int intr_alloc_flags, gpio_isr_handle_t *handle); 241 242 /** 243 * @brief Enable pull-up on GPIO. 244 * 245 * @param gpio_num GPIO number 246 * 247 * @return 248 * - ESP_OK Success 249 * - ESP_ERR_INVALID_ARG Parameter error 250 */ 251 esp_err_t gpio_pullup_en(gpio_num_t gpio_num); 252 253 /** 254 * @brief Disable pull-up on GPIO. 255 * 256 * @param gpio_num GPIO number 257 * 258 * @return 259 * - ESP_OK Success 260 * - ESP_ERR_INVALID_ARG Parameter error 261 */ 262 esp_err_t gpio_pullup_dis(gpio_num_t gpio_num); 263 264 /** 265 * @brief Enable pull-down on GPIO. 266 * 267 * @param gpio_num GPIO number 268 * 269 * @return 270 * - ESP_OK Success 271 * - ESP_ERR_INVALID_ARG Parameter error 272 */ 273 esp_err_t gpio_pulldown_en(gpio_num_t gpio_num); 274 275 /** 276 * @brief Disable pull-down on GPIO. 277 * 278 * @param gpio_num GPIO number 279 * 280 * @return 281 * - ESP_OK Success 282 * - ESP_ERR_INVALID_ARG Parameter error 283 */ 284 esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num); 285 286 /** 287 * @brief Install the driver's GPIO ISR handler service, which allows per-pin GPIO interrupt handlers. 288 * 289 * This function is incompatible with gpio_isr_register() - if that function is used, a single global ISR is registered for all GPIO interrupts. If this function is used, the ISR service provides a global GPIO ISR and individual pin handlers are registered via the gpio_isr_handler_add() function. 290 * 291 * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred) 292 * ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info. 293 * 294 * @return 295 * - ESP_OK Success 296 * - ESP_ERR_NO_MEM No memory to install this service 297 * - ESP_ERR_INVALID_STATE ISR service already installed. 298 * - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags 299 * - ESP_ERR_INVALID_ARG GPIO error 300 */ 301 esp_err_t gpio_install_isr_service(int intr_alloc_flags); 302 303 /** 304 * @brief Uninstall the driver's GPIO ISR service, freeing related resources. 305 */ 306 void gpio_uninstall_isr_service(void); 307 308 /** 309 * @brief Add ISR handler for the corresponding GPIO pin. 310 * 311 * Call this function after using gpio_install_isr_service() to 312 * install the driver's GPIO ISR handler service. 313 * 314 * The pin ISR handlers no longer need to be declared with IRAM_ATTR, 315 * unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the 316 * ISR in gpio_install_isr_service(). 317 * 318 * This ISR handler will be called from an ISR. So there is a stack 319 * size limit (configurable as "ISR stack size" in menuconfig). This 320 * limit is smaller compared to a global GPIO interrupt handler due 321 * to the additional level of indirection. 322 * 323 * @param gpio_num GPIO number 324 * @param isr_handler ISR handler function for the corresponding GPIO number. 325 * @param args parameter for ISR handler. 326 * 327 * @return 328 * - ESP_OK Success 329 * - ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized. 330 * - ESP_ERR_INVALID_ARG Parameter error 331 */ 332 esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void *args); 333 334 /** 335 * @brief Remove ISR handler for the corresponding GPIO pin. 336 * 337 * @param gpio_num GPIO number 338 * 339 * @return 340 * - ESP_OK Success 341 * - ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized. 342 * - ESP_ERR_INVALID_ARG Parameter error 343 */ 344 esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num); 345 346 /** 347 * @brief Set GPIO pad drive capability 348 * 349 * @param gpio_num GPIO number, only support output GPIOs 350 * @param strength Drive capability of the pad 351 * 352 * @return 353 * - ESP_OK Success 354 * - ESP_ERR_INVALID_ARG Parameter error 355 */ 356 esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength); 357 358 /** 359 * @brief Get GPIO pad drive capability 360 * 361 * @param gpio_num GPIO number, only support output GPIOs 362 * @param strength Pointer to accept drive capability of the pad 363 * 364 * @return 365 * - ESP_OK Success 366 * - ESP_ERR_INVALID_ARG Parameter error 367 */ 368 esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t *strength); 369 370 /** 371 * @brief Enable gpio pad hold function. 372 * 373 * The gpio pad hold function works in both input and output modes, but must be output-capable gpios. 374 * If pad hold enabled: 375 * in output mode: the output level of the pad will be force locked and can not be changed. 376 * in input mode: the input value read will not change, regardless the changes of input signal. 377 * 378 * The state of digital gpio cannot be held during Deep-sleep, and it will resume the hold function 379 * when the chip wakes up from Deep-sleep. If the digital gpio also needs to be held during Deep-sleep, 380 * `gpio_deep_sleep_hold_en` should also be called. 381 * 382 * Power down or call gpio_hold_dis will disable this function. 383 * 384 * @param gpio_num GPIO number, only support output-capable GPIOs 385 * 386 * @return 387 * - ESP_OK Success 388 * - ESP_ERR_NOT_SUPPORTED Not support pad hold function 389 */ 390 esp_err_t gpio_hold_en(gpio_num_t gpio_num); 391 392 /** 393 * @brief Disable gpio pad hold function. 394 * 395 * When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output 396 * the default level if this function is called. If you don't want the level changes, the gpio should be configured to 397 * a known state before this function is called. 398 * e.g. 399 * If you hold gpio18 high during Deep-sleep, after the chip is woken up and `gpio_hold_dis` is called, 400 * gpio18 will output low level(because gpio18 is input mode by default). If you don't want this behavior, 401 * you should configure gpio18 as output mode and set it to hight level before calling `gpio_hold_dis`. 402 * 403 * @param gpio_num GPIO number, only support output-capable GPIOs 404 * 405 * @return 406 * - ESP_OK Success 407 * - ESP_ERR_NOT_SUPPORTED Not support pad hold function 408 */ 409 esp_err_t gpio_hold_dis(gpio_num_t gpio_num); 410 411 /** 412 * @brief Enable all digital gpio pad hold function during Deep-sleep. 413 * 414 * When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is woken up, 415 * 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, 416 * when not in sleep mode, the digital gpio state can be changed even you have called this function. 417 * 418 * 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. 419 */ 420 void gpio_deep_sleep_hold_en(void); 421 422 /** 423 * @brief Disable all digital gpio pad hold function during Deep-sleep. 424 * 425 */ 426 void gpio_deep_sleep_hold_dis(void); 427 428 /** 429 * @brief Set pad input to a peripheral signal through the IOMUX. 430 * @param gpio_num GPIO number of the pad. 431 * @param signal_idx Peripheral signal id to input. One of the ``*_IN_IDX`` signals in ``soc/gpio_sig_map.h``. 432 */ 433 void gpio_iomux_in(uint32_t gpio_num, uint32_t signal_idx); 434 435 /** 436 * @brief Set peripheral output to an GPIO pad through the IOMUX. 437 * @param gpio_num gpio_num GPIO number of the pad. 438 * @param func The function number of the peripheral pin to output pin. 439 * One of the ``FUNC_X_*`` of specified pin (X) in ``soc/io_mux_reg.h``. 440 * @param oen_inv True if the output enable needs to be inverted, otherwise False. 441 */ 442 void gpio_iomux_out(uint8_t gpio_num, int func, bool oen_inv); 443 444 #if SOC_GPIO_SUPPORT_FORCE_HOLD 445 /** 446 * @brief Force hold digital and rtc gpio pad. 447 * @note GPIO force hold, whether the chip in sleep mode or wakeup mode. 448 * */ 449 esp_err_t gpio_force_hold_all(void); 450 451 /** 452 * @brief Force unhold digital and rtc gpio pad. 453 * @note GPIO force unhold, whether the chip in sleep mode or wakeup mode. 454 * */ 455 esp_err_t gpio_force_unhold_all(void); 456 #endif 457 458 #if SOC_GPIO_SUPPORT_SLP_SWITCH 459 /** 460 * @brief Enable SLP_SEL to change GPIO status automantically in lightsleep. 461 * @param gpio_num GPIO number of the pad. 462 * 463 * @return 464 * - ESP_OK Success 465 * 466 */ 467 esp_err_t gpio_sleep_sel_en(gpio_num_t gpio_num); 468 469 /** 470 * @brief Disable SLP_SEL to change GPIO status automantically in lightsleep. 471 * @param gpio_num GPIO number of the pad. 472 * 473 * @return 474 * - ESP_OK Success 475 */ 476 esp_err_t gpio_sleep_sel_dis(gpio_num_t gpio_num); 477 478 /** 479 * @brief GPIO set direction at sleep 480 * 481 * Configure GPIO direction,such as output_only,input_only,output_and_input 482 * 483 * @param gpio_num Configure GPIO pins number, it should be GPIO number. If you want to set direction of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 484 * @param mode GPIO direction 485 * 486 * @return 487 * - ESP_OK Success 488 * - ESP_ERR_INVALID_ARG GPIO error 489 */ 490 esp_err_t gpio_sleep_set_direction(gpio_num_t gpio_num, gpio_mode_t mode); 491 492 /** 493 * @brief Configure GPIO pull-up/pull-down resistors at sleep 494 * 495 * Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not. 496 * 497 * @param gpio_num GPIO number. If you want to set pull up or down mode for e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16); 498 * @param pull GPIO pull up/down mode. 499 * 500 * @return 501 * - ESP_OK Success 502 * - ESP_ERR_INVALID_ARG : Parameter error 503 */ 504 esp_err_t gpio_sleep_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull); 505 #endif 506 507 #if SOC_GPIO_SUPPORT_DEEPSLEEP_WAKEUP 508 509 #define GPIO_IS_DEEP_SLEEP_WAKEUP_VALID_GPIO(gpio_num) ((gpio_num & ~SOC_GPIO_DEEP_SLEEP_WAKEUP_VALID_GPIO_MASK) == 0) 510 511 /** 512 * @brief Enable GPIO deep-sleep wake-up function. 513 * 514 * @param gpio_num GPIO number. 515 * 516 * @param intr_type GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used. 517 * 518 * @note Called by the SDK. User shouldn't call this directly in the APP. 519 * 520 * @return 521 * - ESP_OK Success 522 * - ESP_ERR_INVALID_ARG Parameter error 523 */ 524 esp_err_t gpio_deep_sleep_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type); 525 526 /** 527 * @brief Disable GPIO deep-sleep wake-up function. 528 * 529 * @param gpio_num GPIO number 530 * 531 * @return 532 * - ESP_OK Success 533 * - ESP_ERR_INVALID_ARG Parameter error 534 */ 535 esp_err_t gpio_deep_sleep_wakeup_disable(gpio_num_t gpio_num); 536 537 #endif 538 539 #ifdef __cplusplus 540 } 541 #endif 542
