libgpiod  0.3.2
Modules | Data Structures | Macros | Enumerations | Functions
GPIO line operations

Functions and data structures dealing with GPIO lines. More...

Collaboration diagram for GPIO line operations:

Modules

 Line event operations
 Functions and data structures for requesting and reading GPIO line events.
 

Data Structures

struct  gpiod_line_bulk
 Helper structure for storing a set of GPIO line objects. More...
 
struct  gpiod_line_request_config
 Structure holding configuration of a line request. More...
 

Macros

#define GPIOD_REQUEST_MAX_LINES   64
 Maximum number of GPIO lines that can be requested at once.
 
#define GPIOD_LINE_BULK_INITIALIZER   { { NULL }, 0 }
 Static initializer for GPIO bulk objects. More...
 

Enumerations

enum  { GPIOD_DIRECTION_AS_IS, GPIOD_DIRECTION_INPUT, GPIOD_DIRECTION_OUTPUT }
 Available direction settings. More...
 
enum  { GPIOD_ACTIVE_STATE_HIGH, GPIOD_ACTIVE_STATE_LOW }
 Available active state settings. More...
 
enum  { GPIOD_REQUEST_OPEN_DRAIN = GPIOD_BIT(0), GPIOD_REQUEST_OPEN_SOURCE = GPIOD_BIT(1) }
 Miscellaneous GPIO flags. More...
 

Functions

static void gpiod_line_bulk_init (struct gpiod_line_bulk *bulk)
 Initialize a GPIO bulk object. More...
 
static void gpiod_line_bulk_add (struct gpiod_line_bulk *bulk, struct gpiod_line *line)
 Add a single line to a GPIO bulk object. More...
 
unsigned int gpiod_line_offset (struct gpiod_line *line) GPIOD_API
 Read the GPIO line offset. More...
 
const char * gpiod_line_name (struct gpiod_line *line) GPIOD_API
 Read the GPIO line name. More...
 
const char * gpiod_line_consumer (struct gpiod_line *line) GPIOD_API
 Read the GPIO line consumer name. More...
 
int gpiod_line_direction (struct gpiod_line *line) GPIOD_API
 Read the GPIO line direction setting. More...
 
int gpiod_line_active_state (struct gpiod_line *line) GPIOD_API
 Read the GPIO line active state setting. More...
 
bool gpiod_line_is_used_by_kernel (struct gpiod_line *line) GPIOD_API
 Check if the line is used by the kernel. More...
 
bool gpiod_line_is_open_drain (struct gpiod_line *line) GPIOD_API
 Check if the line is an open-drain GPIO. More...
 
bool gpiod_line_is_open_source (struct gpiod_line *line) GPIOD_API
 Check if the line is an open-source GPIO. More...
 
int gpiod_line_update (struct gpiod_line *line) GPIOD_API
 Re-read the line info. More...
 
bool gpiod_line_needs_update (struct gpiod_line *line) GPIOD_API
 Check if the line info needs to be updated. More...
 
int gpiod_line_request (struct gpiod_line *line, const struct gpiod_line_request_config *config, int default_val) GPIOD_API
 Reserve a single line. More...
 
int gpiod_line_request_input (struct gpiod_line *line, const char *consumer, bool active_low) GPIOD_API
 Reserve a single line, set the direction to input. More...
 
int gpiod_line_request_output (struct gpiod_line *line, const char *consumer, bool active_low, int default_val) GPIOD_API
 Reserve a single line, set the direction to output. More...
 
int gpiod_line_request_bulk (struct gpiod_line_bulk *bulk, const struct gpiod_line_request_config *config, const int *default_vals) GPIOD_API
 Reserve a set of GPIO lines. More...
 
int gpiod_line_request_bulk_input (struct gpiod_line_bulk *bulk, const char *consumer, bool active_low) GPIOD_API
 Reserve a set of GPIO lines, set the direction to input. More...
 
int gpiod_line_request_bulk_output (struct gpiod_line_bulk *bulk, const char *consumer, bool active_low, const int *default_vals) GPIOD_API
 Reserve a set of GPIO lines, set the direction to output. More...
 
void gpiod_line_release (struct gpiod_line *line) GPIOD_API
 Release a previously reserved line. More...
 
void gpiod_line_release_bulk (struct gpiod_line_bulk *bulk) GPIOD_API
 Release a set of previously reserved lines. More...
 
bool gpiod_line_is_reserved (struct gpiod_line *line) GPIOD_API
 Check if the calling user has ownership of this line. More...
 
bool gpiod_line_is_free (struct gpiod_line *line) GPIOD_API
 Check if the calling user has neither requested ownership of this line nor configured any event notifications. More...
 
int gpiod_line_get_value (struct gpiod_line *line) GPIOD_API
 Read current value of a single GPIO line. More...
 
int gpiod_line_get_value_bulk (struct gpiod_line_bulk *bulk, int *values) GPIOD_API
 Read current values of a set of GPIO lines. More...
 
int gpiod_line_set_value (struct gpiod_line *line, int value) GPIOD_API
 Set the value of a single GPIO line. More...
 
int gpiod_line_set_value_bulk (struct gpiod_line_bulk *bulk, int *values) GPIOD_API
 Set the values of a set of GPIO lines. More...
 
struct gpiod_line * gpiod_line_find_by_name (const char *name) GPIOD_API
 Find a GPIO line by its name. More...
 
struct gpiod_chip * gpiod_line_get_chip (struct gpiod_line *line) GPIOD_API
 Get the handle to the GPIO chip controlling this line. More...
 

Detailed Description

Functions and data structures dealing with GPIO lines.

Macro Definition Documentation

◆ GPIOD_LINE_BULK_INITIALIZER

#define GPIOD_LINE_BULK_INITIALIZER   { { NULL }, 0 }

Static initializer for GPIO bulk objects.

This macro simply sets the internally held number of lines to 0.

Definition at line 321 of file gpiod.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Available direction settings.

These values are used both when requesting lines and when retrieving line info.

Enumerator
GPIOD_DIRECTION_AS_IS 

Only relevant for line requests - don't set the direction.

GPIOD_DIRECTION_INPUT 

Direction is input - we're reading the state of a GPIO line.

GPIOD_DIRECTION_OUTPUT 

Direction is output - we're driving the GPIO line.

Definition at line 268 of file gpiod.h.

◆ anonymous enum

anonymous enum

Available active state settings.

Enumerator
GPIOD_ACTIVE_STATE_HIGH 

The active state of a GPIO is active-high.

GPIOD_ACTIVE_STATE_LOW 

The active state of a GPIO is active-low.

Definition at line 280 of file gpiod.h.

◆ anonymous enum

anonymous enum

Miscellaneous GPIO flags.

Enumerator
GPIOD_REQUEST_OPEN_DRAIN 

The line is an open-drain port.

GPIOD_REQUEST_OPEN_SOURCE 

The line is an open-source port.

Definition at line 290 of file gpiod.h.

Function Documentation

◆ gpiod_line_active_state()

int gpiod_line_active_state ( struct gpiod_line *  line)

Read the GPIO line active state setting.

Parameters
lineGPIO line object.
Returns
Returns GPIOD_ACTIVE_STATE_HIGH or GPIOD_ACTIVE_STATE_LOW.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_bulk_add()

static void gpiod_line_bulk_add ( struct gpiod_line_bulk bulk,
struct gpiod_line *  line 
)
inlinestatic

◆ gpiod_line_bulk_init()

static void gpiod_line_bulk_init ( struct gpiod_line_bulk bulk)
inlinestatic

Initialize a GPIO bulk object.

Parameters
bulkLine bulk object.

This routine simply sets the internally held number of lines to 0.

Definition at line 329 of file gpiod.h.

References gpiod_line_bulk::num_lines.

◆ gpiod_line_consumer()

const char* gpiod_line_consumer ( struct gpiod_line *  line)

Read the GPIO line consumer name.

Parameters
lineGPIO line object.
Returns
Name of the GPIO consumer name as it is represented in the kernel. This routine returns a pointer to a null-terminated string or NULL if the line is not used.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_direction()

int gpiod_line_direction ( struct gpiod_line *  line)

Read the GPIO line direction setting.

Parameters
lineGPIO line object.
Returns
Returns GPIOD_DIRECTION_INPUT or GPIOD_DIRECTION_OUTPUT.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_find_by_name()

struct gpiod_line* gpiod_line_find_by_name ( const char *  name)

Find a GPIO line by its name.

Parameters
nameName of the GPIO line.
Returns
Returns the GPIO line handle if the line exists in the system or NULL if it couldn't be located.

If this routine succeeds, the user must manually close the GPIO chip owning this line to avoid memory leaks.

◆ gpiod_line_get_chip()

struct gpiod_chip* gpiod_line_get_chip ( struct gpiod_line *  line)

Get the handle to the GPIO chip controlling this line.

Parameters
lineThe GPIO line object.
Returns
Pointer to the GPIO chip handle controlling this line.

◆ gpiod_line_get_value()

int gpiod_line_get_value ( struct gpiod_line *  line)

Read current value of a single GPIO line.

Parameters
lineGPIO line object.
Returns
0 or 1 if the operation succeeds. On error this routine returns -1 and sets the last error number.

◆ gpiod_line_get_value_bulk()

int gpiod_line_get_value_bulk ( struct gpiod_line_bulk bulk,
int *  values 
)

Read current values of a set of GPIO lines.

Parameters
bulkSet of GPIO lines to reserve.
valuesAn array big enough to hold line_bulk->num_lines values.
Returns
0 is the operation succeeds. In case of an error this routine returns -1 and sets the last error number.

If succeeds, this routine fills the values array with a set of values in the same order, the lines are added to line_bulk. If the lines were not previously requested together, the behavior is undefined.

◆ gpiod_line_is_free()

bool gpiod_line_is_free ( struct gpiod_line *  line)

Check if the calling user has neither requested ownership of this line nor configured any event notifications.

Parameters
lineGPIO line object.
Returns
True if given line is free, false otherwise.

◆ gpiod_line_is_open_drain()

bool gpiod_line_is_open_drain ( struct gpiod_line *  line)

Check if the line is an open-drain GPIO.

Parameters
lineGPIO line object.
Returns
True if the line is an open-drain GPIO, false otherwise.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_is_open_source()

bool gpiod_line_is_open_source ( struct gpiod_line *  line)

Check if the line is an open-source GPIO.

Parameters
lineGPIO line object.
Returns
True if the line is an open-source GPIO, false otherwise.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_is_reserved()

bool gpiod_line_is_reserved ( struct gpiod_line *  line)

Check if the calling user has ownership of this line.

Parameters
lineGPIO line object.
Returns
True if given line was requested, false otherwise.

◆ gpiod_line_is_used_by_kernel()

bool gpiod_line_is_used_by_kernel ( struct gpiod_line *  line)

Check if the line is used by the kernel.

Parameters
lineGPIO line object.
Returns
True if the line is used by the kernel, false otherwise.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_name()

const char* gpiod_line_name ( struct gpiod_line *  line)

Read the GPIO line name.

Parameters
lineGPIO line object.
Returns
Name of the GPIO line as it is represented in the kernel. This routine returns a pointer to a null-terminated string or NULL if the line is unnamed.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_needs_update()

bool gpiod_line_needs_update ( struct gpiod_line *  line)

Check if the line info needs to be updated.

Parameters
lineGPIO line object.
Returns
Returns false if the line is up-to-date. True otherwise.

The line is updated by calling gpiod_line_update() from within gpiod_chip_get_line() and on every line request/release. However: an error returned from gpiod_line_update() only breaks the execution of the former. The request/release routines only set the internal up-to-date flag to false and continue their execution. This routine allows to check if a line info update failed at some point and we should call gpiod_line_update() explicitly.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_offset()

unsigned int gpiod_line_offset ( struct gpiod_line *  line)

Read the GPIO line offset.

Parameters
lineGPIO line object.
Returns
Line offset.

Referenced by gpiod_line_bulk_add().

◆ gpiod_line_release()

void gpiod_line_release ( struct gpiod_line *  line)

Release a previously reserved line.

Parameters
lineGPIO line object.

◆ gpiod_line_release_bulk()

void gpiod_line_release_bulk ( struct gpiod_line_bulk bulk)

Release a set of previously reserved lines.

Parameters
bulkSet of GPIO lines to release.

If the lines were not previously requested together, the behavior is undefined.

◆ gpiod_line_request()

int gpiod_line_request ( struct gpiod_line *  line,
const struct gpiod_line_request_config config,
int  default_val 
)

Reserve a single line.

Parameters
lineGPIO line object.
configRequest options.
default_valDefault line value - only relevant if we're setting the direction to output.
Returns
0 if the line was properly reserved. In case of an error this routine returns -1 and sets the last error number.

If this routine succeeds, the caller takes ownership of the GPIO line until it's released.

◆ gpiod_line_request_bulk()

int gpiod_line_request_bulk ( struct gpiod_line_bulk bulk,
const struct gpiod_line_request_config config,
const int *  default_vals 
)

Reserve a set of GPIO lines.

Parameters
bulkSet of GPIO lines to reserve.
configRequest options.
default_valsDefault line values - only relevant if we're setting the direction to output.
Returns
0 if the all lines were properly requested. In case of an error this routine returns -1 and sets the last error number.

If this routine succeeds, the caller takes ownership of the GPIO lines until they're released. All the requested lines must be prodivided by the same gpiochip.

◆ gpiod_line_request_bulk_input()

int gpiod_line_request_bulk_input ( struct gpiod_line_bulk bulk,
const char *  consumer,
bool  active_low 
)

Reserve a set of GPIO lines, set the direction to input.

Parameters
bulkSet of GPIO lines to reserve.
consumerName of the consumer.
active_lowActive state of the lines (true if low).
Returns
0 if the lines were properly reserved, -1 on failure.

◆ gpiod_line_request_bulk_output()

int gpiod_line_request_bulk_output ( struct gpiod_line_bulk bulk,
const char *  consumer,
bool  active_low,
const int *  default_vals 
)

Reserve a set of GPIO lines, set the direction to output.

Parameters
bulkSet of GPIO lines to reserve.
consumerName of the consumer.
active_lowActive state of the lines (true if low).
default_valsDefault line values.
Returns
0 if the lines were properly reserved, -1 on failure.

◆ gpiod_line_request_input()

int gpiod_line_request_input ( struct gpiod_line *  line,
const char *  consumer,
bool  active_low 
)

Reserve a single line, set the direction to input.

Parameters
lineGPIO line object.
consumerName of the consumer.
active_lowActive state of the line (true if low).
Returns
0 if the line was properly reserved, -1 on failure.

◆ gpiod_line_request_output()

int gpiod_line_request_output ( struct gpiod_line *  line,
const char *  consumer,
bool  active_low,
int  default_val 
)

Reserve a single line, set the direction to output.

Parameters
lineGPIO line object.
consumerName of the consumer.
active_lowActive state of the line (true if low).
default_valDefault line value.
Returns
0 if the line was properly reserved, -1 on failure.

◆ gpiod_line_set_value()

int gpiod_line_set_value ( struct gpiod_line *  line,
int  value 
)

Set the value of a single GPIO line.

Parameters
lineGPIO line object.
valueNew value.
Returns
0 is the operation succeeds. In case of an error this routine returns -1 and sets the last error number.

◆ gpiod_line_set_value_bulk()

int gpiod_line_set_value_bulk ( struct gpiod_line_bulk bulk,
int *  values 
)

Set the values of a set of GPIO lines.

Parameters
bulkSet of GPIO lines to reserve.
valuesAn array holding line_bulk->num_lines new values for lines.
Returns
0 is the operation succeeds. In case of an error this routine returns -1 and sets the last error number.

If the lines were not previously requested together, the behavior is undefined.

◆ gpiod_line_update()

int gpiod_line_update ( struct gpiod_line *  line)

Re-read the line info.

Parameters
lineGPIO line object.
Returns
0 is the operation succeeds. In case of an error this routine returns -1 and sets the last error number.

The line info is initially retrieved from the kernel by gpiod_chip_get_line(). Users can use this line to manually re-read the line info.

Referenced by gpiod_line_bulk_add().