通用输入/输出（GPIO）

功能特性

• 输入功能

  • 消抖功能：输入引脚支持消抖功能，可有效防止因抖动产生的错误信号

  • 中断支持：

    • 电平触发

    • 边沿触发

    • 双边沿触发

• 输出功能

  • 单个引脚输出设置：支持单独设置特定引脚的输出状态

  • 多个引脚同时设置：同一端口的多个引脚可以同时进行输出设置

消抖功能

消抖时钟

消抖时钟源为 dbclk_src，其输出的消抖时钟 dbclk 为: dbclk = dbclk_src / (div + 1) 。其中， div 为可调的分频系数。

芯片的消抖时钟源如下：

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

• 32.768kHz

• OSC4MHz

滤波能力

• 持续时间小于 1 个消抖时钟周期的 Glitch 信号可滤除。

• 持续时间在 1 至 2 个消抖时钟周期的 Glitch 信号不确定。

• 持续时间大于 2 个消抖时钟周期的 Glitch 信号无法滤除。

端口滤波一致性

在同一个端口上的不同引脚， div 是共用的，即消抖时钟一致。

备注

采用消抖功能时，输入信号的处理会有一定的延迟。这可能导致系统响应变慢，尤其是在中断和唤醒操作需要快速响应的情况下。

中断类型

• 电平触发：支持通过电平状态（高电平或低电平）触发中断。

• 边沿触发：支持检测信号的上升沿或下降沿引发中断。

• 双边沿触发：支持同时检测上升沿和下降沿以触发中断。

备注

在切换电平触发类型时，为避免误触发中断，需延迟两拍消抖时钟后再使能中断。

输出竞态保护

GPIO 输出以端口（PORT）为单位，单独控制某个 GPIO 引脚的电平状态在汇编中表现为 读、改、写 三步操作。如果同一组端口被多个线程控制输出，可能会引发竞态条件。

为应对此风险，系统提供了软件和硬件两种方式来保护输出操作，可根据所使用的芯片进行选择。

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720FRTL8735C

RTL8721Dx:

软件保护

• 使用 GPIO_WriteBit_Critical() API 替代 GPIO_WriteBit() 操作。

• 通过软件层面锁定资源，规避多线程或中断上下文的竞态问题。

应用示例

SDK 提供了两类功能示例，帮助开发者了解和使用 GPIO 功能：

• mbed 示例

  • 路径：{SDK}\example\peripheral\mbed\GPIO\{demo}

  • 展示如何在 mbed 环境中实现 GPIO 控制。

• raw 示例

  • 路径：{SDK}\example\peripheral\raw\GPIO\{demo}

  • 展示如何在无抽象层的情况下直接控制 GPIO。

以下是对 raw 示例功能的简要说明：

• raw_gpio_rw 演示如何使用 GPIO 读写 API

• raw_gpio_port 演示如何使用 GPIO Port 读写 API

• raw_gpio_edge_irq 演示如何配置 GPIO, 以触发边沿中断

• raw_gpio_level_irq 演示如何配置 GPIO, 以触发电平中断

备注

要了解示例支持的芯片，请查看示例路径下的 README.md 文件。

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.

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720F

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

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720F

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

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720F

RTL8721Dx:

Not supported.

GPIO DR DDR Function Select

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720F

RTL8721Dx:

Not supported.

GPIO Exported Functions

void GPIO_DeInit(u32 GPIO_Pin)

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

参数:

• GPIO_Pin -- GPIO pin num from PinName.

void GPIO_DebounceClock(u32 GPIO_Port, u32 DivideCount)

Set the specified port debounce clock.

参数:

• 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.

参数:

• 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.

参数:

• GPIO_Pin -- GPIO pin num from PinName.

• NewState -- ENABLE/DISABLE

u32 GPIO_INTHandler(void *pData)

The common GPIO interrupt handler.

参数:

• pData -- The data pointer from the registered IRQ handler

返回:

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.

参数:

• 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.

参数:

• 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.

参数:

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

返回:

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.

参数:

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

备注

• 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.

参数:

• 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.

参数:

• 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.

参数:

• 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.

参数:

• 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

备注

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.

参数:

• 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.

返回:

The value of the specified port pins

备注

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.

参数:

• 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.

参数:

• GPIO_Pin -- GPIO pin num from PinName.

返回:

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.

参数:

• 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.

参数:

• 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

RTL8721DxRTL8720ERTL8710ERTL8726ERTL8713ERTL8730ERTL8721FRTL8720F

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.

参数:

• 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.

备注

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.

参数:

• obj -- GPIO object defined in application software.

void gpio_dir(gpio_t *obj, PinDirection direction)

Set GPIO direction, including input and output.

参数:

• 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.

参数:

• 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.

备注

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.

参数:

• 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.

参数:

• obj -- GPIO irq object defined in application software.

备注

It is the same with function GPIO_DeInit();

void gpio_irq_disable(gpio_irq_t *obj)

Disable GPIO interrupt.

参数:

• obj -- GPIO irq object defined in application software.

void gpio_irq_enable(gpio_irq_t *obj)

Enable GPIO interrupt.

参数:

• 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.

参数:

• 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.

参数:

• 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.

返回:

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.

参数:

• 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.

备注

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.

参数:

• 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.

参数:

• 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.

备注

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.

参数:

• 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.

参数:

• 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.

备注

It is the same with function gpio_mode();

int gpio_read(gpio_t *obj)

Read value of the specified gpio pin.

参数:

• obj -- GPIO object defined in application software.

返回:

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.

参数:

• pin -- PinName according to pinmux spec.

返回:

Selected pin with GPIO function.

void gpio_write(gpio_t *obj, int value)

Set output value of the selected gpio pin.

参数:

• 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.