granicus.if.org Git - esp-idf/blob - components/driver/include/driver/gpio.h

   1 // Copyright 2015-2016 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 #ifndef _DRIVER_GPIO_H_
  16 #define _DRIVER_GPIO_H_
  17 #include "esp_err.h"
  18 #include <esp_types.h>
  19 #include <esp_bit_defs.h>
  20 #include "esp32/rom/gpio.h"
  21 #include "esp_attr.h"
  22 #include "esp_intr_alloc.h"
  23 #include "soc/gpio_periph.h"
  24
  25 #include "sdkconfig.h"
  26
  27 #ifdef CONFIG_LEGACY_INCLUDE_COMMON_HEADERS
  28 #include "soc/rtc_io_reg.h"
  29 #endif
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 #define GPIO_SEL_0              (BIT(0))                         /*!< Pin 0 selected */
  36 #define GPIO_SEL_1              (BIT(1))                         /*!< Pin 1 selected */
  37 #define GPIO_SEL_2              (BIT(2))                         /*!< Pin 2 selected
  38                                                                       @note There are more macros
  39                                                                       like that up to pin 39,
  40                                                                       excluding pins 20, 24 and 28..31.
  41                                                                       They are not shown here
  42                                                                       to reduce redundant information. */
  43 /** @cond */
  44 #define GPIO_SEL_3              (BIT(3))                         /*!< Pin 3 selected */
  45 #define GPIO_SEL_4              (BIT(4))                         /*!< Pin 4 selected */
  46 #define GPIO_SEL_5              (BIT(5))                         /*!< Pin 5 selected */
  47 #define GPIO_SEL_6              (BIT(6))                         /*!< Pin 6 selected */
  48 #define GPIO_SEL_7              (BIT(7))                         /*!< Pin 7 selected */
  49 #define GPIO_SEL_8              (BIT(8))                         /*!< Pin 8 selected */
  50 #define GPIO_SEL_9              (BIT(9))                         /*!< Pin 9 selected */
  51 #define GPIO_SEL_10             (BIT(10))                        /*!< Pin 10 selected */
  52 #define GPIO_SEL_11             (BIT(11))                        /*!< Pin 11 selected */
  53 #define GPIO_SEL_12             (BIT(12))                        /*!< Pin 12 selected */
  54 #define GPIO_SEL_13             (BIT(13))                        /*!< Pin 13 selected */
  55 #define GPIO_SEL_14             (BIT(14))                        /*!< Pin 14 selected */
  56 #define GPIO_SEL_15             (BIT(15))                        /*!< Pin 15 selected */
  57 #define GPIO_SEL_16             (BIT(16))                        /*!< Pin 16 selected */
  58 #define GPIO_SEL_17             (BIT(17))                        /*!< Pin 17 selected */
  59 #define GPIO_SEL_18             (BIT(18))                        /*!< Pin 18 selected */
  60 #define GPIO_SEL_19             (BIT(19))                        /*!< Pin 19 selected */
  61
  62 #define GPIO_SEL_21             (BIT(21))                        /*!< Pin 21 selected */
  63 #define GPIO_SEL_22             (BIT(22))                        /*!< Pin 22 selected */
  64 #define GPIO_SEL_23             (BIT(23))                        /*!< Pin 23 selected */
  65
  66 #define GPIO_SEL_25             (BIT(25))                        /*!< Pin 25 selected */
  67 #define GPIO_SEL_26             (BIT(26))                        /*!< Pin 26 selected */
  68 #define GPIO_SEL_27             (BIT(27))                        /*!< Pin 27 selected */
  69
  70 #define GPIO_SEL_32             ((uint64_t)(((uint64_t)1)<<32))  /*!< Pin 32 selected */
  71 #define GPIO_SEL_33             ((uint64_t)(((uint64_t)1)<<33))  /*!< Pin 33 selected */
  72 #define GPIO_SEL_34             ((uint64_t)(((uint64_t)1)<<34))  /*!< Pin 34 selected */
  73 #define GPIO_SEL_35             ((uint64_t)(((uint64_t)1)<<35))  /*!< Pin 35 selected */
  74 #define GPIO_SEL_36             ((uint64_t)(((uint64_t)1)<<36))  /*!< Pin 36 selected */
  75 #define GPIO_SEL_37             ((uint64_t)(((uint64_t)1)<<37))  /*!< Pin 37 selected */
  76 #define GPIO_SEL_38             ((uint64_t)(((uint64_t)1)<<38))  /*!< Pin 38 selected */
  77 #define GPIO_SEL_39             ((uint64_t)(((uint64_t)1)<<39))  /*!< Pin 39 selected */
  78
  79 #define GPIO_PIN_REG_0          IO_MUX_GPIO0_REG
  80 #define GPIO_PIN_REG_1          IO_MUX_GPIO1_REG
  81 #define GPIO_PIN_REG_2          IO_MUX_GPIO2_REG
  82 #define GPIO_PIN_REG_3          IO_MUX_GPIO3_REG
  83 #define GPIO_PIN_REG_4          IO_MUX_GPIO4_REG
  84 #define GPIO_PIN_REG_5          IO_MUX_GPIO5_REG
  85 #define GPIO_PIN_REG_6          IO_MUX_GPIO6_REG
  86 #define GPIO_PIN_REG_7          IO_MUX_GPIO7_REG
  87 #define GPIO_PIN_REG_8          IO_MUX_GPIO8_REG
  88 #define GPIO_PIN_REG_9          IO_MUX_GPIO9_REG
  89 #define GPIO_PIN_REG_10         IO_MUX_GPIO10_REG
  90 #define GPIO_PIN_REG_11         IO_MUX_GPIO11_REG
  91 #define GPIO_PIN_REG_12         IO_MUX_GPIO12_REG
  92 #define GPIO_PIN_REG_13         IO_MUX_GPIO13_REG
  93 #define GPIO_PIN_REG_14         IO_MUX_GPIO14_REG
  94 #define GPIO_PIN_REG_15         IO_MUX_GPIO15_REG
  95 #define GPIO_PIN_REG_16         IO_MUX_GPIO16_REG
  96 #define GPIO_PIN_REG_17         IO_MUX_GPIO17_REG
  97 #define GPIO_PIN_REG_18         IO_MUX_GPIO18_REG
  98 #define GPIO_PIN_REG_19         IO_MUX_GPIO19_REG
  99 #define GPIO_PIN_REG_20         IO_MUX_GPIO20_REG
 100 #define GPIO_PIN_REG_21         IO_MUX_GPIO21_REG
 101 #define GPIO_PIN_REG_22         IO_MUX_GPIO22_REG
 102 #define GPIO_PIN_REG_23         IO_MUX_GPIO23_REG
 103 #define GPIO_PIN_REG_25         IO_MUX_GPIO25_REG
 104 #define GPIO_PIN_REG_26         IO_MUX_GPIO26_REG
 105 #define GPIO_PIN_REG_27         IO_MUX_GPIO27_REG
 106 #define GPIO_PIN_REG_32         IO_MUX_GPIO32_REG
 107 #define GPIO_PIN_REG_33         IO_MUX_GPIO33_REG
 108 #define GPIO_PIN_REG_34         IO_MUX_GPIO34_REG
 109 #define GPIO_PIN_REG_35         IO_MUX_GPIO35_REG
 110 #define GPIO_PIN_REG_36         IO_MUX_GPIO36_REG
 111 #define GPIO_PIN_REG_37         IO_MUX_GPIO37_REG
 112 #define GPIO_PIN_REG_38         IO_MUX_GPIO38_REG
 113 #define GPIO_PIN_REG_39         IO_MUX_GPIO39_REG
 114
 115 #define GPIO_APP_CPU_INTR_ENA      (BIT(0))
 116 #define GPIO_APP_CPU_NMI_INTR_ENA  (BIT(1))
 117 #define GPIO_PRO_CPU_INTR_ENA      (BIT(2))
 118 #define GPIO_PRO_CPU_NMI_INTR_ENA  (BIT(3))
 119 #define GPIO_SDIO_EXT_INTR_ENA     (BIT(4))
 120
 121 #define GPIO_MODE_DEF_DISABLE         (0)
 122 #define GPIO_MODE_DEF_INPUT           (BIT0)
 123 #define GPIO_MODE_DEF_OUTPUT          (BIT1)
 124 #define GPIO_MODE_DEF_OD              (BIT2)
 125
 126
 127 /** @endcond */
 128
 129 #define GPIO_IS_VALID_GPIO(gpio_num)      ((gpio_num < GPIO_PIN_COUNT && GPIO_PIN_MUX_REG[gpio_num] != 0))   /*!< Check whether it is a valid GPIO number */
 130 #define GPIO_IS_VALID_OUTPUT_GPIO(gpio_num)      ((GPIO_IS_VALID_GPIO(gpio_num)) && (gpio_num < 34))         /*!< Check whether it can be a valid GPIO number of output mode */
 131
 132 typedef enum {
 133     GPIO_NUM_NC = -1,    /*!< Use to signal not connected to S/W */
 134     GPIO_NUM_0 = 0,     /*!< GPIO0, input and output */
 135     GPIO_NUM_1 = 1,     /*!< GPIO1, input and output */
 136     GPIO_NUM_2 = 2,     /*!< GPIO2, input and output
 137                              @note There are more enumerations like that
 138                              up to GPIO39, excluding GPIO20, GPIO24 and GPIO28..31.
 139                              They are not shown here to reduce redundant information.
 140                              @note GPIO34..39 are input mode only. */
 141 /** @cond */
 142     GPIO_NUM_3 = 3,     /*!< GPIO3, input and output */
 143     GPIO_NUM_4 = 4,     /*!< GPIO4, input and output */
 144     GPIO_NUM_5 = 5,     /*!< GPIO5, input and output */
 145     GPIO_NUM_6 = 6,     /*!< GPIO6, input and output */
 146     GPIO_NUM_7 = 7,     /*!< GPIO7, input and output */
 147     GPIO_NUM_8 = 8,     /*!< GPIO8, input and output */
 148     GPIO_NUM_9 = 9,     /*!< GPIO9, input and output */
 149     GPIO_NUM_10 = 10,   /*!< GPIO10, input and output */
 150     GPIO_NUM_11 = 11,   /*!< GPIO11, input and output */
 151     GPIO_NUM_12 = 12,   /*!< GPIO12, input and output */
 152     GPIO_NUM_13 = 13,   /*!< GPIO13, input and output */
 153     GPIO_NUM_14 = 14,   /*!< GPIO14, input and output */
 154     GPIO_NUM_15 = 15,   /*!< GPIO15, input and output */
 155     GPIO_NUM_16 = 16,   /*!< GPIO16, input and output */
 156     GPIO_NUM_17 = 17,   /*!< GPIO17, input and output */
 157     GPIO_NUM_18 = 18,   /*!< GPIO18, input and output */
 158     GPIO_NUM_19 = 19,   /*!< GPIO19, input and output */
 159
 160     GPIO_NUM_21 = 21,   /*!< GPIO21, input and output */
 161     GPIO_NUM_22 = 22,   /*!< GPIO22, input and output */
 162     GPIO_NUM_23 = 23,   /*!< GPIO23, input and output */
 163
 164     GPIO_NUM_25 = 25,   /*!< GPIO25, input and output */
 165     GPIO_NUM_26 = 26,   /*!< GPIO26, input and output */
 166     GPIO_NUM_27 = 27,   /*!< GPIO27, input and output */
 167
 168     GPIO_NUM_32 = 32,   /*!< GPIO32, input and output */
 169     GPIO_NUM_33 = 33,   /*!< GPIO33, input and output */
 170     GPIO_NUM_34 = 34,   /*!< GPIO34, input mode only */
 171     GPIO_NUM_35 = 35,   /*!< GPIO35, input mode only */
 172     GPIO_NUM_36 = 36,   /*!< GPIO36, input mode only */
 173     GPIO_NUM_37 = 37,   /*!< GPIO37, input mode only */
 174     GPIO_NUM_38 = 38,   /*!< GPIO38, input mode only */
 175     GPIO_NUM_39 = 39,   /*!< GPIO39, input mode only */
 176     GPIO_NUM_MAX = 40,
 177 /** @endcond */
 178 } gpio_num_t;
 179
 180 typedef enum {
 181     GPIO_INTR_DISABLE = 0,     /*!< Disable GPIO interrupt                             */
 182     GPIO_INTR_POSEDGE = 1,     /*!< GPIO interrupt type : rising edge                  */
 183     GPIO_INTR_NEGEDGE = 2,     /*!< GPIO interrupt type : falling edge                 */
 184     GPIO_INTR_ANYEDGE = 3,     /*!< GPIO interrupt type : both rising and falling edge */
 185     GPIO_INTR_LOW_LEVEL = 4,   /*!< GPIO interrupt type : input low level trigger      */
 186     GPIO_INTR_HIGH_LEVEL = 5,  /*!< GPIO interrupt type : input high level trigger     */
 187     GPIO_INTR_MAX,
 188 } gpio_int_type_t;
 189
 190 typedef enum {
 191     GPIO_MODE_DISABLE = GPIO_MODE_DEF_DISABLE,                                        /*!< GPIO mode : disable input and output             */
 192     GPIO_MODE_INPUT = GPIO_MODE_DEF_INPUT,                                                         /*!< GPIO mode : input only                           */
 193     GPIO_MODE_OUTPUT = GPIO_MODE_DEF_OUTPUT,                                                       /*!< GPIO mode : output only mode                     */
 194     GPIO_MODE_OUTPUT_OD = ((GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD)),                             /*!< GPIO mode : output only with open-drain mode     */
 195     GPIO_MODE_INPUT_OUTPUT_OD = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)|(GPIO_MODE_DEF_OD)), /*!< GPIO mode : output and input with open-drain mode*/
 196     GPIO_MODE_INPUT_OUTPUT = ((GPIO_MODE_DEF_INPUT)|(GPIO_MODE_DEF_OUTPUT)),                       /*!< GPIO mode : output and input mode                */
 197 } gpio_mode_t;
 198
 199 typedef enum {
 200     GPIO_PULLUP_DISABLE = 0x0,     /*!< Disable GPIO pull-up resistor */
 201     GPIO_PULLUP_ENABLE = 0x1,      /*!< Enable GPIO pull-up resistor */
 202 } gpio_pullup_t;
 203
 204 typedef enum {
 205     GPIO_PULLDOWN_DISABLE = 0x0,   /*!< Disable GPIO pull-down resistor */
 206     GPIO_PULLDOWN_ENABLE = 0x1,    /*!< Enable GPIO pull-down resistor  */
 207 } gpio_pulldown_t;
 208
 209 /**
 210  * @brief Configuration parameters of GPIO pad for gpio_config function
 211  */
 212 typedef struct {
 213     uint64_t pin_bit_mask;          /*!< GPIO pin: set with bit mask, each bit maps to a GPIO */
 214     gpio_mode_t mode;               /*!< GPIO mode: set input/output mode                     */
 215     gpio_pullup_t pull_up_en;       /*!< GPIO pull-up                                         */
 216     gpio_pulldown_t pull_down_en;   /*!< GPIO pull-down                                       */
 217     gpio_int_type_t intr_type;      /*!< GPIO interrupt type                                  */
 218 } gpio_config_t;
 219
 220 typedef enum {
 221     GPIO_PULLUP_ONLY,               /*!< Pad pull up            */
 222     GPIO_PULLDOWN_ONLY,             /*!< Pad pull down          */
 223     GPIO_PULLUP_PULLDOWN,           /*!< Pad pull up + pull down*/
 224     GPIO_FLOATING,                  /*!< Pad floating           */
 225 } gpio_pull_mode_t;
 226
 227 typedef enum {
 228     GPIO_DRIVE_CAP_0       = 0,    /*!< Pad drive capability: weak          */
 229     GPIO_DRIVE_CAP_1       = 1,    /*!< Pad drive capability: stronger      */
 230     GPIO_DRIVE_CAP_2       = 2,    /*!< Pad drive capability: default value */
 231     GPIO_DRIVE_CAP_DEFAULT = 2,    /*!< Pad drive capability: default value */
 232     GPIO_DRIVE_CAP_3       = 3,    /*!< Pad drive capability: strongest     */
 233     GPIO_DRIVE_CAP_MAX,
 234 } gpio_drive_cap_t;
 235
 236 typedef void (*gpio_isr_t)(void*);
 237 typedef intr_handle_t gpio_isr_handle_t;
 238
 239 /**
 240  * @brief GPIO common configuration
 241  *
 242  *        Configure GPIO's Mode,pull-up,PullDown,IntrType
 243  *
 244  * @param  pGPIOConfig Pointer to GPIO configure struct
 245  *
 246  * @return
 247  *     - ESP_OK success
 248  *     - ESP_ERR_INVALID_ARG Parameter error
 249  *
 250  */
 251 esp_err_t gpio_config(const gpio_config_t *pGPIOConfig);
 252
 253 /**
 254  * @brief Reset an gpio to default state (select gpio function, enable pullup and disable input and output).
 255  *
 256  * @param gpio_num GPIO number.
 257  *
 258  * @note This function also configures the IOMUX for this pin to the GPIO
 259  *       function, and disconnects any other peripheral output configured via GPIO
 260  *       Matrix.
 261  *
 262  * @return Always return ESP_OK.
 263  */
 264 esp_err_t gpio_reset_pin(gpio_num_t gpio_num);
 265
 266 /**
 267  * @brief  GPIO set interrupt trigger type
 268  *
 269  * @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);
 270  * @param  intr_type Interrupt type, select from gpio_int_type_t
 271  *
 272  * @return
 273  *     - ESP_OK  Success
 274  *     - ESP_ERR_INVALID_ARG Parameter error
 275  *
 276  */
 277 esp_err_t gpio_set_intr_type(gpio_num_t gpio_num, gpio_int_type_t intr_type);
 278
 279 /**
 280  * @brief  Enable GPIO module interrupt signal
 281  *
 282  * @note Please do not use the interrupt of GPIO36 and GPIO39 when using ADC.
 283  *       Please refer to the comments of `adc1_get_raw`.
 284  *       Please refer to section 3.11 of 'ECO_and_Workarounds_for_Bugs_in_ESP32' for the description of this issue.
 285  *
 286  * @param  gpio_num GPIO number. If you want to enable an interrupt on e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
 287  *
 288  * @return
 289  *     - ESP_OK Success
 290  *     - ESP_ERR_INVALID_ARG Parameter error
 291  *
 292  */
 293 esp_err_t gpio_intr_enable(gpio_num_t gpio_num);
 294
 295 /**
 296  * @brief  Disable GPIO module interrupt signal
 297  *
 298  * @param  gpio_num GPIO number. If you want to disable the interrupt of e.g. GPIO16, gpio_num should be GPIO_NUM_16 (16);
 299  *
 300  * @return
 301  *     - ESP_OK success
 302  *     - ESP_ERR_INVALID_ARG Parameter error
 303  *
 304  */
 305 esp_err_t gpio_intr_disable(gpio_num_t gpio_num);
 306
 307 /**
 308  * @brief  GPIO set output level
 309  *
 310  * @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);
 311  * @param  level Output level. 0: low ; 1: high
 312  *
 313  * @return
 314  *     - ESP_OK Success
 315  *     - ESP_ERR_INVALID_ARG GPIO number error
 316  *
 317  */
 318 esp_err_t gpio_set_level(gpio_num_t gpio_num, uint32_t level);
 319
 320 /**
 321  * @brief  GPIO get input level
 322  *
 323  * @warning If the pad is not configured for input (or input and output) the returned value is always 0.
 324  *
 325  * @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);
 326  *
 327  * @return
 328  *     - 0 the GPIO input level is 0
 329  *     - 1 the GPIO input level is 1
 330  *
 331  */
 332 int gpio_get_level(gpio_num_t gpio_num);
 333
 334 /**
 335  * @brief        GPIO set direction
 336  *
 337  * Configure GPIO direction,such as output_only,input_only,output_and_input
 338  *
 339  * @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);
 340  * @param  mode GPIO direction
 341  *
 342  * @return
 343  *     - ESP_OK Success
 344  *     - ESP_ERR_INVALID_ARG GPIO error
 345  *
 346  */
 347 esp_err_t gpio_set_direction(gpio_num_t gpio_num, gpio_mode_t mode);
 348
 349 /**
 350  * @brief  Configure GPIO pull-up/pull-down resistors
 351  *
 352  * Only pins that support both input & output have integrated pull-up and pull-down resistors. Input-only GPIOs 34-39 do not.
 353  *
 354  * @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);
 355  * @param  pull GPIO pull up/down mode.
 356  *
 357  * @return
 358  *     - ESP_OK Success
 359  *     - ESP_ERR_INVALID_ARG : Parameter error
 360  *
 361  */
 362 esp_err_t gpio_set_pull_mode(gpio_num_t gpio_num, gpio_pull_mode_t pull);
 363
 364 /**
 365  * @brief Enable GPIO wake-up function.
 366  *
 367  * @param gpio_num GPIO number.
 368  *
 369  * @param intr_type GPIO wake-up type. Only GPIO_INTR_LOW_LEVEL or GPIO_INTR_HIGH_LEVEL can be used.
 370  *
 371  * @return
 372  *     - ESP_OK Success
 373  *     - ESP_ERR_INVALID_ARG Parameter error
 374  */
 375 esp_err_t gpio_wakeup_enable(gpio_num_t gpio_num, gpio_int_type_t intr_type);
 376
 377 /**
 378  * @brief Disable GPIO wake-up function.
 379  *
 380  * @param gpio_num GPIO number
 381  *
 382  * @return
 383  *     - ESP_OK Success
 384  *     - ESP_ERR_INVALID_ARG Parameter error
 385  */
 386 esp_err_t gpio_wakeup_disable(gpio_num_t gpio_num);
 387
 388 /**
 389  * @brief   Register GPIO interrupt handler, the handler is an ISR.
 390  *          The handler will be attached to the same CPU core that this function is running on.
 391  *
 392  * This ISR function is called whenever any GPIO interrupt occurs. See
 393  * the alternative gpio_install_isr_service() and
 394  * gpio_isr_handler_add() API in order to have the driver support
 395  * per-GPIO ISRs.
 396  *
 397  * @param  fn  Interrupt handler function.
 398  * @param  intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred)
 399  *            ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
 400  * @param  arg  Parameter for handler function
 401  * @param  handle Pointer to return handle. If non-NULL, a handle for the interrupt will be returned here.
 402  *
 403  * \verbatim embed:rst:leading-asterisk
 404  * To disable or remove the ISR, pass the returned handle to the :doc:`interrupt allocation functions </api-reference/system/intr_alloc>`.
 405  * \endverbatim
 406  *
 407  * @return
 408  *     - ESP_OK Success ;
 409  *     - ESP_ERR_INVALID_ARG GPIO error
 410  *     - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
 411  */
 412 esp_err_t gpio_isr_register(void (*fn)(void*), void * arg, int intr_alloc_flags, gpio_isr_handle_t *handle);
 413
 414 /**
 415   * @brief Enable pull-up on GPIO.
 416   *
 417   * @param gpio_num GPIO number
 418   *
 419   * @return
 420   *     - ESP_OK Success
 421   *     - ESP_ERR_INVALID_ARG Parameter error
 422   */
 423 esp_err_t gpio_pullup_en(gpio_num_t gpio_num);
 424
 425 /**
 426   * @brief Disable pull-up on GPIO.
 427   *
 428   * @param gpio_num GPIO number
 429   *
 430   * @return
 431   *     - ESP_OK Success
 432   *     - ESP_ERR_INVALID_ARG Parameter error
 433   */
 434 esp_err_t gpio_pullup_dis(gpio_num_t gpio_num);
 435
 436 /**
 437   * @brief Enable pull-down on GPIO.
 438   *
 439   * @param gpio_num GPIO number
 440   *
 441   * @return
 442   *     - ESP_OK Success
 443   *     - ESP_ERR_INVALID_ARG Parameter error
 444   */
 445 esp_err_t gpio_pulldown_en(gpio_num_t gpio_num);
 446
 447 /**
 448   * @brief Disable pull-down on GPIO.
 449   *
 450   * @param gpio_num GPIO number
 451   *
 452   * @return
 453   *     - ESP_OK Success
 454   *     - ESP_ERR_INVALID_ARG Parameter error
 455   */
 456 esp_err_t gpio_pulldown_dis(gpio_num_t gpio_num);
 457
 458 /**
 459   * @brief Install the driver's GPIO ISR handler service, which allows per-pin GPIO interrupt handlers.
 460   *
 461   * 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.
 462   *
 463   * @param intr_alloc_flags Flags used to allocate the interrupt. One or multiple (ORred)
 464   *            ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info.
 465   *
 466   * @return
 467   *     - ESP_OK Success
 468   *     - ESP_ERR_NO_MEM No memory to install this service
 469   *     - ESP_ERR_INVALID_STATE ISR service already installed.
 470   *     - ESP_ERR_NOT_FOUND No free interrupt found with the specified flags
 471   *     - ESP_ERR_INVALID_ARG GPIO error
 472   */
 473 esp_err_t gpio_install_isr_service(int intr_alloc_flags);
 474
 475 /**
 476   * @brief Uninstall the driver's GPIO ISR service, freeing related resources.
 477   */
 478 void gpio_uninstall_isr_service(void);
 479
 480 /**
 481   * @brief Add ISR handler for the corresponding GPIO pin.
 482   *
 483   * Call this function after using gpio_install_isr_service() to
 484   * install the driver's GPIO ISR handler service.
 485   *
 486   * The pin ISR handlers no longer need to be declared with IRAM_ATTR,
 487   * unless you pass the ESP_INTR_FLAG_IRAM flag when allocating the
 488   * ISR in gpio_install_isr_service().
 489   *
 490   * This ISR handler will be called from an ISR. So there is a stack
 491   * size limit (configurable as "ISR stack size" in menuconfig). This
 492   * limit is smaller compared to a global GPIO interrupt handler due
 493   * to the additional level of indirection.
 494   *
 495   * @param gpio_num GPIO number
 496   * @param isr_handler ISR handler function for the corresponding GPIO number.
 497   * @param args parameter for ISR handler.
 498   *
 499   * @return
 500   *     - ESP_OK Success
 501   *     - ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.
 502   *     - ESP_ERR_INVALID_ARG Parameter error
 503   */
 504 esp_err_t gpio_isr_handler_add(gpio_num_t gpio_num, gpio_isr_t isr_handler, void* args);
 505
 506 /**
 507   * @brief Remove ISR handler for the corresponding GPIO pin.
 508   *
 509   * @param gpio_num GPIO number
 510   *
 511   * @return
 512   *     - ESP_OK Success
 513   *     - ESP_ERR_INVALID_STATE Wrong state, the ISR service has not been initialized.
 514   *     - ESP_ERR_INVALID_ARG Parameter error
 515   */
 516 esp_err_t gpio_isr_handler_remove(gpio_num_t gpio_num);
 517
 518 /**
 519   * @brief Set GPIO pad drive capability
 520   *
 521   * @param gpio_num GPIO number, only support output GPIOs
 522   * @param strength Drive capability of the pad
 523   *
 524   * @return
 525   *     - ESP_OK Success
 526   *     - ESP_ERR_INVALID_ARG Parameter error
 527   */
 528 esp_err_t gpio_set_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t strength);
 529
 530 /**
 531   * @brief Get GPIO pad drive capability
 532   *
 533   * @param gpio_num GPIO number, only support output GPIOs
 534   * @param strength Pointer to accept drive capability of the pad
 535   *
 536   * @return
 537   *     - ESP_OK Success
 538   *     - ESP_ERR_INVALID_ARG Parameter error
 539   */
 540 esp_err_t gpio_get_drive_capability(gpio_num_t gpio_num, gpio_drive_cap_t* strength);
 541
 542 /**
 543   * @brief Enable gpio pad hold function.
 544   *
 545   * The gpio pad hold function works in both input and output modes, but must be output-capable gpios.
 546   * If pad hold enabled:
 547   *   in output mode: the output level of the pad will be force locked and can not be changed.
 548   *   in input mode: the input value read will not change, regardless the changes of input signal.
 549   *
 550   * The state of digital gpio cannot be held during Deep-sleep, and it will resume the hold function
 551   * when the chip wakes up from Deep-sleep. If the digital gpio also needs to be held during Deep-sleep,
 552   * `gpio_deep_sleep_hold_en` should also be called.
 553   *
 554   * Power down or call gpio_hold_dis will disable this function.
 555   *
 556   * @param gpio_num GPIO number, only support output-capable GPIOs
 557   *
 558   * @return
 559   *     - ESP_OK Success
 560   *     - ESP_ERR_NOT_SUPPORTED Not support pad hold function
 561   */
 562 esp_err_t gpio_hold_en(gpio_num_t gpio_num);
 563
 564 /**
 565   * @brief Disable gpio pad hold function.
 566   *
 567   * When the chip is woken up from Deep-sleep, the gpio will be set to the default mode, so, the gpio will output
 568   * the default level if this function is called. If you dont't want the level changes, the gpio should be configured to
 569   * a known state before this function is called.
 570   *  e.g.
 571   *     If you hold gpio18 high during Deep-sleep, after the chip is woken up and `gpio_hold_dis` is called,
 572   *     gpio18 will output low level(because gpio18 is input mode by default). If you don't want this behavior,
 573   *     you should configure gpio18 as output mode and set it to hight level before calling `gpio_hold_dis`.
 574   *
 575   * @param gpio_num GPIO number, only support output-capable GPIOs
 576   *
 577   * @return
 578   *     - ESP_OK Success
 579   *     - ESP_ERR_NOT_SUPPORTED Not support pad hold function
 580   */
 581 esp_err_t gpio_hold_dis(gpio_num_t gpio_num);
 582
 583 /**
 584   * @brief Enable all digital gpio pad hold function during Deep-sleep.
 585   *
 586   * When the chip is in Deep-sleep mode, all digital gpio will hold the state before sleep, and when the chip is woken up,
 587   * 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,
 588   * when not in sleep mode, the digital gpio state can be changed even you have called this function.
 589   *
 590   * 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.
 591   */
 592 void gpio_deep_sleep_hold_en(void);
 593
 594 /**
 595   * @brief Disable all digital gpio pad hold function during Deep-sleep.
 596   *
 597   */
 598 void gpio_deep_sleep_hold_dis(void);
 599
 600 /**
 601   * @brief Set pad input to a peripheral signal through the IOMUX.
 602   * @param gpio_num GPIO number of the pad.
 603   * @param signal_idx Peripheral signal id to input. One of the ``*_IN_IDX`` signals in ``soc/gpio_sig_map.h``.
 604   */
 605 void gpio_iomux_in(uint32_t gpio_num, uint32_t signal_idx);
 606
 607 /**
 608   * @brief Set peripheral output to an GPIO pad through the IOMUX.
 609   * @param gpio_num gpio_num GPIO number of the pad.
 610   * @param func The function number of the peripheral pin to output pin.
 611   *        One of the ``FUNC_X_*`` of specified pin (X) in ``soc/io_mux_reg.h``.
 612   * @param oen_inv True if the output enable needs to be inversed, otherwise False.
 613   */
 614 void gpio_iomux_out(uint8_t gpio_num, int func, bool oen_inv);
 615
 616 #ifdef __cplusplus
 617 }
 618 #endif
 619
 620 #endif /* _DRIVER_GPIO_H_ */