Low-level GPIO peripheral driver. More...

Detailed Description

Low-level GPIO peripheral driver.

This is a basic GPIO (General-purpose input/output) interface to allow platform independent access to a MCU's input/output pins. This interface is intentionally designed to be as simple as possible, to allow for easy implementation and maximum portability.

The interface provides capabilities to initialize a pin as output-, input- and interrupt pin. With the API you can basically set/clear/toggle the digital signal at the hardware pin when in output mode. Configured as input you can read a digital value that is being applied to the pin externally. When initializing an external interrupt pin, you can register a callback function that is executed in interrupt context once the interrupt condition applies to the pin. Usually you can react to rising or falling signal flanks (or both).

In addition the API provides to set standard input/output circuit modes such as e.g. internal push-pull configurations.

All modern micro controllers organize their GPIOs in some form of ports, often named 'PA', 'PB', 'PC'..., or 'P0', 'P1', 'P2'..., or similar. Each of these ports is then assigned a number of pins, often 8, 16, or 32. A hardware pin can thus be described by its port/pin tuple. To access a pin, the GPIO_PIN(port, pin) macro should be used. For example: If your platform has a pin PB22, it will be port=1 and pin=22. The GPIO_PIN macro should be overridden by a MCU, to allow for efficient encoding of the the port/pin tuple. For example, on many platforms it is possible to OR the pin number with the corresponding ports base register address. This allows for efficient decoding of pin number and base address without the need of any address lookup.

In case the driver does not define it, the below macro definition is used to simply map the port/pin tuple to the pin value. In that case, predefined GPIO definitions in RIOT/boards/ * /include/periph_conf.h will define the selected GPIO pin.

Warning: The scalar GPIO pin type gpio_t is deprecated and will be replaced by a structured GPIO pin type in a future GPIO API. Therefore, don't use the direct comparison of GPIO pins anymore. Instead, use the inline comparison functions gpio_is_equal and gpio_is_valid.

(Low-) Power Implications

On almost all platforms, we can only control the peripheral power state of full ports (i.e. groups of pins), but not for single GPIO pins. Together with CPU specific alternate function handling for pins used by other peripheral drivers, this can make it quite complex to keep track of pins that are currently used at a certain moment. To simplify the implementations (and ease the memory consumption), we expect ports to be powered on (e.g. through peripheral clock gating) when first used and never be powered off again.

GPIO driver implementations should power on the corresponding port during gpio_init() and gpio_init_int().

For external interrupts to work, some platforms may need to block certain power modes (although this is not very likely). This should be done during gpio_init_int().

Modules
	GPIO I/O Utils
	GPIO I/O utility functions.

Files
file	atmega_gpio.h
	Macros and inline functions for accessing GPIOs of the ATmega family.

file	gpio.h
	Low-level GPIO peripheral driver interface definitions.

Data Structures
struct	gpio_isr_ctx_t
	Default interrupt context for GPIO pins. More...

Macros
#define	GPIO_PIN(x, y) ((gpio_t)((x & 0) \| y))
	Convert (port, pin) tuple to `gpio_t` value.

#define	GPIO_UNDEF ((gpio_t)(UINT_MAX))
	GPIO pin not defined.

Typedefs
typedef unsigned int	gpio_t
	GPIO type identifier.

typedef void(*	gpio_cb_t) (void *arg)
	Signature of event callback functions triggered from interrupts.

Enumerations
enum	gpio_mode_t { GPIO_IN , GPIO_IN_PD , GPIO_IN_PU , GPIO_OUT , GPIO_OD , GPIO_OD_PU }
	Available pin modes. More...

enum	gpio_flank_t { GPIO_FALLING = 0 , GPIO_RISING = 1 , GPIO_BOTH = 2 }
	Definition of possible active flanks for external interrupt mode. More...

Functions
int	gpio_init (gpio_t pin, gpio_mode_t mode)
	Initialize the given pin as general purpose input or output.

int	gpio_init_int (gpio_t pin, gpio_mode_t mode, gpio_flank_t flank, gpio_cb_t cb, void *arg)
	Initialize a GPIO pin for external interrupt usage.

void	gpio_irq_enable (gpio_t pin)
	Enable pin interrupt if configured as interrupt source.

void	gpio_irq_disable (gpio_t pin)
	Disable the pin interrupt if configured as interrupt source.

bool	gpio_read (gpio_t pin)
	Get the current value of the given pin.

void	gpio_set (gpio_t pin)
	Set the given pin to HIGH.

void	gpio_clear (gpio_t pin)
	Set the given pin to LOW.

void	gpio_toggle (gpio_t pin)
	Toggle the value of the given pin.

void	gpio_write (gpio_t pin, bool value)
	Set the given pin to the given value.

static int	gpio_is_equal (gpio_t gpio1, gpio_t gpio2)
	Test if a GPIO pin is equal to another GPIO pin.

static int	gpio_is_valid (gpio_t gpio)
	Test if a GPIO pin is a valid pin and not declared as undefined.

Macro Definition Documentation

◆ GPIO_PIN

#define GPIO_PIN	(	x,
		y
	)	((gpio_t)((x & 0) \| y))

Convert (port, pin) tuple to gpio_t value.

Definition at line 100 of file gpio.h.

◆ GPIO_UNDEF

#define GPIO_UNDEF ((gpio_t)(UINT_MAX))

GPIO pin not defined.

Definition at line 107 of file gpio.h.

Typedef Documentation

◆ gpio_cb_t

typedef void(* gpio_cb_t) (void *arg)

Signature of event callback functions triggered from interrupts.

Parameters

[in] arg optional context for the callback

Definition at line 147 of file gpio.h.

◆ gpio_t

typedef unsigned int gpio_t

GPIO type identifier.

Definition at line 92 of file gpio.h.

Enumeration Type Documentation

◆ gpio_flank_t

enum gpio_flank_t

Definition of possible active flanks for external interrupt mode.

Enumerator
GPIO_FALLING	emit interrupt on falling flank
GPIO_RISING	emit interrupt on rising flank
GPIO_BOTH	emit interrupt on both flanks

Definition at line 135 of file gpio.h.

◆ gpio_mode_t

enum gpio_mode_t

Available pin modes.

Generally, a pin can be configured to be input or output. In output mode, a pin can further be put into push-pull or open drain configuration. Though this is supported by most platforms, this is not always the case, so driver implementations may return an error code if a mode is not supported.

Enumerator
GPIO_IN	configure as input without pull resistor
GPIO_IN_PD	configure as input with pull-down resistor
GPIO_IN_PU	configure as input with pull-up resistor
GPIO_OUT	configure as output in push-pull mode
GPIO_OD	configure as output in open-drain mode without pull resistor
GPIO_OD_PU	configure as output in open-drain mode with pull resistor enabled

Definition at line 119 of file gpio.h.

Function Documentation

◆ gpio_clear()

void gpio_clear ( gpio_t pin )

Set the given pin to LOW.

Parameters

[in] pin the pin to clear

◆ gpio_init()

int gpio_init	(	gpio_t	pin,
		gpio_mode_t	mode
	)

Initialize the given pin as general purpose input or output.

When configured as output, the pin state after initialization is undefined. The output pin's state should be untouched during the initialization. This behavior can however not be guaranteed by every platform.

Parameters

[in]	pin	pin to initialize
[in]	mode	mode of the pin, see `gpio_mode_t`

Returns: 0 on success; -1 on error

◆ gpio_init_int()

int gpio_init_int	(	gpio_t	pin,
		gpio_mode_t	mode,
		gpio_flank_t	flank,
		gpio_cb_t	cb,
		void *	arg
	)

Initialize a GPIO pin for external interrupt usage.

The registered callback function will be called in interrupt context every time the defined flank(s) are detected.

The interrupt is activated automatically after the initialization.

Note: You have to add the module periph_gpio_irq to your project to enable this function

Precondition: cb must not be NULL

Parameters

[in]	pin	pin to initialize
[in]	mode	mode of the pin, see `gpio_mode_t`
[in]	flank	define the active flank(s)
[in]	cb	callback that is called from interrupt context
[in]	arg	optional argument passed to the callback

Returns: 0 on success; -1 on error

◆ gpio_irq_disable()

void gpio_irq_disable ( gpio_t pin )

Disable the pin interrupt if configured as interrupt source.

Note: You have to add the module periph_gpio_irq to your project to enable this function

Parameters

[in] pin the pin to disable the interrupt for

◆ gpio_irq_enable()

void gpio_irq_enable ( gpio_t pin )

Enable pin interrupt if configured as interrupt source.

     Interrupts that would have occurred after @see gpio_irq_disable
     was called will be discarded.

Note: You have to add the module periph_gpio_irq to your project to enable this function

Parameters

[in] pin the pin to enable the interrupt for

◆ gpio_is_equal()

static int gpio_is_equal	(	gpio_t	gpio1,
		gpio_t	gpio2
	)

inlinestatic

Test if a GPIO pin is equal to another GPIO pin.

Parameters

[in]	gpio1	First GPIO pin to check
[in]	gpio2	Second GPIO pin to check

Definition at line 270 of file gpio.h.

◆ gpio_is_valid()

static int gpio_is_valid ( gpio_t gpio )

inlinestatic

Test if a GPIO pin is a valid pin and not declared as undefined.

Parameters

[in] gpio GPIO pin to check

Definition at line 280 of file gpio.h.

◆ gpio_read()

bool gpio_read ( gpio_t pin )

Get the current value of the given pin.

Parameters

[in] pin the pin to read

Return values

false	pin is LOW
true	pin is HIGH

◆ gpio_set()

void gpio_set ( gpio_t pin )

Set the given pin to HIGH.

Parameters

[in] pin the pin to set

◆ gpio_toggle()

void gpio_toggle ( gpio_t pin )

Toggle the value of the given pin.

Parameters

[in] pin the pin to toggle

◆ gpio_write()

void gpio_write	(	gpio_t	pin,
		bool	value
	)

Set the given pin to the given value.

Parameters

[in]	pin	the pin to set
[in]	value	value to set the pin to, 0 for LOW, HIGH otherwise

Detailed Description

(Low-) Power Implications

Modules

Files

Data Structures

Macros

Typedefs

Enumerations

Functions

Macro Definition Documentation

◆ GPIO_PIN

◆ GPIO_UNDEF

Typedef Documentation

◆ gpio_cb_t

◆ gpio_t

Enumeration Type Documentation

◆ gpio_flank_t

◆ gpio_mode_t

Function Documentation

◆ gpio_clear()

◆ gpio_init()

◆ gpio_init_int()

◆ gpio_irq_disable()

◆ gpio_irq_enable()

◆ gpio_is_equal()

◆ gpio_is_valid()

◆ gpio_read()

◆ gpio_set()

◆ gpio_toggle()

◆ gpio_write()