GPIO

Description

C interface for the Linux GPIO driver.

<rc/gpio.h>

Developed and tested on the BeagleBone Black but should work fine on any Linux system with the new character-device gpio driver in kernel 4.8 and newer

Author

James Strawson

Date

1/19/2018

Macros
#define	GPIOHANDLE_REQUEST_INPUT   (1UL << 0)
#define	GPIOHANDLE_REQUEST_OUTPUT   (1UL << 1)
#define	GPIOHANDLE_REQUEST_ACTIVE_LOW   (1UL << 2)
#define	GPIOHANDLE_REQUEST_OPEN_DRAIN   (1UL << 3)
#define	GPIOHANDLE_REQUEST_OPEN_SOURCE   (1UL << 4)
#define	GPIOEVENT_REQUEST_RISING_EDGE   (1UL << 0)
#define	GPIOEVENT_REQUEST_FALLING_EDGE   (1UL << 1)
#define	GPIOEVENT_REQUEST_BOTH_EDGES   ((1UL << 0) | (1UL << 1))
#define	RC_GPIOEVENT_ERROR   -1
#define	RC_GPIOEVENT_TIMEOUT   0
#define	RC_GPIOEVENT_RISING_EDGE   1
#define	RC_GPIOEVENT_FALLING_EDGE   2

Functions
int	rc_gpio_init (int chip, int pin, int handle_flags)
	Configures a gpio pin as input or output. More...
int	rc_gpio_set_value (int chip, int pin, int value)
	Sets the value of a GPIO pin when in output mode. More...
int	rc_gpio_get_value (int chip, int pin)
	Reads the value of a GPIO pin when in input mode or output mode. More...
int	rc_gpio_init_event (int chip, int pin, int handle_flags, int event_flags)
	Initializes a pin for interrupt event polling and normal reading. More...
int	rc_gpio_poll (int chip, int pin, int timeout_ms, uint64_t *event_time_ns)
	polls a pin when configured for interrupt event polling More...
void	rc_gpio_cleanup (int chip, int pin)
	closes the file descriptor for a pin More...

Macro Definition Documentation

GPIOHANDLE_REQUEST_INPUT

#define GPIOHANDLE_REQUEST_INPUT   (1UL << 0)

GPIOHANDLE_REQUEST_OUTPUT

#define GPIOHANDLE_REQUEST_OUTPUT   (1UL << 1)

GPIOHANDLE_REQUEST_ACTIVE_LOW

#define GPIOHANDLE_REQUEST_ACTIVE_LOW   (1UL << 2)

GPIOHANDLE_REQUEST_OPEN_DRAIN

#define GPIOHANDLE_REQUEST_OPEN_DRAIN   (1UL << 3)

GPIOHANDLE_REQUEST_OPEN_SOURCE

#define GPIOHANDLE_REQUEST_OPEN_SOURCE   (1UL << 4)

GPIOEVENT_REQUEST_RISING_EDGE

#define GPIOEVENT_REQUEST_RISING_EDGE   (1UL << 0)

possible edge request

GPIOEVENT_REQUEST_FALLING_EDGE

#define GPIOEVENT_REQUEST_FALLING_EDGE   (1UL << 1)

GPIOEVENT_REQUEST_BOTH_EDGES

#define GPIOEVENT_REQUEST_BOTH_EDGES   ((1UL << 0) | (1UL << 1))

RC_GPIOEVENT_ERROR

#define RC_GPIOEVENT_ERROR   -1

possible return values for rc_gpio_poll

RC_GPIOEVENT_TIMEOUT

#define RC_GPIOEVENT_TIMEOUT   0

RC_GPIOEVENT_RISING_EDGE

#define RC_GPIOEVENT_RISING_EDGE   1

RC_GPIOEVENT_FALLING_EDGE

#define RC_GPIOEVENT_FALLING_EDGE   2

Function Documentation

rc_gpio_init()

int rc_gpio_init	(	int	chip,
		int	pin,
		int	handle_flags
	)

Configures a gpio pin as input or output.

This configures the pin by making a gpio handle request to the character device driver. It accepts the same gpio handle request flags as defined in <linux/gpio.h>

• GPIOHANDLE_REQUEST_INPUT
• GPIOHANDLE_REQUEST_OUTPUT
• GPIOHANDLE_REQUEST_ACTIVE_LOW
• GPIOHANDLE_REQUEST_OPEN_DRAIN
• GPIOHANDLE_REQUEST_OPEN_SOURCE

Obviously the INPUT and OUTPUT flags cannot be used at the same time. If you don't know what the other flags mean just stick with INPUT and OUTPUT modes, that covers 99% of use cases.

Parameters

[in]	chip	The chip number, /dev/gpiochipX
[in]	pin	The pin ID
[in]	handle_flags	The handle flags

Returns

0 on success or -1 on failure.

rc_gpio_set_value()

int rc_gpio_set_value	(	int	chip,
		int	pin,
		int	value
	)

Sets the value of a GPIO pin when in output mode.

must call rc_gpio_init with the OUTPUT flag first.

Parameters

[in]	chip	The chip number, /dev/gpiochipX
[in]	pin	The pin ID
[in]	value	0 for off (inactive), nonzero for on (active)

Returns

0 on success or -1 on failure

rc_gpio_get_value()

int rc_gpio_get_value	(	int	chip,
		int	pin
	)

Reads the value of a GPIO pin when in input mode or output mode.

Must call rc_gpio_init first.

Parameters

[in]	chip	The chip number, /dev/gpiochipX
[in]	pin	The pin ID

Returns

1 if pin is high, 0 if pin is low, -1 on error

rc_gpio_init_event()

int rc_gpio_init_event	(	int	chip,
		int	pin,
		int	handle_flags,
		int	event_flags
	)

Initializes a pin for interrupt event polling and normal reading.

Handle flags exists if the user wishes to configure the pic as active-low, open-source, or open-drain. This is usually not necessary and can be left at 0. This function returns the file descriptor used for polling in case the user wants to use a polling method other than rc_gpio_poll.

Parameters

[in]	chip	The chip number, /dev/gpiochipX
[in]	pin	The pin ID
[in]	handle_flags	Additional pin configuration flags, this can usually be left as 0
[in]	event_flags	The event flags, GPIOEVENT_REQUEST_RISING_EDGE, GPIOEVENT_REQUEST_FALLING_EDGE, or GPIOEVENT_REQUEST_BOTH_EDGES

Returns

File descriptor for the GPIO event or -1 on failure

rc_gpio_poll()

int rc_gpio_poll	(	int	chip,
		int	pin,
		int	timeout_ms,
		uint64_t *	event_time_ns
	)

polls a pin when configured for interrupt event polling

This polls for an event and then reads one event from the queue.

Parameters

[in]	chip	The chip number, /dev/gpiochipX
[in]	pin	The pin ID
[in]	timeout_ms	The timeout in milliseconds. Negative value causes infinite timeout, a value of 0 makes the function return immediately after reading an event in the queue.
[out]	event_time_ns	pointer where the time of the gpio event occured. Units are nanoseconds since epoch. Set this as NULL if you don't want to keep the time.

Returns

returns RC_GPIO_EVENT_ERROR, RC_GPIO_EVENT_TIMEOUT, RC_GPIO_EVENT_RISING_EDGE, or RC_GPIO_EVENT_FALLING_EDGE to indicate what happened.

rc_gpio_cleanup()

void rc_gpio_cleanup	(	int	chip,
		int	pin
	)

closes the file descriptor for a pin

Not strictly necessary to run at the end of your program since linux will clean this up for you. However this is sometimes useful in the middle of a program when a pin is no longer needed.

Parameters

[in]	chip	The chip number, /dev/gpiochipX
[in]	pin	The pin ID