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 - mtb_hal_gpio_direction_t
• Configurable GPIO pin drive modes - mtb_hal_gpio_drive_mode_t
• Configurable analog and digital characteristics
• Configurable edge-triggered interrupts and callback assignment on GPIO events - mtb_hal_gpio_event_t

Quick Start

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;
    mtb_hal_gpio_t    pin;
 
    // Initialize pin as an input
    Cy_GPIO_Pin_FastInit(PIN1_PORT, PIN1_PIN, MTB_HAL_GPIO_DIR_INPUT, 0x0, HSIOM_SEL_GPIO);
    mtb_hal_gpio_setup(&pin, PIN1_PORT_NUM, PIN1_PIN);
 
    // Read the logic level on the input pin
    read_val = mtb_hal_gpio_read(&pin);

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;
    mtb_hal_gpio_t    pin;
 
    // Initialize pin GPIO as an output with strong drive mode and initial value = false (low)
    Cy_GPIO_Pin_FastInit(PIN1_PORT, PIN1_PIN, MTB_HAL_GPIO_DIR_OUTPUT, 0x0, HSIOM_SEL_GPIO);
    mtb_hal_gpio_setup(&pin, PIN1_PORT_NUM, PIN1_PIN);
 
    // Write the value to the output pin
    mtb_hal_gpio_write(&pin, 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

mtb_hal_gpio_configure only changes the direction and the drive_mode of the pin. Previously set pin value is retained.

    cy_rslt_t         rslt;
    mtb_hal_gpio_t    pin;
 
    // Initialize pin GPIO as an output with strong drive mode and initial value = false (low)
    Cy_GPIO_Pin_FastInit(PIN1_PORT, PIN1_PIN, MTB_HAL_GPIO_DIR_OUTPUT, 0x0, HSIOM_SEL_GPIO);
    mtb_hal_gpio_setup(&pin, PIN1_PORT_NUM, PIN1_PIN);
 
    // Application Code
 
    // Re-configure pin as an input pin
    mtb_hal_gpio_configure(&pin, MTB_HAL_GPIO_DIR_INPUT, MTB_HAL_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.

 
mtb_hal_gpio_t                 pin_1, pin_2;
uint32_t                       global_count = 0U;
 
 
// Interrupt handler callback function
void gpio_interrupt_handler(void)
{
    mtb_hal_gpio_process_interrupt(&pin_1);
}
 
 
// GPIO event handler
void gpio_event_handler(void* handler_arg, mtb_hal_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_2 on every interrupt event
    mtb_hal_gpio_toggle(&pin_2);
}
 
 
void snippet_mtb_hal_gpio_interrupt(void)
{
    // Macro Definitions
    #define INT_PRIORITY    7
 
    cy_stc_sysint_t         intr_cfg;
 
    // Initialize pin_1 GPIO as an input pin
    Cy_GPIO_Pin_FastInit(PIN1_PORT, PIN1_PIN, MTB_HAL_GPIO_DIR_INPUT, 0x0, HSIOM_SEL_GPIO);
    mtb_hal_gpio_setup(&pin_1, PIN1_PORT_NUM, PIN1_PIN);
 
    // Configure and enable the GPIO interrupt
    intr_cfg.intrSrc = GPIO_IRQ_SRC;
    intr_cfg.intrPriority = INT_PRIORITY;
    Cy_SysInt_Init(&intr_cfg, gpio_interrupt_handler);
    NVIC_EnableIRQ(GPIO_IRQ);
 
    // Initialize pin_2 GPIO as an output with strong drive mode and initial value = false (low)
    Cy_GPIO_Pin_FastInit(PIN2_PORT, PIN2_PIN, MTB_HAL_GPIO_DIR_OUTPUT, 0x0, HSIOM_SEL_GPIO);
    mtb_hal_gpio_setup(&pin_2, PIN2_PORT_NUM, PIN2_PIN);
 
    // Register the GPIO event callback
    mtb_hal_gpio_register_callback(&pin_1, gpio_event_handler, &global_count);
 
    // Enable falling edge interrupt event with interrupt priority set to 7
    mtb_hal_gpio_enable_event(&pin_1, MTB_HAL_GPIO_IRQ_FALL, true);
}
 
 

Snippet 5: Reading and writing from a port

The following snippet shows how to configure a GPIO port to do port-wide reads and writes. The GPIO pins are first initialized as output pins with strong drive mode. These are then accessed at a port level.

    cy_rslt_t rslt;
    mtb_hal_gpio_port_t port_1;
    uint32_t value;
 
    /* Initialize pins P0_0, P0_1, P0_2 GPIO as outputs with strong drive mode and initial value =
       false (low)
     */
    Cy_GPIO_Pin_FastInit(GPIO_PRT0, 0, MTB_HAL_GPIO_DIR_OUTPUT, 0x0, HSIOM_SEL_GPIO);
    Cy_GPIO_Pin_FastInit(GPIO_PRT0, 1, MTB_HAL_GPIO_DIR_OUTPUT, 0x0, HSIOM_SEL_GPIO);
    Cy_GPIO_Pin_FastInit(GPIO_PRT0, 2, MTB_HAL_GPIO_DIR_OUTPUT, 0x0, HSIOM_SEL_GPIO);
 
    /* Initialize GPIO Port 0 for port-wide operations */
    mtb_hal_gpio_port_setup(&port_1, 0UL);
 
    /* Set the output to 0x5. This impacts all pins in the port. */
    mtb_hal_gpio_port_write(&port_1, 0x5);
 
    /* Invert the two LSBs (5 ^ 3) = 6. Other pins in the port are not impacted. */
    mtb_hal_gpio_port_toggle(&port_1, 0x3);
 
    /* Clear the three LSBs (6 & ~7) = 0. Other pins in the port are not impacted. */
    mtb_hal_gpio_port_clear(&port_1, 0x7);
 
    /* Set the output to 0x6. This impacts all pins in the port. */
    mtb_hal_gpio_port_write(&port_1, 0x6);
 
    /* Sets output data of LSB to '1'. Other pins in the port are not impacted. */
    mtb_hal_gpio_port_set(&port_1, 0x1);
 
    /* Reads all bits from the port. */
    mtb_hal_gpio_port_read(&port_1, &value);
 

API Reference
	GPIO HAL Results
	GPIO specific return codes.

Macros
#define	MTB_HAL_GPIO_NC_VALUE   (0xFF)
	Integer representation of no connect gpio (required to exist in all BSPs)
#define	NC   0xFF
	No Connect/Invalid Pin.

Typedefs
typedef void(*	mtb_hal_gpio_event_callback_t) (void *callback_arg, mtb_hal_gpio_event_t event)
	GPIO callback function type.

Enumerations
enum	mtb_hal_gpio_event_t {   MTB_HAL_GPIO_IRQ_NONE = 0 ,   MTB_HAL_GPIO_IRQ_RISE = 1 << 0 ,   MTB_HAL_GPIO_IRQ_FALL = 1 << 1 ,   MTB_HAL_GPIO_IRQ_BOTH = (MTB_HAL_GPIO_IRQ_RISE | MTB_HAL_GPIO_IRQ_FALL) }
	Pin events. More...
enum	mtb_hal_gpio_direction_t {   MTB_HAL_GPIO_DIR_INPUT ,   MTB_HAL_GPIO_DIR_OUTPUT ,   MTB_HAL_GPIO_DIR_BIDIRECTIONAL }
	Pin direction. More...
enum	mtb_hal_gpio_drive_mode_t {   MTB_HAL_GPIO_DRIVE_ANALOG = (MTB_HAL_MAP_GPIO_DRIVE_ANALOG) ,   MTB_HAL_GPIO_DRIVE_NONE = (MTB_HAL_MAP_GPIO_DRIVE_NONE) ,   MTB_HAL_GPIO_DRIVE_PULLUP = (MTB_HAL_MAP_GPIO_DRIVE_PULLUP) ,   MTB_HAL_GPIO_DRIVE_PULLDOWN = (MTB_HAL_MAP_GPIO_DRIVE_PULLDOWN) ,   MTB_HAL_GPIO_DRIVE_OPENDRAINDRIVESLOW = (MTB_HAL_MAP_GPIO_DRIVE_OPENDRAINDRIVESLOW) ,   MTB_HAL_GPIO_DRIVE_OPENDRAINDRIVESHIGH = (MTB_HAL_MAP_GPIO_DRIVE_OPENDRAINDRIVESHIGH) ,   MTB_HAL_GPIO_DRIVE_STRONG = (MTB_HAL_MAP_GPIO_DRIVE_STRONG) ,   MTB_HAL_GPIO_DRIVE_PULLUPDOWN = (MTB_HAL_MAP_GPIO_DRIVE_PULLUPDOWN) ,   MTB_HAL_GPIO_DRIVE_PULL_NONE = (MTB_HAL_MAP_GPIO_DRIVE_PULL_NONE) }
	Pin drive mode. More...

Functions
void	mtb_hal_gpio_setup (mtb_hal_gpio_t *obj, const uint8_t port, const uint8_t pin)
	Init the GPIO object More...
void	mtb_hal_gpio_configure (mtb_hal_gpio_t *obj, mtb_hal_gpio_direction_t direction, mtb_hal_gpio_drive_mode_t drive_mode)
	Configure the GPIO pin See Snippet 3: Reconfiguring a GPIO. More...
void	mtb_hal_gpio_write (mtb_hal_gpio_t *obj, bool value)
	Set the output value for the pin. More...
bool	mtb_hal_gpio_read (mtb_hal_gpio_t *obj)
	Read the input value. More...
void	mtb_hal_gpio_toggle (mtb_hal_gpio_t *obj)
	Toggle the output value See Snippet 4: Interrupts on GPIO events. More...
void	mtb_hal_gpio_port_setup (mtb_hal_gpio_port_t *port, uint32_t port_number)
	Setup the port object. More...
void	mtb_hal_gpio_port_set (mtb_hal_gpio_port_t *port, uint32_t pin_mask)
	Set the output value for specified port with pin_mask. More...
void	mtb_hal_gpio_port_clear (mtb_hal_gpio_port_t *port, uint32_t pin_mask)
	Clear the output value with pin_mask. More...
void	mtb_hal_gpio_port_toggle (mtb_hal_gpio_port_t *port, uint32_t pin_mask)
	Toggle the output value with pin_mask. More...
void	mtb_hal_gpio_port_write (mtb_hal_gpio_port_t *port, uint32_t value)
	Set the output value for specified port. More...
void	mtb_hal_gpio_port_read (mtb_hal_gpio_port_t *port, uint32_t *value)
	Reads all bits from specified port. More...
void	mtb_hal_gpio_register_callback (mtb_hal_gpio_t *obj, mtb_hal_gpio_event_callback_t callback, void *callback_arg)
	Register/clear a callback handler for pin events More...
void	mtb_hal_gpio_enable_event (mtb_hal_gpio_t *obj, mtb_hal_gpio_event_t event, bool enable)
	Enable or Disable the specified GPIO event More...
cy_rslt_t	mtb_hal_gpio_process_interrupt (mtb_hal_gpio_t *obj)
	Process interrupts related related to a GPIO instance. More...

Enumeration Type Documentation

mtb_hal_gpio_event_t

enum mtb_hal_gpio_event_t

Pin events.

Enumerator
MTB_HAL_GPIO_IRQ_NONE	No interrupt.
MTB_HAL_GPIO_IRQ_RISE	Interrupt on rising edge.
MTB_HAL_GPIO_IRQ_FALL	Interrupt on falling edge.
MTB_HAL_GPIO_IRQ_BOTH	Interrupt on both rising and falling edges.

mtb_hal_gpio_direction_t

enum mtb_hal_gpio_direction_t

Pin direction.

Enumerator
MTB_HAL_GPIO_DIR_INPUT	Input pin.
MTB_HAL_GPIO_DIR_OUTPUT	Output pin.
MTB_HAL_GPIO_DIR_BIDIRECTIONAL	Input and output pin.

mtb_hal_gpio_drive_mode_t

enum mtb_hal_gpio_drive_mode_t

Pin drive mode.

Note

When the drive_mode of the pin is set to MTB_HAL_GPIO_DRIVE_PULL_NONE , it is set to MTB_HAL_GPIO_DRIVE_STRONG if the direction of the pin is MTB_HAL_GPIO_DIR_OUTPUT or MTB_HAL_GPIO_DIR_BIDIRECTIONAL. If not, the drive_mode of the pin is set to MTB_HAL_GPIO_DRIVE_NONE.

Enumerator
MTB_HAL_GPIO_DRIVE_ANALOG	Digital Hi-Z. Input only. Input init value(s): 0 or 1 Analog Hi-Z. Use only for analog purpose
MTB_HAL_GPIO_DRIVE_NONE	Pull-up resistor. Input and output. Input init value(s): 1, output value(s): 0
MTB_HAL_GPIO_DRIVE_PULLUP	Pull-down resistor. Input and output. Input init value(s): 0, output value(s): 1
MTB_HAL_GPIO_DRIVE_PULLDOWN	Open-drain, Drives Low. Input and output. Input init value(s): 1, output value(s): 0
MTB_HAL_GPIO_DRIVE_OPENDRAINDRIVESLOW	Open-drain, Drives High. Input and output. Input init value(s): 0, output value(s): 1
MTB_HAL_GPIO_DRIVE_OPENDRAINDRIVESHIGH	Strong output. Output only. Output init value(s): 0 or 1
MTB_HAL_GPIO_DRIVE_STRONG	Pull-up and pull-down resistors. Input and output. Input init value(s): 0 or 1, output value(s): 0 or 1
MTB_HAL_GPIO_DRIVE_PULLUPDOWN	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

mtb_hal_gpio_setup()

void mtb_hal_gpio_setup	(	mtb_hal_gpio_t *	obj,
		const uint8_t	port,
		const uint8_t	pin
	)

Init the GPIO object

Parameters

[in]	obj	The GPIO object
[in]	port	The port number
[in]	pin	The pin number

mtb_hal_gpio_configure()

void mtb_hal_gpio_configure	(	mtb_hal_gpio_t *	obj,
		mtb_hal_gpio_direction_t	direction,
		mtb_hal_gpio_drive_mode_t	drive_mode
	)

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

Parameters

[in]	obj	The GPIO object
[in]	direction	The pin direction
[in]	drive_mode	The pin drive mode

mtb_hal_gpio_write()

void mtb_hal_gpio_write	(	mtb_hal_gpio_t *	obj,
		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]	obj	The GPIO object
[in]	value	The value to be set (high = true, low = false)

mtb_hal_gpio_read()

bool mtb_hal_gpio_read

(

mtb_hal_gpio_t *

obj

)

Read the input value.

This only works for MTB_HAL_GPIO_DIR_INPUT & MTB_HAL_GPIO_DIR_BIDIRECTIONAL pins.
See Snippet 1: Reading value from GPIO.

Parameters

[in]

obj

The GPIO object

Returns

The value of the IO (true = high, false = low)

mtb_hal_gpio_toggle()

void mtb_hal_gpio_toggle

(

mtb_hal_gpio_t *

obj

)

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

Parameters

[in]

obj

The GPIO object

mtb_hal_gpio_port_setup()

void mtb_hal_gpio_port_setup	(	mtb_hal_gpio_port_t *	port,
		uint32_t	port_number
	)

Setup the port object.

Parameters

[out]	port	Pointer to a port object. The caller must allocate the memory for this object but the init function will initialize its contents. mtb_hal_gpio_port_t is an output that is populated based on the input(port_number).
[in]	port_number	The port number

mtb_hal_gpio_port_set()

void mtb_hal_gpio_port_set	(	mtb_hal_gpio_port_t *	port,
		uint32_t	pin_mask
	)

Set the output value for specified port with pin_mask.

Parameters

[in]	port	The port object
[in]	pin_mask	The pin mask (LSB means pin 0)

Sets output data of specific IO pins in the corresponding port to '1', without affecting the output data of the other IO pads in the port. All bits in the bitmask are modified at once.

mtb_hal_gpio_port_clear()

void mtb_hal_gpio_port_clear	(	mtb_hal_gpio_port_t *	port,
		uint32_t	pin_mask
	)

Clear the output value with pin_mask.

Parameters

[in]	port	The GPIO object
[in]	pin_mask	The pin mask (LSB means pin 0)

Sets output data of specific IO pins in the corresponding port to '0', without affecting the output data of the other IO pads in the port. All bits in the bitmask are modified at once.

mtb_hal_gpio_port_toggle()

void mtb_hal_gpio_port_toggle	(	mtb_hal_gpio_port_t *	port,
		uint32_t	pin_mask
	)

Toggle the output value with pin_mask.

Parameters

[in]	port	The GPIO object
[in]	pin_mask	The pin mask (LSB means pin 0)

Inverts the output data of specific IO pins in the corresponding port, without affecting the output data of the other IO pads in the port. All bits in the bitmask are modified at once.

mtb_hal_gpio_port_write()

void mtb_hal_gpio_port_write	(	mtb_hal_gpio_port_t *	port,
		uint32_t	value
	)

Set the output value for specified port.

Parameters

[in]	port	The port object
[in]	value	The value to be set (high = true, low = false)

All GPIO output bits in the port are modified.

mtb_hal_gpio_port_read()

void mtb_hal_gpio_port_read	(	mtb_hal_gpio_port_t *	port,
		uint32_t *	value
	)

Reads all bits from specified port.

Parameters

[in]	port	The port object
[in]	value	The value of the IO (high = true, low = false)

mtb_hal_gpio_register_callback()

void mtb_hal_gpio_register_callback	(	mtb_hal_gpio_t *	obj,
		mtb_hal_gpio_event_callback_t	callback,
		void *	callback_arg
	)

Register/clear a callback handler for pin events

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

See Snippet 4: Interrupts on GPIO events.

Parameters

[in]	obj	The GPIO object
[in]	callback	The callback handler which will be invoked when the event occurs
[in]	callback_arg	Generic argument that will be provided to the callback when called

mtb_hal_gpio_enable_event()

void mtb_hal_gpio_enable_event	(	mtb_hal_gpio_t *	obj,
		mtb_hal_gpio_event_t	event,
		bool	enable
	)

Enable or Disable the specified GPIO event

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

See Snippet 4: Interrupts on GPIO events.

Parameters

[in]	obj	The GPIO object
[in]	event	The GPIO event
[in]	enable	True to turn on interrupts, False to turn off

mtb_hal_gpio_process_interrupt()

cy_rslt_t mtb_hal_gpio_process_interrupt

(

mtb_hal_gpio_t *

obj

)

Process interrupts related related to a GPIO instance.

Parameters

obj	HAL object for which the interrupt should be processed

Returns

CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error