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

• 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 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 */
    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 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) */
    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 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) */
    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 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 */
    cyhal_gpio_toggle(P0_1);
}

void 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);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    /* Initialize pin P0_1 GPIO as an output with strong drive mode and initial value = true (high) */
    rslt = cyhal_gpio_init(P0_1, CYHAL_GPIO_DIR_OUTPUT, CYHAL_GPIO_DRIVE_STRONG, true);
    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 */
    cyhal_gpio_enable_event(P0_0, CYHAL_GPIO_IRQ_FALL, 3, true);
}

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

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_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]	pin	The pin number
[in]	callback	The function to call when the specified event happens. Pass NULL to unregister the handler.
[in]	callback_arg	Generic 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]	pin	The GPIO object
[in]	event	The GPIO event
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off