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. Pin configuration is handled within Sysconfig for this example.

// Driver header file
#include <ti/drivers/GPIO.h>
// TI Drivers Configuration
#include "ti_drivers_config.h"
// GPIO button call back function
void gpioButton0Fxn(uint_least8_t index);
main()
{
    // Turn on user LED
    GPIO_write(CONFIG_GPIO_LED0, CONFIG_GPIO_LED_ON);
    // install Button callback and enable interrupts
    GPIO_setCallback(CONFIG_GPIO_BUTTON0, gpioButton0Fxn);
    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"
void main()
{
    // One-time init of GPIO driver
    GPIO_init();
    // Configure a button pin as input and configure its interrupt
    // Passing INT_ENABLE means you do not need to also call GPIO_enableInt()
    GPIO_setConfig(
        CONFIG_GPIO_BUTTON0,
        GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_FALLING | GPIO_CFG_INT_ENABLE
    );
    // Configure an LED output pin
    GPIO_setConfig(CONFIG_GPIO_LED0, 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 on the device. A pin is then 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 a device specific example of the GPIO_PinConfig array:
//
// Array of Pin configurations
//
GPIO_PinConfig gpioPinConfigs[31] = {
GPIO_CFG_INPUT, // DIO_0
GPIO_CFG_IN_PU | GPIO_CFG_IN_INT_NONE, // CONFIG_GPIO_LP19
GPIO_CFG_INPUT, // DIO_2
GPIO_CFG_INPUT, // DIO_3
...
};
An array of GPIO_CallbackFxn elements that is used to store callback function pointers for GPIO pins. 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. 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 a device specific example of the GPIO_CallbackFxn array:
//
// Array of callback function pointers
//
GPIO_CallbackFxn gpioCallbackFunctions[31] = {
NULL, // DIO_0
NULL, // DIO_1
myGpioCallback, // CONFIG_GPIO_LP19
NULL, // DIO_3
...
};
A device specific GPIO_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 a device specific example of a GPIO_Config structure:
//
// ======== GPIO_config ========
//
const GPIO_Config GPIO_config = {
.configs = (GPIO_PinConfig *)gpioPinConfigs,
.callbacks = (GPIO_CallbackFxn *)gpioCallbackFunctions,
.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.

GPIO_init() is called from Board_init() by default. Calling GPIO_init() multiple times is safe.

Implementation

Unlike most other TI-RTOS drivers, there is no notion of an instance 'handle' with the GPIO driver. This allows lightweight pin control with minimal runtime and memory overhead.

GPIO pins are always referenced by device DIO index.

#include <stdint.h>
#include <ti/devices/DeviceFamily.h>
#include <ti/drivers/gpio/GPIOCC26XX.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.

Data Structures
struct	GPIO_Config
	GPIO driver configuration structure. More...

Macros
#define	GPIO_PIN_TO_MASK(pin) (1 << (pin))

#define	GPIO_INVALID_INDEX 0xFF
	Dummy value for "this pin is not assigned to a GPIO". More...

GPIO_STATUS_* macros are general status codes returned by GPIO driver APIs.
#define	GPIO_STATUS_SUCCESS (0)
	Successful status code returned by GPIO_setConfig(). More...

#define	GPIO_STATUS_ERROR (-1)
	Generic error status code returned by GPIO_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 nondirectional pin configuration macros
#define	GPIO_CFG_NO_DIR

GPIO_PinConfig pin inversion configuration macros
#define	GPIO_CFG_INVERT_OFF

#define	GPIO_CFG_INVERT_ON

GPIO_PinConfig pin hysteresis configuration macros
#define	GPIO_CFG_HYSTERESIS_OFF

#define	GPIO_CFG_HYSTERESIS_ON

GPIO_PinConfig slew rate configuration macros
#define	GPIO_CFG_SLEW_NORMAL

#define	GPIO_CFG_SLEW_REDUCED

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

#define	GPIO_CFG_INT_DISABLE

#define	GPIO_CFG_INT_ENABLE

GPIO_PinConfig power mode configuration macros
For devices that support low power modes, standard GPIO interrupts may be disabled in some modes. These defines allow configuring individual pins as wake-up sources. The GPIO module's wake up configuration is always enabled if it exists, so there is no module-level configuration. See the device-specific header files for details.
#define	GPIO_CFG_SHUTDOWN_WAKE_OFF

#define	GPIO_CFG_SHUTDOWN_WAKE_HIGH

#define	GPIO_CFG_SHUTDOWN_WAKE_LOW

GPIO_pinconfig macro preventing configuration
Should be used if a pin is configured before the first GPIO_init() call, and should not be overwritten
#define	GPIO_CFG_DO_NOT_CONFIG

GPIO_Mux configuration macros
For additional muxing options, see the directions in the device-specific GPIO driver.
#define	GPIO_MUX_GPIO

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_init (void)
	Initializes the GPIO module. More...

uint_fast8_t	GPIO_read (uint_least8_t index)
	Reads the value of a 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...

void	GPIO_setCallback (uint_least8_t index, GPIO_CallbackFxn callback)
	Bind a callback function to a GPIO pin interrupt. More...

GPIO_CallbackFxn	GPIO_getCallback (uint_least8_t index)
	Gets the callback associated with a GPIO pin. More...

int_fast16_t	GPIO_setConfig (uint_least8_t index, GPIO_PinConfig pinConfig)
	Configure the gpio pin. More...

void	GPIO_setInterruptConfig (uint_least8_t index, GPIO_PinConfig config)
	Configure the gpio pin. More...

void	GPIO_getConfig (uint_least8_t index, GPIO_PinConfig *pinConfig)
	Get the current configuration for a gpio pin. More...

void	GPIO_resetConfig (uint_least8_t index)
	Resets the configuration for a gpio pin to the default value. More...

uint32_t	GPIO_getMux (uint_least8_t index)
	Get the current mux for a gpio pin. More...

int_fast16_t	GPIO_setConfigAndMux (uint_least8_t index, GPIO_PinConfig pinConfig, uint32_t mux)
	Configure the gpio pin's config and mux in a single write. More...

void	GPIO_setUserArg (uint_least8_t index, void *arg)
	Set the user argument for a gpio pin. More...

void *	GPIO_getUserArg (uint_least8_t index)
	Get the user argument for a gpio pin. More...

Macro Definition Documentation

§ GPIO_PIN_TO_MASK

#define GPIO_PIN_TO_MASK ( pin ) (1 << (pin))

§ GPIO_STATUS_SUCCESS

#define GPIO_STATUS_SUCCESS (0)

Successful status code returned by GPIO_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 GPIO_setConfig().

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

§ GPIO_INVALID_INDEX

#define GPIO_INVALID_INDEX 0xFF

Dummy value for "this pin is not assigned to a GPIO".

Not for use in customer software. Some drivers use this value to manage the behaviour of optional pins (e.g. UART flow control, SPI chip select). If you pass this value to any GPIO methods, it will return immediately and no register writes will be performed.

Typedef Documentation

§ GPIO_PinConfig

typedef uint32_t GPIO_PinConfig

GPIO pin configuration settings.

The meaning of the bits within PinConfig are entirely device-specific and are typically one-to-one with the hardware register controlling pin configuration.

Only create and manipulate these values using GPIO_CFG_* defines.

§ 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. The driver clears interrupt flags before dispatching callbacks.

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_init()

void GPIO_init ( void )

Initializes the GPIO module.

The pins defined in the application-provided GPIO_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_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

§ 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, or use GPIO_CFG_INT_ENABLE when calling setConfig.

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_getCallback()

GPIO_CallbackFxn GPIO_getCallback ( uint_least8_t index )

Gets the callback associated with a GPIO pin.

Parameters

index GPIO index

Returns: The callback function for the pin or NULL.

§ 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

Returns: GPIO_STATUS_SUCCESS or an error if the pin cannot be configured

§ GPIO_setInterruptConfig()

void GPIO_setInterruptConfig	(	uint_least8_t	index,
		GPIO_PinConfig	config
	)

Configure the gpio pin.

Dynamically configure a gpio pin to a device specific setting. This variant only allows configuring the interrupt settings (rising edge, falling edge, etc.) and enabling or disabling interrupts.

Only GPIO_CFG_IN_INT_XXX macros and GPIO_CFG_INT_ENABLE/DISABLE may be passed to the config parameter for this function. If you do not pass GPIO_CFG_INT_ENABLE, this function will disable interrupts.

Parameters

index	GPIO index
config	pin configuration settings

§ GPIO_getConfig()

void GPIO_getConfig	(	uint_least8_t	index,
		GPIO_PinConfig *	pinConfig
	)

Get the current configuration for a gpio pin.

GPIO_getConfig() gets the current pin configuration.

This value may not be identical to the value used in setConfig, as some configuration options are applied directly to hardware on some devices and not saved in order to save memory.

Parameters

index	GPIO index
pinConfig	Location to store device specific pin configuration settings

§ GPIO_resetConfig()

void GPIO_resetConfig ( uint_least8_t index )

Resets the configuration for a gpio pin to the default value.

The default pin configuration is provided in the static GPIO_PinConfig array, defined by sysconfig or the board file at compile time. Also clears the callback and user argument.

Parameters

index GPIO index

§ GPIO_getMux()

uint32_t GPIO_getMux ( uint_least8_t index )

Get the current mux for a gpio pin.

For details and valid mux options, see the device-specific header file.

Parameters

index GPIO index

Returns: A device-specific mux value or GPIO_MUX_GPIO.

§ GPIO_setConfigAndMux()

int_fast16_t GPIO_setConfigAndMux	(	uint_least8_t	index,
		GPIO_PinConfig	pinConfig,
		uint32_t	mux
	)

Configure the gpio pin's config and mux in a single write.

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 some devices, configuring the pin and then muxing it can create a small drop on the line, which is enough to trigger some communication protocols. This helper function sets the pin configuration and the mux in a single access.

Parameters

index	GPIO index
pinConfig	device specific pin configuration settings
mux	Device-specific mux value to use a special mode, or GPIO_MUX_GPIO to reset the pin to standard IO.

Returns: GPIO_STATUS_SUCCESS or an error if the pin cannot be configured

§ GPIO_setUserArg()

void GPIO_setUserArg	(	uint_least8_t	index,
		void *	arg
	)

Set the user argument for a gpio pin.

This can be retrieved using GPIO_getUserArg() and can be helpful to share callback logic across different pins.

Parameters

index	GPIO index
arg	Pointer to a user object

§ GPIO_getUserArg()

void* GPIO_getUserArg ( uint_least8_t index )

Get the user argument for a gpio pin.

Parameters

index GPIO index

Returns: Pointer to a user object set by GPIO_setUserArg()

Detailed Description

Overview

Usage

Synopsis

Examples

GPIO Driver Configuration

Initializing the GPIO Driver

Implementation

Data Structures

Macros

Typedefs

Functions

Macro Definition Documentation

§ GPIO_PIN_TO_MASK

§ GPIO_STATUS_SUCCESS

§ GPIO_STATUS_ERROR

§ GPIO_INVALID_INDEX

Typedef Documentation

§ GPIO_PinConfig

§ GPIO_CallbackFxn

Function Documentation

§ GPIO_clearInt()

§ GPIO_disableInt()

§ GPIO_enableInt()

§ GPIO_init()

§ GPIO_read()

§ GPIO_toggle()

§ GPIO_write()

§ GPIO_setCallback()

§ GPIO_getCallback()

§ GPIO_setConfig()

§ GPIO_setInterruptConfig()

§ GPIO_getConfig()

§ GPIO_resetConfig()

§ GPIO_getMux()

§ GPIO_setConfigAndMux()

§ GPIO_setUserArg()

§ GPIO_getUserArg()