Low-level GPIO peripheral driver. More...

Detailed Description

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.

Files

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

Enumerations

enum  gpio_mode_t {
  GPIO_IN = ((uint8_t)0x00), GPIO_IN_PD = ((uint8_t)IOC_OVERRIDE_PDE), GPIO_IN_PU = ((uint8_t)IOC_OVERRIDE_PUE), GPIO_OUT = ((uint8_t)IOC_OVERRIDE_OE),
  GPIO_OD = (0xff), GPIO_OD_PU = (0xff), GPIO_IN = (IN), GPIO_IN_PD = (IN | PD),
  GPIO_IN_PU = (IN | PU), GPIO_OUT = (OUT), GPIO_OD = (OUT | OD), GPIO_OD_PU = (OUT | OD | PU),
  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. More...
 
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. More...
 
void gpio_irq_enable (gpio_t pin)
 Enable pin interrupt if configured as interrupt source. More...
 
void gpio_irq_disable (gpio_t pin)
 Disable the pin interrupt if configured as interrupt source. More...
 
int gpio_read (gpio_t pin)
 Get the current value of the given pin. More...
 
void gpio_set (gpio_t pin)
 Set the given pin to HIGH. More...
 
void gpio_clear (gpio_t pin)
 Set the given pin to LOW. More...
 
void gpio_toggle (gpio_t pin)
 Toggle the value of the given pin. More...
 
void gpio_write (gpio_t pin, int value)
 Set the given pin to the given value. More...
 

Typedef Documentation

typedef void(* gpio_cb_t) (void *arg)
Parameters
[in]argoptional context for the callback

Definition at line 124 of file gpio.h.

Enumeration Type Documentation

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 112 of file gpio.h.

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 

input, no pull

GPIO_IN_PD 

input, pull-down

GPIO_IN_PU 

input, pull-up

GPIO_OUT 

output

GPIO_OD 

not supported

GPIO_OD_PU 

not supported

GPIO_IN 

in without pull resistor

GPIO_IN_PD 

in with pull-down

GPIO_IN_PU 

in with pull-up

GPIO_OUT 

push-pull output

GPIO_OD 

open-drain output

GPIO_OD_PU 

open-drain output with pull-up

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 96 of file gpio.h.

Function Documentation

void gpio_clear ( gpio_t  pin)
Parameters
[in]pinthe pin to clear
int gpio_init ( gpio_t  pin,
gpio_mode_t  mode 
)
Parameters
[in]pinpin to initialize
[in]modemode of the pin, see gpio_mode_t
Returns
0 on success
-1 on error
int gpio_init_int ( gpio_t  pin,
gpio_mode_t  mode,
gpio_flank_t  flank,
gpio_cb_t  cb,
void *  arg 
)

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.

Parameters
[in]pinpin to initialize
[in]modemode of the pin, see gpio_mode_t
[in]flankdefine the active flank(s)
[in]cbcallback that is called from interrupt context
[in]argoptional argument passed to the callback
Returns
0 on success
-1 on error
void gpio_irq_disable ( gpio_t  pin)
Parameters
[in]pinthe pin to disable the interrupt for
void gpio_irq_enable ( gpio_t  pin)
Parameters
[in]pinthe pin to enable the interrupt for
int gpio_read ( gpio_t  pin)
Parameters
[in]pinthe pin to read
Returns
0 when pin is LOW
>0 for HIGH
void gpio_set ( gpio_t  pin)
Parameters
[in]pinthe pin to set
void gpio_toggle ( gpio_t  pin)
Parameters
[in]pinthe pin to toggle
void gpio_write ( gpio_t  pin,
int  value 
)
Parameters
[in]pinthe pin to set
[in]valuevalue to set the pin to, 0 for LOW, HIGH otherwise