Hardware Abstraction Layer (HAL)
GPIO (General Purpose Input Output)

General Description

High level interface for configuring and interacting with general purpose input/outputs (GPIO).

The GPIO driver provides functions to configure and initialize GPIO, and to read and write data to the pin. The driver also supports interrupt generation on GPIO signals with rising, falling or both edges.

Note
The APIs in this driver need not be used if a GPIO is to be used as an input or output of peripherals like I2C or PWM. The respective peripheral's driver will utilize the GPIO interface to configure and initialize its GPIO pins.

Features

Quick Start

cyhal_gpio_init can be used for a simple GPIO initialization by providing the pin number (pin), pin direction (direction), pin drive mode (drive_mode) and the initial value on the pin (init_val).

Code Snippets

Snippet 1: Reading value from GPIO

The following snippet initializes GPIO pin P0_0 as an input with high impedance digital drive mode and initial value = false (low). A value is read from the pin and stored to a uint8_t variable (read_val).

cy_rslt_t rslt;
bool read_val;
/* Initialize pin P0_0 as an input */
/* Read the logic level on the input pin */
read_val = cyhal_gpio_read(P0_0);

Snippet 2: Writing value to a GPIO

The following snippet initializes GPIO pin P0_0 as an output pin with strong drive mode and initial value = false (low). A value = true (high) is written to the output driver.

cy_rslt_t rslt;
bool write_val = true;
/* Initialize pin P0_0 GPIO as an output with strong drive mode and initial value = false (low) */
/* Write the value to the output pin */
cyhal_gpio_write(P0_0, write_val);

Snippet 3: Reconfiguring a GPIO

The following snippet shows how to reconfigure a GPIO pin during run-time using the firmware. The GPIO pin P0_0 is first initialized as an output pin with strong drive mode. The pin is then reconfigured as an input with high impedance digital drive mode.

Note
cyhal_gpio_configure only changes the direction and the drive_mode of the pin. Previously set pin value is retained.
cy_rslt_t rslt;
/* Initialize pin P0_0 GPIO as an output with strong drive mode and initial value = false (low) */
/* Application Code */
/* Re-configure pin P0_0 as an input pin */

Snippet 4: Interrupts on GPIO events

GPIO events can be mapped to an interrupt and assigned to a callback function. The callback function needs to be first registered and then the event needs to be enabled. The following snippet initializes GPIO pin P0_0 as an input pin. It registers a callback function and enables detection of a falling edge event to trigger the callback.

Note
If no argument needs to be passed to the callback function then a NULL can be passed during registering.
uint32_t global_count = 0;
/* Interrupt handler callback function */
void gpio_interrupt_handler(void *handler_arg, cyhal_gpio_irq_event_t event)
{
CY_UNUSED_PARAMETER(event);
/* Increment global_count (passed as handler_arg) using a pointer */
uint32_t* count = (uint32_t *) handler_arg;
*count = *count + 1;
/* Toggle pin P0_1 on every interrupt */
}
void snippet_cyhal_gpio_interrupt()
{
cy_rslt_t rslt;
/* Initialize pin P0_0 GPIO as an input pin */
CY_ASSERT(CY_RSLT_SUCCESS == rslt);
/* Initialize pin P0_1 GPIO as an output with strong drive mode and initial value = true (high) */
CY_ASSERT(CY_RSLT_SUCCESS == rslt);
/* Register callback function - gpio_interrupt_handler and pass the value global_count */
cyhal_gpio_register_callback(P0_0, gpio_interrupt_handler, (void *)&global_count);
/* Enable falling edge interrupt event with interrupt priority set to 3 */
}

Macros

#define CYHAL_NC_PIN_VALUE   (NC)
 Integer representation of no connect pin (required to exist in all BSPs)
 

Typedefs

typedef void(* cyhal_gpio_event_callback_t) (void *callback_arg, cyhal_gpio_event_t event)
 GPIO callback function type.
 

Enumerations

enum  cyhal_gpio_event_t {
  CYHAL_GPIO_IRQ_NONE = 0,
  CYHAL_GPIO_IRQ_RISE = 1 << 0,
  CYHAL_GPIO_IRQ_FALL = 1 << 1,
  CYHAL_GPIO_IRQ_BOTH = (CYHAL_GPIO_IRQ_RISE | CYHAL_GPIO_IRQ_FALL)
}
 Pin events. More...
 
enum  cyhal_gpio_direction_t {
  CYHAL_GPIO_DIR_INPUT,
  CYHAL_GPIO_DIR_OUTPUT,
  CYHAL_GPIO_DIR_BIDIRECTIONAL
}
 Pin direction. More...
 
enum  cyhal_gpio_drive_mode_t {
  CYHAL_GPIO_DRIVE_NONE,
  CYHAL_GPIO_DRIVE_ANALOG,
  CYHAL_GPIO_DRIVE_PULLUP,
  CYHAL_GPIO_DRIVE_PULLDOWN,
  CYHAL_GPIO_DRIVE_OPENDRAINDRIVESLOW,
  CYHAL_GPIO_DRIVE_OPENDRAINDRIVESHIGH,
  CYHAL_GPIO_DRIVE_STRONG,
  CYHAL_GPIO_DRIVE_PULLUPDOWN,
  CYHAL_GPIO_DRIVE_PULL_NONE
}
 Pin drive mode. More...
 

Functions

cy_rslt_t cyhal_gpio_init (cyhal_gpio_t pin, cyhal_gpio_direction_t direction, cyhal_gpio_drive_mode_t drive_mode, bool init_val)
 Initialize the GPIO pin
See Snippet 1: Reading value from GPIO. More...
 
void cyhal_gpio_free (cyhal_gpio_t pin)
 Uninitialize the gpio peripheral and the cyhal_gpio_t object. More...
 
cy_rslt_t cyhal_gpio_configure (cyhal_gpio_t pin, cyhal_gpio_direction_t direction, cyhal_gpio_drive_mode_t drive_mode)
 Configure the GPIO pin
See Snippet 3: Reconfiguring a GPIO. More...
 
void cyhal_gpio_write (cyhal_gpio_t pin, bool value)
 Set the output value for the pin. More...
 
bool cyhal_gpio_read (cyhal_gpio_t pin)
 Read the input value. More...
 
void cyhal_gpio_toggle (cyhal_gpio_t pin)
 Toggle the output value
See Snippet 4: Interrupts on GPIO events. More...
 
void cyhal_gpio_register_callback (cyhal_gpio_t pin, cyhal_gpio_event_callback_t callback, void *callback_arg)
 Register/clear a callback handler for pin events
More...
 
void cyhal_gpio_enable_event (cyhal_gpio_t pin, cyhal_gpio_event_t event, uint8_t intr_priority, bool enable)
 Enable or Disable the specified GPIO event
More...
 

Enumeration Type Documentation

◆ cyhal_gpio_event_t

Pin events.

Enumerator
CYHAL_GPIO_IRQ_NONE 

No interrupt.

CYHAL_GPIO_IRQ_RISE 

Interrupt on rising edge.

CYHAL_GPIO_IRQ_FALL 

Interrupt on falling edge.

CYHAL_GPIO_IRQ_BOTH 

Interrupt on both rising and falling edges.

◆ cyhal_gpio_direction_t

Pin direction.

Enumerator
CYHAL_GPIO_DIR_INPUT 

Input pin.

CYHAL_GPIO_DIR_OUTPUT 

Output pin.

CYHAL_GPIO_DIR_BIDIRECTIONAL 

Input and output pin.

◆ cyhal_gpio_drive_mode_t

Pin drive mode.

Note
When the drive_mode of the pin is set to CYHAL_GPIO_DRIVE_PULL_NONE , it is set to CYHAL_GPIO_DRIVE_STRONG if the direction of the pin is CYHAL_GPIO_DIR_OUTPUT or CYHAL_GPIO_DIR_BIDIRECTIONAL. If not, the drive_mode of the pin is set to CYHAL_GPIO_DRIVE_NONE.
Enumerator
CYHAL_GPIO_DRIVE_NONE 

Digital Hi-Z.

Input only. Input init value(s): 0 or 1

CYHAL_GPIO_DRIVE_ANALOG 

Analog Hi-Z.

Use only for analog purpose

CYHAL_GPIO_DRIVE_PULLUP 

Pull-up resistor.

Input and output. Input init value(s): 1, output value(s): 0

CYHAL_GPIO_DRIVE_PULLDOWN 

Pull-down resistor.

Input and output. Input init value(s): 0, output value(s): 1

CYHAL_GPIO_DRIVE_OPENDRAINDRIVESLOW 

Open-drain, Drives Low.

Input and output. Input init value(s): 1, output value(s): 0

CYHAL_GPIO_DRIVE_OPENDRAINDRIVESHIGH 

Open-drain, Drives High.

Input and output. Input init value(s): 0, output value(s): 1

CYHAL_GPIO_DRIVE_STRONG 

Strong output.

Output only. Output init value(s): 0 or 1

CYHAL_GPIO_DRIVE_PULLUPDOWN 

Pull-up and pull-down resistors.

Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1

CYHAL_GPIO_DRIVE_PULL_NONE 

No Pull-up or pull-down resistors.

Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1

Function Documentation

◆ cyhal_gpio_init()

cy_rslt_t cyhal_gpio_init ( cyhal_gpio_t  pin,
cyhal_gpio_direction_t  direction,
cyhal_gpio_drive_mode_t  drive_mode,
bool  init_val 
)

Initialize the GPIO pin
See Snippet 1: Reading value from GPIO.

Parameters
[in]pinThe GPIO pin to initialize
[in]directionThe pin direction
[in]drive_modeThe pin drive mode
[in]init_valInitial value on the pin
Returns
The status of the init request

Guidance for using gpio drive modes ( cyhal_gpio_drive_mode_t for details). For default use drive modes: Input GPIO direction - CYHAL_GPIO_DRIVE_NONE Output GPIO direction - CYHAL_GPIO_DRIVE_STRONG Bidirectional GPIO - CYHAL_GPIO_DRIVE_PULLUPDOWN

Warning
Don't use CYHAL_GPIO_DRIVE_STRONG for input GPIO direction. It may cause an overcurrent issue.

◆ cyhal_gpio_free()

void cyhal_gpio_free ( cyhal_gpio_t  pin)

Uninitialize the gpio peripheral and the cyhal_gpio_t object.

Parameters
[in]pinPin number

◆ cyhal_gpio_configure()

cy_rslt_t cyhal_gpio_configure ( cyhal_gpio_t  pin,
cyhal_gpio_direction_t  direction,
cyhal_gpio_drive_mode_t  drive_mode 
)

Configure the GPIO pin
See Snippet 3: Reconfiguring a GPIO.

Parameters
[in]pinThe GPIO pin
[in]directionThe pin direction
[in]drive_modeThe pin drive mode
Returns
The status of the configure request

◆ cyhal_gpio_write()

void cyhal_gpio_write ( cyhal_gpio_t  pin,
bool  value 
)

Set the output value for the pin.

This only works for output & in_out pins.
See Snippet 2: Writing value to a GPIO.

Parameters
[in]pinThe GPIO object
[in]valueThe value to be set (high = true, low = false)

◆ cyhal_gpio_read()

bool cyhal_gpio_read ( cyhal_gpio_t  pin)

Read the input value.

This only works for CYHAL_GPIO_DIR_INPUT & CYHAL_GPIO_DIR_BIDIRECTIONAL pins.
See Snippet 1: Reading value from GPIO.

Parameters
[in]pinThe GPIO object
Returns
The value of the IO (true = high, false = low)

◆ cyhal_gpio_toggle()

void cyhal_gpio_toggle ( cyhal_gpio_t  pin)

Toggle the output value
See Snippet 4: Interrupts on GPIO events.

Parameters
[in]pinThe GPIO object

◆ cyhal_gpio_register_callback()

void cyhal_gpio_register_callback ( cyhal_gpio_t  pin,
cyhal_gpio_event_callback_t  callback,
void *  callback_arg 
)

Register/clear a callback handler for pin events

This function will be called when one of the events enabled by cyhal_gpio_enable_event occurs.

See Snippet 4: Interrupts on GPIO events.

Parameters
[in]pinThe pin number
[in]callbackThe function to call when the specified event happens. Pass NULL to unregister the handler.
[in]callback_argGeneric argument that will be provided to the callback when called, can be NULL

◆ cyhal_gpio_enable_event()

void cyhal_gpio_enable_event ( cyhal_gpio_t  pin,
cyhal_gpio_event_t  event,
uint8_t  intr_priority,
bool  enable 
)

Enable or Disable the specified GPIO event

When an enabled event occurs, the function specified by cyhal_gpio_register_callback will be called.

See Snippet 4: Interrupts on GPIO events.

Parameters
[in]pinThe GPIO object
[in]eventThe GPIO event
[in]intr_priorityThe priority for NVIC interrupt events
[in]enableTrue to turn on interrupts, False to turn off