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