General-purpose I/Os (GPIO)

Features

  • Input Functionality

    • Debounce Feature: Input pins support debounce functionality to effectively prevent erroneous signals caused by bouncing.

    • Interrupt Support:

      • Level Trigger

      • Edge Trigger

      • Dual-edge Trigger

  • Output Functionality

    • Single Pin Output Configuration: Supports setting the output state of a specific pin individually.

    • Simultaneous Multiple Pin Configuration: Multiple pins of the same port can be configured for output simultaneously.

Debounce Feature

Debounce Clock

The debounce clock source is dbclk_src, with the output debounce clock dbclk defined as: dbclk = dbclk_src / (div + 1). Here, div is an adjustable division factor.

The debounce clock source for the chip is as follows:

RTL8721Dx:

  • 32.768kHz

  • OSC4MHz

Filtering Capability

  • Glitch signals shorter than 1 debounce clock cycle can be filtered out.

  • Glitch signals lasting between 1 to 2 debounce clock cycles are uncertain.

  • Glitch signals longer than 2 debounce clock cycles cannot be filtered out.

Port Filtering Consistency

For different pins on the same port, the div is shared, ensuring consistent debounce clock.

Note

Using the debounce feature introduces input signal processing delay. This may slow system response, particularly in scenarios requiring fast response such as interrupts and wake-up operations.

Interrupt Types

  • Level Trigger: Supports interrupt triggering via level state (high or low level).

  • Edge Trigger: Supports interrupt triggering on rising or falling edges.

  • Dual-edge Trigger: Supports triggering on both rising and falling edges.

Note

To avoid false triggering of interrupts when switching the edge trigger type, enable the interrupt only after a two-cycle debounce clock delay.

Output Race Condition Protection

GPIO outputs are controlled by port (PORT), and controlling the level state of a specific GPIO pin is a three-step operation in assembly: read, modify, write. If multiple threads control outputs on the same port group, a race condition may occur.

To mitigate this risk, both software and hardware protection methods are provided depending on the chip.

RTL8721Dx:

Software Protection

  • Use the GPIO_WriteBit_Critical() API instead of the GPIO_WriteBit() operation.

  • Locks resources at the software layer to avoid race conditions in multi-threaded or interrupt contexts.

Usage Examples

The SDK provides two types of feature examples to help developers understand and utilize GPIO functionality:

  • mbed Examples

    • Path: {SDK}\example\peripheral\mbed\GPIO\{demo}

    • Demonstrates how to implement GPIO control in the mbed environment.

  • raw Examples

    • Path: {SDK}\example\peripheral\raw\GPIO\{demo}

    • Demonstrates direct GPIO control without abstraction layers.

A brief description of the raw examples:

Note

To understand the chips supported by the examples, refer to the README.md file in the example path.

Raw API

GPIO Exported Types

typedef void (*GPIO_IRQ_FUN)(void *Data, u32 Id)

GPIO IRQ Function Definition.

struct GPIO_InitTypeDef

GPIO Init Structure Definition.

Public Members

u32 GPIO_Mode

Specifies the operating mode for the selected pins. This parameter can be a value of GPIO Mode

u32 GPIO_PuPd

Specifies the operating Pull-up/Pull down for the selected pins. This parameter can be a value of GPIO Pull Type

u32 GPIO_ITTrigger

Specifies interrupt mode is level or edge trigger This parameter can be a value of GPIO Interrupt Trigger Type

u32 GPIO_ITPolarity

Specifies interrupt mode is high or low active trigger This parameter can be a value of GPIO Interrupt Polarity Type

u32 GPIO_ITDebounce

Specifies enable or disable de-bounce for interrupt This parameter can be a value of GPIO Interrupt Debounce Type

u32 GPIO_Pin

Specifies the selected pins. This parameter contains two parts: Pin[7:5]: port number; Pin[4:0]: pin number

typedef void (*GPIO_USER_IRQ_FUN)(u32 Id)

GPIO User IRQ Function Definition.

RTL8721Dx:

Not supported.

GPIO Exported Constants

GPIO Interrupt Debounce Type

/* Disable interrupt debounce */
#define GPIO_INT_DEBOUNCE_DISABLE 0x0

/* Enable interrupt debounce */
#define GPIO_INT_DEBOUNCE_ENABLE 0x1

/* Check if GPIO interrupt debounce type is valid. */
#define IS_GPIOIT_DEBOUNCE_TYPE (((TYPE) == GPIO_INT_DEBOUNCE_DISABLE) || \
    ((TYPE) == GPIO_INT_DEBOUNCE_ENABLE))

GPIO Interrupt Polarity Type

/* Setting interrupt to low active: falling edge or low level */
#define GPIO_INT_POLARITY_ACTIVE_LOW 0x0

/* Setting interrupt to high active: rising edge or high level */
#define GPIO_INT_POLARITY_ACTIVE_HIGH 0x1

/* Check if GPIO interrupt polarity type is valid. */
#define IS_GPIOIT_POLARITY_TYPE (((TYPE) == GPIO_INT_POLARITY_ACTIVE_LOW) || \
    ((TYPE) == GPIO_INT_POLARITY_ACTIVE_HIGH))

GPIO Interrupt Trigger Type

/* This interrupt is level trigger */
#define GPIO_INT_Trigger_LEVEL 0x0

/* This interrupt is edge trigger */
#define GPIO_INT_Trigger_EDGE 0x1

/* This interrupt is both-edge trigger */
#define GPIO_INT_Trigger_BOTHEDGE 0x2

/* Check if GPIO interrupt trigger type is valid. */
#define IS_GPIOIT_LEVEL_TYPE (((TYPE) == GPIO_INT_Trigger_LEVEL) || \
    ((TYPE) == GPIO_INT_Trigger_EDGE) || \
    ((TYPE) == GPIO_INT_Trigger_BOTHEDGE))

GPIO IRQ Event

/* No interrupt event */
#define HAL_IRQ_NONE 0x0

/* Rising edge or high level interrupt event */
#define HAL_IRQ_RISE 0x1

/* Falling edge or low level interrupt event */
#define HAL_IRQ_FALL 0x2

GPIO Mode

/* GPIO Input Mode */
#define GPIO_Mode_IN 0x0

/* GPIO Output Mode */
#define GPIO_Mode_OUT 0x1

/* GPIO Interrupt Mode */
#define GPIO_Mode_INT 0x2

GPIO Pin State

/* Pin state is low */
#define GPIO_PIN_LOW 0x0

/* Pin state is high */
#define GPIO_PIN_HIGH 0x1

GPIO Port Type

/* Port number A */
#define GPIO_PORT_A 0x0
RTL8721Dx: 
/* Port number B */
#define GPIO_PORT_B 0x1

/* Check if GPIO port number is valid. */
#define IS_GPIO_PORT_NUM ((PORT) == GPIO_PORT_A || \
    (PORT) == GPIO_PORT_B)

GPIO Pull Type

/* GPIO Internal HIGHZ */
#define GPIO_PuPd_NOPULL 0x0

/* GPIO Internal Pull DOWN */
#define GPIO_PuPd_DOWN 0x1

/* GPIO Internal Pull UP */
#define GPIO_PuPd_UP 0x2

/* GPIO Internal PAD shutdown */
#define GPIO_PuPd_SHUTDOWN 0x3

GPIO IRQ Entry Used Magic Number

RTL8721Dx:

Not supported.

GPIO DR DDR Function Select

RTL8721Dx:

Not supported.

GPIO Exported Functions

void GPIO_DeInit(u32 GPIO_Pin)

De-Initialize a GPIO Pin, reset it as default setting.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

void GPIO_DebounceClock(u32 GPIO_Port, u32 DivideCount)

Set the specified port debounce clock.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

  • DivideCount – Debounce clock division with 32KHz.range: 0x0 - 0x7F. debounce time = (DivideCount +1) * 2 * 32μs.

void GPIO_Direction(u32 GPIO_Pin, u32 data_direction)

Set the specified GPIO pin data Direction.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

  • data_direction –

    Specifies GPIO pin direction This parameter can be one of the following values:

    • GPIO_Mode_IN: GPIO pin direction config input mode

    • GPIO_Mode_OUT: GPIO pin direction config output mode

void GPIO_INTConfig(u32 GPIO_Pin, u32 NewState)

Disable or Enable the interrupt of a specified pin.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

  • NewState – ENABLE/DISABLE

u32 GPIO_INTHandler(void *pData)

The common GPIO interrupt handler.

Parameters:

  • pData – The data pointer from the registered IRQ handler

Returns:

0 on success, 0xFFFFFFFF on error

void GPIO_INTMode(u32 GPIO_Pin, u32 NewState, u32 GPIO_ITTrigger, u32 GPIO_ITPolarity, u32 GPIO_ITDebounce)

Config GPIO interrupt mode.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

  • NewState – ENABLE/DISABLE

  • GPIO_ITTrigger –

    Specifies interrupt mode is level or edge trigger This parameter can be one of the following values:

    • GPIO_INT_Trigger_LEVEL: level trigger

    • GPIO_INT_Trigger_EDGE: edge trigger

    • GPIO_INT_Trigger_BOTHEDGE: both-edge trigger

  • GPIO_ITPolarity –

    Specifies interrupt mode is high or low active trigger This parameter can be one of the following values:

    • GPIO_INT_POLARITY_ACTIVE_LOW: falling edge or low level active

    • GPIO_INT_POLARITY_ACTIVE_HIGH: rising edge or high level active

  • GPIO_ITDebounce –

    Enable or disable de-bounce for interrupt This parameter can be one of the following values:

    • GPIO_INT_DEBOUNCE_DISABLE: disable de-bounce

    • GPIO_INT_DEBOUNCE_ENABLE: enable de-bounce

void GPIO_INTStatusClearEdge(u32 GPIO_Port)

Clear the edge interrupt status.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

u32 GPIO_INTStatusGet(u32 GPIO_Port)

Get the interrupt status.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

Returns:

The interrupt status of the specified port pins

void GPIO_Init(GPIO_InitTypeDef *GPIO_InitStruct)

Initialize the GPIO registers according to the specified parameters in GPIO_InitStruct.

Parameters:

  • GPIO_InitStruct – Pointer to a GPIO_InitTypeDef structure that contains the configuration information for the GPIO peripheral.

Note

  • OpenDrain output: on drive + OUT + GPIO[gpio_bit] = 0, pin should have pull-up resistor.

  • Input HighZ: no drive + IN, user can input high or low use this pin.

void GPIO_LevelSync(u32 GPIO_Port, u32 NewState)

Set the level sensitive interrupt synchronized to pclk_intr.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

  • NewState – All level-sensitive interrupts being synchronized to pclk_intr This parameter can be one of the following values: ENABLE: Synchronize to pclk_intr with 2 cycles DISABLE: No synchronization to pclk_intr (default)

void GPIO_ODInit(u8 PinName, u32 PUInternal)

Initialize specified GPIO pin output in Open Drain mode.

Parameters:

  • PinName – Value of PINMUX_Pin_Name_definitions.

  • PUInternal – Which can ENABLE or DISABLE.

void GPIO_ODWriteBit(u8 PinName, u32 PinState)

Write a specified output port pin in Open Drain mode.

Parameters:

  • PinName – Value of PINMUX_Pin_Name_definitions.

  • PinState –

    This parameter can be one of the following values:

    • GPIO_PIN_LOW: Pin state set to low

    • GPIO_PIN_HIGH: Pin state set to high

void GPIO_PortDirection(u32 GPIO_Port, u32 GPIO_Mask, u32 data_direction)

Set the specified GPIO port pins data direction.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

  • GPIO_Mask – One bit one GPIO pin, 0x00000000 ~0xFFFFFFFF.

  • data_direction –

    Specifies GPIO port pins direction This parameter can be one of the following values:

    • GPIO_Mode_IN: GPIO port pins direction config input mode

    • GPIO_Mode_OUT: GPIO port pins direction config output mode

Note

It can config multiple pins of one port by parameter GPIO_Mask

u32 GPIO_PortRead(u32 GPIO_Port, u32 GPIO_Mask)

Read the specified GPIO pins.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

  • GPIO_Mask – One bit one GPIO pin, 0x00000000 ~0xFFFFFFFF.

Returns:

The value of the specified port pins

Note

It can config multiple pins of one port by parameter GPIO_Mask

void GPIO_PortWrite(u32 GPIO_Port, u32 GPIO_Mask, u32 Port_State)

Write the specified port pins.

Parameters:

  • GPIO_Port – Specifies port number, which can be any GPIO_PORT_X defined in GPIO Port Type.

  • GPIO_Mask – One bit one GPIO pin, 0x00000000 ~0xFFFFFFFF.

  • Port_State – Specifies the state going to be set to the assigned GPIO pins.

u32 GPIO_ReadDataBit(u32 GPIO_Pin)

Read a specified GPIO pin Value.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

Returns:

The input port pin current status (High or Low).

void GPIO_UserRegIrq(u32 GPIO_Pin, void *IrqHandler, void *IrqData)

Register a user interrupt handler for a specified pin.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

  • IrqHandler – The IRQ handler to be assigned to the specified pin

  • IrqData – The pointer will be passed to the IRQ handler

void GPIO_WriteBit(u32 GPIO_Pin, u32 Pin_State)

Write a specified output port pin.

Parameters:

  • GPIO_Pin – GPIO pin num from PinName.

  • Pin_State –

    The state going to be set to the assigned GPIO pin. This parameter can be one of the following values:

    • GPIO_PIN_LOW: Pin state set to low

    • GPIO_PIN_HIGH: Pin state set to high

RTL8721Dx:

Not supported.

Mbed API

MBED_GPIO Exported Types

Enumeration Type

enum gpio_irq_event

Enum gpio_irq_event.

Values:

/* No IRQ event */
IRQ_NONE

/* Rising edge trigger */
IRQ_RISE

/* Falling edge trigger */
IRQ_FALL

/* Low level trigger */
IRQ_LOW = 3

/* High level trigger */
IRQ_HIGH = 4

/* Dual-edge (falling and rising) trigger */
IRQ_FALL_RISE = 5

Structure Type

typedef void (*gpio_irq_handler)(uint32_t id, uint32_t event)

Typedef function pointer for GPIO IRQ callback handler.

MBED_GPIO Exported Functions

void gpio_change_dir(gpio_t *obj, PinDirection direction)

Change GPIO direction.

Parameters:

  • obj – GPIO object defined in application software.

  • direction –

    This parameter can be one of the following values:

    • PIN_INPUT: The pin is changed to input.

    • PIN_OUTPUT: The pin is changed to output.

Note

It is the same with function gpio_dir();

void gpio_deinit(gpio_t *obj)

Deinitialize the GPIO device, including mode, direction and pull control registers.

Parameters:

  • obj – GPIO object defined in application software.

void gpio_dir(gpio_t *obj, PinDirection direction)

Set GPIO direction, including input and output.

Parameters:

  • obj – GPIO object defined in application software.

  • direction –

    This parameter can be one of the following values:

    • PIN_INPUT: The pin is set as input.

    • PIN_OUTPUT: The pin is set as output.

void gpio_direct_write(gpio_t *obj, bool value)

Set output value of the selected gpio pin.

Parameters:

  • obj – GPIO object defined in application software.

  • value –

    The value to be written to the selected pin. This parameter can be one of the following values:

    • 0: Set selected pin to low.

    • 1: Set selected pin to high.

Note

It is the same with function gpio_write();

void gpio_init(gpio_t *obj, PinName pin)

Initialize the GPIO device, including mode, direction and pull control registers.

Parameters:

  • obj – GPIO object defined in application software.

  • pin – PinName according to pinmux spec.

void gpio_irq_deinit(gpio_irq_t *obj)

Deinitialize the GPIO device’s interrupt mode, including mode, trigger and polarity registers.

Parameters:

  • obj – GPIO irq object defined in application software.

Note

It is the same with function GPIO_DeInit();

void gpio_irq_disable(gpio_irq_t *obj)

Disable GPIO interrupt.

Parameters:

  • obj – GPIO irq object defined in application software.

void gpio_irq_enable(gpio_irq_t *obj)

Enable GPIO interrupt.

Parameters:

  • obj – GPIO irq object defined in application software.

void gpio_irq_free(gpio_irq_t *obj)

Deinitialize the GPIO device interrupt mode, including mode, trigger and polarity registers.

Parameters:

  • obj – GPIO irq object defined in application software.

int gpio_irq_init(gpio_irq_t *obj, PinName pin, gpio_irq_handler handler, uint32_t id)

Initialize the GPIO device’s interrupt mode, including mode, trigger and polarity registers.

Parameters:

  • obj – GPIO irq object defined in application software.

  • pin – PinName according to pinmux spec.

  • handler – Interrupt handler to be assigned to the specified pin.

  • id – Handler parameter.

Returns:

0 if initialization is ok.

void gpio_irq_pull_ctrl(gpio_irq_t *obj, PinMode pull_type)

Configure pull type of the selected interrupt pin.

Parameters:

  • obj – GPIO irq object defined in application software.

  • pull_type –

    This parameter can be one of the following values:

    • PullNone: HighZ, user can input high or low with this pin.

    • PullDown: Pull down.

    • PullUp: Pull up.

Note

It is the same with function gpio_mode();

void gpio_irq_set(gpio_irq_t *obj, gpio_irq_event event, uint32_t enable)

Configure GPIO interrupt as enabled or disabled.

Parameters:

  • obj – GPIO irq object defined in application software.

  • event –

    GPIO interrupt event, this parameter can be one of the following values:

    • IRQ_RISE: Rising edge interrupt event.

    • IRQ_FALL: Falling edge interrupt event.

    • IRQ_FALL_RISE: Both rising and falling edge interrupt event.

    • IRQ_LOW: Low level interrupt event.

    • IRQ_HIGH: High level interrupt event.

    • IRQ_NONE: No interrupt event.

  • enable –

    This parameter can be one of the following values:

    • 0: Disable GPIO interrupt.

    • 1: Enable GPIO interrupt.

void gpio_irq_set_event(gpio_irq_t *obj, gpio_irq_event event)

Configure GPIO interrupt as enabled.

Parameters:

  • obj – GPIO irq object defined in application software.

  • event –

    GPIO interrupt event, this parameter can be one of the following values:

    • IRQ_RISE: Rising edge interrupt event.

    • IRQ_FALL: Falling edge interrupt event.

    • IRQ_FALL_RISE: Both rising and falling edge interrupt event.

    • IRQ_LOW: Low level interrupt event.

    • IRQ_HIGH: High level interrupt event.

    • IRQ_NONE: No interrupt event.

Note

It is the same with function gpio_irq_set();

void gpio_mode(gpio_t *obj, PinMode mode)

Set GPIO mode, including pullnone, pulldown and pullup.

Parameters:

  • obj – GPIO object defined in application software.

  • mode –

    This parameter can be one of the following values:

    • PullNone: HighZ, user can input high or low with this pin.

    • PullDown: Pull down.

    • PullUp: Pull up.

void gpio_pull_ctrl(gpio_t *obj, PinMode pull_type)

Set pull type of the selected pin, including pullnone, pulldown and pullup.

Parameters:

  • obj – GPIO object defined in application software.

  • pull_type –

    This parameter can be one of the following values:

    • PullNone: HighZ, user can input high or low with this pin.

    • PullDown: Pull down.

    • PullUp: Pull up.

Note

It is the same with function gpio_mode();

int gpio_read(gpio_t *obj)

Read value of the specified gpio pin.

Parameters:

  • obj – GPIO object defined in application software.

Returns:

State of the specified gpio pin. It can be one of the following values:

  • 0: Pin state is low.

  • 1: Pin state is high.

uint32_t gpio_set(PinName pin)

Configure the selected pin as GPIO.

Parameters:

  • pin – PinName according to pinmux spec.

Returns:

Selected pin with GPIO function.

void gpio_write(gpio_t *obj, int value)

Set output value of the selected gpio pin.

Parameters:

  • obj – GPIO object defined in application software.

  • value –

    The value to be written to the selected pin. This parameter can be one of the following values:

    • 0: Set selected pin to low.

    • 1: Set selected pin to high.