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

Configurable GPIO pin direction - cyhal_gpio_direction_t
Configurable GPIO pin drive modes - cyhal_gpio_drive_mode_t
Configurable analog and digital characteristics
Configurable edge-triggered interrupts and callback assignment on GPIO events - cyhal_gpio_event_t

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 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
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_NONE, false);
    // 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 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)
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, false);
    // 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 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)
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, false);
    // Application Code
    // Re-configure pin P0_0 as an input pin
    rslt = cyhal_gpio_configure(P0_0, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_NONE);

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 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;
cyhal_gpio_callback_data_t cb_data =
{
    .callback     = gpio_interrupt_handler,
    .callback_arg = (void*)&global_count
};
// Interrupt handler callback function
void gpio_interrupt_handler(void* handler_arg, cyhal_gpio_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
    cyhal_gpio_toggle(P0_1);
}
cy_rslt_t snippet_cyhal_gpio_interrupt()
{
    cy_rslt_t rslt;
    // Initialize pin P0_0 GPIO as an input pin
    rslt = cyhal_gpio_init(P0_0, CYHAL_GPIO_DIR_INPUT, CYHAL_GPIO_DRIVE_NONE, false);
    // Initialize pin P0_1 GPIO as an output with strong drive mode and initial value = true (high)
    if (CY_RSLT_SUCCESS == rslt)
    {
        rslt = cyhal_gpio_init(P0_1, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, true);
    }
    if (CY_RSLT_SUCCESS == rslt)
    {
        // Register callback function - gpio_interrupt_handler and pass the value global_count
        cyhal_gpio_register_callback(P0_0, &cb_data);
        // Enable falling edge interrupt event with interrupt priority set to 3
        cyhal_gpio_enable_event(P0_0, CYHAL_GPIO_IRQ_FALL, 3, true);
    }
    return rslt;
}

API Reference
	GPIO HAL Results
	GPIO specific return codes.

Data Structures
struct	cyhal_gpio_callback_data_t
	Structure containing callback data for pins. More...

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_callback_data_t *callback_data)
	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...

cy_rslt_t	cyhal_gpio_connect_digital (cyhal_gpio_t pin, cyhal_source_t source)
	Connects a source signal and enables an input to a pin that, when triggered, will set the pins output. More...

cy_rslt_t	cyhal_gpio_enable_output (cyhal_gpio_t pin, cyhal_signal_type_t type, cyhal_source_t *source)
	Enables an output signal from a pin that is triggered by the pins input. More...

cy_rslt_t	cyhal_gpio_disconnect_digital (cyhal_gpio_t pin, cyhal_source_t source)
	Disconnects a source signal and disables an input to a pin. More...

cy_rslt_t	cyhal_gpio_disable_output (cyhal_gpio_t pin)
	Disables an output signal from a pin. More...

Data Structure Documentation

◆ cyhal_gpio_callback_data_t

struct cyhal_gpio_callback_data_t

Data Fields
cyhal_gpio_event_callback_t	callback	The callback function to run.
void *	callback_arg	Optional argument for the callback.
struct cyhal_gpio_callback_data_s *	next	NULL. Filled in by the HAL driver
cyhal_gpio_t	pin	NC. Filled in by the HAL driver

Enumeration Type Documentation

◆ cyhal_gpio_event_t

enum 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

enum 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

enum 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]	pin	The GPIO pin to initialize
[in]	direction	The pin direction
[in]	drive_mode	The pin drive mode
[in]	init_val	Initial 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] pin Pin 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]	pin	The GPIO pin
[in]	direction	The pin direction
[in]	drive_mode	The 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]	pin	The GPIO object
[in]	value	The 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] pin The 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] pin The GPIO object

◆ cyhal_gpio_register_callback()

void cyhal_gpio_register_callback	(	cyhal_gpio_t	pin,
		cyhal_gpio_callback_data_t *	callback_data
	)

Register/clear a callback handler for pin events

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

See Snippet 4: Interrupts on GPIO events.

Note: The signature for this function is slightly different from other HAL register_callback functions. This is because the cyhal_gpio_t is a enum value and not a pointer to a struct. This prevents storing the callback information on the instance object itself. So instead we need a different mechanism to keep track of this data.

Parameters

[in]	pin	The GPIO object
[in]	callback_data	The callback data to register. Use NULL to unregister. This object must persist for the length of time the callback is registered. As such, it should not be declared on the stack.

◆ 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]	pin	The GPIO object
[in]	event	The GPIO event
[in]	intr_priority	The priority for NVIC interrupt events. Interrupt priorities specific to a pin may not be supported on all platforms. Refer to platform implementation specific documentation for details.
[in]	enable	True to turn on interrupts, False to turn off

◆ cyhal_gpio_connect_digital()

cy_rslt_t cyhal_gpio_connect_digital	(	cyhal_gpio_t	pin,
		cyhal_source_t	source
	)

Connects a source signal and enables an input to a pin that, when triggered, will set the pins output.

Parameters

[in]	pin	GPIO object
[in]	source	Source signal obtained from another driver's cyhal_<PERIPH>_enable_output

Returns: The status of the connection

◆ cyhal_gpio_enable_output()

cy_rslt_t cyhal_gpio_enable_output	(	cyhal_gpio_t	pin,
		cyhal_signal_type_t	type,
		cyhal_source_t *	source
	)

Enables an output signal from a pin that is triggered by the pins input.

Parameters

[in]	pin	GPIO object
[in]	type	Whether the signal will act as a edge or level input
[out]	source	Pointer to user-allocated source signal object which will be initialized by enable_output. `source` should be passed to (dis)connect_digital functions to (dis)connect the associated endpoints.

Returns: The status of the output enable

◆ cyhal_gpio_disconnect_digital()

cy_rslt_t cyhal_gpio_disconnect_digital	(	cyhal_gpio_t	pin,
		cyhal_source_t	source
	)

Disconnects a source signal and disables an input to a pin.

Parameters

[in]	pin	GPIO object
[in]	source	Source signal from cyhal_<PERIPH>_enable_output to disable

Returns: The status of the disconnection

◆ cyhal_gpio_disable_output()

cy_rslt_t cyhal_gpio_disable_output ( cyhal_gpio_t pin )

Disables an output signal from a pin.

Parameters

[in] pin GPIO object

Returns: The status of the output enable

General Description

Features

Quick Start

Code Snippets

Snippet 1: Reading value from GPIO

Snippet 2: Writing value to a GPIO

Snippet 3: Reconfiguring a GPIO

Snippet 4: Interrupts on GPIO events

API Reference

Data Structures

Macros

Typedefs

Enumerations

Functions

Data Structure Documentation

◆ cyhal_gpio_callback_data_t

Enumeration Type Documentation

◆ cyhal_gpio_event_t

◆ cyhal_gpio_direction_t

◆ cyhal_gpio_drive_mode_t

Function Documentation

◆ cyhal_gpio_init()

◆ cyhal_gpio_free()

◆ cyhal_gpio_configure()

◆ cyhal_gpio_write()

◆ cyhal_gpio_read()

◆ cyhal_gpio_toggle()

◆ cyhal_gpio_register_callback()

◆ cyhal_gpio_enable_event()

◆ cyhal_gpio_connect_digital()

◆ cyhal_gpio_enable_output()

◆ cyhal_gpio_disconnect_digital()

◆ cyhal_gpio_disable_output()