GPIO chip

group chips

Functions and data structures for GPIO chip operations.

A GPIO chip object is associated with an open file descriptor to the GPIO character device. It exposes basic information about the chip and allows callers to retrieve information about each line, watch lines for state changes and make line requests.

Functions

struct gpiod_chip *gpiod_chip_open(const char *path)

Open a chip by path.

Parameters:

path – Path to the gpiochip device file.

Returns:

GPIO chip object or NULL if an error occurred. The returned object must be closed by the caller using gpiod_chip_close.

void gpiod_chip_close(struct gpiod_chip *chip)

Close the chip and release all associated resources.

Parameters:

chip – Chip to close.

struct gpiod_chip_info *gpiod_chip_get_info(struct gpiod_chip *chip)

Get information about the chip.

Parameters:

chip – GPIO chip object.

Returns:

New GPIO chip info object or NULL if an error occurred. The returned object must be freed by the caller using gpiod_chip_info_free.

const char *gpiod_chip_get_path(struct gpiod_chip *chip)

Get the path used to open the chip.

Parameters:

chip – GPIO chip object.

Returns:

Path to the file passed as argument to gpiod_chip_open. The returned pointer is valid for the lifetime of the chip object and must not be freed by the caller.

struct gpiod_line_info *gpiod_chip_get_line_info(struct gpiod_chip *chip, unsigned int offset)

Get a snapshot of information about a line.

Parameters:

  • chip – GPIO chip object.

  • offset – The offset of the GPIO line.

Returns:

New GPIO line info object or NULL if an error occurred. The returned object must be freed by the caller using gpiod_line_info_free.

struct gpiod_line_info *gpiod_chip_watch_line_info(struct gpiod_chip *chip, unsigned int offset)

Get a snapshot of the status of a line and start watching it for future changes.

Note

Line status does not include the line value. To monitor the line value the line must be requested as an input with edge detection set.

Parameters:

  • chip – GPIO chip object.

  • offset – The offset of the GPIO line.

Returns:

New GPIO line info object or NULL if an error occurred. The returned object must be freed by the caller using gpiod_line_info_free.

int gpiod_chip_unwatch_line_info(struct gpiod_chip *chip, unsigned int offset)

Stop watching a line for status changes.

Parameters:

  • chip – GPIO chip object.

  • offset – The offset of the line to stop watching.

Returns:

0 on success, -1 on failure.

int gpiod_chip_get_fd(struct gpiod_chip *chip)

Get the file descriptor associated with the chip.

This function never fails. The returned file descriptor must not be closed by the caller. Call gpiod_chip_close to close the file descriptor by closing the chip owning it.

Parameters:

chip – GPIO chip object.

Returns:

File descriptor number for the chip.

int gpiod_chip_wait_info_event(struct gpiod_chip *chip, int64_t timeout_ns)

Wait for line status change events on any of the watched lines on the chip.

Parameters:

  • chip – GPIO chip object.

  • timeout_ns – Wait time limit in nanoseconds. If set to 0, the function returns immediately. If set to a negative number, the function blocks indefinitely until an event becomes available.

Returns:

0 if wait timed out, -1 if an error occurred, 1 if an event is pending.

struct gpiod_info_event *gpiod_chip_read_info_event(struct gpiod_chip *chip)

Read a single line status change event from the chip.

Note

If no events are pending, this function will block.

Parameters:

chip – GPIO chip object.

Returns:

Newly read watch event object or NULL on error. The event must be freed by the caller using gpiod_info_event_free.

int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip, const char *name)

Map a line’s name to its offset within the chip.

Note

If a line with given name is not exposed by the chip, the function sets errno to ENOENT.

Parameters:

  • chip – GPIO chip object.

  • name – Name of the GPIO line to map.

Returns:

Offset of the line within the chip or -1 on error.

struct gpiod_line_request *gpiod_chip_request_lines(struct gpiod_chip *chip, struct gpiod_request_config *req_cfg, struct gpiod_line_config *line_cfg)

Request a set of lines for exclusive usage.

Parameters:

  • chip – GPIO chip object.

  • req_cfg – Request config object. Can be NULL for default settings.

  • line_cfg – Line config object.

Returns:

New line request object or NULL if an error occurred. The request must be released by the caller using gpiod_line_request_release.