General Purpose Input/Output (GPIO) API. More...

Typedefs
typedef void(*	gpio_irq_callback_t) (uint gpio, uint32_t events)

Enumerations
enum	gpio_function { GPIO_FUNC_XIP = 0, GPIO_FUNC_SPI = 1, GPIO_FUNC_UART = 2, GPIO_FUNC_I2C = 3, GPIO_FUNC_PWM = 4, GPIO_FUNC_SIO = 5, GPIO_FUNC_PIO0 = 6, GPIO_FUNC_PIO1 = 7, GPIO_FUNC_GPCK = 8, GPIO_FUNC_USB = 9, GPIO_FUNC_NULL = 0xf }
	GPIO function definitions for use with function select. More...

enum	gpio_irq_level { GPIO_IRQ_LEVEL_LOW = 0x1u, GPIO_IRQ_LEVEL_HIGH = 0x2u, GPIO_IRQ_EDGE_FALL = 0x4u, GPIO_IRQ_EDGE_RISE = 0x8u }
	GPIO Interrupt level definitions. More...

Functions
void	gpio_set_function (uint gpio, enum gpio_function fn)
	Select GPIO function. More...

void	gpio_set_pulls (uint gpio, bool up, bool down)
	Select up and down pulls on specific GPIO. More...

static void	gpio_pull_up (uint gpio)
	Set specified GPIO to be pulled up. More...

static bool	gpio_is_pulled_up (uint gpio)
	Determine if the specified GPIO is pulled up. More...

static void	gpio_pull_down (uint gpio)
	Set specified GPIO to be pulled down. More...

static bool	gpio_is_pulled_down (uint gpio)
	Determine if the specified GPIO is pulled down. More...

static void	gpio_disable_pulls (uint gpio)
	Disable pulls on specified GPIO. More...

void	gpio_set_outover (uint gpio, uint value)
	Set GPIO output override. More...

void	gpio_set_inover (uint gpio, uint value)
	Select GPIO input override. More...

void	gpio_set_oeover (uint gpio, uint value)
	Select GPIO output enable override. More...

void	gpio_set_input_enabled (uint gpio, bool enabled)
	Enable GPIO input. More...

void	gpio_set_irq_enabled (uint gpio, uint32_t events, bool enabled)
	Enable or disable interrupts for specified GPIO. More...

void	gpio_set_irq_enabled_with_callback (uint gpio, uint32_t events, bool enabled, gpio_irq_callback_t callback)
	Enable interrupts for specified GPIO. More...

void	gpio_set_dormant_irq_enabled (uint gpio, uint32_t events, bool enabled)
	Enable dormant wake up interrupt for specified GPIO. More...

void	gpio_acknowledge_irq (uint gpio, uint32_t events)
	Acknowledge a GPIO interrupt. More...

void	gpio_init (uint gpio)
	Initialise a GPIO for (enabled I/O and set func to GPIO_FUNC_SIO) More...

void	gpio_init_mask (uint gpio_mask)
	Initialise multiple GPIOs (enabled I/O and set func to GPIO_FUNC_SIO) More...

static bool	gpio_get (uint gpio)
	Get state of a single specified GPIO. More...

static uint32_t	gpio_get_all (void)
	Get raw value of all GPIOs. More...

static void	gpio_set_mask (uint32_t mask)
	Drive high every GPIO appearing in mask. More...

static void	gpio_clr_mask (uint32_t mask)
	Drive low every GPIO appearing in mask. More...

static void	gpio_xor_mask (uint32_t mask)
	Toggle every GPIO appearing in mask. More...

static void	gpio_put_masked (uint32_t mask, uint32_t value)
	Drive GPIO high/low depending on parameters. More...

static void	gpio_put_all (uint32_t value)
	Drive all pins simultaneously. More...

static void	gpio_put (uint gpio, bool value)
	Drive a single GPIO high/low. More...

static void	gpio_set_dir_out_masked (uint32_t mask)
	Set a number of GPIOs to output. More...

static void	gpio_set_dir_in_masked (uint32_t mask)
	Set a number of GPIOs to input. More...

static void	gpio_set_dir_masked (uint32_t mask, uint32_t value)
	Set multiple GPIO directions. More...

static void	gpio_set_dir_all_bits (uint32_t values)
	Set direction of all pins simultaneously. More...

static void	gpio_set_dir (uint gpio, bool out)
	Set a single GPIO direction. More...

static bool	gpio_is_dir_out (uint gpio)
	Check if a specific GPIO direction is OUT. More...

static uint	gpio_get_dir (uint gpio)
	Get a specific GPIO direction. More...

Detailed Description

General Purpose Input/Output (GPIO) API.

RP2040 has 36 multi-functional General Purpose Input / Output (GPIO) pins, divided into two banks. In a typical use case, the pins in the QSPI bank (QSPI_SS, QSPI_SCLK and QSPI_SD0 to QSPI_SD3) are used to execute code from an external flash device, leaving the User bank (GPIO0 to GPIO29) for the programmer to use. All GPIOs support digital input and output, but GPIO26 to GPIO29 can also be used as inputs to the chip’s Analogue to Digital Converter (ADC). Each GPIO can be controlled directly by software running on the processors, or by a number of other functional blocks.

The function allocated to each GPIO is selected by calling the gpio_set_function function.

Note: Not all functions are available on all pins.

Each GPIO can have one function selected at a time. Likewise, each peripheral input (e.g. UART0 RX) should only be selected on one GPIO at a time. If the same peripheral input is connected to multiple GPIOs, the peripheral sees the logical OR of these GPIO inputs. Please refer to the datasheet for more information on GPIO function select.

Function Select Table

GPIO	F1	F2	F3	F4	F5	F6	F7	F8	F9
0	SPI0 RX	UART0 TX	I2C0 SDA	PWM0 A	SIO	PIO0	PIO1		USB OVCUR DET
1	SPI0 CSn	UART0 RX	I2C0 SCL	PWM0 B	SIO	PIO0	PIO1		USB VBUS DET
2	SPI0 SCK	UART0 CTS	I2C1 SDA	PWM1 A	SIO	PIO0	PIO1		USB VBUS EN
3	SPI0 TX	UART0 RTS	I2C1 SCL	PWM1 B	SIO	PIO0	PIO1		USB OVCUR DET
4	SPI0 RX	UART1 TX	I2C0 SDA	PWM2 A	SIO	PIO0	PIO1		USB VBUS DET
5	SPI0 CSn	UART1 RX	I2C0 SCL	PWM2 B	SIO	PIO0	PIO1		USB VBUS EN
6	SPI0 SCK	UART1 CTS	I2C1 SDA	PWM3 A	SIO	PIO0	PIO1		USB OVCUR DET
7	SPI0 TX	UART1 RTS	I2C1 SCL	PWM3 B	SIO	PIO0	PIO1		USB VBUS DET
8	SPI1 RX	UART1 TX	I2C0 SDA	PWM4 A	SIO	PIO0	PIO1		USB VBUS EN
9	SPI1 CSn	UART1 RX	I2C0 SCL	PWM4 B	SIO	PIO0	PIO1		USB OVCUR DET
10	SPI1 SCK	UART1 CTS	I2C1 SDA	PWM5 A	SIO	PIO0	PIO1		USB VBUS DET
11	SPI1 TX	UART1 RTS	I2C1 SCL	PWM5 B	SIO	PIO0	PIO1		USB VBUS EN
12	SPI1 RX	UART0 TX	I2C0 SDA	PWM6 A	SIO	PIO0	PIO1		USB OVCUR DET
13	SPI1 CSn	UART0 RX	I2C0 SCL	PWM6 B	SIO	PIO0	PIO1		USB VBUS DET
14	SPI1 SCK	UART0 CTS	I2C1 SDA	PWM7 A	SIO	PIO0	PIO1		USB VBUS EN
15	SPI1 TX	UART0 RTS	I2C1 SCL	PWM7 B	SIO	PIO0	PIO1		USB OVCUR DET
16	SPI0 RX	UART0 TX	I2C0 SDA	PWM0 A	SIO	PIO0	PIO1		USB VBUS DET
17	SPI0 CSn	UART0 RX	I2C0 SCL	PWM0 B	SIO	PIO0	PIO1		USB VBUS EN
18	SPI0 SCK	UART0 CTS	I2C1 SDA	PWM1 A	SIO	PIO0	PIO1		USB OVCUR DET
19	SPI0 TX	UART0 RTS	I2C1 SCL	PWM1 B	SIO	PIO0	PIO1		USB VBUS DET
20	SPI0 RX	UART1 TX	I2C0 SDA	PWM2 A	SIO	PIO0	PIO1	CLOCK GPIN0	USB VBUS EN
21	SPI0 CSn	UART1 RX	I2C0 SCL	PWM2 B	SIO	PIO0	PIO1	CLOCK GPOUT0	USB OVCUR DET
22	SPI0 SCK	UART1 CTS	I2C1 SDA	PWM3 A	SIO	PIO0	PIO1	CLOCK GPIN1	USB VBUS DET
23	SPI0 TX	UART1 RTS	I2C1 SCL	PWM3 B	SIO	PIO0	PIO1	CLOCK GPOUT1	USB VBUS EN
24	SPI1 RX	UART1 TX	I2C0 SDA	PWM4 A	SIO	PIO0	PIO1	CLOCK GPOUT2	USB OVCUR DET
25	SPI1 CSn	UART1 RX	I2C0 SCL	PWM4 B	SIO	PIO0	PIO1	CLOCK GPOUT3	USB VBUS DET
26	SPI1 SCK	UART1 CTS	I2C1 SDA	PWM5 A	SIO	PIO0	PIO1		USB VBUS EN
27	SPI1 TX	UART1 RTS	I2C1 SCL	PWM5 B	SIO	PIO0	PIO1		USB OVCUR DET
28	SPI1 RX	UART0 TX	I2C0 SDA	PWM6 A	SIO	PIO0	PIO1		USB VBUS DET
29	SPI1 CSn	UART0 RX	I2C0 SCL	PWM6 B	SIO	PIO0	PIO1		USB VBUS EN

Typedef Documentation

◆ gpio_irq_callback_t

typedef void(* gpio_irq_callback_t) (uint gpio, uint32_t events)

Callback function type for GPIO events

Parameters

gpio	Which GPIO caused this interrupt
events	Which events caused this interrupt. See gpio_set_irq_enabled for details.

See also: gpio_set_irq_enabled_with_callback()

Enumeration Type Documentation

◆ gpio_function

enum gpio_function

GPIO function definitions for use with function select.

GPIO function selectors

Each GPIO can have one function selected at a time. Likewise, each peripheral input (e.g. UART0 RX) should only be selected on one GPIO at a time. If the same peripheral input is connected to multiple GPIOs, the peripheral sees the logical OR of these GPIO inputs.

Please refer to the datsheet for more information on GPIO function selection.

◆ gpio_irq_level

enum gpio_irq_level

GPIO Interrupt level definitions.

GPIO Interrupt levels

An interrupt can be generated for every GPIO pin in 4 scenarios:

Level High: the GPIO pin is a logical 1
Level Low: the GPIO pin is a logical 0
Edge High: the GPIO has transitioned from a logical 0 to a logical 1
Edge Low: the GPIO has transitioned from a logical 1 to a logical 0

The level interrupts are not latched. This means that if the pin is a logical 1 and the level high interrupt is active, it will become inactive as soon as the pin changes to a logical 0. The edge interrupts are stored in the INTR register and can be cleared by writing to the INTR register.

Function Documentation

◆ gpio_acknowledge_irq()

void gpio_acknowledge_irq	(	uint	gpio,
		uint32_t	events
	)

Acknowledge a GPIO interrupt.

Parameters

gpio	GPIO number
events	Bitmask of events to clear. See gpio_set_irq_enabled for details.

◆ gpio_clr_mask()

static void gpio_clr_mask ( uint32_t mask )

inlinestatic

Drive low every GPIO appearing in mask.

Parameters

mask	Bitmask of GPIO values to clear, as bits 0-29

◆ gpio_disable_pulls()

static void gpio_disable_pulls ( uint gpio )

inlinestatic

Disable pulls on specified GPIO.

Parameters

gpio	GPIO number

◆ gpio_get()

static bool gpio_get ( uint gpio )

inlinestatic

Get state of a single specified GPIO.

Parameters

gpio	GPIO number

Returns: Current state of the GPIO. 0 for low, non-zero for high

◆ gpio_get_all()

static uint32_t gpio_get_all ( void )

inlinestatic

Get raw value of all GPIOs.

Returns: Bitmask of raw GPIO values, as bits 0-29

◆ gpio_get_dir()

static uint gpio_get_dir ( uint gpio )

inlinestatic

Get a specific GPIO direction.

Parameters

gpio	GPIO number

Returns: 1 for out, 0 for in

◆ gpio_init()

void gpio_init ( uint gpio )

Initialise a GPIO for (enabled I/O and set func to GPIO_FUNC_SIO)

Clear the output enable (i.e. set to input) Clear any output value.

Parameters

gpio	GPIO number

◆ gpio_init_mask()

void gpio_init_mask ( uint gpio_mask )

Initialise multiple GPIOs (enabled I/O and set func to GPIO_FUNC_SIO)

Clear the output enable (i.e. set to input) Clear any output value.

Parameters

gpio_mask Mask with 1 bit per GPIO number to initialize

◆ gpio_is_dir_out()

static bool gpio_is_dir_out ( uint gpio )

inlinestatic

Check if a specific GPIO direction is OUT.

Parameters

gpio	GPIO number

Returns: true if the direction for the pin is OUT

◆ gpio_is_pulled_down()

static bool gpio_is_pulled_down ( uint gpio )

inlinestatic

Determine if the specified GPIO is pulled down.

Parameters

gpio	GPIO number

Returns: true if the GPIO is pulled down

◆ gpio_is_pulled_up()

static bool gpio_is_pulled_up ( uint gpio )

inlinestatic

Determine if the specified GPIO is pulled up.

Parameters

gpio	GPIO number

Returns: true if the GPIO is pulled up

◆ gpio_pull_down()

static void gpio_pull_down ( uint gpio )

inlinestatic

Set specified GPIO to be pulled down.

Parameters

gpio	GPIO number

◆ gpio_pull_up()

static void gpio_pull_up ( uint gpio )

inlinestatic

Set specified GPIO to be pulled up.

Parameters

gpio	GPIO number

◆ gpio_put()

static void gpio_put	(	uint	gpio,
		bool	value
	)

inlinestatic

Drive a single GPIO high/low.

Parameters

gpio	GPIO number
value	If false clear the GPIO, otherwise set it.

◆ gpio_put_all()

static void gpio_put_all ( uint32_t value )

inlinestatic

Drive all pins simultaneously.

Parameters

value Bitmask of GPIO values to change, as bits 0-29

◆ gpio_put_masked()

static void gpio_put_masked	(	uint32_t	mask,
		uint32_t	value
	)

inlinestatic

Drive GPIO high/low depending on parameters.

Parameters

mask	Bitmask of GPIO values to change, as bits 0-29
value	Value to set

For each 1 bit in mask, drive that pin to the value given by corresponding bit in value, leaving other pins unchanged. Since this uses the TOGL alias, it is concurrency-safe with e.g. an IRQ bashing different pins from the same core.

◆ gpio_set_dir()

static void gpio_set_dir	(	uint	gpio,
		bool	out
	)

inlinestatic

Set a single GPIO direction.

Parameters

gpio	GPIO number
out	true for out, false for in

◆ gpio_set_dir_all_bits()

static void gpio_set_dir_all_bits ( uint32_t values )

inlinestatic

Set direction of all pins simultaneously.

Parameters

values individual settings for each gpio; for GPIO N, bit N is 1 for out, 0 for in

◆ gpio_set_dir_in_masked()

static void gpio_set_dir_in_masked ( uint32_t mask )

inlinestatic

Set a number of GPIOs to input.

Parameters

mask	Bitmask of GPIO to set to input, as bits 0-29

◆ gpio_set_dir_masked()

static void gpio_set_dir_masked	(	uint32_t	mask,
		uint32_t	value
	)

inlinestatic

Set multiple GPIO directions.

Parameters

mask	Bitmask of GPIO to set to input, as bits 0-29
value	Values to set

For each 1 bit in "mask", switch that pin to the direction given by corresponding bit in "value", leaving other pins unchanged. E.g. gpio_set_dir_masked(0x3, 0x2); -> set pin 0 to input, pin 1 to output, simultaneously.

◆ gpio_set_dir_out_masked()

static void gpio_set_dir_out_masked ( uint32_t mask )

inlinestatic

Set a number of GPIOs to output.

Switch all GPIOs in "mask" to output

Parameters

mask	Bitmask of GPIO to set to output, as bits 0-29

◆ gpio_set_dormant_irq_enabled()

void gpio_set_dormant_irq_enabled	(	uint	gpio,
		uint32_t	events,
		bool	enabled
	)

Enable dormant wake up interrupt for specified GPIO.

This configures IRQs to restart the XOSC or ROSC when they are disabled in dormant mode

Parameters

gpio	GPIO number
events	Which events will cause an interrupt. See gpio_set_irq_enabled for details.
enabled	Enable/disable flag

◆ gpio_set_function()

void gpio_set_function	(	uint	gpio,
		enum gpio_function	fn
	)

Select GPIO function.

Parameters

gpio	GPIO number
fn	Which GPIO function select to use from list gpio_function

◆ gpio_set_inover()

void gpio_set_inover	(	uint	gpio,
		uint	value
	)

Select GPIO input override.

Parameters

gpio	GPIO number
value	See gpio_override

◆ gpio_set_input_enabled()

void gpio_set_input_enabled	(	uint	gpio,
		bool	enabled
	)

Enable GPIO input.

Parameters

gpio	GPIO number
enabled	true to enable input on specified GPIO

◆ gpio_set_irq_enabled()

void gpio_set_irq_enabled	(	uint	gpio,
		uint32_t	events,
		bool	enabled
	)

Enable or disable interrupts for specified GPIO.

Note: The IO IRQs are independent per-processor. This configures IRQs for the processor that calls the function.

Parameters

gpio	GPIO number
events	Which events will cause an interrupt
enabled	Enable or disable flag

Events is a bitmask of the following:

bit	interrupt
0	Low level
1	High level
2	Edge low
3	Edge high

◆ gpio_set_irq_enabled_with_callback()

void gpio_set_irq_enabled_with_callback	(	uint	gpio,
		uint32_t	events,
		bool	enabled,
		gpio_irq_callback_t	callback
	)

Enable interrupts for specified GPIO.

Note: The IO IRQs are independent per-processor. This configures IRQs for the processor that calls the function.

Parameters

gpio	GPIO number
events	Which events will cause an interrupt. See gpio_set_irq_enabled for details.
enabled	Enable or disable flag
callback	user function to call on GPIO irq. Note only one of these can be set per processor.

Note: Currently the GPIO parameter is ignored, and this callback will be called for any enabled GPIO IRQ on any pin.

◆ gpio_set_mask()

static void gpio_set_mask ( uint32_t mask )

inlinestatic

Drive high every GPIO appearing in mask.

Parameters

mask	Bitmask of GPIO values to set, as bits 0-29

◆ gpio_set_oeover()

void gpio_set_oeover	(	uint	gpio,
		uint	value
	)

Select GPIO output enable override.

Parameters

gpio	GPIO number
value	See gpio_override

◆ gpio_set_outover()

void gpio_set_outover	(	uint	gpio,
		uint	value
	)

Set GPIO output override.

Parameters

gpio	GPIO number
value	See gpio_override

◆ gpio_set_pulls()

void gpio_set_pulls	(	uint	gpio,
		bool	up,
		bool	down
	)

Select up and down pulls on specific GPIO.

Parameters

gpio	GPIO number
up	If true set a pull up on the GPIO
down	If true set a pull down on the GPIO

Note: On the RP2040, setting both pulls enables a "bus keep" function, i.e. a weak pull to whatever is current high/low state of GPIO.

◆ gpio_xor_mask()

static void gpio_xor_mask ( uint32_t mask )

inlinestatic

Toggle every GPIO appearing in mask.

Parameters

mask	Bitmask of GPIO values to toggle, as bits 0-29

Typedefs

Enumerations

Functions

Detailed Description

Function Select Table

Typedef Documentation

◆ gpio_irq_callback_t

Enumeration Type Documentation

◆ gpio_function

◆ gpio_irq_level

Function Documentation

◆ gpio_acknowledge_irq()

◆ gpio_clr_mask()

◆ gpio_disable_pulls()

◆ gpio_get()

◆ gpio_get_all()

◆ gpio_get_dir()

◆ gpio_init()

◆ gpio_init_mask()

◆ gpio_is_dir_out()

◆ gpio_is_pulled_down()

◆ gpio_is_pulled_up()

◆ gpio_pull_down()

◆ gpio_pull_up()

◆ gpio_put()

◆ gpio_put_all()

◆ gpio_put_masked()

◆ gpio_set_dir()

◆ gpio_set_dir_all_bits()

◆ gpio_set_dir_in_masked()

◆ gpio_set_dir_masked()

◆ gpio_set_dir_out_masked()

◆ gpio_set_dormant_irq_enabled()

◆ gpio_set_function()

◆ gpio_set_inover()

◆ gpio_set_input_enabled()

◆ gpio_set_irq_enabled()

◆ gpio_set_irq_enabled_with_callback()

◆ gpio_set_mask()

◆ gpio_set_oeover()

◆ gpio_set_outover()

◆ gpio_set_pulls()

◆ gpio_xor_mask()