High-level API

Simple high-level routines for straightforward GPIO manipulation without the need to use the gpiod_* structures or to keep track of resources. More...

Data Structures
struct	gpiod_ctxless_event_poll_fd
	Helper structure for the ctxless event loop poll callback. More...

Typedefs
typedef void(*	gpiod_ctxless_set_value_cb) (void *)
	Simple set value callback signature.
typedef int(*	gpiod_ctxless_event_handle_cb) (int, unsigned int, const struct timespec *, void *)
	Simple event callback signature. More...
typedef int(*	gpiod_ctxless_event_poll_cb) (unsigned int, struct gpiod_ctxless_event_poll_fd *, const struct timespec *, void *)
	Simple event poll callback signature. More...

Enumerations
enum	{   GPIOD_CTXLESS_FLAG_OPEN_DRAIN = GPIOD_BIT(0), GPIOD_CTXLESS_FLAG_OPEN_SOURCE = GPIOD_BIT(1), GPIOD_CTXLESS_FLAG_BIAS_DISABLE = GPIOD_BIT(2), GPIOD_CTXLESS_FLAG_BIAS_PULL_DOWN = GPIOD_BIT(3),   GPIOD_CTXLESS_FLAG_BIAS_PULL_UP = GPIOD_BIT(4) }
	Miscellaneous GPIO flags. More...
enum	{ GPIOD_CTXLESS_EVENT_RISING_EDGE = 1, GPIOD_CTXLESS_EVENT_FALLING_EDGE, GPIOD_CTXLESS_EVENT_BOTH_EDGES }
	Event types that the ctxless event monitor can wait for. More...
enum	{ GPIOD_CTXLESS_EVENT_CB_TIMEOUT = 1, GPIOD_CTXLESS_EVENT_CB_RISING_EDGE, GPIOD_CTXLESS_EVENT_CB_FALLING_EDGE }
	Event types that can be passed to the ctxless event callback. More...
enum	{ GPIOD_CTXLESS_EVENT_CB_RET_ERR = -1, GPIOD_CTXLESS_EVENT_CB_RET_OK = 0, GPIOD_CTXLESS_EVENT_CB_RET_STOP = 1 }
	Return status values that the ctxless event callback can return. More...
enum	{ GPIOD_CTXLESS_EVENT_POLL_RET_STOP = -2, GPIOD_CTXLESS_EVENT_POLL_RET_ERR = -1, GPIOD_CTXLESS_EVENT_POLL_RET_TIMEOUT = 0 }
	Return status values that the ctxless event poll callback can return. More...

Functions
int	gpiod_ctxless_get_value (const char *device, unsigned int offset, bool active_low, const char *consumer) GPIOD_API
	Read current value from a single GPIO line. More...
int	gpiod_ctxless_get_value_ext (const char *device, unsigned int offset, bool active_low, const char *consumer, int flags) GPIOD_API
	Read current value from a single GPIO line. More...
int	gpiod_ctxless_get_value_multiple (const char *device, const unsigned int *offsets, int *values, unsigned int num_lines, bool active_low, const char *consumer) GPIOD_API
	Read current values from a set of GPIO lines. More...
int	gpiod_ctxless_get_value_multiple_ext (const char *device, const unsigned int *offsets, int *values, unsigned int num_lines, bool active_low, const char *consumer, int flags) GPIOD_API
	Read current values from a set of GPIO lines. More...
int	gpiod_ctxless_set_value (const char *device, unsigned int offset, int value, bool active_low, const char *consumer, gpiod_ctxless_set_value_cb cb, void *data) GPIOD_API
	Set value of a single GPIO line. More...
int	gpiod_ctxless_set_value_ext (const char *device, unsigned int offset, int value, bool active_low, const char *consumer, gpiod_ctxless_set_value_cb cb, void *data, int flags) GPIOD_API
	Set value of a single GPIO line. More...
int	gpiod_ctxless_set_value_multiple (const char *device, const unsigned int *offsets, const int *values, unsigned int num_lines, bool active_low, const char *consumer, gpiod_ctxless_set_value_cb cb, void *data) GPIOD_API
	Set values of multiple GPIO lines. More...
int	gpiod_ctxless_set_value_multiple_ext (const char *device, const unsigned int *offsets, const int *values, unsigned int num_lines, bool active_low, const char *consumer, gpiod_ctxless_set_value_cb cb, void *data, int flags) GPIOD_API
	Set values of multiple GPIO lines. More...
int	gpiod_ctxless_event_loop (const char *device, unsigned int offset, bool active_low, const char *consumer, const struct timespec *timeout, gpiod_ctxless_event_poll_cb poll_cb, gpiod_ctxless_event_handle_cb event_cb, void *data) GPIOD_API GPIOD_DEPRECATED
	Wait for events on a single GPIO line. More...
int	gpiod_ctxless_event_loop_multiple (const char *device, const unsigned int *offsets, unsigned int num_lines, bool active_low, const char *consumer, const struct timespec *timeout, gpiod_ctxless_event_poll_cb poll_cb, gpiod_ctxless_event_handle_cb event_cb, void *data) GPIOD_API GPIOD_DEPRECATED
	Wait for events on multiple GPIO lines. More...
int	gpiod_ctxless_event_monitor (const char *device, int event_type, unsigned int offset, bool active_low, const char *consumer, const struct timespec *timeout, gpiod_ctxless_event_poll_cb poll_cb, gpiod_ctxless_event_handle_cb event_cb, void *data) GPIOD_API
	Wait for events on a single GPIO line. More...
int	gpiod_ctxless_event_monitor_ext (const char *device, int event_type, unsigned int offset, bool active_low, const char *consumer, const struct timespec *timeout, gpiod_ctxless_event_poll_cb poll_cb, gpiod_ctxless_event_handle_cb event_cb, void *data, int flags) GPIOD_API
	Wait for events on a single GPIO line. More...
int	gpiod_ctxless_event_monitor_multiple (const char *device, int event_type, const unsigned int *offsets, unsigned int num_lines, bool active_low, const char *consumer, const struct timespec *timeout, gpiod_ctxless_event_poll_cb poll_cb, gpiod_ctxless_event_handle_cb event_cb, void *data) GPIOD_API
	Wait for events on multiple GPIO lines. More...
int	gpiod_ctxless_event_monitor_multiple_ext (const char *device, int event_type, const unsigned int *offsets, unsigned int num_lines, bool active_low, const char *consumer, const struct timespec *timeout, gpiod_ctxless_event_poll_cb poll_cb, gpiod_ctxless_event_handle_cb event_cb, void *data, int flags) GPIOD_API
	Wait for events on multiple GPIO lines. More...
int	gpiod_ctxless_find_line (const char *name, char *chipname, size_t chipname_size, unsigned int *offset) GPIOD_API
	Determine the chip name and line offset of a line with given name. More...

Detailed Description

Simple high-level routines for straightforward GPIO manipulation without the need to use the gpiod_* structures or to keep track of resources.

Typedef Documentation

gpiod_ctxless_event_handle_cb

typedef int(* gpiod_ctxless_event_handle_cb) (int, unsigned int, const struct timespec *, void *)

Simple event callback signature.

The callback function takes the following arguments: event type (int), GPIO line offset (unsigned int), event timestamp (const struct timespec *) and a pointer to user data (void *).

This callback is called by the ctxless event loop functions for each GPIO event. If the callback returns GPIOD_CTXLESS_EVENT_CB_RET_ERR, it should also set errno.

Definition at line 296 of file gpiod.h.

gpiod_ctxless_event_poll_cb

typedef int(* gpiod_ctxless_event_poll_cb) (unsigned int, struct gpiod_ctxless_event_poll_fd *, const struct timespec *, void *)

Simple event poll callback signature.

The poll callback function takes the following arguments: number of lines (unsigned int), an array of file descriptors on which input events should be monitored (struct gpiod_ctxless_event_poll_fd *), poll timeout (const struct timespec *) and a pointer to user data (void *).

The callback should poll for input events on the set of descriptors and return an appropriate value that can be interpreted by the event loop routine.

Definition at line 336 of file gpiod.h.

Enumeration Type Documentation

anonymous enum

anonymous enum

Miscellaneous GPIO flags.

Enumerator
GPIOD_CTXLESS_FLAG_OPEN_DRAIN	The line is an open-drain port.
GPIOD_CTXLESS_FLAG_OPEN_SOURCE	The line is an open-source port.
GPIOD_CTXLESS_FLAG_BIAS_DISABLE	The line has neither either pull-up nor pull-down resistor.
GPIOD_CTXLESS_FLAG_BIAS_PULL_DOWN	The line has pull-down resistor enabled.
GPIOD_CTXLESS_FLAG_BIAS_PULL_UP	The line has pull-up resistor enabled.

Definition at line 94 of file gpiod.h.

anonymous enum

anonymous enum

Event types that the ctxless event monitor can wait for.

Enumerator
GPIOD_CTXLESS_EVENT_RISING_EDGE	Wait for rising edge events only. Wait for falling edge events only.
GPIOD_CTXLESS_EVENT_FALLING_EDGE	Wait for both types of events.

Definition at line 252 of file gpiod.h.

anonymous enum

anonymous enum

Event types that can be passed to the ctxless event callback.

Enumerator
GPIOD_CTXLESS_EVENT_CB_TIMEOUT	Waiting for events timed out.
GPIOD_CTXLESS_EVENT_CB_RISING_EDGE	Rising edge event occured.
GPIOD_CTXLESS_EVENT_CB_FALLING_EDGE	Falling edge event occured.

Definition at line 264 of file gpiod.h.

anonymous enum

anonymous enum

Return status values that the ctxless event callback can return.

Enumerator
GPIOD_CTXLESS_EVENT_CB_RET_ERR	Stop processing events and indicate an error.
GPIOD_CTXLESS_EVENT_CB_RET_OK	Continue processing events.
GPIOD_CTXLESS_EVENT_CB_RET_STOP	Stop processing events.

Definition at line 276 of file gpiod.h.

anonymous enum

anonymous enum

Return status values that the ctxless event poll callback can return.

Positive value returned from the polling callback indicates the number of events that occurred on the set of monitored lines.

Enumerator
GPIOD_CTXLESS_EVENT_POLL_RET_STOP	The event loop should stop processing events.
GPIOD_CTXLESS_EVENT_POLL_RET_ERR	Polling error occurred (the polling function should set errno).
GPIOD_CTXLESS_EVENT_POLL_RET_TIMEOUT	Poll timed out.

Definition at line 305 of file gpiod.h.

Function Documentation

gpiod_ctxless_event_loop()

int gpiod_ctxless_event_loop	(	const char *	device,
		unsigned int	offset,
		bool	active_low,
		const char *	consumer,
		const struct timespec *	timeout,
		gpiod_ctxless_event_poll_cb	poll_cb,
		gpiod_ctxless_event_handle_cb	event_cb,
		void *	data
	)

Wait for events on a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
offset	GPIO line offset to monitor.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
timeout	Maximum wait time for each iteration.
poll_cb	Callback function to call when waiting for events.
event_cb	Callback function to call for each line event.
data	User data passed to the callback.

Returns

0 if no errors were encountered, -1 if an error occurred.

Note

The way the ctxless event loop works is described in detail in gpiod_ctxless_event_loop_multiple - this is just a wrapper aound this routine which calls it for a single GPIO line.

Deprecated:

This function suffers from an issue where HW may not allow setting up both rising and falling egde interrupts at the same time.

gpiod_ctxless_event_loop_multiple()

int gpiod_ctxless_event_loop_multiple	(	const char *	device,
		const unsigned int *	offsets,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer,
		const struct timespec *	timeout,
		gpiod_ctxless_event_poll_cb	poll_cb,
		gpiod_ctxless_event_handle_cb	event_cb,
		void *	data
	)

Wait for events on multiple GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
offsets	Array of GPIO line offsets to monitor.
num_lines	Number of lines to monitor.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
timeout	Maximum wait time for each iteration.
poll_cb	Callback function to call when waiting for events. Can be NULL.
event_cb	Callback function to call on event occurrence.
data	User data passed to the callback.

Returns

0 no errors were encountered, -1 if an error occurred.

Note

The poll callback can be NULL in which case the routine will fall back to a basic, ppoll() based callback.

Deprecated:

This function suffers from an issue where HW may not allow setting up both rising and falling egde interrupts at the same time.

Internally this routine opens the GPIO chip, requests the set of lines for both-edges events and calls the polling callback in a loop. The role of the polling callback is to detect input events on a set of file descriptors and notify the caller about the fds ready for reading.

The ctxless event loop then reads each queued event from marked descriptors and calls the event callback. Both callbacks can stop the loop at any point.

The poll_cb argument can be NULL in which case the function falls back to a default, ppoll() based callback.

gpiod_ctxless_event_monitor()

int gpiod_ctxless_event_monitor	(	const char *	device,
		int	event_type,
		unsigned int	offset,
		bool	active_low,
		const char *	consumer,
		const struct timespec *	timeout,
		gpiod_ctxless_event_poll_cb	poll_cb,
		gpiod_ctxless_event_handle_cb	event_cb,
		void *	data
	)

Wait for events on a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
event_type	Type of events to listen for.
offset	GPIO line offset to monitor.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
timeout	Maximum wait time for each iteration.
poll_cb	Callback function to call when waiting for events.
event_cb	Callback function to call for each line event.
data	User data passed to the callback.

Returns

0 if no errors were encountered, -1 if an error occurred.

Note

The way the ctxless event loop works is described in detail in gpiod_ctxless_event_monitor_multiple - this is just a wrapper aound this routine which calls it for a single GPIO line.

gpiod_ctxless_event_monitor_ext()

int gpiod_ctxless_event_monitor_ext	(	const char *	device,
		int	event_type,
		unsigned int	offset,
		bool	active_low,
		const char *	consumer,
		const struct timespec *	timeout,
		gpiod_ctxless_event_poll_cb	poll_cb,
		gpiod_ctxless_event_handle_cb	event_cb,
		void *	data,
		int	flags
	)

Wait for events on a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
event_type	Type of events to listen for.
offset	GPIO line offset to monitor.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
timeout	Maximum wait time for each iteration.
poll_cb	Callback function to call when waiting for events.
event_cb	Callback function to call for each line event.
data	User data passed to the callback.
flags	The flags for the line.

Returns

0 if no errors were encountered, -1 if an error occurred.

Note

The way the ctxless event loop works is described in detail in gpiod_ctxless_event_monitor_multiple - this is just a wrapper aound this routine which calls it for a single GPIO line.

gpiod_ctxless_event_monitor_multiple()

int gpiod_ctxless_event_monitor_multiple	(	const char *	device,
		int	event_type,
		const unsigned int *	offsets,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer,
		const struct timespec *	timeout,
		gpiod_ctxless_event_poll_cb	poll_cb,
		gpiod_ctxless_event_handle_cb	event_cb,
		void *	data
	)

Wait for events on multiple GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
event_type	Type of events to listen for.
offsets	Array of GPIO line offsets to monitor.
num_lines	Number of lines to monitor.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
timeout	Maximum wait time for each iteration.
poll_cb	Callback function to call when waiting for events. Can be NULL.
event_cb	Callback function to call on event occurrence.
data	User data passed to the callback.

Returns

0 no errors were encountered, -1 if an error occurred.

Note

The poll callback can be NULL in which case the routine will fall back to a basic, ppoll() based callback.

Internally this routine opens the GPIO chip, requests the set of lines for the type of events specified in the event_type parameter and calls the polling callback in a loop. The role of the polling callback is to detect input events on a set of file descriptors and notify the caller about the fds ready for reading.

The ctxless event loop then reads each queued event from marked descriptors and calls the event callback. Both callbacks can stop the loop at any point.

The poll_cb argument can be NULL in which case the function falls back to a default, ppoll() based callback.

gpiod_ctxless_event_monitor_multiple_ext()

int gpiod_ctxless_event_monitor_multiple_ext	(	const char *	device,
		int	event_type,
		const unsigned int *	offsets,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer,
		const struct timespec *	timeout,
		gpiod_ctxless_event_poll_cb	poll_cb,
		gpiod_ctxless_event_handle_cb	event_cb,
		void *	data,
		int	flags
	)

Wait for events on multiple GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
event_type	Type of events to listen for.
offsets	Array of GPIO line offsets to monitor.
num_lines	Number of lines to monitor.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
timeout	Maximum wait time for each iteration.
poll_cb	Callback function to call when waiting for events. Can be NULL.
event_cb	Callback function to call on event occurrence.
data	User data passed to the callback.
flags	The flags for the lines.

Returns

0 no errors were encountered, -1 if an error occurred.

Note

The poll callback can be NULL in which case the routine will fall back to a basic, ppoll() based callback.

Internally this routine opens the GPIO chip, requests the set of lines for the type of events specified in the event_type parameter and calls the polling callback in a loop. The role of the polling callback is to detect input events on a set of file descriptors and notify the caller about the fds ready for reading.

The ctxless event loop then reads each queued event from marked descriptors and calls the event callback. Both callbacks can stop the loop at any point.

The poll_cb argument can be NULL in which case the function falls back to a default, ppoll() based callback.

gpiod_ctxless_find_line()

int gpiod_ctxless_find_line	(	const char *	name,
		char *	chipname,
		size_t	chipname_size,
		unsigned int *	offset
	)

Determine the chip name and line offset of a line with given name.

Parameters

name	The name of the GPIO line to lookup.
chipname	Buffer in which the name of the GPIO chip will be stored.
chipname_size	Size of the chip name buffer.
offset	Pointer to an integer in which the line offset will be stored.

Returns

-1 on error, 0 if the line with given name doesn't exist and 1 if the line was found. In the first two cases the contents of chipname and offset remain unchanged.

Note

The chip name is truncated if the buffer can't hold its entire size.

Attention

GPIO line names are not unique in the linux kernel, neither globally nor within a single chip. This function finds the first line with given name.

gpiod_ctxless_get_value()

int gpiod_ctxless_get_value	(	const char *	device,
		unsigned int	offset,
		bool	active_low,
		const char *	consumer
	)

Read current value from a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
offset	Offset of the GPIO line.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.

Returns

0 or 1 (GPIO value) if the operation succeeds, -1 on error.

gpiod_ctxless_get_value_ext()

int gpiod_ctxless_get_value_ext	(	const char *	device,
		unsigned int	offset,
		bool	active_low,
		const char *	consumer,
		int	flags
	)

Read current value from a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
offset	Offset of the GPIO line.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
flags	The flags for the line.

Returns

0 or 1 (GPIO value) if the operation succeeds, -1 on error.

gpiod_ctxless_get_value_multiple()

int gpiod_ctxless_get_value_multiple	(	const char *	device,
		const unsigned int *	offsets,
		int *	values,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer
	)

Read current values from a set of GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
offsets	Array of offsets of lines whose values should be read.
values	Buffer in which the values will be stored.
num_lines	Number of lines, must be > 0.
active_low	The active state of the lines - true if low.
consumer	Name of the consumer.

Returns

0 if the operation succeeds, -1 on error.

gpiod_ctxless_get_value_multiple_ext()

int gpiod_ctxless_get_value_multiple_ext	(	const char *	device,
		const unsigned int *	offsets,
		int *	values,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer,
		int	flags
	)

Read current values from a set of GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
offsets	Array of offsets of lines whose values should be read.
values	Buffer in which the values will be stored.
num_lines	Number of lines, must be > 0.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
flags	The flags for the lines.

Returns

0 if the operation succeeds, -1 on error.

gpiod_ctxless_set_value()

int gpiod_ctxless_set_value	(	const char *	device,
		unsigned int	offset,
		int	value,
		bool	active_low,
		const char *	consumer,
		gpiod_ctxless_set_value_cb	cb,
		void *	data
	)

Set value of a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
offset	The offset of the GPIO line.
value	New value (0 or 1).
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
cb	Optional callback function that will be called right after setting the value. Users can use this, for example, to pause the execution after toggling a GPIO.
data	Optional user data that will be passed to the callback function.

Returns

0 if the operation succeeds, -1 on error.

gpiod_ctxless_set_value_ext()

int gpiod_ctxless_set_value_ext	(	const char *	device,
		unsigned int	offset,
		int	value,
		bool	active_low,
		const char *	consumer,
		gpiod_ctxless_set_value_cb	cb,
		void *	data,
		int	flags
	)

Set value of a single GPIO line.

Parameters

device	Name, path, number or label of the gpiochip.
offset	The offset of the GPIO line.
value	New value (0 or 1).
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
cb	Optional callback function that will be called right after setting the value. Users can use this, for example, to pause the execution after toggling a GPIO.
data	Optional user data that will be passed to the callback function.
flags	The flags for the line.

Returns

0 if the operation succeeds, -1 on error.

gpiod_ctxless_set_value_multiple()

int gpiod_ctxless_set_value_multiple	(	const char *	device,
		const unsigned int *	offsets,
		const int *	values,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer,
		gpiod_ctxless_set_value_cb	cb,
		void *	data
	)

Set values of multiple GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
offsets	Array of offsets of lines the values of which should be set.
values	Array of integers containing new values.
num_lines	Number of lines, must be > 0.
active_low	The active state of the lines - true if low.
consumer	Name of the consumer.
cb	Optional callback function that will be called right after setting all values. Works the same as in gpiod_ctxless_set_value.
data	Optional user data that will be passed to the callback function.

Returns

0 if the operation succeeds, -1 on error.

gpiod_ctxless_set_value_multiple_ext()

int gpiod_ctxless_set_value_multiple_ext	(	const char *	device,
		const unsigned int *	offsets,
		const int *	values,
		unsigned int	num_lines,
		bool	active_low,
		const char *	consumer,
		gpiod_ctxless_set_value_cb	cb,
		void *	data,
		int	flags
	)

Set values of multiple GPIO lines.

Parameters

device	Name, path, number or label of the gpiochip.
offsets	Array of offsets of lines the values of which should be set.
values	Array of integers containing new values.
num_lines	Number of lines, must be > 0.
active_low	The active state of this line - true if low.
consumer	Name of the consumer.
cb	Optional callback function that will be called right after setting all values. Works the same as in gpiod_ctxless_set_value.
data	Optional user data that will be passed to the callback function.
flags	The flags for the lines.

Returns

0 if the operation succeeds, -1 on error.

References GPIOD_CTXLESS_EVENT_FALLING_EDGE, and GPIOD_CTXLESS_EVENT_RISING_EDGE.