1 /* 2 * SPDX-FileCopyrightText: 2020-2021 Espressif Systems (Shanghai) CO LTD 3 * 4 * SPDX-License-Identifier: Apache-2.0 5 */ 6 7 #pragma once 8 9 #include <stdint.h> 10 #include <stdbool.h> 11 #include "esp_err.h" 12 #include "esp_attr.h" 13 #include "soc/soc_caps.h" 14 15 #if SOC_DEDICATED_GPIO_SUPPORTED 16 17 #ifdef __cplusplus 18 extern "C" { 19 #endif 20 21 /** 22 * @brief Type of Dedicated GPIO bundle 23 */ 24 typedef struct dedic_gpio_bundle_t *dedic_gpio_bundle_handle_t; 25 26 /** 27 * @brief Type of Dedicated GPIO bundle configuration 28 */ 29 typedef struct { 30 const int *gpio_array; /*!< Array of GPIO numbers, gpio_array[0] ~ gpio_array[size-1] <=> low_dedic_channel_num ~ high_dedic_channel_num */ 31 size_t array_size; /*!< Number of GPIOs in gpio_array */ 32 struct { 33 unsigned int in_en: 1; /*!< Enable input */ 34 unsigned int in_invert: 1; /*!< Invert input signal */ 35 unsigned int out_en: 1; /*!< Enable output */ 36 unsigned int out_invert: 1; /*!< Invert output signal */ 37 } flags; /*!< Flags to control specific behaviour of GPIO bundle */ 38 } dedic_gpio_bundle_config_t; 39 40 /** 41 * @brief Create GPIO bundle and return the handle 42 * 43 * @param[in] config Configuration of GPIO bundle 44 * @param[out] ret_bundle Returned handle of the new created GPIO bundle 45 * @return 46 * - ESP_OK: Create GPIO bundle successfully 47 * - ESP_ERR_INVALID_ARG: Create GPIO bundle failed because of invalid argument 48 * - ESP_ERR_NO_MEM: Create GPIO bundle failed because of no capable memory 49 * - ESP_ERR_NOT_FOUND: Create GPIO bundle failed because of no enough continuous dedicated channels 50 * - ESP_FAIL: Create GPIO bundle failed because of other error 51 * 52 * @note One has to enable at least input or output mode in "config" parameter. 53 */ 54 esp_err_t dedic_gpio_new_bundle(const dedic_gpio_bundle_config_t *config, dedic_gpio_bundle_handle_t *ret_bundle); 55 56 /** 57 * @brief Destory GPIO bundle 58 * 59 * @param[in] bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 60 * @return 61 * - ESP_OK: Destory GPIO bundle successfully 62 * - ESP_ERR_INVALID_ARG: Destory GPIO bundle failed because of invalid argument 63 * - ESP_FAIL: Destory GPIO bundle failed because of other error 64 */ 65 esp_err_t dedic_gpio_del_bundle(dedic_gpio_bundle_handle_t bundle); 66 67 /**@{*/ 68 /** 69 * @brief Get allocated channel mask 70 * 71 * @param[in] bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 72 * @param[out] mask Returned mask value for on specific direction (in or out) 73 * @return 74 * - ESP_OK: Get channel mask successfully 75 * - ESP_ERR_INVALID_ARG: Get channel mask failed because of invalid argument 76 * - ESP_FAIL: Get channel mask failed because of other error 77 * 78 * @note Each bundle should have at least one mask (in or/and out), based on bundle configuration. 79 * @note With the returned mask, user can directly invoke LL function like "cpu_ll_write_dedic_gpio_mask" 80 * or write assembly code with dedicated GPIO instructions, to get better performance on GPIO manipulation. 81 */ 82 esp_err_t dedic_gpio_get_out_mask(dedic_gpio_bundle_handle_t bundle, uint32_t *mask); 83 esp_err_t dedic_gpio_get_in_mask(dedic_gpio_bundle_handle_t bundle, uint32_t *mask); 84 /**@}*/ 85 86 /** 87 * @brief Write value to GPIO bundle 88 * 89 * @param[in] bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 90 * @param[in] mask Mask of the GPIOs to be written in the given bundle 91 * @param[in] value Value to write to given GPIO bundle, low bit represents low member in the bundle 92 * 93 * @note The mask is seen from the view of GPIO bundle. 94 * For example, bundleA contains [GPIO10, GPIO12, GPIO17], to set GPIO17 individually, the mask should be 0x04. 95 * @note For performance reasons, this function doesn't check the validity of any parameters, and is placed in IRAM. 96 */ 97 void dedic_gpio_bundle_write(dedic_gpio_bundle_handle_t bundle, uint32_t mask, uint32_t value) IRAM_ATTR; 98 99 /** 100 * @brief Read the value that output from the given GPIO bundle 101 * 102 * @param[in] bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 103 * @return Value that output from the GPIO bundle, low bit represents low member in the bundle 104 * 105 * @note For performance reasons, this function doesn't check the validity of any parameters, and is placed in IRAM. 106 */ 107 uint32_t dedic_gpio_bundle_read_out(dedic_gpio_bundle_handle_t bundle) IRAM_ATTR; 108 109 /** 110 * @brief Read the value that input to the given GPIO bundle 111 * 112 * @param[in] bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 113 * @return Value that input to the GPIO bundle, low bit represents low member in the bundle 114 * 115 * @note For performance reasons, this function doesn't check the validity of any parameters, and is placed in IRAM. 116 */ 117 uint32_t dedic_gpio_bundle_read_in(dedic_gpio_bundle_handle_t bundle) IRAM_ATTR; 118 119 #if SOC_DEDIC_GPIO_HAS_INTERRUPT 120 121 /** 122 * @brief Supported type of dedicated GPIO interrupt 123 */ 124 typedef enum { 125 DEDIC_GPIO_INTR_NONE, /*!< No interrupt */ 126 DEDIC_GPIO_INTR_LOW_LEVEL = 2, /*!< Interrupt on low level */ 127 DEDIC_GPIO_INTR_HIGH_LEVEL, /*!< Interrupt on high level */ 128 DEDIC_GPIO_INTR_NEG_EDGE, /*!< Interrupt on negedge */ 129 DEDIC_GPIO_INTR_POS_EDGE, /*!< Interrupt on posedge */ 130 DEDIC_GPIO_INTR_BOTH_EDGE /*!< Interrupt on both negedge and posedge */ 131 } dedic_gpio_intr_type_t; 132 133 /** 134 * @brief Type of dedicated GPIO ISR callback function 135 * 136 * @param bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 137 * @param index Index of the GPIO in its corresponding bundle (count from 0) 138 * @param args User defined arguments for the callback function. It's passed through `dedic_gpio_bundle_set_interrupt_and_callback` 139 * @return If a high priority task is woken up by the callback function 140 */ 141 typedef bool (*dedic_gpio_isr_callback_t)(dedic_gpio_bundle_handle_t bundle, uint32_t index, void *args); 142 143 /** 144 * @brief Set interrupt and callback function for GPIO bundle 145 * 146 * @param[in] bundle Handle of GPIO bundle that returned from "dedic_gpio_new_bundle" 147 * @param[in] mask Mask of the GPIOs in the given bundle 148 * @param[in] intr_type Interrupt type, set to DEDIC_GPIO_INTR_NONE can disable interrupt 149 * @param[in] cb_isr Callback function, which got invoked in ISR context. A NULL pointer here will bypass the callback 150 * @param[in] cb_args User defined argument to be passed to the callback function 151 * 152 * @note This function is only valid for bundle with input mode enabled. See "dedic_gpio_bundle_config_t" 153 * @note The mask is seen from the view of GPIO Bundle. 154 * For example, bundleA contains [GPIO10, GPIO12, GPIO17], to set GPIO17 individually, the mask should be 0x04. 155 * 156 * @return 157 * - ESP_OK: Set GPIO interrupt and callback function successfully 158 * - ESP_ERR_INVALID_ARG: Set GPIO interrupt and callback function failed because of invalid argument 159 * - ESP_FAIL: Set GPIO interrupt and callback function failed because of other error 160 */ 161 esp_err_t dedic_gpio_bundle_set_interrupt_and_callback(dedic_gpio_bundle_handle_t bundle, uint32_t mask, dedic_gpio_intr_type_t intr_type, dedic_gpio_isr_callback_t cb_isr, void *cb_args); 162 163 #endif // SOC_DEDIC_GPIO_HAS_INTERRUPT 164 165 #ifdef __cplusplus 166 } 167 #endif 168 169 #endif //SOC_DEDICATED_GPIO_SUPPORTED 170
