Typedefs | Functions
GPIO.h File Reference

Detailed Description

General Purpose I/O driver interface.

The GPIO header file should be included in an application as follows:


The GPIO module allows you to manage General Purpose I/O pins via simple and portable APIs. GPIO pin behavior is usually configured statically, but can also be configured or reconfigured at runtime.

Because of its simplicity, the GPIO driver does not follow the model of other TI-RTOS drivers in which a driver application interface has separate device-specific implementations. This difference is most apparent in the GPIOxxx_Config structure, which does not require you to specify a particular function table or object.


This section provides a basic usage summary and a set of examples in the form of commented code fragments. Detailed descriptions of the GPIO APIs and their effect are provided in subsequent sections.


// Import GPIO Driver definitions
// Define names for GPIO pin indexes
#define BUTTON 0
#define LED 1
// One-time init of GPIO driver
// Read GPIO pin
unsigned int state = GPIO_read(BUTTON);
// Write to GPIO pin
GPIO_write(LED, state);


Creating an input callback: The following example demonstrates how to configure a GPIO pin to generate an interrupt and how to toggle an an LED on and off within the registered interrupt callback function.

// Driver header file
// TI Drivers Configuration
#include "ti_drivers_config.h"
// Board file
// GPIO button call back function
void gpioButton0Fxn(uint_least8_t index);
// One-time Board initialization
// One-time init of GPIO driver
// Turn on user LED
// install Button callback
GPIO_setCallback(CONFIG_GPIO_BUTTON0, gpioButton0Fxn);
// Enable interrupts
// ======== gpioButton0Fxn ========
// Callback function for the GPIO interrupt on CONFIG_GPIO_BUTTON0
// Note: index is the GPIO id for the button which is not used here
void gpioButton0Fxn(uint_least8_t index)
// Toggle the LED

Runtime pin configuration: The following example demonstrates how to (re)configure GPIO pins.

// Driver header file
// TI Driver configuration
#include "ti_drivers_config.h"
void main()
// One-time init of GPIO driver
// Configure a button input pin
// Configure an LED output pin

GPIO Driver Configuration

In order to use the GPIO APIs, the application is required to provide 3 structures in the ti_drivers_config.c file:

  1. An array of GPIO_PinConfig elements that defines the initial configuration of each pin used by the application. A pin is referenced in the application by its corresponding index in this array. The pin type (that is, INPUT/OUTPUT), its initial state (that is OUTPUT_HIGH or LOW), interrupt behavior (RISING/FALLING edge, etc.), and device specific pin identification are configured in each element of this array (see Macros used to configure GPIO pins). Below is an MSP432 device specific example of the GPIO_PinConfig array:
    // Array of Pin configurations
    GPIO_PinConfig gpioPinConfigs[] = {
    // Input pins
    // MSP_EXP432P401R_GPIO_S1
    // MSP_EXP432P401R_GPIO_S2
    // Output pins
    // MSP_EXP432P401R_GPIO_LED1
  2. An array of GPIO_CallbackFxn elements that is used to store callback function pointers for GPIO pins configured with interrupts. The indexes for these array elements correspond to the pins defined in the GPIO_pinConfig array. These function pointers can be defined statically by referencing the callback function name in the array element, or dynamically, by setting the array element to NULL and using GPIO_setCallback() at runtime to plug the callback entry. Pins not used for interrupts can be omitted from the callback array to reduce memory usage (if they are placed at the end of GPIO_pinConfig array). The callback function syntax should match the following:
    void (*GPIO_CallbackFxn)(uint_least8_t index);
    The index parameter is the same index that was passed to GPIO_setCallback(). This allows the same callback function to be used for multiple GPIO interrupts, by using the index to identify the GPIO that caused the interrupt.
    Callback functions are called in the context of an interrupt service routine and should be designed accordingly.
    When an interrupt is triggered, the interrupt status of all (interrupt enabled) pins on a port will be read, cleared, and the respective callbacks will be executed. Callbacks will be called in order from least significant bit to most significant bit. Below is an MSP432 device specific example of the GPIO_CallbackFxn array:
    // Array of callback function pointers
    GPIO_CallbackFxn gpioCallbackFunctions[] = {
    // MSP_EXP432P401R_GPIO_S1
    // MSP_EXP432P401R_GPIO_S2
  3. A device specific GPIOxxx_Config structure that tells the GPIO driver where the two aforementioned arrays are and the number of elements in each. The interrupt priority of all pins configured to generate interrupts is also specified here. Values for the interrupt priority are device-specific. You should be well-acquainted with the interrupt controller used in your device before setting this parameter to a non-default value. The sentinel value of (~0) (the default value) is used to indicate that the lowest possible priority should be used. Below is an MSP432 device specific example of a GPIOxxx_Config structure:
    // MSP432 specific GPIOxxx_Config structure
    const GPIOMSP432_Config GPIOMSP432_config = {
    .pinConfigs = (GPIO_PinConfig *)gpioPinConfigs,
    .callbacks = (GPIO_CallbackFxn *)gpioCallbackFunctions,
    .numberOfPinConfigs = sizeof(gpioPinConfigs)/sizeof(GPIO_PinConfig),
    .numberOfCallbacks = sizeof(gpioCallbackFunctions)/sizeof(GPIO_CallbackFxn),
    .intPriority = (~0)

Initializing the GPIO Driver

GPIO_init() must be called before any other GPIO APIs. This function configures each GPIO pin in the user-provided GPIO_PinConfig array according to the defined settings. The user can also reconfigure a pin dynamically after GPIO_init() is called by using the GPIO_setConfig(), and GPIO_setCallback() APIs.


Unlike most other TI-RTOS drivers, the GPIO driver has no generic function table with pointers to device-specific API implementations. All the generic GPIO APIs are implemented by the device-specific GPIO driver module. Additionally, there is no notion of an instance 'handle' with the GPIO driver.

GPIO pins are referenced by their numeric index in the GPIO_PinConfig array. This design approach was used to enhance runtime and memory efficiency.

#include <stdint.h>
Include dependency graph for GPIO.h:
This graph shows which files directly or indirectly include this file:

Go to the source code of this file.


GPIO_STATUS_* macros are general status codes returned by GPIO driver APIs.
#define GPIO_STATUS_RESERVED   (-32)
 Common GPIO status code reservation offset. More...
 Successful status code returned by GPI_setConfig(). More...
#define GPIO_STATUS_ERROR   (-1)
 Generic error status code returned by GPI_setConfig(). More...
GPIO_PinConfig output pin configuration macros
GPIO_PinConfig input pin configuration macros
#define GPIO_CFG_IN_PU
#define GPIO_CFG_IN_PD
GPIO_PinConfig interrupt configuration macros
Special GPIO_PinConfig configuration macros
 'Or' in this GPIO_PinConfig definition to inform GPIO_setConfig() to only configure the interrupt attributes of a GPIO input pin. More...
 Use this GPIO_PinConfig definition to inform GPIO_init() NOT to configure the corresponding pin. More...


typedef uint32_t GPIO_PinConfig
 GPIO pin configuration settings. More...
typedef void(* GPIO_CallbackFxn) (uint_least8_t index)
 GPIO callback function type. More...


void GPIO_clearInt (uint_least8_t index)
 Clear a GPIO pin interrupt flag. More...
void GPIO_disableInt (uint_least8_t index)
 Disable a GPIO pin interrupt. More...
void GPIO_enableInt (uint_least8_t index)
 Enable a GPIO pin interrupt. More...
void GPIO_getConfig (uint_least8_t index, GPIO_PinConfig *pinConfig)
 Get the current configuration for a gpio pin. More...
void GPIO_init ()
 Initializes the GPIO module. More...
uint_fast8_t GPIO_read (uint_least8_t index)
 Reads the value of a GPIO pin. More...
void GPIO_setCallback (uint_least8_t index, GPIO_CallbackFxn callback)
 Bind a callback function to a GPIO pin interrupt. More...
int_fast16_t GPIO_setConfig (uint_least8_t index, GPIO_PinConfig pinConfig)
 Configure the gpio pin. More...
void GPIO_toggle (uint_least8_t index)
 Toggles the current state of a GPIO. More...
void GPIO_write (uint_least8_t index, unsigned int value)
 Writes the value to a GPIO pin. More...

Macro Definition Documentation


#define GPIO_STATUS_RESERVED   (-32)

Common GPIO status code reservation offset.

GPIO driver implementations should offset status codes with GPIO_STATUS_RESERVED growing negatively.

Example implementation specific status codes:




Successful status code returned by GPI_setConfig().

GPI_setConfig() returns GPIO_STATUS_SUCCESS if the API was executed successfully.


#define GPIO_STATUS_ERROR   (-1)

Generic error status code returned by GPI_setConfig().

GPI_setConfig() returns GPIO_STATUS_ERROR if the API was not executed successfully.

Typedef Documentation

§ GPIO_PinConfig

typedef uint32_t GPIO_PinConfig

GPIO pin configuration settings.

The upper 16 bits of the 32 bit PinConfig is reserved for pin configuration settings.

The lower 16 bits are reserved for device-specific port/pin identifications

§ GPIO_CallbackFxn

typedef void(* GPIO_CallbackFxn) (uint_least8_t index)

GPIO callback function type.

indexGPIO index. This is the same index that was passed to GPIO_setCallback(). This allows you to use the same callback function for multiple GPIO interrupts, by using the index to identify the GPIO that caused the interrupt.

Function Documentation

§ GPIO_clearInt()

void GPIO_clearInt ( uint_least8_t  index)

Clear a GPIO pin interrupt flag.

Clears the GPIO interrupt for the specified index.

Note: It is not necessary to call this API within a callback assigned to a pin.

indexGPIO index

§ GPIO_disableInt()

void GPIO_disableInt ( uint_least8_t  index)

Disable a GPIO pin interrupt.

Disables interrupts for the specified GPIO index.

indexGPIO index

§ GPIO_enableInt()

void GPIO_enableInt ( uint_least8_t  index)

Enable a GPIO pin interrupt.

Enables GPIO interrupts for the selected index to occur.

Note: Prior to enabling a GPIO pin interrupt, make sure that a corresponding callback function has been provided. Use the GPIO_setCallback() API for this purpose at runtime. Alternatively, the callback function can be statically configured in the GPIO_CallbackFxn array provided.

indexGPIO index

§ GPIO_getConfig()

void GPIO_getConfig ( uint_least8_t  index,
GPIO_PinConfig pinConfig 

Get the current configuration for a gpio pin.

The pin configuration is provided in the static GPIO_PinConfig array, but can be changed with GPIO_setConfig(). GPIO_getConfig() gets the current pin configuration.

indexGPIO index
pinConfigLocation to store device specific pin configuration settings

§ GPIO_init()

void GPIO_init ( )

Initializes the GPIO module.

The pins defined in the application-provided GPIOXXX_config structure are initialized accordingly.

The GPIO_config structure must exist and be persistent before this function can be called. This function must also be called before any other GPIO driver APIs.

§ GPIO_read()

uint_fast8_t GPIO_read ( uint_least8_t  index)

Reads the value of a GPIO pin.

The value returned will either be zero or one depending on the state of the pin.

indexGPIO index
0 or 1, depending on the state of the pin.

§ GPIO_setCallback()

void GPIO_setCallback ( uint_least8_t  index,
GPIO_CallbackFxn  callback 

Bind a callback function to a GPIO pin interrupt.

Associate a callback function with a particular GPIO pin interrupt.

Callbacks can be changed at any time, making it easy to switch between efficient, state-specific interrupt handlers.

Note: The callback function is called within the context of an interrupt handler.

Note: This API does not enable the GPIO pin interrupt. Use GPIO_enableInt() and GPIO_disableInt() to enable and disable the pin interrupt as necessary.

Note: it is not necessary to call GPIO_clearInt() within a callback. That operation is performed internally before the callback is invoked.

indexGPIO index
callbackaddress of the callback function

§ GPIO_setConfig()

int_fast16_t GPIO_setConfig ( uint_least8_t  index,
GPIO_PinConfig  pinConfig 

Configure the gpio pin.

Dynamically configure a gpio pin to a device specific setting. For many applications, the pin configurations provided in the static GPIO_PinConfig array is sufficient.

For input pins with interrupt configurations, a corresponding interrupt object will be created as needed.

indexGPIO index
pinConfigdevice specific pin configuration settings

§ GPIO_toggle()

void GPIO_toggle ( uint_least8_t  index)

Toggles the current state of a GPIO.

indexGPIO index

§ GPIO_write()

void GPIO_write ( uint_least8_t  index,
unsigned int  value 

Writes the value to a GPIO pin.

indexGPIO index
valuemust be either 0 or 1
© Copyright 1995-2019, Texas Instruments Incorporated. All rights reserved.
Trademarks | Privacy policy | Terms of use | Terms of sale