1 /* 2 * Copyright 2018-2020 NXP 3 * All rights reserved. 4 * 5 * 6 * SPDX-License-Identifier: BSD-3-Clause 7 */ 8 9 #ifndef __HAL_GPIO_H__ 10 #define __HAL_GPIO_H__ 11 12 #include "fsl_common.h" 13 #if defined(SDK_OS_FREE_RTOS) 14 #include "FreeRTOS.h" 15 #endif 16 17 /*! 18 * @addtogroup GPIO_Adapter 19 * @{ 20 */ 21 22 /******************************************************************************* 23 * Public macro 24 ******************************************************************************/ 25 /*! @name Driver version */ 26 /*@{*/ 27 #define FSL_GPIO_ADAPTER_VERSION (MAKE_VERSION(1, 0, 1)) /*!< Version 1.0.1. */ 28 /*@}*/ 29 30 /*! @brief Definition of GPIO conflict check Enable. */ 31 #ifndef HAL_GPIO_CONFLICT_CHECK_ENABLE 32 #define HAL_GPIO_CONFLICT_CHECK_ENABLE (1) 33 #endif 34 35 /*! @brief Definition of GPIO adapter handle size. */ 36 #define HAL_GPIO_HANDLE_SIZE (16U) 37 38 /*! 39 * @brief Defines the gpio handle 40 * 41 * This macro is used to define a 4 byte aligned gpio handle. 42 * Then use "(hal_gpio_handle_t)name" to get the gpio handle. 43 * 44 * The macro should be global and could be optional. You could also define gpio handle by yourself. 45 * 46 * This is an example, 47 * @code 48 * GPIO_HANDLE_DEFINE(gpioHandle); 49 * @endcode 50 * 51 * @param name The name string of the gpio handle. 52 */ 53 #define GPIO_HANDLE_DEFINE(name) uint32_t name[((HAL_GPIO_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))] 54 55 /*! @brief Definition of GPIO adapter isr priority. */ 56 #ifndef HAL_GPIO_ISR_PRIORITY 57 #if defined(__GIC_PRIO_BITS) 58 #define HAL_GPIO_ISR_PRIORITY (25U) 59 #else 60 #if defined(configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) 61 #define HAL_GPIO_ISR_PRIORITY (configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) 62 #else 63 /* The default value 3 is used to support different ARM Core, such as CM0P, CM4, CM7, and CM33, etc. 64 * The minimum number of priority bits implemented in the NVIC is 2 on these SOCs. The value of mininum 65 * priority is 3 (2^2 - 1). So, the default value is 3. 66 */ 67 #define HAL_GPIO_ISR_PRIORITY (3U) 68 #endif /* defined(configLIBRARY_MAX_SYSCALL_INTERRUPT_PRIORITY) */ 69 #endif /* defined(__GIC_PRIO_BITS) */ 70 #endif /* HAL_GPIO_ISR_PRIORITY */ 71 72 /******************************************************************************* 73 * Definitions 74 ******************************************************************************/ 75 /*! @brief The handle of GPIO adapter. */ 76 typedef void *hal_gpio_handle_t; 77 78 /*! @brief The callback function of GPIO adapter. */ 79 typedef void (*hal_gpio_callback_t)(void *param); 80 81 /*! @brief The interrupt trigger of GPIO adapter. */ 82 typedef enum _hal_gpio_interrupt_trigger 83 { 84 kHAL_GpioInterruptDisable = 0x0U, /*!< Interrupt disable. */ 85 kHAL_GpioInterruptLogicZero = 0x1U, /*!< Interrupt when logic zero. */ 86 kHAL_GpioInterruptRisingEdge = 0x2U, /*!< Interrupt on rising edge. */ 87 kHAL_GpioInterruptFallingEdge = 0x3U, /*!< Interrupt on falling edge. */ 88 kHAL_GpioInterruptEitherEdge = 0x4U, /*!< Interrupt on either edge. */ 89 kHAL_GpioInterruptLogicOne = 0x5U, /*!< Interrupt when logic one. */ 90 } hal_gpio_interrupt_trigger_t; 91 92 /*! @brief The status of GPIO adapter. */ 93 typedef enum _hal_gpio_status 94 { 95 kStatus_HAL_GpioSuccess = kStatus_Success, /*!< Success */ 96 kStatus_HAL_GpioError = MAKE_STATUS(kStatusGroup_HAL_GPIO, 1), /*!< Failed */ 97 kStatus_HAL_GpioLackSource = MAKE_STATUS(kStatusGroup_HAL_GPIO, 2), /*!< Lack of sources */ 98 kStatus_HAL_GpioPinConflict = MAKE_STATUS(kStatusGroup_HAL_GPIO, 3), /*!< PIN conflict */ 99 } hal_gpio_status_t; 100 101 /*! @brief The direction of GPIO adapter. */ 102 typedef enum _hal_gpio_direction 103 { 104 kHAL_GpioDirectionIn = 0x00U, /*!< Out */ 105 kHAL_GpioDirectionOut, /*!< In */ 106 } hal_gpio_direction_t; 107 108 /*! @brief The pin config struct of GPIO adapter. */ 109 typedef struct _hal_gpio_pin_config 110 { 111 hal_gpio_direction_t direction; 112 uint8_t level; 113 uint8_t port; 114 uint8_t pin; 115 } hal_gpio_pin_config_t; 116 117 /******************************************************************************* 118 * API 119 ******************************************************************************/ 120 121 #if defined(__cplusplus) 122 extern "C" { 123 #endif /* __cplusplus */ 124 125 /*! 126 * @brief Initializes static variable located in .bss section. 127 * 128 * This function is used to initialize variable located in .bss section. 129 * Usually users don't need to call this API. 130 * It's just used in the case GPIO adapter is used before .bss section is automatically cleaned up by IDE. 131 * Example below shows how to use this API. 132 * @code 133 * HAL_GpioPreInit(); 134 * GPIO_HANDLE_DEFINE(g_GpioHandle); 135 * hal_gpio_pin_config_t config; 136 * config.direction = kHAL_GpioDirectionOut; 137 * config.port = 0; 138 * config.pin = 0; 139 * config.level = 0; 140 * HAL_GpioInit((hal_gpio_handle_t)g_GpioHandle, &config); 141 * @endcode 142 */ 143 void HAL_GpioPreInit(void); 144 145 /*! 146 * @brief Initializes an GPIO instance with the GPIO handle and the user configuration structure. 147 * 148 * This function configures the GPIO module with user-defined settings. The user can configure the configuration 149 * structure. The parameter gpioHandle is a pointer to point to a memory space of size #HAL_GPIO_HANDLE_SIZE allocated 150 * by the caller. Example below shows how to use this API to configure the GPIO. 151 * @code 152 * GPIO_HANDLE_DEFINE(g_GpioHandle); 153 * hal_gpio_pin_config_t config; 154 * config.direction = kHAL_GpioDirectionOut; 155 * config.port = 0; 156 * config.pin = 0; 157 * config.level = 0; 158 * HAL_GpioInit((hal_gpio_handle_t)g_GpioHandle, &config); 159 * @endcode 160 * 161 * @param gpioHandle GPIO handle pointer. 162 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 163 * You can define the handle in the following two ways: 164 * #GPIO_HANDLE_DEFINE(gpioHandle); 165 * or 166 * uint32_t gpioHandle[((HAL_GPIO_HANDLE_SIZE + sizeof(uint32_t) - 1U) / sizeof(uint32_t))]; 167 * @param pinConfig Pointer to user-defined configuration structure. 168 * @retval kStatus_HAL_GpioError An error occurred while initializing the GPIO. 169 * @retval kStatus_HAL_GpioPinConflict The pair of the pin and port passed by pinConfig is initialized. 170 * @retval kStatus_HAL_GpioSuccess GPIO initialization succeed 171 */ 172 hal_gpio_status_t HAL_GpioInit(hal_gpio_handle_t gpioHandle, hal_gpio_pin_config_t *pinConfig); 173 174 /*! 175 * @brief Deinitializes a GPIO instance. 176 * 177 * This function disables the trigger mode. 178 * 179 * @param gpioHandle GPIO handle pointer. 180 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 181 * @retval kStatus_HAL_GpioSuccess GPIO de-initialization succeed 182 */ 183 hal_gpio_status_t HAL_GpioDeinit(hal_gpio_handle_t gpioHandle); 184 185 /*! 186 * @brief Gets the pin voltage. 187 * 188 * This function gets the pin voltage. 0 - low level voltage, 1 - high level voltage. 189 * 190 * @param gpioHandle GPIO handle pointer. 191 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 192 * @param pinState A pointer to save the pin state. 193 * @retval kStatus_HAL_GpioSuccess Get successfully. 194 */ 195 hal_gpio_status_t HAL_GpioGetInput(hal_gpio_handle_t gpioHandle, uint8_t *pinState); 196 197 /*! 198 * @brief Sets the pin voltage. 199 * 200 * This function sets the pin voltage. 0 - low level voltage, 1 - high level voltage. 201 * 202 * @param gpioHandle GPIO handle pointer. 203 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 204 * @param pinState Pin state. 205 * @retval kStatus_HAL_GpioSuccess Set successfully. 206 */ 207 hal_gpio_status_t HAL_GpioSetOutput(hal_gpio_handle_t gpioHandle, uint8_t pinState); 208 209 /*! 210 * @brief Gets the pin interrupt trigger mode. 211 * 212 * This function gets the pin interrupt trigger mode. The trigger mode please refer to 213 * #hal_gpio_interrupt_trigger_t. 214 * 215 * @param gpioHandle GPIO handle pointer. 216 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 217 * @param gpioTrigger A pointer to save the pin trigger mode value. 218 * @retval kStatus_HAL_GpioSuccess Get successfully. 219 * @retval kStatus_HAL_GpioError The pin is the ouput setting. 220 */ 221 hal_gpio_status_t HAL_GpioGetTriggerMode(hal_gpio_handle_t gpioHandle, hal_gpio_interrupt_trigger_t *gpioTrigger); 222 223 /*! 224 * @brief Sets the pin interrupt trigger mode. 225 * 226 * This function sets the pin interrupt trigger mode. The trigger mode please refer to 227 * #hal_gpio_interrupt_trigger_t. 228 * 229 * @param gpioHandle GPIO handle pointer. 230 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 231 * @param gpioTrigger The pin trigger mode value. 232 * @retval kStatus_HAL_GpioSuccess Set successfully. 233 * @retval kStatus_HAL_GpioError The pin is the ouput setting. 234 */ 235 hal_gpio_status_t HAL_GpioSetTriggerMode(hal_gpio_handle_t gpioHandle, hal_gpio_interrupt_trigger_t gpioTrigger); 236 237 /*! 238 * @brief Installs a callback and callback parameter. 239 * 240 * This function is used to install the callback and callback parameter for GPIO module. 241 * When the pin state interrupt happened, the driver will notify the upper layer by the installed callback 242 * function. After the callback called, the GPIO pin state can be got by calling function #HAL_GpioGetInput. 243 * 244 * @param gpioHandle GPIO handle pointer. 245 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 246 * @param callback The callback function. 247 * @param callbackParam The parameter of the callback function. 248 * @retval kStatus_HAL_GpioSuccess Successfully install the callback. 249 */ 250 hal_gpio_status_t HAL_GpioInstallCallback(hal_gpio_handle_t gpioHandle, 251 hal_gpio_callback_t callback, 252 void *callbackParam); 253 254 /*! 255 * @brief Enables or disables the GPIO wake-up feature. 256 * 257 * This function enables or disables the GPIO wake-up feature. 258 * 259 * @param gpioHandle GPIO handle pointer. 260 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 261 * @param enable enable or disable (0 - disable, 1 - enable). 262 * @retval kStatus_HAL_GpioError An error occurred. 263 * @retval kStatus_HAL_GpioSuccess Set successfully. 264 */ 265 hal_gpio_status_t HAL_GpioWakeUpSetting(hal_gpio_handle_t gpioHandle, uint8_t enable); 266 267 /*! 268 * @brief Prepares to enter low power consumption. 269 * 270 * This function is used to prepare to enter low power consumption. 271 * 272 * @param gpioHandle GPIO handle pointer. 273 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 274 * @retval kStatus_HAL_GpioSuccess Successful operation. 275 */ 276 hal_gpio_status_t HAL_GpioEnterLowpower(hal_gpio_handle_t gpioHandle); 277 278 /*! 279 * @brief Restores from low power consumption. 280 * 281 * This function is used to restore from low power consumption. 282 * 283 * @param gpioHandle GPIO handle pointer. 284 * The handle should be 4 byte aligned, because unaligned access doesn't be supported on some devices. 285 * @retval kStatus_HAL_GpioSuccess Successful operation. 286 */ 287 hal_gpio_status_t HAL_GpioExitLowpower(hal_gpio_handle_t gpioHandle); 288 289 #if defined(__cplusplus) 290 } 291 #endif /* __cplusplus */ 292 /*! @}*/ 293 #endif /* __HAL_GPIO_H__ */ 294
