| Kinetis SDK API Reference Manual 1.0.0-beta Freescale Semiconductor, Inc.

- Introduction
- Related Pages
- API Usage

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
Data Structures | Typedefs
GPIO Peripheral Driver
General Purpose Input/Output (GPIO)

The section describes the programming interface of the GPIO Peripheral driver. More...

## Data Structures
struct | gpio_input_pin_t
| The GPIO input pin configuration structure. More...
struct | gpio_output_pin_t
| The GPIO output pin configuration structure. More...
struct | gpio_input_pin_user_config_t
| The GPIO input pin structure. More...
struct | gpio_output_pin_user_config_t
| The GPIO output pin structure. More...

## Typedefs
typedef void(* | gpio_isr_callback_t )(void)
| The GPIO ISR callback function.

## GPIO Pin Macros
#define | GPIO_PINS_OUT_OF_RANGE (0xFFFFFFFFU)
| Indicates the end of a pin configuration structure. More...
#define | GPIO_PORT_SHIFT (0x8U)
| Bits shifted for the GPIO port number. More...
#define | GPIO_MAKE_PIN(r, p) (((r)<< GPIO_PORT_SHIFT) | (p))
| Combines the port number and the pin number into a single scalar value. More...
#define | GPIO_EXTRACT_PORT(v) (((v) >> GPIO_PORT_SHIFT) & 0xFFU)
| Extracts the port number from a combined port and pin value. More...
#define | GPIO_EXTRACT_PIN(v) ((v) & 0xFFU)
| Extracts the pin number from a combined port and pin value. More...

## Initialization
void | gpio_init (const gpio_input_pin_user_config_t *inputPins, const gpio_output_pin_user_config_t *outputPins)
| Initialize all GPIO pins used by board. More...
void | gpio_input_pin_init (const gpio_input_pin_user_config_t *inputPin)
| Initializes one GPIO input pin used by board. More...
void | gpio_output_pin_init (const gpio_output_pin_user_config_t *outputPin)
| Initializes one GPIO output pin used by board. More...

## Pin Direction
uint32_t | gpio_get_pin_direction (uint32_t pinName)
| Gets the current direction of the individual GPIO pin. More...
void | gpio_set_pin_direction (uint32_t pinName, gpio_pin_direction_t direction)
| Sets the current direction of the individual GPIO pin. More...

## Output Operations
void | gpio_write_pin_output (uint32_t pinName, uint32_t output)
| Sets the output level of the individual GPIO pin to the logic 1 or 0. More...
void | gpio_set_pin_output (uint32_t pinName)
| Sets the output level of the individual GPIO pin to the logic 1. More...
void | gpio_clear_pin_output (uint32_t pinName)
| Sets the output level of the individual GPIO pin to the logic 0. More...
void | gpio_toggle_pin_output (uint32_t pinName)
| Reverses current output logic of the individual GPIO pin. More...

## Input Operations
uint32_t | gpio_read_pin_input (uint32_t pinName)
| Reads the current input value of the individual GPIO pin. More...

## Interrupt
void | gpio_clear_pin_interrupt_flag (uint32_t pinName)
| Clears the individual GPIO pin interrupt status flag. More...
void | gpio_register_isr_callback_function (uint32_t pinName, gpio_isr_callback_t function)
| Registers the GPIO ISR callback function. More...

### GPIO Peripheral Driver

# Overview

The GPIO peripheral driver configures pins to digital input/output and provides APIs for input/output operations.

# GPIO Pin Definitions

The user should define GPIO pins according to the target board configuration and ensure that the definitions are correct. One header file should be defined to save GPIO pin names and the input/output configuration arrays defined in source files.
Include this header file in source files where you want to use GPIO driver to operate GPIO pins.GPIO pin header file example:
// Feel free to change the pin names as what you want
enum _gpio_pins
{
kGpioLED1 = GPIO_MAKE_PIN(HW_PORTC, 0x0),
kGpioLED2 = GPIO_MAKE_PIN(HW_PORTC, 0x1),
kGpioLED3 = GPIO_MAKE_PIN(HW_PORTC, 0x2),
kGpioLED4 = GPIO_MAKE_PIN(HW_PORTC, 0x3),
};
// Extern input/output arrays defined in source files.
extern gpio_input_pin_t inputPin[];
extern gpio_output_pin_t outputPin[];

# Initialization

To initialize the GPIO driver, two arrays, the gpio_input_pin_t inputPin[] and the gpio_output_pin_t outputPin[], should be defined first. Then , call the gpio_init() function and pass these two arrays.
Example of the inputPin and outputPin array definition of:
#include "gpio/fsl_gpio_driver.h"
#include "gpio_pin_header_file.h"
// Configure kGpioPTA2 as a digital input and enable the interrupt on the rising edge.
gpio_input_pin_t inputPin[] = {
{
.pinName = kGpioPTA2,
.config.isPullEnable = false,
.config.pullSelect = kPortPullDown,
.config.isPassiveFilterEnabled = false,
.config.interrupt = kPortIntRisingEdge,
},
{
//Note: This pinName must be defined here to indicate end of array.
.pinName = GPIO_PINS_OUT_OF_RANGE,
}
};
// Configure the kGpioLED4 and kGpioPTB9 as a digital output and enable the high drive strength.
gpio_output_pin_t outputPin[] = {
{
.pinName = kGpioLED4,
.config.outputLogic = 0,
.config.slewRate = kPortFastSlewRate,
.config.driveStrength = kPortHighDriveStrength,
.config.interrupt = kPortIntDisabled,
},
{
.pinName = kGpioPTB9,
.config.outputLogic = 0,
.config.slewRate = kPortFastSlewRate,
.config.driveStrength = kPortHighDriveStrength,
.config.interrupt = kPortIntDisabled,
},
{
//Note: This pinName must be defined here to indicate the end of array.
.pinName = GPIO_PINS_OUT_OF_RANGE,
}
};
// Initializes GPIO pins.
gpio_init(inputPin, outputPin);

Note
  If the digital filter is enabled, the digital filter clock source and width must be configured before calling the gpio_init function. To configure the digital filter, use this API from porting the HAL driver. Each pin in the same port shares the same digital filter settings.
  void port_hal_configure_digital_filter_clock(uint32_t instance,
  port_digital_filter_clock_source_t clockSource);
  void port_hal_configure_digital_filter_width(uint32_t instance, uint8_t width);

# Output Operations

To use the output operation, configure the target GPIO pin as a digital output in the gpio_init function. The output operations include set, clear, and toggle of the output logic level. For these operations, three APIs are provided:
void gpio_set_pin_output(uint32_t pinName);
void gpio_clear_pin_output(uint32_t pinName);
void gpio_toggle_pin_output(uint32_t pinName);
These functions are used when the logic level of the GPIO output is known.
Otherwise, a different function is provided to configure the output logic level according to a passed parameter:
void gpio_write_pin_output(uint32_t pinName, uint32_t output);
Use this function to change the GPIO output according to the results of other code. Pass an integer as the "uint32_t output" parameter. If that integer is not 0, it generates the high logic. If the integer is 0, it generates the low logic.

# Input Operations

To use the input operation, configure the target GPIO pin as a digital input in the gpio_init function. For the input operation, the most commonly used API is:
uint32_t gpio_read_pin_input(uint32_t pinName);
This function returns the logic level read from a specific GPIO pin.
If the digital filter is enabled, use this function to disable it:
void gpio_configure_digital_filter(uint32_t pinName, bool isDigitalFilterEnabled);

# Interrupt

Enable a specific pin interrupt in GPIO initialization structures. Both output and input can trigger an interrupt. This API clears the interrupt flag inside the interrupt handler:
void gpio_clear_pin_interrupt_flag(uint32_t pinName);

## Data Structure Documentation

struct gpio_input_pin_t

Although every pin is configurable, valid configurations depend on a specific SoC. Users should check the related reference manual to ensure that the specific feature is valid in an individual pin. A configuration of unavailable features is harmless, but takes no effect.

### Data Fields
bool | isPullEnable
| Enable or disable pull. More...
port_pull_t | pullSelect
| Select internal pull(up/down) resistor. More...
bool | isPassiveFilterEnabled
| Enable or disable passive filter. More...
port_interrupt_config_t | interrupt
| Select interrupt/DMA request. More...

#### Field Documentation

bool gpio_input_pin_t::isPullEnable

port_pull_t gpio_input_pin_t::pullSelect

bool gpio_input_pin_t::isPassiveFilterEnabled

port_interrupt_config_t gpio_input_pin_t::interrupt

struct gpio_output_pin_t

Although every pin is configurable, valid configurations depend on a specific SoC. Users should check the related reference manual to ensure that the specific feature is valid in an individual pin. The configuration of unavailable features is harmless, but takes no effect.

### Data Fields
uint32_t | outputLogic
| Set default output logic. More...
port_slew_rate_t | slewRate
port_drive_strength_t | driveStrength
| Select fast/slow slew rate. More...

#### Field Documentation

uint32_t gpio_output_pin_t::outputLogic

port_drive_strength_t gpio_output_pin_t::driveStrength

Select low/high drive strength.

struct gpio_input_pin_user_config_t

Although the pinName is defined as a uint32_t type, values assigned to the pinName should be the enumeration names defined in the enum _gpio_pins.

### Data Fields
uint32_t | pinName
| Virtual pin name from enum defined by the user. More...
gpio_input_pin_t | config
| Input pin configuration structure. More...

#### Field Documentation

uint32_t gpio_input_pin_user_config_t::pinName

gpio_input_pin_t gpio_input_pin_user_config_t::config

struct gpio_output_pin_user_config_t

Although the pinName is defined as a uint32_t type, values assigned to the pinName should be the enumeration names defined in the enum _gpio_pins.

### Data Fields
uint32_t | pinName
| Virtual pin name from enum defined by the user. More...
gpio_output_pin_t | config
| Input pin configuration structure. More...

#### Field Documentation

uint32_t gpio_output_pin_user_config_t::pinName

gpio_output_pin_t gpio_output_pin_user_config_t::config

## Macro Definition Documentation

#define GPIO_PINS_OUT_OF_RANGE (0xFFFFFFFFU)

#define GPIO_PORT_SHIFT (0x8U)

#define GPIO_MAKE_PIN | ( |  | r,
|  |  | p
| ) |  | (((r)<< GPIO_PORT_SHIFT) | (p))

#define GPIO_EXTRACT_PORT | ( |  | v | ) | (((v) >> GPIO_PORT_SHIFT) & 0xFFU)

#define GPIO_EXTRACT_PIN | ( |  | v | ) | ((v) & 0xFFU)

## Function Documentation

void gpio_init | ( | const gpio_input_pin_user_config_t * | inputPins,
|  | const gpio_output_pin_user_config_t * | outputPins
| ) |  |

To initialize the GPIO driver, define two arrays similar to the gpio_input_pin_user_config_t inputPin[] and the gpio_output_pin_user_config_t outputPin[] in the user file. Then, call the gpio_init() function and pass in the two arrays. If the input or output pins are not needed, pass in a NULL.

This is an example to define an input pin array:

// Configure the kGpioPTA2 as digital input.
gpio_input_pin_user_config_t inputPin[] = {
{
.pinName = kGpioPTA2,
.config.isPullEnable = false,
.config.pullSelect = kPortPullDown,
.config.isPassiveFilterEnabled = false,
.config.interrupt = kPortIntDisabled,
},
{
// Note: This pinName must be defined here to indicate the end of the array.
.pinName = GPIO_PINS_OUT_OF_RANGE,
}
};

Parameters

  inputPins | input GPIO pins pointer.
  outputPins | output GPIO pins pointer.

void gpio_input_pin_init | ( | const gpio_input_pin_user_config_t * | inputPin | ) |

Parameters

  inputPins | input GPIO pins pointer.

void gpio_output_pin_init | ( | const gpio_output_pin_user_config_t * | outputPin | ) |

Parameters

  outputPins | output GPIO pins pointer.

uint32_t gpio_get_pin_direction | ( | uint32_t | pinName | ) |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.

Returns
  GPIO directions.
  - 0: corresponding pin is set as digital input.
  - 1: corresponding pin is set as digital output.

void gpio_set_pin_direction | ( | uint32_t | pinName,
|  | gpio_pin_direction_t | direction
| ) |  |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.
  direction | GPIO directions. kGpioDigitalInput: corresponding pin is set as digital input. kGpioDigitalOutput: corresponding pin is set as digital output.

void gpio_write_pin_output | ( | uint32_t | pinName,
|  | uint32_t | output
| ) |  |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.
  output | pin output logic level. 0: corresponding pin output low logic level. Non-0: corresponding pin output high logic level.

void gpio_set_pin_output | ( | uint32_t | pinName | ) |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.

void gpio_clear_pin_output | ( | uint32_t | pinName | ) |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.

void gpio_toggle_pin_output | ( | uint32_t | pinName | ) |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.

uint32_t gpio_read_pin_input | ( | uint32_t | pinName | ) |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.

Returns
  GPIO port input value.
  - 0: Pin logic level is 0, or is not configured for use by digital function.
  - 1: Pin logic level is 1.

void gpio_clear_pin_interrupt_flag | ( | uint32_t | pinName | ) |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.

void gpio_register_isr_callback_function | ( | uint32_t | pinName,
|  | gpio_isr_callback_t | function
| ) |  |

Parameters

  pinName | GPIO pin name defined by the user in the GPIO pin enumeration list.
  function | Pointer to the GPIO ISR callback function.