1 /* 2 * Copyright (c) 2020-2021 Huawei Device Co., Ltd. 3 * 4 * HDF is dual licensed: you can use it either under the terms of 5 * the GPL, or the BSD license, at your option. 6 * See the LICENSE file in the root of this repository for complete details. 7 */ 8 9 /** 10 * @addtogroup GPIO 11 * @{ 12 * 13 * @brief Provides standard general-purpose input/output (GPIO) interfaces for driver development. 14 * 15 * You can use this module to perform operations on a GPIO pin, including setting the input/output direction, 16 * reading/writing the level value, and setting the interrupt service routine (ISR) function. 17 * 18 * @since 1.0 19 */ 20 21 /** 22 * @file gpio_if.h 23 * 24 * @brief Declares the standard GPIO interface functions. 25 * 26 * @since 1.0 27 */ 28 29 #ifndef GPIO_IF_H 30 #define GPIO_IF_H 31 32 #include "platform_if.h" 33 #include "osal_irq.h" 34 35 #ifdef __cplusplus 36 #if __cplusplus 37 extern "C" { 38 #endif 39 #endif /* __cplusplus */ 40 41 /** 42 * @brief Enumerates GPIO level values. 43 * 44 * @since 1.0 45 */ 46 enum GpioValue { 47 GPIO_VAL_LOW = 0, /**< Low GPIO level */ 48 GPIO_VAL_HIGH = 1, /**< High GPIO level */ 49 GPIO_VAL_ERR, /**< Invalid GPIO level */ 50 }; 51 52 /** 53 * @brief Enumerates GPIO directions. 54 * 55 * @since 1.0 56 */ 57 enum GpioDirType { 58 GPIO_DIR_IN = 0, /**< Input direction */ 59 GPIO_DIR_OUT = 1, /**< Output direction */ 60 GPIO_DIR_ERR, /**< Invalid direction */ 61 }; 62 63 /** 64 * @brief Enumerates GPIO irq types. 65 * 66 * @since 1.0 67 */ 68 enum GpioIrqType { 69 /** Trigger is not set */ 70 GPIO_IRQ_TRIGGER_NONE = OSAL_IRQF_TRIGGER_NONE, 71 /** Rising edge triggered */ 72 GPIO_IRQ_TRIGGER_RISING = OSAL_IRQF_TRIGGER_RISING, 73 /** Falling edge triggered */ 74 GPIO_IRQ_TRIGGER_FALLING = OSAL_IRQF_TRIGGER_FALLING, 75 /** High-level triggered */ 76 GPIO_IRQ_TRIGGER_HIGH = OSAL_IRQF_TRIGGER_HIGH, 77 /** Low-level triggered */ 78 GPIO_IRQ_TRIGGER_LOW = OSAL_IRQF_TRIGGER_LOW, 79 /** execute interrupt service routine in thread context */ 80 GPIO_IRQ_USING_THREAD = (0x1 << 8), 81 }; 82 83 /** 84 * @brief Defines the function type of a GPIO interrupt service routine (ISR). 85 * 86 * This function is used when you call {@link GpioSetIrq} to register the ISR for a GPIO pin. 87 * 88 * @param gpio Indicates the GPIO number of the ISR. 89 * @param data Indicates the pointer to the private data passed to this ISR (The data is specified when the ISR 90 * is registered). 91 * 92 * @return Returns <b>0</b> if the ISR function type is successfully defined; returns a negative value otherwise. 93 * @see GpioSetIrq 94 * @since 1.0 95 */ 96 typedef int32_t (*GpioIrqFunc)(uint16_t gpio, void *data); 97 98 /** 99 * @brief Reads the level value of a GPIO pin. 100 * 101 * Before using this function, you need to call {@link GpioSetDir} to set the GPIO pin direction to input. 102 * 103 * @param gpio Indicates the GPIO pin number. 104 * @param val Indicates the pointer to the read level value. For details, see {@link GpioValue}. 105 * 106 * @return Returns <b>0</b> if the GPIO pin level value is successfully read; returns a negative value otherwise. 107 * @since 1.0 108 */ 109 int32_t GpioRead(uint16_t gpio, uint16_t *val); 110 111 /** 112 * @brief Writes the level value for a GPIO pin. 113 * 114 * Before using this function, you need to call {@link GpioSetDir} to set the GPIO pin direction to output. 115 * 116 * @param gpio Indicates the GPIO pin number. 117 * @param val Indicates the level value to be written. For details, see {@link GpioValue}. 118 * 119 * @return Returns <b>0</b> if the GPIO pin level value is successfully written; returns a negative value otherwise. 120 * @since 1.0 121 */ 122 int32_t GpioWrite(uint16_t gpio, uint16_t val); 123 124 /** 125 * @brief Sets the input/output direction for a GPIO pin. 126 * 127 * Generally, you can set the direction to input when external level signals need to be read, and set the 128 * direction to output when the level signals need to be sent externally. 129 * 130 * @param gpio Indicates the GPIO pin number. 131 * @param dir Indicates the direction to set. For details, see {@link GpioDirType}. 132 * 133 * @return Returns <b>0</b> if the GPIO pin direction is successfully set; returns a negative value otherwise. 134 * @since 1.0 135 */ 136 int32_t GpioSetDir(uint16_t gpio, uint16_t dir); 137 138 /** 139 * @brief Obtains the input/output direction of a GPIO pin. 140 * 141 * @param gpio Indicates the GPIO pin number. 142 * @param dir Indicates the pointer to the obtained input/output direction. For details, see {@link GpioDirType}. 143 * 144 * @return Returns <b>0</b> if the GPIO pin direction is successfully obtained; returns a negative value otherwise. 145 * @since 1.0 146 */ 147 int32_t GpioGetDir(uint16_t gpio, uint16_t *dir); 148 149 /** 150 * @brief Sets the ISR function for a GPIO pin. 151 * 152 * Before using a GPIO pin as an interrupt, you must call this function to set an ISR function for this GPIO pin, 153 * including the ISR parameters and the interrupt trigger mode. 154 * After the setting is successful, you also need to call {@link GpioEnableIrq} to enable the interrupt, so that 155 * the ISR function can respond correctly. 156 * 157 * @param gpio Indicates the GPIO pin number. 158 * @param mode Indicates the interrupt trigger mode. For details, see {@link OSAL_IRQF_TRIGGER_RISING}. 159 * @param func Indicates the ISR function to set, which is specified by {@link GpioIrqFunc}. 160 * @param arg Indicates the pointer to the parameters passed to the ISR function. 161 * 162 * @return Returns <b>0</b> if the ISR function of the GPIO pin is successfully set; returns a negative value otherwise. 163 * @since 1.0 164 */ 165 int32_t GpioSetIrq(uint16_t gpio, uint16_t mode, GpioIrqFunc func, void *arg); 166 167 /** 168 * @brief Cancels the setting of the ISR function for a GPIO pin. 169 * 170 * If you do not need the GPIO pin as an interrupt, call this function to cancel the ISR function set via 171 * {@link GpioSetIrq}. Since this ISR function is no longer valid, you are advised to use {@link GpioDisableIrq} to 172 * disable the GPIO pin interrupt. 173 * 174 * @param gpio Indicates the GPIO pin number. 175 * @param arg Indicates the pointer to the parameters passed to the ISR function. 176 * 177 * @return Returns <b>0</b> if the ISR function of the GPIO pin is successfully cancelled; returns a negative value 178 * otherwise. 179 * @since 1.0 180 */ 181 int32_t GpioUnsetIrq(uint16_t gpio, void *arg); 182 183 /** 184 * @brief Enables a GPIO pin interrupt. 185 * 186 * Before enabling the interrupt, you must call {@link GpioSetIrq} to set the ISR function for the GPIO pin. 187 * 188 * @param gpio Indicates the GPIO pin number. 189 * 190 * @return Returns <b>0</b> if the GPIO pin interrupt is successfully enabled; returns a negative value otherwise. 191 * @since 1.0 192 */ 193 int32_t GpioEnableIrq(uint16_t gpio); 194 195 /** 196 * @brief Disables a GPIO pin interrupt. 197 * 198 * You can call this function when you need to temporarily mask a GPIO pin interrupt or cancel an ISR function. 199 * 200 * @param gpio Indicates the GPIO pin number. 201 * 202 * @return Returns <b>0</b> if the GPIO pin interrupt is successfully disabled; returns a negative value otherwise. 203 * @since 1.0 204 */ 205 int32_t GpioDisableIrq(uint16_t gpio); 206 207 /** 208 * @brief Gets the GPIO global number. 209 * 210 * Before using a GPIO pin, you can pass in the GPIO name to get the GPIO global number instead of calculating 211 * it manually. 212 * 213 * @param gpioName Indicates the GPIO pin's name. 214 * 215 * @return Returns greater than or equal to <b>0</b> if gets the GPIO global number successfully ; returns a 216 * negative value otherwise. 217 * @since 1.0 218 */ 219 int32_t GpioGetByName(const char *gpioName); 220 221 #ifdef __cplusplus 222 #if __cplusplus 223 } 224 #endif 225 #endif /* __cplusplus */ 226 227 #endif /* GPIO_IF_H */ 228 /** @} */ 229