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