1 /* 2 * Copyright (c) 2015-2024, Texas Instruments Incorporated 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions 7 * are met: 8 * 9 * * Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 12 * * Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * * Neither the name of Texas Instruments Incorporated nor the names of 17 * its contributors may be used to endorse or promote products derived 18 * from this software without specific prior written permission. 19 * 20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, 22 * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 27 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 28 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 29 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 30 * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 */ 32 /*!**************************************************************************** 33 * @file GPIO.h 34 * 35 * @brief General Purpose I/O driver interface. 36 * 37 * The GPIO header file should be included in an application as follows: 38 * @code 39 * #include <ti/drivers/GPIO.h> 40 * @endcode 41 * 42 * # Overview # 43 * The GPIO module allows you to manage General Purpose I/O pins via simple 44 * and portable APIs. GPIO pin behavior is usually configured statically, 45 * but can also be configured or reconfigured at runtime. 46 * 47 * Because of its simplicity, the GPIO driver does not follow the model of 48 * other TI-RTOS drivers in which a driver application interface has 49 * separate device-specific implementations. This difference is most 50 * apparent in the GPIOxxx_Config structure, which does not require you to 51 * specify a particular function table or object. 52 * 53 * # Usage # 54 * This section provides a basic \ref ti_drivers_GPIO_Synopsis 55 * "usage summary" and a set of \ref ti_drivers_GPIO_Examples "examples" 56 * in the form of commented code fragments. Detailed descriptions of the 57 * GPIO APIs and their effect are provided in subsequent sections. 58 * 59 * @anchor ti_drivers_GPIO_Synopsis 60 * ### Synopsis # 61 * @anchor ti_drivers_GPIO_Synopsis_Code 62 * @code 63 * // Import GPIO Driver definitions 64 * #include <ti/drivers/GPIO.h> 65 * 66 * // Define names for GPIO pin indexes 67 * #define BUTTON 0 68 * #define LED 1 69 * 70 * // One-time init of GPIO driver 71 * GPIO_init(); 72 * 73 * // Read GPIO pin 74 * unsigned int state = GPIO_read(BUTTON); 75 * 76 * // Write to GPIO pin 77 * GPIO_write(LED, state); 78 * @endcode 79 * 80 * @anchor ti_drivers_GPIO_Examples 81 * ### Examples # 82 * * @ref ti_drivers_GPIO_Example_callback "Creating an input callback" 83 * * @ref ti_drivers_GPIO_Example_reconfigure "Runtime pin configuration" 84 * 85 * @anchor ti_drivers_GPIO_Example_callback 86 * **Creating an input callback**: The following example demonstrates how 87 * to configure a GPIO pin to generate an interrupt and how to toggle an 88 * an LED on and off within the registered interrupt callback function. Pin 89 * configuration is handled within Sysconfig for this example. 90 * @code 91 * // Driver header file 92 * #include <ti/drivers/GPIO.h> 93 * 94 * // TI Drivers Configuration 95 * #include "ti_drivers_config.h" 96 * 97 * // GPIO button call back function 98 * void gpioButton0Fxn(uint_least8_t index); 99 * 100 * main() 101 * { 102 * // Turn on user LED 103 * GPIO_write(CONFIG_GPIO_LED0, CONFIG_GPIO_LED_ON); 104 * 105 * // install Button callback and enable interrupts 106 * GPIO_setCallback(CONFIG_GPIO_BUTTON0, gpioButton0Fxn); 107 * GPIO_enableInt(CONFIG_GPIO_BUTTON0); 108 * } 109 * 110 * // 111 * // ======== gpioButton0Fxn ======== 112 * // Callback function for the GPIO interrupt on CONFIG_GPIO_BUTTON0 113 * // 114 * // Note: index is the GPIO id for the button which is not used here 115 * // 116 * void gpioButton0Fxn(uint_least8_t index) 117 * { 118 * // Toggle the LED 119 * GPIO_toggle(CONFIG_GPIO_LED0); 120 * } 121 * @endcode 122 * 123 * @anchor ti_drivers_GPIO_Example_reconfigure 124 * **Runtime pin configuration**: The following example demonstrates how 125 * to (re)configure GPIO pins. 126 * @code 127 * // Driver header file 128 * #include <ti/drivers/GPIO.h> 129 * 130 * // TI Driver configuration 131 * #include "ti_drivers_config.h" 132 * 133 * void main() 134 * { 135 * // One-time init of GPIO driver 136 * GPIO_init(); 137 * 138 * // Configure a button pin as input and configure its interrupt 139 * // Passing INT_ENABLE means you do not need to also call GPIO_enableInt() 140 * GPIO_setConfig( 141 * CONFIG_GPIO_BUTTON0, 142 * GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING | GPIO_CFG_INT_ENABLE 143 * ); 144 * 145 * // Configure an LED output pin 146 * GPIO_setConfig(CONFIG_GPIO_LED0, GPIO_CFG_OUT_STD | GPIO_CFG_OUT_LOW); 147 * } 148 * @endcode 149 * 150 * ### GPIO Driver Configuration # 151 * 152 * In order to use the GPIO APIs, the application is required 153 * to provide 3 structures in the ti_drivers_config.c file: 154 * 1. An array of @ref GPIO_PinConfig elements that defines the 155 * initial configuration of each pin on the device. A pin is then 156 * referenced in the application by its corresponding index in this 157 * array. The pin type (that is, INPUT/OUTPUT), its initial state (that is 158 * OUTPUT_HIGH or LOW), interrupt behavior (RISING/FALLING edge, etc.), and 159 * device specific pin identification are configured in each element 160 * of this array (see @ref GPIO_PinConfigSettings). 161 * Below is a device specific example of the GPIO_PinConfig array: 162 * @code 163 * // 164 * // Array of Pin configurations 165 * // 166 * GPIO_PinConfig gpioPinConfigs[31] = { 167 * GPIO_CFG_INPUT, // DIO_0 168 * GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_NONE, // CONFIG_GPIO_LP19 169 * GPIO_CFG_INPUT, // DIO_2 170 * GPIO_CFG_INPUT, // DIO_3 171 * ... 172 * }; 173 * @endcode 174 * 175 * 2. An array of @ref GPIO_CallbackFxn elements that is used to store 176 * callback function pointers for GPIO pins. The indexes for these array 177 * elements correspond to the pins defined in the GPIO_pinConfig array. 178 * These function pointers can be defined statically by referencing the 179 * callback function name in the array element, or dynamically, by setting 180 * the array element to NULL and using GPIO_setCallback() at runtime to 181 * plug the callback entry. The callback function syntax should match the 182 * following: 183 * @code 184 * void (*GPIO_CallbackFxn)(uint_least8_t index); 185 * @endcode 186 * The index parameter is the same index that was passed to 187 * GPIO_setCallback(). This allows the same callback function to be used 188 * for multiple GPIO interrupts, by using the index to identify the GPIO 189 * that caused the interrupt. 190 * @remark Callback functions are called in the context of an interrupt 191 * service routine and should be designed accordingly. 192 * 193 * When an interrupt is triggered, the interrupt status of all 194 * (interrupt enabled) pins on a port will be read, cleared, and the 195 * respective callbacks will be executed. Callbacks will be called in order 196 * from least significant bit to most significant bit. 197 * Below is a device specific example of the GPIO_CallbackFxn array: 198 * @code 199 * // 200 * // Array of callback function pointers 201 * // 202 * GPIO_CallbackFxn gpioCallbackFunctions[31] = { 203 * NULL, // DIO_0 204 * NULL, // DIO_1 205 * myGpioCallback, // CONFIG_GPIO_LP19 206 * NULL, // DIO_3 207 * ... 208 * }; 209 * @endcode 210 * 211 * 3. A device specific GPIO_Config structure that tells the GPIO 212 * driver where the two aforementioned arrays are and the number of elements 213 * in each. The interrupt priority of all pins configured to generate 214 * interrupts is also specified here. Values for the interrupt priority are 215 * device-specific. You should be well-acquainted with the interrupt 216 * controller used in your device before setting this parameter to a 217 * non-default value. The sentinel value of (~0) (the default value) is 218 * used to indicate that the lowest possible priority should be used. 219 * Below is a device specific example of a GPIO_Config structure: 220 * @code 221 * // 222 * // ======== GPIO_config ======== 223 * // 224 * const GPIO_Config GPIO_config = { 225 * .configs = (GPIO_PinConfig *)gpioPinConfigs, 226 * .callbacks = (GPIO_CallbackFxn *)gpioCallbackFunctions, 227 * .intPriority = (~0) 228 * }; 229 * @endcode 230 * 231 * ### Initializing the GPIO Driver # 232 * 233 * GPIO_init() must be called before any other GPIO APIs. This function 234 * configures each GPIO pin in the user-provided @ref GPIO_PinConfig 235 * array according to the defined settings. The user can also reconfigure 236 * a pin dynamically after GPIO_init() is called by using the 237 * GPIO_setConfig(), and GPIO_setCallback() APIs. 238 * 239 * GPIO_init() is called from Board_init() by default. Calling GPIO_init() 240 * multiple times is safe. 241 * 242 * # Implementation # 243 * 244 * Unlike most other TI-RTOS drivers, there is no notion of an instance 245 * 'handle' with the GPIO driver. This allows lightweight pin control with 246 * minimal runtime and memory overhead. 247 * 248 * GPIO pins are always referenced by device DIO index. 249 * 250 ****************************************************************************** 251 */ 252 253 #ifndef ti_drivers_GPIO__include 254 #define ti_drivers_GPIO__include 255 256 #include <stdint.h> 257 258 #include <ti/devices/DeviceFamily.h> 259 260 /* The device-specific header is used to map GPIO_CFG_X_INTERNAL definitions 261 * directly to device-specific configuration values, allowing efficient runtime 262 * reconfiguration without the need for bit twiddling. 263 */ 264 #if (DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X0_CC26X0 || \ 265 DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X1_CC26X1 || \ 266 DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X2_CC26X2 || \ 267 DeviceFamily_PARENT == DeviceFamily_PARENT_CC13X4_CC26X3_CC26X4) 268 #include <ti/drivers/gpio/GPIOCC26XX.h> 269 #elif (DeviceFamily_PARENT == DeviceFamily_PARENT_CC23X0 || DeviceFamily_PARENT == DeviceFamily_PARENT_CC27XX) 270 #include <ti/drivers/gpio/GPIOLPF3.h> 271 #elif (DeviceFamily_PARENT == DeviceFamily_PARENT_CC35XX) 272 #include <ti/drivers/gpio/GPIOWFF3.h> 273 #endif 274 275 /* Generic functions for converting pin indexes to and from masks. Internal use 276 * only. CLZ is an ARM instruction for `count leading zeroes`, so if multiple 277 * bits in the pinmask are set MASK_TO_PIN will only return the highest set 278 * bit. PIN_TO_MASK is used for setting registers. 279 */ 280 #if defined(__IAR_SYSTEMS_ICC__) 281 #include <intrinsics.h> 282 #define GPIO_MASK_TO_PIN(pinmask) (31 - __CLZ(pinmask)) 283 #elif defined(__TI_COMPILER_VERSION__) 284 #include <arm_acle.h> 285 #define GPIO_MASK_TO_PIN(pinmask) (31 - __clz(pinmask)) 286 #elif defined(__GNUC__) && !defined(__TI_COMPILER_VERSION__) 287 #include <arm_acle.h> 288 #define GPIO_MASK_TO_PIN(pinmask) (31 - __builtin_clz(pinmask)) 289 #endif 290 291 #define GPIO_PIN_TO_MASK(pin) (1 << (pin)) 292 293 #ifdef __cplusplus 294 extern "C" { 295 #endif 296 297 /** 298 * @name GPIO_STATUS_* macros are general status codes returned by GPIO driver APIs. 299 * @{ 300 */ 301 302 /*! 303 * @brief Successful status code returned by GPIO_setConfig(). 304 * 305 * GPI_setConfig() returns GPIO_STATUS_SUCCESS if the API was executed 306 * successfully. 307 */ 308 #define GPIO_STATUS_SUCCESS (0) 309 310 /*! 311 * @brief Generic error status code returned by GPIO_setConfig(). 312 * 313 * GPI_setConfig() returns GPIO_STATUS_ERROR if the API was not executed 314 * successfully. 315 */ 316 #define GPIO_STATUS_ERROR (-1) 317 /** @}*/ 318 319 /*! 320 * @brief GPIO pin configuration settings 321 * 322 * The meaning of the bits within PinConfig are entirely device-specific 323 * and are typically one-to-one with the hardware register controlling pin 324 * configuration. 325 * 326 * Only create and manipulate these values using GPIO_CFG_* defines. 327 */ 328 typedef uint32_t GPIO_PinConfig; 329 330 /*! 331 * @brief Dummy value for "this pin is not assigned to a GPIO". 332 * 333 * Not for use in customer software. Some drivers use this value to manage the 334 * behaviour of optional pins (e.g. UART flow control, SPI chip select). If you 335 * pass this value to any GPIO methods, it will return immediately and no 336 * register writes will be performed. 337 */ 338 #define GPIO_INVALID_INDEX 0xFF 339 340 /*! 341 * \defgroup GPIO_PinConfigSettings Macros used to configure GPIO pins 342 * @{ 343 */ 344 /** @name GPIO_PinConfig output pin configuration macros 345 * @{ 346 */ 347 /*! @hideinitializer Pin is an output. Equivalent to OUT_STD. */ 348 #define GPIO_CFG_OUTPUT GPIO_CFG_OUTPUT_INTERNAL | GPIO_CFG_PULL_NONE_INTERNAL 349 /*! @hideinitializer Output pin is actively driven high and low */ 350 #define GPIO_CFG_OUT_STD GPIO_CFG_OUTPUT_INTERNAL | GPIO_CFG_PULL_NONE_INTERNAL 351 /*! @hideinitializer Output pin is Open Drain */ 352 #define GPIO_CFG_OUT_OD_NOPULL GPIO_CFG_OUTPUT_OPEN_DRAIN_INTERNAL | GPIO_CFG_PULL_NONE_INTERNAL 353 /*! @hideinitializer Output pin is Open Drain w/ pull up */ 354 #define GPIO_CFG_OUT_OD_PU GPIO_CFG_OUTPUT_OPEN_DRAIN_INTERNAL | GPIO_CFG_PULL_UP_INTERNAL 355 /*! @hideinitializer Output pin is Open Drain w/ pull dn */ 356 #define GPIO_CFG_OUT_OD_PD GPIO_CFG_OUTPUT_OPEN_DRAIN_INTERNAL | GPIO_CFG_PULL_DOWN_INTERNAL 357 358 /*! @hideinitializer Set output pin strength to low */ 359 #define GPIO_CFG_OUT_STR_LOW GPIO_CFG_DRVSTR_LOW_INTERNAL 360 /*! @hideinitializer Set output pin strength to medium */ 361 #define GPIO_CFG_OUT_STR_MED GPIO_CFG_DRVSTR_MED_INTERNAL 362 /*! @hideinitializer Set output pin strength to high */ 363 #define GPIO_CFG_OUT_STR_HIGH GPIO_CFG_DRVSTR_HIGH_INTERNAL 364 365 /*! @hideinitializer Set pin's output to 1. */ 366 #define GPIO_CFG_OUT_HIGH GPIO_CFG_OUTPUT_DEFAULT_HIGH_INTERNAL 367 /*! @hideinitializer Set pin's output to 0. */ 368 #define GPIO_CFG_OUT_LOW GPIO_CFG_OUTPUT_DEFAULT_LOW_INTERNAL 369 /** @} */ 370 371 /** @name GPIO_PinConfig input pin configuration macros 372 * @{ 373 */ 374 /*! @hideinitializer Pin is an input. */ 375 #define GPIO_CFG_INPUT GPIO_CFG_INPUT_INTERNAL | GPIO_CFG_PULL_NONE_INTERNAL 376 /*! @hideinitializer Input pin with no internal PU/PD */ 377 #define GPIO_CFG_IN_NOPULL GPIO_CFG_INPUT_INTERNAL | GPIO_CFG_PULL_NONE_INTERNAL 378 /*! @hideinitializer Input pin with internal PU */ 379 #define GPIO_CFG_IN_PU GPIO_CFG_INPUT_INTERNAL | GPIO_CFG_PULL_UP_INTERNAL 380 /*! @hideinitializer Input pin with internal PD */ 381 #define GPIO_CFG_IN_PD GPIO_CFG_INPUT_INTERNAL | GPIO_CFG_PULL_DOWN_INTERNAL 382 /** @} */ 383 384 /** @name GPIO_PinConfig nondirectional pin configuration macros 385 * @{ 386 */ 387 /*! @hideinitializer Input and output are both disabled. Primarily useful for disabling muxed pins. */ 388 #define GPIO_CFG_NO_DIR GPIO_CFG_NO_DIR_INTERNAL | GPIO_CFG_PULL_NONE_INTERNAL 389 /** @} */ 390 391 /** @name GPIO_PinConfig pin inversion configuration macros 392 * @{ 393 */ 394 /*! @hideinitializer Input/output values are normal (default) */ 395 #define GPIO_CFG_INVERT_OFF GPIO_CFG_INVERT_OFF_INTERNAL 396 /*! @hideinitializer Input/output values are inverted */ 397 #define GPIO_CFG_INVERT_ON GPIO_CFG_INVERT_ON_INTERNAL 398 /** @} */ 399 400 /** @name GPIO_PinConfig pin hysteresis configuration macros 401 * @{ 402 */ 403 /*! @hideinitializer Input hysteresis is disabled (default) */ 404 #define GPIO_CFG_HYSTERESIS_OFF GPIO_CFG_HYSTERESIS_OFF_INTERNAL 405 /*! @hideinitializer Input hysteresis is enabled */ 406 #define GPIO_CFG_HYSTERESIS_ON GPIO_CFG_HYSTERESIS_ON_INTERNAL 407 /** @} */ 408 409 /** @name GPIO_PinConfig slew rate configuration macros 410 * @{ 411 */ 412 /*! @hideinitializer Output slew rate is unchanged (default) */ 413 #define GPIO_CFG_SLEW_NORMAL GPIO_CFG_SLEW_NORMAL_INTERNAL 414 /*! @hideinitializer Output slew rate is reduced */ 415 #define GPIO_CFG_SLEW_REDUCED GPIO_CFG_SLEW_REDUCED_INTERNAL 416 /** @} */ 417 418 /** @name GPIO_PinConfig interrupt configuration macros 419 * @{ 420 */ 421 /*! @hideinitializer No Interrupt (default) */ 422 #define GPIO_CFG_IN_INT_NONE GPIO_CFG_INT_NONE_INTERNAL 423 /*! @hideinitializer Interrupt on falling edge */ 424 #define GPIO_CFG_IN_INT_FALLING GPIO_CFG_INT_FALLING_INTERNAL 425 /*! @hideinitializer Interrupt on rising edge */ 426 #define GPIO_CFG_IN_INT_RISING GPIO_CFG_INT_RISING_INTERNAL 427 /*! @hideinitializer Interrupt on both edges */ 428 #define GPIO_CFG_IN_INT_BOTH_EDGES GPIO_CFG_INT_BOTH_EDGES_INTERNAL 429 /*! @hideinitializer Interrupt on low level */ 430 #define GPIO_CFG_IN_INT_LOW GPIO_CFG_INT_LOW_INTERNAL 431 /*! @hideinitializer Interrupt on high level */ 432 #define GPIO_CFG_IN_INT_HIGH GPIO_CFG_INT_HIGH_INTERNAL 433 434 /*! @hideinitializer Interrupt disabled (default) */ 435 #define GPIO_CFG_INT_DISABLE GPIO_CFG_INT_DISABLE_INTERNAL 436 /*! @hideinitializer Interrupt enabled */ 437 #define GPIO_CFG_INT_ENABLE GPIO_CFG_INT_ENABLE_INTERNAL 438 /** @} */ 439 440 /** @name GPIO_PinConfig power mode configuration macros 441 * @brief For devices that support low power modes, standard GPIO interrupts 442 * may be disabled in some modes. These defines allow configuring individual 443 * pins as wake-up sources. The GPIO module's wake up configuration is always 444 * enabled if it exists, so there is no module-level configuration. 445 * See the device-specific header files for details. 446 * @{ 447 */ 448 /*! @hideinitializer This pin will not wake the device up */ 449 #define GPIO_CFG_SHUTDOWN_WAKE_OFF GPIO_CFG_SHUTDOWN_WAKE_OFF_INTERNAL 450 /*! @hideinitializer A high value will wake the device from shutdown */ 451 #define GPIO_CFG_SHUTDOWN_WAKE_HIGH GPIO_CFG_SHUTDOWN_WAKE_HIGH_INTERNAL 452 /*! @hideinitializer A low value will wake the device from shutdown */ 453 #define GPIO_CFG_SHUTDOWN_WAKE_LOW GPIO_CFG_SHUTDOWN_WAKE_LOW_INTERNAL 454 /** @} */ 455 456 /** @name GPIO_pinconfig macro preventing configuration 457 * @brief Should be used if a pin is configured before the first GPIO_init() 458 * call, and should not be overwritten 459 * @{ 460 */ 461 /*! @hideinitializer Prevent this GPIO from being configured 462 * by the GPIO driver */ 463 #define GPIO_CFG_DO_NOT_CONFIG GPIO_CFG_DO_NOT_CONFIG_INTERNAL 464 /** @} */ 465 466 /** @name GPIO_Mux configuration macros 467 * @brief For additional muxing options, see the directions in the 468 * device-specific GPIO driver. 469 * @{ 470 */ 471 /*! @hideinitializer Set this pin to be a GPIO (the default) */ 472 #define GPIO_MUX_GPIO GPIO_MUX_GPIO_INTERNAL 473 /** @} */ 474 /** @} end of GPIO_PinConfigSettings group */ 475 476 /*! 477 * @brief GPIO callback function type 478 * 479 * @param index GPIO index. This is the same index that 480 * was passed to GPIO_setCallback(). This allows 481 * you to use the same callback function for multiple 482 * GPIO interrupts, by using the index to identify 483 * the GPIO that caused the interrupt. 484 */ 485 typedef void (*GPIO_CallbackFxn)(uint_least8_t index); 486 487 /*! 488 * @brief GPIO driver configuration structure 489 * 490 * The GPIO_Config struct contains the defaults for pin configuration. 491 * 492 * The interrupt priority of all pins configured to generate interrupts 493 * is also specified here. Values for the interrupt priority are 494 * device-specific. You should be well-acquainted with the interrupt 495 * controller used in your device before setting this parameter to a 496 * non-default value. The sentinel value of (~0) (the default value) is 497 * used to indicate that the lowest possible priority should be used. 498 */ 499 typedef struct 500 { 501 GPIO_PinConfig *configs; 502 GPIO_CallbackFxn *callbacks; 503 void **userArgs; 504 uint32_t intPriority; 505 } GPIO_Config; 506 507 /*! 508 * @brief Clear a GPIO pin interrupt flag 509 * 510 * Clears the GPIO interrupt for the specified index. 511 * 512 * Note: It is not necessary to call this API within a callback assigned 513 * to a pin. The driver clears interrupt flags before dispatching callbacks. 514 * 515 * @param index GPIO index 516 */ 517 extern void GPIO_clearInt(uint_least8_t index); 518 519 /*! 520 * @brief Disable a GPIO pin interrupt 521 * 522 * Disables interrupts for the specified GPIO index. 523 * 524 * @param index GPIO index 525 */ 526 extern void GPIO_disableInt(uint_least8_t index); 527 528 /*! 529 * @brief Enable a GPIO pin interrupt 530 * 531 * Enables GPIO interrupts for the selected index to occur. 532 * 533 * Note: Prior to enabling a GPIO pin interrupt, make sure 534 * that a corresponding callback function has been provided. 535 * Use the GPIO_setCallback() API for this purpose at runtime. 536 * Alternatively, the callback function can be statically 537 * configured in the GPIO_CallbackFxn array provided. 538 * 539 * @param index GPIO index 540 */ 541 extern void GPIO_enableInt(uint_least8_t index); 542 543 /*! 544 * @brief Initializes the GPIO module 545 * 546 * The pins defined in the application-provided *GPIO_config* structure 547 * are initialized accordingly. 548 * 549 * @pre The GPIO_config structure must exist and be persistent before this 550 * function can be called. This function must also be called before 551 * any other GPIO driver APIs. 552 */ 553 extern void GPIO_init(void); 554 555 /*! 556 * @brief Reads the value of a GPIO pin 557 * 558 * The value returned will either be zero or one depending on the 559 * state of the pin. 560 * 561 * @param index GPIO index 562 * 563 * @return 0 or 1, depending on the state of the pin. 564 */ 565 extern uint_fast8_t GPIO_read(uint_least8_t index); 566 567 /*! 568 * @brief Toggles the current state of a GPIO 569 * 570 * @param index GPIO index 571 */ 572 extern void GPIO_toggle(uint_least8_t index); 573 574 /*! 575 * @brief Writes the value to a GPIO pin 576 * 577 * @param index GPIO index 578 * @param value must be either 0 or 1 579 */ 580 extern void GPIO_write(uint_least8_t index, unsigned int value); 581 582 /*! 583 * @brief Bind a callback function to a GPIO pin interrupt 584 * 585 * Associate a callback function with a particular GPIO pin interrupt. 586 * 587 * Callbacks can be changed at any time, making it easy to switch between 588 * efficient, state-specific interrupt handlers. 589 * 590 * Note: The callback function is called within the context of an interrupt 591 * handler. 592 * 593 * Note: This API does not enable the GPIO pin interrupt. 594 * Use GPIO_enableInt() and GPIO_disableInt() to enable and disable the pin 595 * interrupt as necessary, or use GPIO_CFG_INT_ENABLE when calling setConfig. 596 * 597 * Note: it is not necessary to call GPIO_clearInt() within a callback. 598 * That operation is performed internally before the callback is invoked. 599 * 600 * @param index GPIO index 601 * @param callback address of the callback function 602 */ 603 extern void GPIO_setCallback(uint_least8_t index, GPIO_CallbackFxn callback); 604 605 /*! 606 * @brief Gets the callback associated with a GPIO pin. 607 * 608 * @param index GPIO index 609 * 610 * @return The callback function for the pin or NULL. 611 */ 612 extern GPIO_CallbackFxn GPIO_getCallback(uint_least8_t index); 613 614 /*! 615 * @brief Configure the gpio pin 616 * 617 * Dynamically configure a gpio pin to a device specific setting. 618 * For many applications, the pin configurations provided in the static 619 * GPIO_PinConfig array is sufficient. 620 * 621 * For input pins with interrupt configurations, a corresponding interrupt 622 * object will be created as needed. 623 * 624 * @param index GPIO index 625 * @param pinConfig device specific pin configuration settings 626 * 627 * @return GPIO_STATUS_SUCCESS or an error if the pin cannot be configured 628 */ 629 extern int_fast16_t GPIO_setConfig(uint_least8_t index, GPIO_PinConfig pinConfig); 630 631 /*! 632 * @brief Configure the gpio pin 633 * 634 * Dynamically configure a gpio pin to a device specific setting. 635 * This variant only allows configuring the interrupt settings (rising edge, 636 * falling edge, etc.) and enabling or disabling interrupts. 637 * 638 * Only GPIO_CFG_IN_INT_XXX macros and GPIO_CFG_INT_ENABLE/DISABLE may be 639 * passed to the config parameter for this function. If you do not pass 640 * GPIO_CFG_INT_ENABLE, this function will disable interrupts. 641 * 642 * @param index GPIO index 643 * @param config pin configuration settings 644 */ 645 extern void GPIO_setInterruptConfig(uint_least8_t index, GPIO_PinConfig config); 646 647 /*! 648 * @brief Get the current configuration for a gpio pin 649 * 650 * GPIO_getConfig() gets the current pin configuration. 651 * 652 * This value may not be identical to the value used in setConfig, as some 653 * configuration options are applied directly to hardware on some devices and 654 * not saved in order to save memory. 655 * 656 * @param index GPIO index 657 * @param pinConfig Location to store device specific pin 658 * configuration settings 659 */ 660 extern void GPIO_getConfig(uint_least8_t index, GPIO_PinConfig *pinConfig); 661 662 /*! 663 * @brief Resets the configuration for a gpio pin to the default value 664 * 665 * The default pin configuration is provided in the static GPIO_PinConfig 666 * array, defined by sysconfig or the board file at compile time. Also clears 667 * the callback and user argument. 668 * 669 * @param index GPIO index 670 */ 671 extern void GPIO_resetConfig(uint_least8_t index); 672 673 /*! 674 * @brief Get the current mux for a gpio pin 675 * 676 * For details and valid mux options, see the device-specific header file. 677 * 678 * @param index GPIO index 679 * 680 * @return A device-specific mux value or GPIO_MUX_GPIO. 681 */ 682 extern uint32_t GPIO_getMux(uint_least8_t index); 683 684 /*! 685 * @brief Configure the gpio pin's config and mux in a single write 686 * 687 * Dynamically configure a gpio pin to a device specific setting. 688 * For many applications, the pin configurations provided in the static 689 * GPIO_PinConfig array is sufficient. 690 * 691 * For some devices, configuring the pin and then muxing it can create a small 692 * drop on the line, which is enough to trigger some communication protocols. 693 * This helper function sets the pin configuration and the mux in a single access. 694 * 695 * @param index GPIO index 696 * @param pinConfig device specific pin configuration settings 697 * @param mux Device-specific mux value to use a special mode, 698 * or GPIO_MUX_GPIO to reset the pin to standard IO. 699 * 700 * @return GPIO_STATUS_SUCCESS or an error if the pin cannot be configured 701 */ 702 extern int_fast16_t GPIO_setConfigAndMux(uint_least8_t index, GPIO_PinConfig pinConfig, uint32_t mux); 703 704 /*! 705 * @brief Set the user argument for a gpio pin 706 * 707 * This can be retrieved using GPIO_getUserArg() and can be helpful to share 708 * callback logic across different pins. 709 * 710 * @param index GPIO index 711 * @param arg Pointer to a user object 712 */ 713 void GPIO_setUserArg(uint_least8_t index, void *arg); 714 715 /*! 716 * @brief Get the user argument for a gpio pin 717 * 718 * @param index GPIO index 719 * 720 * @return Pointer to a user object set by GPIO_setUserArg() 721 */ 722 void *GPIO_getUserArg(uint_least8_t index); 723 724 #ifdef __cplusplus 725 } 726 #endif 727 728 #endif /* ti_drivers_GPIO__include */ 729
