Detailed Description

General Purpose I/O driver interface.

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

Overview

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.

Usage

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.

Synopsis

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

Examples

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
#include <ti/drivers/GPIO.h>
// TI Drivers Configuration
#include "ti_drivers_config.h"
// Board file
#include <ti/drivers/Board.h>
// GPIO button call back function
void gpioButton0Fxn(uint_least8_t index);
main()
{
    // One-time Board initialization
    Board_init();
    // One-time init of GPIO driver
    GPIO_init();
    // Turn on user LED
    GPIO_write(CONFIG_GPIO_LED0, CONFIG_GPIO_LED_ON);
    // install Button callback
    GPIO_setCallback(CONFIG_GPIO_BUTTON0, gpioButton0Fxn);
    // Enable interrupts
    GPIO_enableInt(CONFIG_GPIO_BUTTON0);
}
//
//  ======== 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
    GPIO_toggle(CONFIG_GPIO_LED0);
}

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

// Driver header file
#include <ti/drivers/GPIO.h>
// TI Driver configuration
#include "ti_drivers_config.h"
#define LED    CONFIG_GPIO_LED0
#define BUTTON CONFIG_GPIO_BUTTON0
void main()
{
    // One-time init of GPIO driver
    GPIO_init();
    // Configure a button input pin
    GPIO_setConfig(BUTTON, GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING);
    // Configure an LED output pin
    GPIO_setConfig(LED, GPIO_CFG_OUT_STD | GPIO_CFG_OUT_LOW);
}

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:

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
GPIOMSP432_P1_1 | GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING,
// MSP_EXP432P401R_GPIO_S2
GPIOMSP432_P1_4 | GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING,
// Output pins
// MSP_EXP432P401R_GPIO_LED1
GPIOMSP432_P1_0 | GPIO_CFG_OUT_STD | GPIO_CFG_OUT_STR_HIGH | GPIO_CFG_OUT_LOW,
// MSP_EXP432P401R_GPIO_LED_RED
GPIOMSP432_P2_0 | GPIO_CFG_OUT_STD | GPIO_CFG_OUT_STR_HIGH | GPIO_CFG_OUT_LOW,
};
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.
Remarks
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
NULL,
// MSP_EXP432P401R_GPIO_S2
NULL
};
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.

Implementation

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.

Macros
GPIO_STATUS_* macros are general status codes returned by GPIO driver APIs.
#define	GPIO_STATUS_RESERVED (-32)
	Common GPIO status code reservation offset. More...

#define	GPIO_STATUS_SUCCESS (0)
	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
#define	GPIO_CFG_OUTPUT

#define	GPIO_CFG_OUT_STD

#define	GPIO_CFG_OUT_OD_NOPULL

#define	GPIO_CFG_OUT_OD_PU

#define	GPIO_CFG_OUT_OD_PD

#define	GPIO_CFG_OUT_STR_LOW

#define	GPIO_CFG_OUT_STR_MED

#define	GPIO_CFG_OUT_STR_HIGH

#define	GPIO_CFG_OUT_HIGH

#define	GPIO_CFG_OUT_LOW

GPIO_PinConfig input pin configuration macros
#define	GPIO_CFG_INPUT

#define	GPIO_CFG_IN_NOPULL

#define	GPIO_CFG_IN_PU

#define	GPIO_CFG_IN_PD

GPIO_PinConfig interrupt configuration macros
#define	GPIO_CFG_IN_INT_NONE

#define	GPIO_CFG_IN_INT_FALLING

#define	GPIO_CFG_IN_INT_RISING

#define	GPIO_CFG_IN_INT_BOTH_EDGES

#define	GPIO_CFG_IN_INT_LOW

#define	GPIO_CFG_IN_INT_HIGH

Special GPIO_PinConfig configuration macros
#define	GPIO_CFG_IN_INT_ONLY
	'Or' in this GPIO_PinConfig definition to inform GPIO_setConfig() to only configure the interrupt attributes of a GPIO input pin. More...

#define	GPIO_DO_NOT_CONFIG
	Use this GPIO_PinConfig definition to inform GPIO_init() NOT to configure the corresponding pin. More...

Typedefs
typedef uint32_t	GPIO_PinConfig
	GPIO pin configuration settings. More...

typedef void(*	GPIO_CallbackFxn) (uint_least8_t index)
	GPIO callback function type. More...

Functions
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

§ GPIO_STATUS_RESERVED

#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:

#define GPIOTXYZ_STATUS_ERROR1    GPIO_STATUS_RESERVED - 1
#define GPIOTXYZ_STATUS_ERROR0    GPIO_STATUS_RESERVED - 0
#define GPIOTXYZ_STATUS_ERROR2    GPIO_STATUS_RESERVED - 2

§ GPIO_STATUS_SUCCESS

#define GPIO_STATUS_SUCCESS (0)

Successful status code returned by GPI_setConfig().

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

§ GPIO_STATUS_ERROR

#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.

Parameters

index GPIO 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.

Parameters

index GPIO index

§ GPIO_disableInt()

void GPIO_disableInt ( uint_least8_t index )

Disable a GPIO pin interrupt.

Disables interrupts for the specified GPIO index.

Parameters

index GPIO 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.

Parameters

index GPIO 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.

Parameters

index	GPIO index
pinConfig	Location 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.

Precondition: 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.

Parameters

index GPIO index

Returns: 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.

Parameters

index	GPIO index
callback	address 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.

Parameters

index	GPIO index
pinConfig	device specific pin configuration settings

§ GPIO_toggle()

void GPIO_toggle ( uint_least8_t index )

Toggles the current state of a GPIO.

Parameters

index GPIO index

§ GPIO_write()

void GPIO_write	(	uint_least8_t	index,
		unsigned int	value
	)

Writes the value to a GPIO pin.

Parameters

index	GPIO index
value	must be either 0 or 1

Detailed Description

Overview

Usage

Synopsis

Examples

GPIO Driver Configuration

Initializing the GPIO Driver

Implementation

Macros

Typedefs

Functions

Macro Definition Documentation

§ GPIO_STATUS_RESERVED

§ GPIO_STATUS_SUCCESS

§ GPIO_STATUS_ERROR

Typedef Documentation

§ GPIO_PinConfig

§ GPIO_CallbackFxn

Function Documentation

§ GPIO_clearInt()

§ GPIO_disableInt()

§ GPIO_enableInt()

§ GPIO_getConfig()

§ GPIO_init()

§ GPIO_read()

§ GPIO_setCallback()

§ GPIO_setConfig()

§ GPIO_toggle()

§ GPIO_write()