1 /** 2 * @file gpio.h 3 * @brief General-Purpose Input/Output (GPIO) function prototypes and data types. 4 */ 5 6 /* **************************************************************************** 7 * Copyright (C) 2016 Maxim Integrated Products, Inc., All Rights Reserved. 8 * 9 * Permission is hereby granted, free of charge, to any person obtaining a 10 * copy of this software and associated documentation files (the "Software"), 11 * to deal in the Software without restriction, including without limitation 12 * the rights to use, copy, modify, merge, publish, distribute, sublicense, 13 * and/or sell copies of the Software, and to permit persons to whom the 14 * Software is furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be included 17 * in all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS 20 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF 21 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 22 * IN NO EVENT SHALL MAXIM INTEGRATED BE LIABLE FOR ANY CLAIM, DAMAGES 23 * OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, 24 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 25 * OTHER DEALINGS IN THE SOFTWARE. 26 * 27 * Except as contained in this notice, the name of Maxim Integrated 28 * Products, Inc. shall not be used except as stated in the Maxim Integrated 29 * Products, Inc. Branding Policy. 30 * 31 * The mere transfer of this software does not imply any licenses 32 * of trade secrets, proprietary technology, copyrights, patents, 33 * trademarks, maskwork rights, or any other form of intellectual 34 * property whatsoever. Maxim Integrated Products, Inc. retains all 35 * ownership rights. 36 * 37 * $Date: 2018-12-18 15:37:22 -0600 (Tue, 18 Dec 2018) $ 38 * $Revision: 40072 $ 39 * 40 *************************************************************************** */ 41 42 /* Define to prevent redundant inclusion */ 43 #ifndef _GPIO_H_ 44 #define _GPIO_H_ 45 46 /* **** Includes **** */ 47 #include "gpio_regs.h" 48 49 #ifdef __cplusplus 50 extern "C" { 51 #endif 52 53 /** 54 * @defgroup gpio General-Purpose Input/Output (GPIO) 55 * @ingroup periphlibs 56 * @{ 57 */ 58 59 /* **** Definitions **** */ 60 /** 61 * @defgroup gpio_port_pin Port and Pin Definitions 62 * @ingroup gpio 63 * @{ 64 * @defgroup gpio_port Port Definitions 65 * @ingroup gpio_port_pin 66 * @{ 67 */ 68 #define PORT_0 ((uint32_t)(0UL)) /**< Port 0 Define*/ 69 #define PORT_1 ((uint32_t)(1UL)) /**< Port 1 Define*/ 70 #define PORT_2 ((uint32_t)(2UL)) /**< Port 2 Define*/ 71 #define PORT_3 ((uint32_t)(3UL)) /**< Port 3 Define*/ 72 #define PORT_4 ((uint32_t)(4UL)) /**< Port 4 Define*/ 73 /**@} end of gpio_port group*/ 74 /** 75 * @defgroup gpio_pin Pin Definitions 76 * @ingroup gpio_port_pin 77 * @{ 78 */ 79 #define PIN_0 ((uint32_t)(1UL << 0)) /**< Pin 0 Define */ 80 #define PIN_1 ((uint32_t)(1UL << 1)) /**< Pin 1 Define */ 81 #define PIN_2 ((uint32_t)(1UL << 2)) /**< Pin 2 Define */ 82 #define PIN_3 ((uint32_t)(1UL << 3)) /**< Pin 3 Define */ 83 #define PIN_4 ((uint32_t)(1UL << 4)) /**< Pin 4 Define */ 84 #define PIN_5 ((uint32_t)(1UL << 5)) /**< Pin 5 Define */ 85 #define PIN_6 ((uint32_t)(1UL << 6)) /**< Pin 6 Define */ 86 #define PIN_7 ((uint32_t)(1UL << 7)) /**< Pin 7 Define */ 87 #define PIN_8 ((uint32_t)(1UL << 8)) /**< Pin 8 Define */ 88 #define PIN_9 ((uint32_t)(1UL << 9)) /**< Pin 9 Define */ 89 #define PIN_10 ((uint32_t)(1UL << 10)) /**< Pin 10 Define */ 90 #define PIN_11 ((uint32_t)(1UL << 11)) /**< Pin 11 Define */ 91 #define PIN_12 ((uint32_t)(1UL << 12)) /**< Pin 12 Define */ 92 #define PIN_13 ((uint32_t)(1UL << 13)) /**< Pin 13 Define */ 93 #define PIN_14 ((uint32_t)(1UL << 14)) /**< Pin 14 Define */ 94 #define PIN_15 ((uint32_t)(1UL << 15)) /**< Pin 15 Define */ 95 #define PIN_16 ((uint32_t)(1UL << 16)) /**< Pin 16 Define */ 96 #define PIN_17 ((uint32_t)(1UL << 17)) /**< Pin 17 Define */ 97 #define PIN_18 ((uint32_t)(1UL << 18)) /**< Pin 18 Define */ 98 #define PIN_19 ((uint32_t)(1UL << 19)) /**< Pin 19 Define */ 99 #define PIN_20 ((uint32_t)(1UL << 20)) /**< Pin 20 Define */ 100 #define PIN_21 ((uint32_t)(1UL << 21)) /**< Pin 21 Define */ 101 #define PIN_22 ((uint32_t)(1UL << 22)) /**< Pin 22 Define */ 102 #define PIN_23 ((uint32_t)(1UL << 23)) /**< Pin 23 Define */ 103 #define PIN_24 ((uint32_t)(1UL << 24)) /**< Pin 24 Define */ 104 #define PIN_25 ((uint32_t)(1UL << 25)) /**< Pin 25 Define */ 105 #define PIN_26 ((uint32_t)(1UL << 26)) /**< Pin 26 Define */ 106 #define PIN_27 ((uint32_t)(1UL << 27)) /**< Pin 27 Define */ 107 #define PIN_28 ((uint32_t)(1UL << 28)) /**< Pin 28 Define */ 108 #define PIN_29 ((uint32_t)(1UL << 29)) /**< Pin 29 Define */ 109 #define PIN_30 ((uint32_t)(1UL << 30)) /**< Pin 30 Define */ 110 #define PIN_31 ((uint32_t)(1UL << 31)) /**< Pin 31 Define */ 111 /**@} end of gpio_pin group */ 112 /**@} end of gpio_port_pin group */ 113 114 /** 115 * Enumeration type for the GPIO Function Type 116 */ 117 typedef enum { 118 GPIO_FUNC_IN, /**< GPIO Input */ 119 GPIO_FUNC_OUT, /**< GPIO Output */ 120 GPIO_FUNC_ALT1, /**< Alternate Function Selection */ 121 GPIO_FUNC_ALT2, /**< Alternate Function Selection */ 122 GPIO_FUNC_ALT3, /**< Alternate Function Selection */ 123 GPIO_FUNC_ALT4, /**< Alternate Function Selection */ 124 } gpio_func_t; 125 126 /** 127 * Enumeration type for the type of GPIO pad on a given pin. 128 */ 129 typedef enum { 130 GPIO_PAD_NONE, /**< No pull-up or pull-down */ 131 GPIO_PAD_PULL_UP, /**< Set pad to weak pull-up */ 132 GPIO_PAD_PULL_DOWN, /**< Set pad to weak pull-down */ 133 } gpio_pad_t; 134 135 /** 136 * Structure type for configuring a GPIO port. 137 */ 138 typedef struct { 139 uint32_t port; /**< Index of GPIO port */ 140 uint32_t mask; /**< Pin mask (multiple pins may be set) */ 141 gpio_func_t func; /**< Function type */ 142 gpio_pad_t pad; /**< Pad type */ 143 } gpio_cfg_t; 144 145 /** 146 * Enumeration type for the interrupt modes. 147 */ 148 typedef enum { 149 GPIO_INT_LEVEL = 0, /**< Interrupt is level sensitive */ 150 GPIO_INT_EDGE = 1 /**< Interrupt is edge sensitive */ 151 } gpio_int_mode_t; 152 153 /** 154 * Enumeration type for the interrupt polarity. 155 */ 156 typedef enum { 157 GPIO_INT_FALLING = 0, /**< Interrupt triggers on falling edge */ 158 GPIO_INT_HIGH = GPIO_INT_FALLING, /**< Interrupt triggers when level is high */ 159 GPIO_INT_RISING, /**< Interrupt triggers on rising edge */ 160 GPIO_INT_LOW = GPIO_INT_RISING, /**< Interrupt triggers when level is low */ 161 GPIO_INT_BOTH /**< Interrupt triggers on either edge */ 162 } gpio_int_pol_t; 163 164 /* **** Function Prototypes **** */ 165 166 /** 167 * @brief Initialize GPIO. 168 * @return #E_NO_ERROR if everything is successful. 169 */ 170 int GPIO_Init(void); 171 172 /** 173 * @brief Configure GPIO pin(s). 174 * @param cfg Pointer to configuration structure describing the pin. 175 * @return #E_NO_ERROR if everything is successful. 176 */ 177 int GPIO_Config(const gpio_cfg_t *cfg); 178 179 /** 180 * @brief Gets the pin(s) input state. 181 * @param cfg Pointer to configuration structure describing the pin. 182 * @return The requested pin state. 183 */ 184 uint32_t GPIO_InGet(const gpio_cfg_t *cfg); 185 186 /** 187 * @brief Sets the pin(s) to a high level output. 188 * @param cfg Pointer to configuration structure describing the pin. 189 * 190 */ 191 void GPIO_OutSet(const gpio_cfg_t *cfg); 192 193 /** 194 * @brief Clears the pin(s) to a low level output. 195 * @param cfg Pointer to configuration structure describing the pin. 196 * 197 */ 198 void GPIO_OutClr(const gpio_cfg_t *cfg); 199 200 /** 201 * @brief Gets the pin(s) output state. 202 * @param cfg Pointer to configuration structure describing the pin. 203 * 204 * @return The state of the requested pin. 205 * 206 */ 207 uint32_t GPIO_OutGet(const gpio_cfg_t *cfg); 208 209 /** 210 * @brief Write the pin(s) to a desired output level. 211 * @param cfg Pointer to configuration structure describing the pin. 212 * @param val Desired output level of the pin(s). This will be masked 213 * with the configuration mask. 214 */ 215 void GPIO_OutPut(const gpio_cfg_t *cfg, uint32_t val); 216 217 /** 218 * @brief Toggles the the pin(s) output level. 219 * @param cfg Pointer to configuration structure describing the pin. 220 * 221 */ 222 void GPIO_OutToggle(const gpio_cfg_t *cfg); 223 224 /** 225 * @brief Configure GPIO interrupt(s) 226 * @param cfg Pointer to configuration structure describing the pin. 227 * @param mode Requested interrupt mode. 228 * @param pol Requested interrupt polarity. 229 * @return #E_NO_ERROR if everything is successful. 230 */ 231 int GPIO_IntConfig(const gpio_cfg_t *cfg, gpio_int_mode_t mode, gpio_int_pol_t pol); 232 233 /** 234 * @brief Enables the specified GPIO interrupt 235 * @param cfg Pointer to configuration structure describing the pin. 236 * 237 */ 238 void GPIO_IntEnable(const gpio_cfg_t *cfg); 239 240 /** 241 * @brief Disables the specified GPIO interrupt. 242 * @param cfg Pointer to configuration structure describing the pin. 243 */ 244 void GPIO_IntDisable(const gpio_cfg_t *cfg); 245 246 /** 247 * @brief Gets the interrupt(s) status on a GPIO pin. 248 * @param cfg Pointer to configuration structure describing the pin 249 * for which the status is being requested. 250 * @return The requested interrupt status. 251 */ 252 uint32_t GPIO_IntStatus(const gpio_cfg_t *cfg); 253 254 /** 255 * @brief Clears the interrupt(s) status on a GPIO pin. 256 * @param cfg Pointer to configuration structure describing the pin 257 * to clear the interrupt state of. 258 */ 259 void GPIO_IntClr(const gpio_cfg_t *cfg); 260 261 /** 262 * @brief Type alias for a GPIO callback function with prototype: 263 * @code 264 void callback_fn(void *cbdata); 265 * @endcode 266 * @param cbdata A void pointer to the data type as registered when 267 * GPIO_RegisterCallback() was called. 268 */ 269 typedef void (*gpio_callback_fn)(void *cbdata); 270 271 /** 272 * @brief Registers a callback for the interrupt on a given port and pin. 273 * @param cfg Pointer to configuration structure describing the pin 274 * @param callback A pointer to a function of type \c #gpio_callback_fn. 275 * @param cbdata The parameter to be passed to the callback function, #gpio_callback_fn, when an interrupt occurs. 276 * 277 */ 278 void GPIO_RegisterCallback(const gpio_cfg_t *cfg, gpio_callback_fn callback, void *cbdata); 279 280 /** 281 * @brief GPIO IRQ Handler. @note If a callback is registered for a given 282 * interrupt, the callback function will be called. 283 * 284 * @param port number of the port that generated the interrupt service routine. 285 * 286 */ 287 void GPIO_Handler(unsigned int port); 288 289 /**@} end of group gpio */ 290 291 #ifdef __cplusplus 292 } 293 #endif 294 295 #endif /* _GPIO_H_ */ 296