Skip to contentSkip to conversation

core: implement v2.0 API

RFC Superseded Bartosz Golaszewski 2 participants 12 messages May 18, 2021 – Jun 2, 2021

Subsystems (2)

v2 of 3 Superseded Latest is v3 →

lore
Share & tools
lore
#0 lore raw

RFC v2 1/1 core: implement v2.0 API

This is the second shot at the v2.0 C API for libgpiod.

Special thanks go out to Kent for his valuable advice and suggestions.

The biggest changes are:

The concept of attributes has been removed - instead the translation from configuration options to kernel request happens at the time of the line request call and can only fail at this stage - the config mutators no longer return any value.

If the caller has passed a config that is too complicated, the request function will set errno to E2BIG which stands for: "Argument list too long".

The direction and edge options have been split from the former request_type.

The objects are no longer reference counted and no longer can be the responsibility for their lifetime shared.

There are many other minor tweaks everywhere.

One thing I've been contemplating is whether we should expose some functions allowing callers to check if the line config has already become too complex or values passed are invalid. This would allow languages that have exceptions throw them before we actually make the request call. Does this make sense?

This time the new API is in one big patch for easier review. This changeset doesn't modify the bindings or tests but the tools compile and pass all tests.

---
 include/gpiod.h            | 1222 ++++++++++++++++++-----------------
 lib/Makefile.am            |   13 +-
 lib/chip.c                 |  216 +++++++
 lib/core.c                 | 1240 ------------------------------------
 lib/edge-event.c           |  184 ++++++
 lib/helpers.c              |  302 ---------
 lib/info-event.c           |   83 +++
 lib/internal.c             |   58 ++
 lib/internal.h             |   28 +
 lib/line-config.c          |  674 ++++++++++++++++++++
 lib/line-info.c            |  164 +++++
 lib/line-request.c         |  192 ++++++
 lib/misc.c                 |   63 ++
 lib/request-config.c       |   98 +++
 tools/gpio-tools-test.bats |   12 +-
 tools/gpiodetect.c         |   13 +-
 tools/gpiofind.c           |    3 +-
 tools/gpioget.c            |   66 +-
 tools/gpioinfo.c           |   60 +-
 tools/gpiomon.c            |  133 ++--
 tools/gpioset.c            |   75 ++-
 tools/tools-common.c       |    8 +-
 tools/tools-common.h       |    2 +-
 23 files changed, 2607 insertions(+), 2302 deletions(-)
 create mode 100644 lib/chip.c
 delete mode 100644 lib/core.c
 create mode 100644 lib/edge-event.c
 delete mode 100644 lib/helpers.c
 create mode 100644 lib/info-event.c
 create mode 100644 lib/internal.c
 create mode 100644 lib/line-config.c
 create mode 100644 lib/line-info.c
 create mode 100644 lib/line-request.c
 create mode 100644 lib/request-config.c
include/gpiod.h +634 -588
index a4ce01f..bd4689f 100644
@@ -1,12 +1,12 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 /* SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <[email protected]> */
+/* SPDX-FileCopyrightText: 2021 Bartosz Golaszewski <[email protected]> */
 
 #ifndef __LIBGPIOD_GPIOD_H__
 #define __LIBGPIOD_GPIOD_H__
 
 #include <stdbool.h>
-#include <stdlib.h>
-#include <time.h>
+#include <stdint.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -25,220 +25,141 @@ extern "C" {
  * <p>The API is logically split into several parts such as: GPIO chip & line
  * operators, GPIO events handling etc.
  *
- * <p>General note on error handling: all routines exported by libgpiod  set
- * errno to one of the error values defined in errno.h upon failure. The way
- * of notifying the caller that an error occurred varies between functions,
- * but in general a function that returns an int, returns -1 on error, while
- * a function returning a pointer bails out on error condition by returning
- * a NULL pointer.
- */
-
-struct gpiod_chip;
-struct gpiod_line;
-struct gpiod_line_bulk;
-
-/**
- * @defgroup common Common helper macros
- * @{
+ * <p>General note on error handling: all routines exported by libgpiod that
+ * can fail, set errno to one of the error values defined in errno.h upon
+ * failure. The way of notifying the caller that an error occurred varies
+ * between functions, but in general a function that returns an int, returns -1
+ * on error, while a function returning a pointer indicates an error condition
+ * by returning a NULL pointer.
  *
- * Commonly used utility macros.
+ * <p>In general libgpiod functions are not NULL-aware and it's expected that
+ * users pass valid pointers to objects as arguments.
  */
 
-/**
- * @brief Shift 1 by given offset.
- * @param nr Bit position.
- * @return 1 shifted by nr.
- */
-#define GPIOD_BIT(nr)		(1UL << (nr))
+struct gpiod_chip;
+struct gpiod_line_info;
+struct gpiod_line_config;
+struct gpiod_request_config;
+struct gpiod_line_request;
+struct gpiod_info_event;
+struct gpiod_edge_event;
+struct gpiod_edge_event_buffer;
 
 /**
- * @}
- *
- * @defgroup chips GPIO chip operations
+ * @defgroup chips GPIO chips
  * @{
  *
- * Functions and data structures dealing with GPIO chips.
- */
-
-/**
- * @brief Check if the file pointed to by path is a GPIO chip character device.
- * @param path Path to check.
- * @return True if the file exists and is a GPIO chip character device or a
- *         symbolic link to it.
+ * Functions and data structures for manipulating GPIO chips.
  */
-bool gpiod_is_gpiochip_device(const char *path);
 
 /**
- * @brief Open a gpiochip by path.
+ * @brief Open a GPIO chip by path.
  * @param path Path to the gpiochip device file.
- * @return GPIO chip handle or NULL if an error occurred.
+ * @return GPIO chip request or NULL if an error occurred.
  */
 struct gpiod_chip *gpiod_chip_open(const char *path);
 
 /**
- * @brief Increase the refcount on this GPIO object.
- * @param chip The GPIO chip object.
- * @return Passed reference to the GPIO chip.
+ * @brief Close a GPIO chip and release all associated resources.
+ * @param chip Chip to close.
  */
-struct gpiod_chip *gpiod_chip_ref(struct gpiod_chip *chip);
-
-/**
- * @brief Decrease the refcount on this GPIO object. If the refcount reaches 0,
- *        close the chip device and free all associated resources.
- * @param chip The GPIO chip object.
- */
-void gpiod_chip_unref(struct gpiod_chip *chip);
+void gpiod_chip_close(struct gpiod_chip *chip);
 
 /**
  * @brief Get the GPIO chip name as represented in the kernel.
- * @param chip The GPIO chip object.
+ * @param chip GPIO chip object.
  * @return Pointer to a human-readable string containing the chip name.
  */
 const char *gpiod_chip_get_name(struct gpiod_chip *chip);
 
 /**
  * @brief Get the GPIO chip label as represented in the kernel.
- * @param chip The GPIO chip object.
+ * @param chip GPIO chip object.
  * @return Pointer to a human-readable string containing the chip label.
  */
 const char *gpiod_chip_get_label(struct gpiod_chip *chip);
 
 /**
  * @brief Get the number of GPIO lines exposed by this chip.
- * @param chip The GPIO chip object.
+ * @param chip GPIO chip object.
  * @return Number of GPIO lines.
  */
 unsigned int gpiod_chip_get_num_lines(struct gpiod_chip *chip);
 
 /**
- * @brief Get the handle to the GPIO line at given offset.
- * @param chip The GPIO chip object.
+ * @brief Get the current snapshot of information about the line at given
+ *        offset.
+ * @param chip GPIO chip object.
  * @param offset The offset of the GPIO line.
- * @return Pointer to the GPIO line handle or NULL if an error occured.
- */
-struct gpiod_line *
-gpiod_chip_get_line(struct gpiod_chip *chip, unsigned int offset);
-
-/**
- * @brief Retrieve a set of lines and store them in a line bulk object.
- * @param chip The GPIO chip object.
- * @param offsets Array of offsets of lines to retrieve.
- * @param num_offsets Number of lines to retrieve.
- * @return New line bulk object or NULL on error.
+ * @return New GPIO line info object or NULL if an error occurred.
  */
-struct gpiod_line_bulk *
-gpiod_chip_get_lines(struct gpiod_chip *chip, unsigned int *offsets,
-		     unsigned int num_offsets);
+struct gpiod_line_info *gpiod_chip_get_line_info(struct gpiod_chip *chip,
+						 unsigned int offset);
 
 /**
- * @brief Retrieve all lines exposed by a chip and store them in a bulk object.
- * @param chip The GPIO chip object.
- * @return New line bulk object or NULL on error.
- */
-struct gpiod_line_bulk *
-gpiod_chip_get_all_lines(struct gpiod_chip *chip);
-
-/**
- * @brief Map a GPIO line's name to its offset within the chip.
- * @param chip The GPIO chip object.
- * @param name Name of the GPIO line to map.
- * @return Offset of the line within the chip or -1 if a line with given name
- *         is not exposed by the chip.
- */
-int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name);
-
-/**
- * @}
- *
- * @defgroup lines GPIO line operations
- * @{
- *
- * Functions and data structures dealing with GPIO lines.
- *
- * @defgroup line_bulk Operating on multiple lines
- * @{
- *
- * Convenience data structures and helper functions for storing and operating
- * on multiple lines at once.
- */
-
-/**
- * @brief Allocate and initialize a new line bulk object.
- * @param max_lines Maximum number of lines this object can hold.
- * @return New line bulk object or NULL on error.
- */
-struct gpiod_line_bulk *gpiod_line_bulk_new(unsigned int max_lines);
-
-/**
- * @brief Reset a bulk object. Remove all lines and set size to 0.
- * @param bulk Bulk object to reset.
- */
-void gpiod_line_bulk_reset(struct gpiod_line_bulk *bulk);
-
-/**
- * @brief Release all resources allocated for this bulk object.
- * @param bulk Bulk object to free.
+ * @brief Get the current snapshot of information about the line at given
+ *        offset and start watching it for future changes.
+ * @param chip GPIO chip object.
+ * @param offset The offset of the GPIO line.
+ * @return New GPIO line info object or NULL if an error occurred.
  */
-void gpiod_line_bulk_free(struct gpiod_line_bulk *bulk);
+struct gpiod_line_info *gpiod_chip_watch_line_info(struct gpiod_chip *chip,
+						   unsigned int offset);
 
 /**
- * @brief Add a single line to a GPIO bulk object.
- * @param bulk Line bulk object.
- * @param line Line to add.
- * @return 0 on success, -1 on error.
- * @note The line is added at the next free bulk index.
- *
- * The function can fail if this bulk already holds its maximum amount of
- * lines or if the added line is associated with a different chip than all
- * the other lines already held by this object.
+ * @brief Stop watching the line at given offset for status changes.
+ * @param chip GPIO chip object.
+ * @param offset The offset of the GPIO line.
+ * @return 0 on success, -1 on failure.
  */
-int gpiod_line_bulk_add_line(struct gpiod_line_bulk *bulk,
-			     struct gpiod_line *line);
+int gpiod_chip_unwatch_line_info(struct gpiod_chip *chip, unsigned int offset);
 
 /**
- * @brief Retrieve the line handle from a line bulk object at given index.
- * @param bulk Line bulk object.
- * @param index Index of the line to retrieve.
- * @return Line handle at given index or NULL if index is greater or equal to
- *         the number of lines this bulk can hold.
+ * @brief Get the file descriptor associated with this chip.
+ * @param chip GPIO chip object.
+ * @return File descriptor number. This function never fails.
  */
-struct gpiod_line *
-gpiod_line_bulk_get_line(struct gpiod_line_bulk *bulk, unsigned int index);
+int gpiod_chip_get_fd(struct gpiod_chip *chip);
 
 /**
- * @brief Retrieve the number of GPIO lines held by this line bulk object.
- * @param bulk Line bulk object.
- * @return Number of lines held by this line bulk.
+ * @brief Wait for line status events on any of the lines associated with
+ *        this chip.
+ * @param chip GPIO chip object.
+ * @param timeout Wait time limit in nanoseconds.
+ * @return 0 if wait timed out, -1 if an error occurred, 1 if an event is
+ *         pending.
  */
-unsigned int gpiod_line_bulk_num_lines(struct gpiod_line_bulk *bulk);
+int gpiod_chip_info_event_wait(struct gpiod_chip *chip, uint64_t timeout);
 
 /**
- * @brief Values returned by the callback passed to
- *        ::gpiod_line_bulk_foreach_line.
+ * @brief Read a single line status change event from this chip.
+ * @param chip GPIO chip object.
+ * @return Newly read watch event object or NULL on error.
+ * @note If no events are pending, this function will block.
  */
-enum {
-	/**< Continue the loop. */
-	GPIOD_LINE_BULK_CB_NEXT = 0,
-	/**< Stop the loop. */
-	GPIOD_LINE_BULK_CB_STOP,
-};
+struct gpiod_info_event *gpiod_chip_info_event_read(struct gpiod_chip *chip);
 
 /**
- * @brief Signature of the callback passed to ::gpiod_line_bulk_foreach_line.
- *
- * Takes the current line and additional user data as arguments.
+ * @brief Map a GPIO line's name to its offset within the chip.
+ * @param chip GPIO chip object.
+ * @param name Name of the GPIO line to map.
+ * @return Offset of the line within the chip or -1 on error.
+ * @note If a line with given name is not exposed by the chip, the function
+ *       sets errno to ENOENT.
  */
-typedef int (*gpiod_line_bulk_foreach_cb)(struct gpiod_line *, void *);
+int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name);
 
 /**
- * @brief Iterate over all lines held by this bulk object.
- * @param bulk Bulk object to iterate over.
- * @param func Callback to be called for each line.
- * @param data User data pointer that is passed to the callback.
+ * @brief Request a set of lines for exclusive usage.
+ * @param chip GPIO chip object.
+ * @param req_cfg Request config object.
+ * @param line_cfg Line config object.
+ * @return New line request object or NULL if an error occurred.
  */
-void gpiod_line_bulk_foreach_line(struct gpiod_line_bulk *bulk,
-				  gpiod_line_bulk_foreach_cb func,
-				  void *data);
+struct gpiod_line_request *
+gpiod_chip_request_lines(struct gpiod_chip *chip,
+			 struct gpiod_request_config *req_cfg,
+			 struct gpiod_line_config *line_cfg);
 
 /**
  * @}
@@ -287,551 +208,655 @@ enum {
 };
 
 /**
- * @brief Read the GPIO line offset.
- * @param line GPIO line object.
- * @return Line offset.
+ * @brief Possible edge detection settings.
  */
-unsigned int gpiod_line_offset(struct gpiod_line *line);
+enum {
+	GPIOD_LINE_EDGE_NONE = 1,
+	/**< Line edge detection is disabled. */
+	GPIOD_LINE_EDGE_RISING,
+	/**< Line detects rising edge events. */
+	GPIOD_LINE_EDGE_FALLING,
+	/**< Line detect falling edge events. */
+	GPIOD_LINE_EDGE_BOTH,
+	/**< Line detects both rising and falling edge events. */
+};
+
+/**
+ * @brief Free a line info object and release all associated resources.
+ * @param info GPIO line info object to free.
+ */
+void gpiod_line_info_free(struct gpiod_line_info *info);
+
+/**
+ * @brief Get the hardware offset of the line.
+ * @param info GPIO line info object.
+ * @return Offset of the line within the parent chip.
+ */
+unsigned int gpiod_line_info_get_offset(struct gpiod_line_info *info);
 
 /**
  * @brief Read the GPIO line name.
- * @param line GPIO line object.
+ * @param info GPIO line info object.
  * @return 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.
  */
-const char *gpiod_line_name(struct gpiod_line *line);
+const char *gpiod_line_info_get_name(struct gpiod_line_info *info);
+
+/**
+ * @brief Check if the line is currently in use.
+ * @param info GPIO line object.
+ * @return True if the line is in use, false otherwise.
+ *
+ * The user space can't know exactly why a line is busy. It may have been
+ * requested by another process or hogged by the kernel. It only matters that
+ * the line is used and we can't request it.
+ */
+bool gpiod_line_info_is_used(struct gpiod_line_info *info);
 
 /**
  * @brief Read the GPIO line consumer name.
- * @param line GPIO line object.
+ * @param info GPIO line info object.
  * @return 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.
  */
-const char *gpiod_line_consumer(struct gpiod_line *line);
+const char *gpiod_line_info_get_consumer(struct gpiod_line_info *info);
 
 /**
  * @brief Read the GPIO line direction setting.
- * @param line GPIO line object.
+ * @param info GPIO line info object.
  * @return Returns GPIOD_LINE_DIRECTION_INPUT or GPIOD_LINE_DIRECTION_OUTPUT.
  */
-int gpiod_line_direction(struct gpiod_line *line);
+int gpiod_line_info_get_direction(struct gpiod_line_info *info);
 
 /**
  * @brief Check if the signal of this line is inverted.
- * @param line GPIO line object.
+ * @param info GPIO line object.
  * @return True if this line is "active-low", false otherwise.
  */
-bool gpiod_line_is_active_low(struct gpiod_line *line);
+bool gpiod_line_info_is_active_low(struct gpiod_line_info *info);
 
 /**
  * @brief Read the GPIO line bias setting.
- * @param line GPIO line object.
+ * @param info GPIO line object.
  * @return Returns GPIOD_LINE_BIAS_PULL_UP, GPIOD_LINE_BIAS_PULL_DOWN,
  *         GPIOD_LINE_BIAS_DISABLE or GPIOD_LINE_BIAS_UNKNOWN.
  */
-int gpiod_line_bias(struct gpiod_line *line);
+int gpiod_line_info_get_bias(struct gpiod_line_info *info);
 
 /**
- * @brief Check if the line is currently in use.
- * @param line GPIO line object.
- * @return True if the line is in use, false otherwise.
+ * @brief Read the GPIO line drive setting.
+ * @param info GPIO line info object.
+ * @return Returns GPIOD_LINE_DRIVE_PUSH_PULL, GPIOD_LINE_DRIVE_OPEN_DRAIN or
+ *         GPIOD_LINE_DRIVE_OPEN_SOURCE.
+ */
+int gpiod_line_info_get_drive(struct gpiod_line_info *info);
+
+/**
+ * @brief Read the current edge detection setting of this line.
+ * @param info GPIO line info object.
+ * @return Returns GPIOD_LINE_EDGE_NONE, GPIOD_LINE_EDGE_RISING,
+ *         GPIOD_LINE_EDGE_FALLING or GPIOD_LINE_EDGE_BOTH.
+ */
+int gpiod_line_info_get_edge_detection(struct gpiod_line_info *info);
+
+/**
+ * @brief Check if this line is debounced (either by hardware or by the kernel
+ *        software debouncer).
+ * @param info GPIO line info object.
+ * @return True if the line is debounced, false otherwise.
+ */
+bool gpiod_line_info_is_debounced(struct gpiod_line_info *info);
+
+/**
+ * @brief Read the current debounce period in microseconds.
+ * @param info GPIO line info object.
+ * @return Current debounce period in microseconds, 0 if the line is not
+ *         debounced.
+ */
+unsigned long
+gpiod_line_info_get_debounce_period(struct gpiod_line_info *info);
+
+/**
+ * @}
  *
- * The user space can't know exactly why a line is busy. It may have been
- * requested by another process or hogged by the kernel. It only matters that
- * the line is used and we can't request it.
+ * @defgroup line_watch Line status watch events
+ * @{
+ *
+ * Accessors for the info event objects allowing to monitor changes in GPIO
+ * line state.
  */
-bool gpiod_line_is_used(struct gpiod_line *line);
 
 /**
- * @brief Read the GPIO line drive setting.
- * @param line GPIO line object.
- * @return Returns GPIOD_LINE_DRIVE_PUSH_PULL, GPIOD_LINE_DRIVE_OPEN_DRAIN or
- *         GPIOD_LINE_DRIVE_OPEN_SOURCE.
+ * @brief Possible line status change event types.
+ */
+enum {
+	GPIOD_INFO_EVENT_LINE_REQUESTED = 1,
+	/**< Line has been requested. */
+	GPIOD_INFO_EVENT_LINE_RELEASED,
+	/**< Previously requested line has been released. */
+	GPIOD_INFO_EVENT_LINE_CONFIG_CHANGED,
+	/**< Line configuration has changed. */
+};
+
+/**
+ * @brief Free the info event object and release all associated resources.
+ * @param event Info event to free.
+ */
+void gpiod_info_event_free(struct gpiod_info_event *event);
+
+/**
+ * @brief Get the event type of this status change event.
+ * @param event Line status watch event.
+ * @return One of ::GPIOD_INFO_EVENT_LINE_REQUESTED,
+ *         ::GPIOD_INFO_EVENT_LINE_RELEASED or
+ *         ::GPIOD_INFO_EVENT_LINE_CONFIG_CHANGED.
+ */
+int gpiod_info_event_get_event_type(struct gpiod_info_event *event);
+
+/**
+ * @brief Get the timestamp of the event.
+ * @param event Line status watch event.
+ * @return Timestamp in nanoseconds.
  */
-int gpiod_line_drive(struct gpiod_line *line);
+uint64_t gpiod_info_event_get_timestamp(struct gpiod_info_event *event);
 
 /**
- * @brief Get the handle to the GPIO chip controlling this line.
- * @param line The GPIO line object.
- * @return Pointer to the GPIO chip handle controlling this line.
+ * @brief Get the pointer to the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a pointer to the line-info object associated with this event
+ *         whose lifetime is tied to the event object. It must not be freed by
+ *         the caller.
  */
-struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line);
+struct gpiod_line_info *
+gpiod_info_event_peek_line_info(struct gpiod_info_event *event);
+
+/**
+ * @brief Get a copy of the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a copy of the line-info object associated with this event or
+ *         NULL on error. The lifetime of the returned object must be managed
+ *         by the caller and the line-info object must be freed using
+ *         ::gpiod_line_info_free.
+ */
+struct gpiod_line_info *
+gpiod_info_event_copy_line_info(struct gpiod_info_event *event);
 
 /**
  * @}
  *
- * @defgroup line_request Line requests
+ * @defgroup line_config Line configuration objects
  * @{
  *
- * Interface for requesting GPIO lines from userspace for both values and
- * events.
+ * Functions for manipulating line configuration objects.
  */
 
 /**
- * @brief Available types of requests.
+ * @brief Available direction settings.
  */
 enum {
-	GPIOD_LINE_REQUEST_DIRECTION_AS_IS = 1,
+	GPIOD_LINE_CONFIG_DIRECTION_AS_IS = 1,
 	/**< Request the line(s), but don't change current direction. */
-	GPIOD_LINE_REQUEST_DIRECTION_INPUT,
+	GPIOD_LINE_CONFIG_DIRECTION_INPUT,
 	/**< Request the line(s) for reading the GPIO line state. */
-	GPIOD_LINE_REQUEST_DIRECTION_OUTPUT,
+	GPIOD_LINE_CONFIG_DIRECTION_OUTPUT,
 	/**< Request the line(s) for setting the GPIO line state. */
-	GPIOD_LINE_REQUEST_EVENT_FALLING_EDGE,
+};
+
+/**
+ * @brief Available drive settings for line requests.
+ */
+enum {
+	GPIOD_LINE_CONFIG_DRIVE_PUSH_PULL = 1,
+	/**< Drive setting should be set to push-pull (the default). */
+	GPIOD_LINE_CONFIG_DRIVE_OPEN_DRAIN,
+	/**< Line output should be set to open-drain. */
+	GPIOD_LINE_CONFIG_DRIVE_OPEN_SOURCE,
+	/**< Line output should be set to open-source. */
+};
+
+/**
+ * @brief Available internal bias settings for line requests.
+ */
+enum {
+	GPIOD_LINE_CONFIG_BIAS_DISABLED = 1,
+	/**< The internal bias should be disabled (the default). */
+	GPIOD_LINE_CONFIG_BIAS_PULL_UP,
+	/**< The internal pull-up bias is enabled. */
+	GPIOD_LINE_CONFIG_BIAS_PULL_DOWN,
+	/**< The internal pull-down bias is enabled. */
+};
+
+/**
+ * @brief Available edge event detection settings.
+ */
+enum {
+	GPIOD_LINE_CONFIG_EDGE_FALLING = 1,
 	/**< Only watch falling edge events. */
-	GPIOD_LINE_REQUEST_EVENT_RISING_EDGE,
+	GPIOD_LINE_CONFIG_EDGE_RISING,
 	/**< Only watch rising edge events. */
-	GPIOD_LINE_REQUEST_EVENT_BOTH_EDGES,
+	GPIOD_LINE_CONFIG_EDGE_BOTH,
 	/**< Monitor both types of events. */
 };
 
 /**
- * @brief Miscellaneous GPIO request flags.
+ * @brief Available clock types used for event timestamps.
  */
 enum {
-	GPIOD_LINE_REQUEST_FLAG_OPEN_DRAIN	= GPIOD_BIT(0),
-	/**< The line is an open-drain port. */
-	GPIOD_LINE_REQUEST_FLAG_OPEN_SOURCE	= GPIOD_BIT(1),
-	/**< The line is an open-source port. */
-	GPIOD_LINE_REQUEST_FLAG_ACTIVE_LOW	= GPIOD_BIT(2),
-	/**< The active state of the line is low (high is the default). */
-	GPIOD_LINE_REQUEST_FLAG_BIAS_DISABLED	= GPIOD_BIT(3),
-	/**< The line has neither either pull-up nor pull-down resistor. */
-	GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_DOWN	= GPIOD_BIT(4),
-	/**< The line has pull-down resistor enabled. */
-	GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP	= GPIOD_BIT(5),
-	/**< The line has pull-up resistor enabled. */
+	GPIOD_LINE_CONFIG_CLOCK_MONOTONIC = 1,
+	/**< Use the monotonic clock. */
+	GPIOD_LINE_CONFIG_CLOCK_REALTIME,
+	/**< Use the realtime clock. */
 };
 
 /**
- * @brief Structure holding configuration of a line request.
+ * @brief Create a new line config object.
+ * @return New line config object or NULL on error.
  */
-struct gpiod_line_request_config {
-	const char *consumer;
-	/**< Name of the consumer. */
-	int request_type;
-	/**< Request type. */
-	int flags;
-	/**< Other configuration flags. */
-};
+struct gpiod_line_config *gpiod_line_config_new(void);
 
 /**
- * @brief Reserve a single line.
- * @param line GPIO line object.
- * @param config Request options.
- * @param default_val Initial line value - only relevant if we're setting
- *                    the direction to output.
- * @return 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.
+ * @brief Free the line config object and release all associated resources.
+ * @param config Line config object to free.
  */
-int gpiod_line_request(struct gpiod_line *line,
-		       const struct gpiod_line_request_config *config,
-		       int default_val);
+void gpiod_line_config_free(struct gpiod_line_config *config);
 
 /**
- * @brief Reserve a single line, set the direction to input.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @return 0 if the line was properly reserved, -1 on failure.
+ * @brief Set the direction of all lines.
+ * @param config Line config object.
+ * @param direction New direction.
  */
-int gpiod_line_request_input(struct gpiod_line *line, const char *consumer);
+void gpiod_line_config_set_direction(struct gpiod_line_config *config,
+				     int direction);
 
 /**
- * @brief Reserve a single line, set the direction to output.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @param default_val Initial line value.
- * @return 0 if the line was properly reserved, -1 on failure.
+ * @brief Set the direction for a single line at given offset.
+ * @param config Line config object.
+ * @param direction New direction.
+ * @param offset Offset of the line for which to set the direction.
  */
-int gpiod_line_request_output(struct gpiod_line *line,
-			      const char *consumer, int default_val);
+void gpiod_line_config_set_direction_offset(struct gpiod_line_config *config,
+					    int direction, unsigned int offset);
 
 /**
- * @brief Request rising edge event notifications on a single line.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the direction for a subset of lines.
+ * @param config Line config object.
+ * @param direction New direction.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the direction.
  */
-int gpiod_line_request_rising_edge_events(struct gpiod_line *line,
-					  const char *consumer);
+void gpiod_line_config_set_direction_subset(struct gpiod_line_config *config,
+					    int direction,
+					    unsigned int num_offsets,
+					    const unsigned int *offsets);
 
 /**
- * @brief Request falling edge event notifications on a single line.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the edge event detection for all lines.
+ * @param config Line config object.
+ * @param edge Type of edge events to detect.
  */
-int gpiod_line_request_falling_edge_events(struct gpiod_line *line,
-					   const char *consumer);
+void gpiod_line_config_set_edge_detection(struct gpiod_line_config *config,
+					  int edge);
 
 /**
- * @brief Request all event type notifications on a single line.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the edge event detection for a single line at given offset.
+ * @param config Line config object.
+ * @param edge Type of edge events to detect.
+ * @param offset Offset of the line for which to set the edge detection.
  */
-int gpiod_line_request_both_edges_events(struct gpiod_line *line,
-					 const char *consumer);
+void
+gpiod_line_config_set_edge_detection_offset(struct gpiod_line_config *config,
+					    int edge, unsigned int offset);
 
 /**
- * @brief Reserve a single line, set the direction to input.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the line was properly reserved, -1 on failure.
+ * @brief Set the edge event detection for a subset of lines.
+ * @param config Line config object.
+ * @param edge Type of edge events to detect.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the edge detection.
  */
-int gpiod_line_request_input_flags(struct gpiod_line *line,
-				   const char *consumer, int flags);
+void
+gpiod_line_config_set_edge_detection_subset(struct gpiod_line_config *config,
+					    int edge, unsigned int num_offsets,
+					    const unsigned int *offsets);
 
 /**
- * @brief Reserve a single line, set the direction to output.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @param default_val Initial line value.
- * @return 0 if the line was properly reserved, -1 on failure.
+ * @brief Set the drive of all lines.
+ * @param config Line config object.
+ * @param drive New drive.
  */
-int gpiod_line_request_output_flags(struct gpiod_line *line,
-				    const char *consumer, int flags,
-				    int default_val);
+void gpiod_line_config_set_drive(struct gpiod_line_config *config, int drive);
 
 /**
- * @brief Request rising edge event notifications on a single line.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the drive for a single line at given offset.
+ * @param config Line config object.
+ * @param drive New drive.
+ * @param offset Offset of the line for which to set the drive.
  */
-int gpiod_line_request_rising_edge_events_flags(struct gpiod_line *line,
-						const char *consumer,
-						int flags);
+void gpiod_line_config_set_drive_offset(struct gpiod_line_config *config,
+					int drive, unsigned int offset);
 
 /**
- * @brief Request falling edge event notifications on a single line.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the drive for a subset of lines.
+ * @param config Line config object.
+ * @param drive New drive.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the drive.
  */
-int gpiod_line_request_falling_edge_events_flags(struct gpiod_line *line,
-						 const char *consumer,
-						 int flags);
+void gpiod_line_config_set_drive_subset(struct gpiod_line_config *config,
+					int drive, unsigned int num_offsets,
+					const unsigned int *offsets);
 
 /**
- * @brief Request all event type notifications on a single line.
- * @param line GPIO line object.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the bias of all lines.
+ * @param config Line config object.
+ * @param bias New bias.
  */
-int gpiod_line_request_both_edges_events_flags(struct gpiod_line *line,
-					       const char *consumer,
-					       int flags);
+void gpiod_line_config_set_bias(struct gpiod_line_config *config, int bias);
 
 /**
- * @brief Reserve a set of GPIO lines.
- * @param bulk Set of GPIO lines to reserve.
- * @param config Request options.
- * @param default_vals Initial line values - only relevant if we're setting
- *                     the direction to output.
- * @return 0 if 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 provided by the
- * same gpiochip.
+ * @brief Set the bias for a single line at given offset.
+ * @param config Line config object.
+ * @param bias New bias.
+ * @param offset Offset of the line for which to set the bias.
  */
-int gpiod_line_request_bulk(struct gpiod_line_bulk *bulk,
-			    const struct gpiod_line_request_config *config,
-			    const int *default_vals);
+void gpiod_line_config_set_bias_offset(struct gpiod_line_config *config,
+				       int bias, unsigned int offset);
 
 /**
- * @brief Reserve a set of GPIO lines, set the direction to input.
- * @param bulk Set of GPIO lines to reserve.
- * @param consumer Name of the consumer.
- * @return 0 if the lines were properly reserved, -1 on failure.
+ * @brief Set the bias for a subset of lines.
+ * @param config Line config object.
+ * @param bias New bias.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the bias.
  */
-int gpiod_line_request_bulk_input(struct gpiod_line_bulk *bulk,
-				  const char *consumer);
+void gpiod_line_config_set_bias_subset(struct gpiod_line_config *config,
+				       int bias, unsigned int num_offsets,
+				       const unsigned int *offsets);
 
 /**
- * @brief Reserve a set of GPIO lines, set the direction to output.
- * @param bulk Set of GPIO lines to reserve.
- * @param consumer Name of the consumer.
- * @param default_vals Initial line values.
- * @return 0 if the lines were properly reserved, -1 on failure.
+ * @brief Set all lines as active-low.
+ * @param config Line config object.
  */
-int gpiod_line_request_bulk_output(struct gpiod_line_bulk *bulk,
-				   const char *consumer,
-				   const int *default_vals);
+void gpiod_line_config_set_active_low(struct gpiod_line_config *config);
 
 /**
- * @brief Request rising edge event notifications on a set of lines.
- * @param bulk Set of GPIO lines to request.
- * @param consumer Name of the consumer.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set a single line as active-low.
+ * @param config Line config object.
+ * @param offset Offset of the line for which to set the active setting.
  */
-int gpiod_line_request_bulk_rising_edge_events(struct gpiod_line_bulk *bulk,
-					       const char *consumer);
+void gpiod_line_config_set_active_low_offset(struct gpiod_line_config *config,
+					     unsigned int offset);
 
 /**
- * @brief Request falling edge event notifications on a set of lines.
- * @param bulk Set of GPIO lines to request.
- * @param consumer Name of the consumer.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set a subset of lines as active-low.
+ * @param config Line config object.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the active setting.
  */
-int gpiod_line_request_bulk_falling_edge_events(struct gpiod_line_bulk *bulk,
-						const char *consumer);
+void gpiod_line_config_set_active_low_subset(struct gpiod_line_config *config,
+					     unsigned int num_offsets,
+					     const unsigned int *offsets);
 
 /**
- * @brief Request all event type notifications on a set of lines.
- * @param bulk Set of GPIO lines to request.
- * @param consumer Name of the consumer.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set all lines as active-high.
+ * @param config Line config object.
  */
-int gpiod_line_request_bulk_both_edges_events(struct gpiod_line_bulk *bulk,
-					      const char *consumer);
+void gpiod_line_config_set_active_high(struct gpiod_line_config *config);
 
 /**
- * @brief Reserve a set of GPIO lines, set the direction to input.
- * @param bulk Set of GPIO lines to reserve.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the lines were properly reserved, -1 on failure.
+ * @brief Set a single line as active-high.
+ * @param config Line config object.
+ * @param offset Offset of the line for which to set the active setting.
  */
-int gpiod_line_request_bulk_input_flags(struct gpiod_line_bulk *bulk,
-					const char *consumer, int flags);
+void gpiod_line_config_set_active_high_offset(struct gpiod_line_config *config,
+					      unsigned int offset);
 
 /**
- * @brief Reserve a set of GPIO lines, set the direction to output.
- * @param bulk Set of GPIO lines to reserve.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @param default_vals Initial line values.
- * @return 0 if the lines were properly reserved, -1 on failure.
+ * @brief Set a subset of lines as active-high.
+ * @param config Line config object.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the active setting.
  */
-int gpiod_line_request_bulk_output_flags(struct gpiod_line_bulk *bulk,
-					 const char *consumer, int flags,
-					 const int *default_vals);
+void gpiod_line_config_set_active_high_subset(struct gpiod_line_config *config,
+					      unsigned int num_offsets,
+					      const unsigned int *offsets);
 
 /**
- * @brief Request rising edge event notifications on a set of lines.
- * @param bulk Set of GPIO lines to request.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the debounce period for all lines.
+ * @param config Line config object.
+ * @param period New debounce period. Disables debouncing if 0.
  */
-int gpiod_line_request_bulk_rising_edge_events_flags(
-					struct gpiod_line_bulk *bulk,
-					const char *consumer, int flags);
+void gpiod_line_config_set_debounce_period(struct gpiod_line_config *config,
+					   unsigned int period);
 
 /**
- * @brief Request falling edge event notifications on a set of lines.
- * @param bulk Set of GPIO lines to request.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the debounce period for a single line at given offset.
+ * @param config Line config object.
+ * @param period New debounce period. Disables debouncing if 0.
+ * @param offset Offset of the line for which to set the debounce period.
  */
-int gpiod_line_request_bulk_falling_edge_events_flags(
-					struct gpiod_line_bulk *bulk,
-					const char *consumer, int flags);
+void
+gpiod_line_config_set_debounce_period_offset(struct gpiod_line_config *config,
+					     unsigned int period,
+					     unsigned int offset);
 
 /**
- * @brief Request all event type notifications on a set of lines.
- * @param bulk Set of GPIO lines to request.
- * @param consumer Name of the consumer.
- * @param flags Additional request flags.
- * @return 0 if the operation succeeds, -1 on failure.
+ * @brief Set the debounce period for a subset of lines.
+ * @param config Line config object.
+ * @param period New debounce period. Disables debouncing if 0.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the debounce period.
  */
-int gpiod_line_request_bulk_both_edges_events_flags(
-					struct gpiod_line_bulk *bulk,
-					const char *consumer, int flags);
+void
+gpiod_line_config_set_debounce_period_subset(struct gpiod_line_config *config,
+					     unsigned int period,
+					     unsigned int num_offsets,
+					     const unsigned int *offsets);
 
 /**
- * @brief Release a previously reserved line.
- * @param line GPIO line object.
+ * @brief Set the event timestamp clock for all lines.
+ * @param config Line config object.
+ * @param clock New clock to use.
  */
-void gpiod_line_release(struct gpiod_line *line);
+void gpiod_line_config_set_event_clock(struct gpiod_line_config *config,
+				       int clock);
 
 /**
- * @brief Release a set of previously reserved lines.
- * @param bulk Set of GPIO lines to release.
- *
- * If the lines were not previously requested together, the behavior is
- * undefined.
+ * @brief Set the event clock for a single line at given offset.
+ * @param config Line config object.
+ * @param clock New event clock to use.
+ * @param offset Offset of the line for which to set the event clock type.
  */
-void gpiod_line_release_bulk(struct gpiod_line_bulk *bulk);
+void gpiod_line_config_set_event_clock_offset(struct gpiod_line_config *config,
+					      int clock, unsigned int offset);
+
+/**
+ * @brief Set the event clock for a subset of lines.
+ * @param config Line config object.
+ * @param clock New event clock to use.
+ * @param num_offsets Number of offsets in the array.
+ * @param offsets Array of line offsets for which to set the event clock type.
+ */
+void gpiod_line_config_set_event_clock_subset(struct gpiod_line_config *config,
+					      int clock,
+					      unsigned int num_offsets,
+					      const unsigned int *offsets);
+
+/**
+ * @brief Set the output value for a single offset.
+ * @param config Line config object.
+ * @param offset Offset of the line.
+ * @param value Output value to set.
+ */
+void gpiod_line_config_set_output_value(struct gpiod_line_config *config,
+					unsigned int offset, int value);
+
+/**
+ * @brief Set the output values for a set of offsets.
+ * @param config Line config object.
+ * @param num_offsets Number of offsets for which to set values.
+ * @param offsets Array of line offsets to set values for.
+ * @param values Array of output values associated with the offsets passed in
+ *               the previous argument.
+ */
+void gpiod_line_config_set_output_values(struct gpiod_line_config *config,
+					 unsigned int num_offsets,
+					 const unsigned int *offsets,
+					 const int *values);
 
 /**
  * @}
  *
- * @defgroup line_value Reading & setting line values
+ * @defgroup request_config Request configuration objects
  * @{
  *
- * Functions allowing to read and set GPIO line values for single lines and
- * in bulk.
+ * Functions for manipulating request configuration objects.
  */
 
 /**
- * @brief Read current value of a single GPIO line.
- * @param line GPIO line object.
- * @return 0 or 1 if the operation succeeds. On error this routine returns -1
- *         and sets the last error number.
+ * @brief Create a new request config object.
+ * @return New request config object or NULL on error.
  */
-int gpiod_line_get_value(struct gpiod_line *line);
+struct gpiod_request_config *gpiod_request_config_new(void);
 
 /**
- * @brief Read current values of a set of GPIO lines.
- * @param bulk Set of GPIO lines to reserve.
- * @param values An array big enough to hold line_bulk->num_lines values.
- * @return 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.
+ * @brief Free the request config object and release all associated resources.
+ * @param config Line config object.
  */
-int gpiod_line_get_value_bulk(struct gpiod_line_bulk *bulk, int *values);
+void gpiod_request_config_free(struct gpiod_request_config *config);
 
 /**
- * @brief Set the value of a single GPIO line.
- * @param line GPIO line object.
- * @param value New value.
- * @return 0 is the operation succeeds. In case of an error this routine
- *         returns -1 and sets the last error number.
+ * @brief Set the consumer string.
+ * @param config Request config object.
+ * @param consumer Consumer name.
+ * @return 0 on success, -1 on failure.
  */
-int gpiod_line_set_value(struct gpiod_line *line, int value);
+int gpiod_request_config_set_consumer(struct gpiod_request_config *config,
+				      const char *consumer);
 
 /**
- * @brief Set the values of a set of GPIO lines.
- * @param bulk Set of GPIO lines to reserve.
- * @param values An array holding line_bulk->num_lines new values for lines.
- *               A NULL pointer is interpreted as a logical low for all lines.
- * @return 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.
+ * @brief Set line offsets for this request.
+ * @param config Request config object.
+ * @param num_offsets Number of offsets.
+ * @param offsets Array of line offsets.
+ * @return 0 on success, -1 on failure.
  */
-int gpiod_line_set_value_bulk(struct gpiod_line_bulk *bulk, const int *values);
+int gpiod_request_config_set_offsets(struct gpiod_request_config *config,
+				     unsigned int num_offsets,
+				     unsigned int *offsets);
+
+/**
+ * @brief Set the size of the kernel event buffer.
+ * @param config Request config object.
+ * @param event_buffer_size New event buffer size.
+ * @return 0 on success, -1 on failure.
+ */
+int
+gpiod_request_config_set_event_buffer_size(struct gpiod_request_config *config,
+					   unsigned int event_buffer_size);
 
 /**
  * @}
  *
- * @defgroup line_config Setting line configuration
+ * @defgroup request_request Line request operations
  * @{
  *
- * Functions allowing modification of config options of GPIO lines requested
- * from user-space.
- */
-
-/**
- * @brief Update the configuration of a single GPIO line.
- * @param line GPIO line object.
- * @param direction Updated direction which may be one of
- *                  GPIOD_LINE_REQUEST_DIRECTION_AS_IS,
- *                  GPIOD_LINE_REQUEST_DIRECTION_INPUT, or
- *                  GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
- * @param flags Replacement flags.
- * @param value The new output value for the line when direction is
- *              GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
- * @return 0 is the operation succeeds. In case of an error this routine
- *         returns -1 and sets the last error number.
- */
-int gpiod_line_set_config(struct gpiod_line *line, int direction,
-			  int flags, int value);
-
-/**
- * @brief Update the configuration of a set of GPIO lines.
- * @param bulk Set of GPIO lines.
- * @param direction Updated direction which may be one of
- *                  GPIOD_LINE_REQUEST_DIRECTION_AS_IS,
- *                  GPIOD_LINE_REQUEST_DIRECTION_INPUT, or
- *                  GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
- * @param flags Replacement flags.
- * @param values An array holding line_bulk->num_lines new logical values
- *               for lines when direction is
- *               GPIOD_LINE_REQUEST_DIRECTION_OUTPUT.
- *               A NULL pointer is interpreted as a logical low for all lines.
- * @return 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.
+ * Functions allowing interaction with a set of requested lines.
  */
-int gpiod_line_set_config_bulk(struct gpiod_line_bulk *bulk,
-			       int direction, int flags, const int *values);
 
+/**
+ * @brief Release the requested lines and free all associated resources.
+ * @param request Line request object to release.
+ */
+void gpiod_line_request_release(struct gpiod_line_request *request);
 
 /**
- * @brief Update the configuration flags of a single GPIO line.
- * @param line GPIO line object.
- * @param flags Replacement flags.
- * @return 0 is the operation succeeds. In case of an error this routine
- *         returns -1 and sets the last error number.
+ * @brief Read the value of a single line associated with this request.
+ * @param request Line request object.
+ * @param offset Offset of the line of which the value should be read.
+ * @return Returns 1 or 0 on success and -1 on error.
  */
-int gpiod_line_set_flags(struct gpiod_line *line, int flags);
+int gpiod_line_request_get_value(struct gpiod_line_request *request,
+				 unsigned int offset);
 
 /**
- * @brief Update the configuration flags of a set of GPIO lines.
- * @param bulk Set of GPIO lines.
- * @param flags Replacement flags.
- * @return 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.
+ * @brief Read values of lines associated with this request.
+ * @param request GPIO line request.
+ * @param num_lines Number of lines for which to read values.
+ * @param offsets Array of offsets corresponding with the lines associated with
+ *                this request for which to read values.
+ * @param values Array in which the values will be stored.
+ * @return 0 on success, -1 on failure.
  */
-int gpiod_line_set_flags_bulk(struct gpiod_line_bulk *bulk, int flags);
+int gpiod_line_request_get_values(struct gpiod_line_request *request,
+				  unsigned num_lines,
+				  const unsigned int *offsets, int *values);
 
 /**
- * @brief Set the direction of a single GPIO line to input.
- * @param line GPIO line object.
- * @return 0 is the operation succeeds. In case of an error this routine
- *         returns -1 and sets the last error number.
+ * @brief Set the value of a single line associated with this request.
+ * @param request Line request object.
+ * @param offset Offset of the line of which the value should be set.
+ * @param value Value to set.
  */
-int gpiod_line_set_direction_input(struct gpiod_line *line);
+int gpiod_line_request_set_value(struct gpiod_line_request *request,
+				 unsigned int offset, int value);
 
 /**
- * @brief Set the direction of a set of GPIO lines to input.
- * @param bulk Set of GPIO lines.
- * @return 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.
+ * @brief Set values of lines associated with this line request.
+ * @param request GPIO line request.
+ * @param num_lines Number of lines for which to set values.
+ * @param offsets Array of offsets corresponding with the lines associated with
+ *                this request for which to set values.
+ * @param values Array of values to set. The members of this array must
+ *               correspond with the offsets in the previous argument.
+ * @return 0 on success, -1 on failure.
  */
-int
-gpiod_line_set_direction_input_bulk(struct gpiod_line_bulk *bulk);
+int gpiod_line_request_set_values(struct gpiod_line_request *request,
+				  unsigned int num_lines,
+				  const unsigned int *offsets,
+				  const int *values);
 
 /**
- * @brief Set the direction of a single GPIO line to output.
- * @param line GPIO line object.
- * @param value The logical value output on the line.
- * @return 0 is the operation succeeds. In case of an error this routine
- *         returns -1 and sets the last error number.
+ * @brief Update the configuration of lines associated with this line request.
+ * @param request GPIO line request.
+ * @param config New line config to apply.
+ * @return 0 on success, -1 on failure.
  */
-int gpiod_line_set_direction_output(struct gpiod_line *line, int value);
+int gpiod_line_request_reconfigure_lines(struct gpiod_line_request *request,
+					 struct gpiod_line_config *config);
 
 /**
- * @brief Set the direction of a set of GPIO lines to output.
- * @param bulk Set of GPIO lines.
- * @param values An array holding line_bulk->num_lines new logical values
- *               for lines.  A NULL pointer is interpreted as a logical low
- *               for all lines.
- * @return 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.
+ * @brief Get the file descriptor associated with this line request.
+ * @param request GPIO line request.
+ * @return Number of the file descriptor associated with this request. This
+ *         function never fails.
  */
-int gpiod_line_set_direction_output_bulk(struct gpiod_line_bulk *bulk,
-					 const int *values);
+int gpiod_line_request_get_fd(struct gpiod_line_request *request);
+
+/**
+ * @brief Wait for edge events on any of the lines associated with this request.
+ * @param request GPIO line request.
+ * @param timeout Wait time limit in nanoseconds.
+ * @return 0 if wait timed out, -1 if an error occurred, 1 if an event is
+ *         pending.
+ */
+int gpiod_line_request_edge_event_wait(struct gpiod_line_request *request,
+				       uint64_t timeout);
+
+/**
+ * @brief Read a number of edge events from a line request.
+ * @param request GPIO line request.
+ * @param buffer Line event buffer.
+ * @param max_events Maximum number of events to read.
+ * @return On success returns the number of events read from the file
+ *         descriptor, on failure return -1.
+ * @note This function will block if no event was queued for this line.
+ */
+int gpiod_line_request_edge_event_read(struct gpiod_line_request *request,
+				       struct gpiod_edge_event_buffer *buffer,
+				       unsigned int max_events);
 
 /**
  * @}
@@ -856,102 +881,115 @@ enum {
 };
 
 /**
- * @brief Structure holding event info.
+ * @brief Free the edge event object.
+ * @param event Edge event object to free.
+ * @note Must not be used with events stored in the buffer and retrieved using
+ *       ::gpiod_edge_event_buffer_peek_event.
  */
-struct gpiod_line_event {
-	struct timespec ts;
-	/**< Best estimate of time of event occurrence. */
-	int event_type;
-	/**< Type of the event that occurred. */
-	int offset;
-	/**< Offset of line on which the event occurred. */
-};
+void gpiod_edge_event_free(struct gpiod_edge_event *event);
 
 /**
- * @brief Wait for an event on a single line.
- * @param line GPIO line object.
- * @param timeout Wait time limit.
- * @return 0 if wait timed out, -1 if an error occurred, 1 if an event
- *         occurred.
+ * @brief Get the event type.
+ * @param event GPIO edge event.
+ * @return The event type (::GPIOD_LINE_EVENT_RISING_EDGE or
+ *         ::GPIOD_LINE_EVENT_FALLING_EDGE).
  */
-int gpiod_line_event_wait(struct gpiod_line *line,
-			  const struct timespec *timeout);
+int gpiod_edge_event_get_event_type(struct gpiod_edge_event *event);
 
 /**
- * @brief Wait for events on a set of lines.
- * @param bulk Set of GPIO lines to monitor.
- * @param timeout Wait time limit.
- * @param event_bulk Bulk object in which to store the line handles on which
- *                   events occurred. Can be NULL.
- * @return 0 if wait timed out, -1 if an error occurred, 1 if at least one
- *         event occurred.
+ * @brief Get the timestamp of the event.
+ * @param event GPIO edge event.
+ * @return Timestamp in nanoseconds.
  */
-int gpiod_line_event_wait_bulk(struct gpiod_line_bulk *bulk,
-			       const struct timespec *timeout,
-			       struct gpiod_line_bulk *event_bulk);
+uint64_t gpiod_edge_event_get_timestamp(struct gpiod_edge_event *event);
 
 /**
- * @brief Read next pending event from the GPIO line.
- * @param line GPIO line object.
- * @param event Buffer to which the event data will be copied.
- * @return 0 if the event was read correctly, -1 on error.
- * @note This function will block if no event was queued for this line.
+ * @brief Get the hardware offset of the line on which the event was triggered.
+ * @param event GPIO edge event.
+ * @return Line offset.
  */
-int gpiod_line_event_read(struct gpiod_line *line,
-			  struct gpiod_line_event *event);
+unsigned int gpiod_edge_event_get_line_offset(struct gpiod_edge_event *event);
 
 /**
- * @brief Read up to a certain number of events from the GPIO line.
- * @param line GPIO line object.
- * @param events Buffer to which the event data will be copied. Must hold at
- *               least the amount of events specified in num_events.
- * @param num_events Specifies how many events can be stored in the buffer.
- * @return On success returns the number of events stored in the buffer, on
- *         failure -1 is returned.
+ * @brief Get the global sequence number of this event.
+ * @param event GPIO edge event.
+ * @return Sequence number of the event relative to all lines in the associated
+ *         line request.
  */
-int gpiod_line_event_read_multiple(struct gpiod_line *line,
-				   struct gpiod_line_event *events,
-				   unsigned int num_events);
+unsigned int gpiod_edge_event_get_global_seqno(struct gpiod_edge_event *event);
 
 /**
- * @brief Get the event file descriptor.
- * @param line GPIO line object.
- * @return Number of the event file descriptor or -1 if the user tries to
- *         retrieve the descriptor from a line that wasn't configured for
- *         event monitoring.
- *
- * Users may want to poll the event file descriptor on their own. This routine
- * allows to access it.
+ * @brief Get the event sequence number specific to this line.
+ * @param event GPIO edge event.
+ * @return Sequence number of the event relative to this line within the
+ *         lifetime of the associated line request.
+ */
+unsigned int gpiod_edge_event_get_line_seqno(struct gpiod_edge_event *event);
+
+/**
+ * @brief Create a new edge event buffer.
+ * @param capacity Number of events this buffer can store (min = 1, max = 1024).
+ * @return New edge event buffer or NULL on error.
+ */
+struct gpiod_edge_event_buffer *
+gpiod_edge_event_buffer_new(unsigned int capacity);
+
+/**
+ * @brief Free the edge event buffer and release all associated resources.
+ * @param buffer Edge event buffer to free.
  */
-int gpiod_line_event_get_fd(struct gpiod_line *line);
+void gpiod_edge_event_buffer_free(struct gpiod_edge_event_buffer *buffer);
 
 /**
- * @brief Read the last GPIO event directly from a file descriptor.
+ * @brief Get a weak reference to an event in the buffer.
+ * @param buffer Line event buffer.
+ * @param index Index of the event in the buffer.
+ * @return Pointer to an event stored in the buffer. The lifetime of this
+ *         event is tied to the buffer object. Users must not call event
+ *         reference counting functions on pointers retrieved using this
+ *         function.
+ */
+struct gpiod_edge_event *
+gpiod_edge_event_buffer_peek_event(struct gpiod_edge_event_buffer *buffer,
+				   unsigned long index);
+
+/**
+ * @brief Get a copy of an edge event.
+ * @param buffer Line event buffer.
+ * @param index Index of the event in the buffer.
+ * @return Returns a copy of the edge event stored in this buffer. The event's
+ *         lifetime is managed by the caller. The event must be released using
+ *         ::gpiod_edge_event_free.
+ */
+struct gpiod_edge_event *
+gpiod_edge_event_buffer_copy_event(struct gpiod_edge_event_buffer *buffer,
+				   unsigned long index);
+
+/**
+ * @brief Get the number of events this buffers stores.
+ * @param buffer Line event buffer.
+ * @return Number of events stored in this buffer.
+ */
+unsigned int
+gpiod_edge_event_buffer_num_events(struct gpiod_edge_event_buffer *buffer);
+
+/**
+ * @brief Read GPIO edge events directly from a file descriptor.
  * @param fd File descriptor.
- * @param event Buffer in which the event data will be stored.
- * @return 0 if the event was read correctly, -1 on error.
+ * @param buffer Line event buffer.
+ * @param max_events Maximum number of events to read.
+ * @return On success returns the number of events read from the file
+ *         descriptor, on failure return -1.
  *
  * Users who directly poll the file descriptor for incoming events can also
  * directly read the event data from it using this routine. This function
  * translates the kernel representation of the event to the libgpiod format.
  */
-int gpiod_line_event_read_fd(int fd, struct gpiod_line_event *event);
+int gpiod_edge_event_buffer_read_fd(int fd,
+				    struct gpiod_edge_event_buffer *buffer,
+				    unsigned int max_events);
 
 /**
- * @brief Read up to a certain number of events directly from a file descriptor.
- * @param fd File descriptor.
- * @param events Buffer to which the event data will be copied. Must hold at
- *               least the amount of events specified in num_events.
- * @param num_events Specifies how many events can be stored in the buffer.
- * @return On success returns the number of events stored in the buffer, on
- *         failure -1 is returned.
- */
-int gpiod_line_event_read_fd_multiple(int fd, struct gpiod_line_event *events,
-				      unsigned int num_events);
-
-/**
- * @}
- *
  * @}
  *
  * @defgroup misc Stuff that didn't fit anywhere else
@@ -960,6 +998,14 @@ int gpiod_line_event_read_fd_multiple(int fd, struct gpiod_line_event *events,
  * Various libgpiod-related functions.
  */
 
+/**
+ * @brief Check if the file pointed to by path is a GPIO chip character device.
+ * @param path Path to check.
+ * @return True if the file exists and is a GPIO chip character device or a
+ *         symbolic link to it.
+ */
+bool gpiod_is_gpiochip_device(const char *path);
+
 /**
  * @brief Get the API version of the library as a human-readable string.
  * @return Human-readable string containing the library version.
lib/Makefile.am +12 -1
index 8441584..5423f72 100644
@@ -2,7 +2,18 @@
 # SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <[email protected]>
 
 lib_LTLIBRARIES = libgpiod.la
-libgpiod_la_SOURCES = core.c helpers.c internal.h misc.c uapi/gpio.h
+libgpiod_la_SOURCES =	chip.c \
+			edge-event.c \
+			info-event.c \
+			internal.h \
+			internal.c \
+			line-config.c \
+			line-info.c \
+			line-request.c \
+			misc.c \
+			request-config.c \
+			uapi/gpio.h
+
 libgpiod_la_CFLAGS = -Wall -Wextra -g -std=gnu89
 libgpiod_la_CFLAGS += -fvisibility=hidden -I$(top_srcdir)/include/
 libgpiod_la_CFLAGS += -include $(top_builddir)/config.h
lib/chip.c new file +216 -0

216 lines not on this page · raw message

lib/core.c deleted +0 -1240

1,240 lines not on this page · raw message

lib/edge-event.c new file +184 -0

184 lines not on this page · raw message

lib/helpers.c deleted +0 -302

302 lines not on this page · raw message

lib/info-event.c new file +83 -0

83 lines not on this page · raw message

lib/internal.c new file +58 -0

58 lines not on this page · raw message

lib/internal.h +28 -0
index 8b3f69a..7730f77 100644

Lines of this file are not shown. View the raw message.

lib/line-config.c new file +674 -0

674 lines not on this page · raw message

lib/line-info.c new file +164 -0

164 lines not on this page · raw message

lib/line-request.c new file +192 -0

192 lines not on this page · raw message

lib/misc.c +63 -0

63 lines not on this page · raw message

lib/request-config.c new file +98 -0

98 lines not on this page · raw message

tools/gpio-tools-test.bats +6 -6
index a5b97e1..e1b79b4 100755

Lines of this file are not shown. View the raw message.

tools/gpiodetect.c +4 -9
index 10706e2..9047091 100644

Lines of this file are not shown. View the raw message.

tools/gpiofind.c +2 -1
index 32b7852..910cb8b 100644

Lines of this file are not shown. View the raw message.

tools/gpioget.c +40 -26

66 lines not on this page · raw message

tools/gpioinfo.c +29 -31

60 lines not on this page · raw message

tools/gpiomon.c +70 -63

133 lines not on this page · raw message

tools/gpioset.c +45 -30

75 lines not on this page · raw message

tools/tools-common.c +4 -4
index 80087ee..36724d5 100644

Lines of this file are not shown. View the raw message.

tools/tools-common.h +1 -1
index 5d5b505..f059440 100644

Lines of this file are not shown. View the raw message.

The rest of this diff is not shown. View the raw message.

Signature · 1 line
2.30.1

Part of the diff is not shown here. View the raw message.

#1 lore raw
Quoted 21 lines · Bartosz Golaszewski

This is the second shot at the v2.0 C API for libgpiod.

Special thanks go out to Kent for his valuable advice and suggestions.

The biggest changes are:

The concept of attributes has been removed - instead the translation from configuration options to kernel request happens at the time of the line request call and can only fail at this stage - the config mutators no longer return any value.

If the caller has passed a config that is too complicated, the request function will set errno to E2BIG which stands for: "Argument list too long".

The direction and edge options have been split from the former request_type.

The objects are no longer reference counted and no longer can be the responsibility for their lifetime shared.

Quoted 8 lines

There are many other minor tweaks everywhere.

One thing I've been contemplating is whether we should expose some functions allowing callers to check if the line config has already become too complex or values passed are invalid. This would allow languages that have exceptions throw them before we actually make the request call. Does this make sense?

Wrt passing invalid values, I suggested error-less mutators on the assumption they wouldn't have parameters that require range checking. e.g. my Go library has AsInput() and AsOutput(value)
Your equivalents are:
gpiod_line_config_set_direction(cfg, GPIOD_LINE_CONFIG_DIRECTION_INPUT)
and
gpiod_line_config_set_direction(cfg, GPIOD_LINE_CONFIG_DIRECTION_OUTPUT)

If you need to perform range checking on the parameters then the mutator should return an error code.

OTOH, for the active level you provide two error-less mutators, gpiod_line_config_set_active_low() and gpiod_line_config_set_active_high(), which is fine.

Wrt exposing complexity validation functions, I don't see the benefit. The config may transition through complex states, so long as at the time the gpiod_chip_request_lines() or gpiod_line_request_reconfigure_lines() is called it isn't too complex and so can be translated to the uAPI. The check has to be performed as part of those functions either way, and validating a transitional config doesn't prove anything.

Quoted 46 lines

This time the new API is in one big patch for easier review. This changeset doesn't modify the bindings or tests but the tools compile and pass all tests.

---
 include/gpiod.h            | 1222 ++++++++++++++++++-----------------
 lib/Makefile.am            |   13 +-
 lib/chip.c                 |  216 +++++++
 lib/core.c                 | 1240 ------------------------------------
 lib/edge-event.c           |  184 ++++++
 lib/helpers.c              |  302 ---------
 lib/info-event.c           |   83 +++
 lib/internal.c             |   58 ++
 lib/internal.h             |   28 +
 lib/line-config.c          |  674 ++++++++++++++++++++
 lib/line-info.c            |  164 +++++
 lib/line-request.c         |  192 ++++++
 lib/misc.c                 |   63 ++
 lib/request-config.c       |   98 +++
 tools/gpio-tools-test.bats |   12 +-
 tools/gpiodetect.c         |   13 +-
 tools/gpiofind.c           |    3 +-
 tools/gpioget.c            |   66 +-
 tools/gpioinfo.c           |   60 +-
 tools/gpiomon.c            |  133 ++--
 tools/gpioset.c            |   75 ++-
 tools/tools-common.c       |    8 +-
 tools/tools-common.h       |    2 +-
 23 files changed, 2607 insertions(+), 2302 deletions(-)
 create mode 100644 lib/chip.c
 delete mode 100644 lib/core.c
 create mode 100644 lib/edge-event.c
 delete mode 100644 lib/helpers.c
 create mode 100644 lib/info-event.c
 create mode 100644 lib/internal.c
 create mode 100644 lib/line-config.c
 create mode 100644 lib/line-info.c
 create mode 100644 lib/line-request.c
 create mode 100644 lib/request-config.c
include/gpiod.h +0 -0
index a4ce01f..bd4689f 100644

include/gpiod.h line 3

Quoted 3 lines
include/gpiod.h +1 -0
@@ -1,12 +1,12 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 /* SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <[email protected]> */
+/* SPDX-FileCopyrightText: 2021 Bartosz Golaszewski <[email protected]> */

I'm only going to look at the header here - I'm assuming the other changes just follow from the API changes.

<snip>

Quoted 16 lines
include/gpiod.h +3 -10
 /**
- * @brief Get the handle to the GPIO line at given offset.
- * @param chip The GPIO chip object.
+ * @brief Get the current snapshot of information about the line at given
+ *        offset.
+ * @param chip GPIO chip object.
  * @param offset The offset of the GPIO line.
- * @return Pointer to the GPIO line handle or NULL if an error occured.
- */
-struct gpiod_line *
-gpiod_chip_get_line(struct gpiod_chip *chip, unsigned int offset);
-
-/**
- * @brief Retrieve a set of lines and store them in a line bulk object.
- * @param chip The GPIO chip object.

include/gpiod.h extern "C" { · line 97

Quoted 10 lines
include/gpiod.h +3 -6
- * @param offsets Array of offsets of lines to retrieve.
- * @param num_offsets Number of lines to retrieve.
- * @return New line bulk object or NULL on error.
+ * @return New GPIO line info object or NULL if an error occurred.
  */
-struct gpiod_line_bulk *
-gpiod_chip_get_lines(struct gpiod_chip *chip, unsigned int *offsets,
-		     unsigned int num_offsets);
+struct gpiod_line_info *gpiod_chip_get_line_info(struct gpiod_chip *chip,
+						 unsigned int offset);

Caller takes ownership of the gpiod_line_info, or are we peeking into the gpiod_chip internals? Either way, needs a comment.

<snip>

Quoted 10 lines

/**
- * @brief Get the handle to the GPIO chip controlling this line.
- * @param line The GPIO line object.
- * @return Pointer to the GPIO chip handle controlling this line.
+ * @brief Get the pointer to the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a pointer to the line-info object associated with this event
+ * whose lifetime is tied to the event object. It must not be freed by
+ * the caller.
*/

include/gpiod.h enum { · line 374

Quoted 4 lines
include/gpiod.h +3 -1
-struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line);
+struct gpiod_line_info *
+gpiod_info_event_peek_line_info(struct gpiod_info_event *event);
+

Rather than the peek/copy you use here, I would rename the peek to get...

include/gpiod.h enum {

Quoted 11 lines
include/gpiod.h +10 -0
+/**
+ * @brief Get a copy of the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a copy of the line-info object associated with this event or
+ *         NULL on error. The lifetime of the returned object must be managed
+ *         by the caller and the line-info object must be freed using
+ *         ::gpiod_line_info_free.
+ */
 
+struct gpiod_line_info *
+gpiod_info_event_copy_line_info(struct gpiod_info_event *event);

... and change this to

+struct gpiod_line_info * +gpiod_line_info_copy(struct gpiod_line_info *info);

as that is more generally useful.

Similarly elsewhere you use the peek/copy pattern.

<snip>

include/gpiod.h enum { · line 695

Quoted 9 lines
include/gpiod.h +9 -0
+/**
+ * @brief Set the output value for a single offset.
+ * @param config Line config object.
+ * @param offset Offset of the line.
+ * @param value Output value to set.
+ */
+void gpiod_line_config_set_output_value(struct gpiod_line_config *config,
+					unsigned int offset, int value);
+

I would rename this to gpiod_line_config_set_output() and have it set the direction (to GPIOD_LINE_CONFIG_DIRECTION_OUTPUT of course) as well as the value.

And maybe add a gpiod_line_config_set_input()?

<snip>

Those are the only things that jump out at me at the moment. I much prefer this version over the previous. Sorry I haven't had a chance to look at it earlier.

Cheers,
Kent.

#2 lore raw
Quoted 40 lines · Kent Gibson
Quoted 21 lines · Bartosz Golaszewski

This is the second shot at the v2.0 C API for libgpiod.

Special thanks go out to Kent for his valuable advice and suggestions.

The biggest changes are:

The concept of attributes has been removed - instead the translation from configuration options to kernel request happens at the time of the line request call and can only fail at this stage - the config mutators no longer return any value.

If the caller has passed a config that is too complicated, the request function will set errno to E2BIG which stands for: "Argument list too long".

The direction and edge options have been split from the former request_type.

The objects are no longer reference counted and no longer can be the responsibility for their lifetime shared.

Quoted 8 lines

There are many other minor tweaks everywhere.

One thing I've been contemplating is whether we should expose some functions allowing callers to check if the line config has already become too complex or values passed are invalid. This would allow languages that have exceptions throw them before we actually make the request call. Does this make sense?

Wrt passing invalid values, I suggested error-less mutators on the assumption they wouldn't have parameters that require range checking. e.g. my Go library has AsInput() and AsOutput(value)
Your equivalents are:
gpiod_line_config_set_direction(cfg, GPIOD_LINE_CONFIG_DIRECTION_INPUT)
and
gpiod_line_config_set_direction(cfg, GPIOD_LINE_CONFIG_DIRECTION_OUTPUT)

Quoted 3 lines

If you need to perform range checking on the parameters then the mutator should return an error code.

Isn't this inconsistent with the complexity validation that only happens at request-time? You could say that a config could also transition from a state with an invalid value to a one where it's fine. The error code would indicate the reason for the request
failure: either E2BIG for too complex config or EINVAL for invalid values inside it.

Quoted 11 lines

OTOH, for the active level you provide two error-less mutators, gpiod_line_config_set_active_low() and gpiod_line_config_set_active_high(), which is fine.

Wrt exposing complexity validation functions, I don't see the benefit. The config may transition through complex states, so long as at the time the gpiod_chip_request_lines() or gpiod_line_request_reconfigure_lines() is called it isn't too complex and so can be translated to the uAPI. The check has to be performed as part of those functions either way, and validating a transitional config doesn't prove anything.

Indeed. OTOH with return values in mutators taking integer values we would throw errors on invalid values passed. I need to think about it some more.

Quoted 77 lines
Quoted 46 lines

This time the new API is in one big patch for easier review. This changeset doesn't modify the bindings or tests but the tools compile and pass all tests.

---
 include/gpiod.h            | 1222 ++++++++++++++++++-----------------
 lib/Makefile.am            |   13 +-
 lib/chip.c                 |  216 +++++++
 lib/core.c                 | 1240 ------------------------------------
 lib/edge-event.c           |  184 ++++++
 lib/helpers.c              |  302 ---------
 lib/info-event.c           |   83 +++
 lib/internal.c             |   58 ++
 lib/internal.h             |   28 +
 lib/line-config.c          |  674 ++++++++++++++++++++
 lib/line-info.c            |  164 +++++
 lib/line-request.c         |  192 ++++++
 lib/misc.c                 |   63 ++
 lib/request-config.c       |   98 +++
 tools/gpio-tools-test.bats |   12 +-
 tools/gpiodetect.c         |   13 +-
 tools/gpiofind.c           |    3 +-
 tools/gpioget.c            |   66 +-
 tools/gpioinfo.c           |   60 +-
 tools/gpiomon.c            |  133 ++--
 tools/gpioset.c            |   75 ++-
 tools/tools-common.c       |    8 +-
 tools/tools-common.h       |    2 +-
 23 files changed, 2607 insertions(+), 2302 deletions(-)
 create mode 100644 lib/chip.c
 delete mode 100644 lib/core.c
 create mode 100644 lib/edge-event.c
 delete mode 100644 lib/helpers.c
 create mode 100644 lib/info-event.c
 create mode 100644 lib/internal.c
 create mode 100644 lib/line-config.c
 create mode 100644 lib/line-info.c
 create mode 100644 lib/line-request.c
 create mode 100644 lib/request-config.c
include/gpiod.h +0 -0
index a4ce01f..bd4689f 100644

include/gpiod.h line 3

Quoted 3 lines
include/gpiod.h +1 -0
@@ -1,12 +1,12 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 /* SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <[email protected]> */
+/* SPDX-FileCopyrightText: 2021 Bartosz Golaszewski <[email protected]> */

I'm only going to look at the header here - I'm assuming the other changes just follow from the API changes.

<snip>

Quoted 21 lines
include/gpiod.h +4 -14
 /**
- * @brief Get the handle to the GPIO line at given offset.
- * @param chip The GPIO chip object.
+ * @brief Get the current snapshot of information about the line at given
+ *        offset.
+ * @param chip GPIO chip object.
  * @param offset The offset of the GPIO line.
- * @return Pointer to the GPIO line handle or NULL if an error occured.
- */
-struct gpiod_line *
-gpiod_chip_get_line(struct gpiod_chip *chip, unsigned int offset);
-
-/**
- * @brief Retrieve a set of lines and store them in a line bulk object.
- * @param chip The GPIO chip object.
- * @param offsets Array of offsets of lines to retrieve.
- * @param num_offsets Number of lines to retrieve.
- * @return New line bulk object or NULL on error.
+ * @return New GPIO line info object or NULL if an error occurred.
  */
-struct gpiod_line_bulk *
Quoted 9 lines

include/gpiod.h extern "C" { · line 97

Quoted 5 lines
include/gpiod.h +2 -2
-gpiod_chip_get_lines(struct gpiod_chip *chip, unsigned int *offsets,
-                  unsigned int num_offsets);
+struct gpiod_line_info *gpiod_chip_get_line_info(struct gpiod_chip *chip,
+                                              unsigned int offset);

Caller takes ownership of the gpiod_line_info, or are we peeking into the gpiod_chip internals? Either way, needs a comment.

Caller takes ownership to underline the fact that it's a non-mutable snapshot of the line config at the time when it was retrieved. I'll add a comment.

Quoted 11 lines

<snip>

Quoted 9 lines

/**
- * @brief Get the handle to the GPIO chip controlling this line.
- * @param line The GPIO line object.
- * @return Pointer to the GPIO chip handle controlling this line.
+ * @brief Get the pointer to the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a pointer to the line-info object associated with this event
+ * whose lifetime is tied to the event object. It must not be freed by
+ * the caller.

Quoted 8 lines

include/gpiod.h enum { · line 374

Quoted 5 lines

*/

include/gpiod.h +3 -1
-struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line);
+struct gpiod_line_info *
+gpiod_info_event_peek_line_info(struct gpiod_info_event *event);
+

Rather than the peek/copy you use here, I would rename the peek to get...

Ha! I think we'll disagree here again. In most cases in low-level linux C libraries, a "get" for complex objects returns a copy (or a new reference if we're using shared objects). I would like to stay consistent with that pattern. To me "peek" is a good way to distinguish those functions that allow you to look into the internals of the parent object. If anything - I'd go with the get/peek pattern where the former returns a new object over whose lifetime the caller takes responsibility and the latter returns a pointer to an object stored in the parent. I went with copy/peek because it hints at a different behavior than regular get but I can live with get/peek.

Quoted 24 lines

include/gpiod.h enum {

Quoted 12 lines
include/gpiod.h +10 -0
+/**
+ * @brief Get a copy of the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a copy of the line-info object associated with this event or
+ *         NULL on error. The lifetime of the returned object must be managed
+ *         by the caller and the line-info object must be freed using
+ *         ::gpiod_line_info_free.
+ */
 
+struct gpiod_line_info *
+gpiod_info_event_copy_line_info(struct gpiod_info_event *event);

... and change this to

+struct gpiod_line_info * +gpiod_line_info_copy(struct gpiod_line_info *info);

as that is more generally useful.

Similarly elsewhere you use the peek/copy pattern.

<snip>

Quoted 14 lines

include/gpiod.h enum { · line 695

Quoted 9 lines
include/gpiod.h +9 -0
+/**
+ * @brief Set the output value for a single offset.
+ * @param config Line config object.
+ * @param offset Offset of the line.
+ * @param value Output value to set.
+ */
+void gpiod_line_config_set_output_value(struct gpiod_line_config *config,
+                                     unsigned int offset, int value);
+

I would rename this to gpiod_line_config_set_output() and have it set the direction (to GPIOD_LINE_CONFIG_DIRECTION_OUTPUT of course) as well as the value.

I like it but how would that plug into the global direction setting?

Quoted 2 lines

And maybe add a gpiod_line_config_set_input()?

What about "as is" with this pattern? We agreed that input would be the default so we need some way to set "as is" too.

Thanks a lot for the review!

Bart

Quoted 8 lines

<snip>

Those are the only things that jump out at me at the moment. I much prefer this version over the previous. Sorry I haven't had a chance to look at it earlier.

Cheers,
Kent.

#3 lore raw
Quoted 45 lines · Bartosz Golaszewski
Quoted 40 lines · Kent Gibson
Quoted 21 lines · Bartosz Golaszewski

This is the second shot at the v2.0 C API for libgpiod.

Special thanks go out to Kent for his valuable advice and suggestions.

The biggest changes are:

The concept of attributes has been removed - instead the translation from configuration options to kernel request happens at the time of the line request call and can only fail at this stage - the config mutators no longer return any value.

If the caller has passed a config that is too complicated, the request function will set errno to E2BIG which stands for: "Argument list too long".

The direction and edge options have been split from the former request_type.

The objects are no longer reference counted and no longer can be the responsibility for their lifetime shared.

Quoted 8 lines

There are many other minor tweaks everywhere.

One thing I've been contemplating is whether we should expose some functions allowing callers to check if the line config has already become too complex or values passed are invalid. This would allow languages that have exceptions throw them before we actually make the request call. Does this make sense?

Wrt passing invalid values, I suggested error-less mutators on the assumption they wouldn't have parameters that require range checking. e.g. my Go library has AsInput() and AsOutput(value)
Your equivalents are:
gpiod_line_config_set_direction(cfg, GPIOD_LINE_CONFIG_DIRECTION_INPUT)
and
gpiod_line_config_set_direction(cfg, GPIOD_LINE_CONFIG_DIRECTION_OUTPUT)

Quoted 3 lines

If you need to perform range checking on the parameters then the mutator should return an error code.

Quoted 7 lines

Isn't this inconsistent with the complexity validation that only happens at request-time? You could say that a config could also transition from a state with an invalid value to a one where it's fine. The error code would indicate the reason for the request
failure: either E2BIG for too complex config or EINVAL for invalid values inside it.

No - they are two different things. Also, this in response to the possibility of exposing validation functions, and if you want that for the parameter ranges then it should be as part of the mutator not as a separate function.

And from a practical standpoint, a range check on a parameter is simple and easy, while the complexity check is hard.

Quoted 12 lines
Quoted 11 lines

OTOH, for the active level you provide two error-less mutators, gpiod_line_config_set_active_low() and gpiod_line_config_set_active_high(), which is fine.

Wrt exposing complexity validation functions, I don't see the benefit. The config may transition through complex states, so long as at the time the gpiod_chip_request_lines() or gpiod_line_request_reconfigure_lines() is called it isn't too complex and so can be translated to the uAPI. The check has to be performed as part of those functions either way, and validating a transitional config doesn't prove anything.

Quoted 4 lines

Indeed. OTOH with return values in mutators taking integer values we would throw errors on invalid values passed. I need to think about it some more.

I was assuming separate mutators for each of the enum values, as you do for the active level but, with the offset and subset variants multiplying the number of mutators, I can see why you would go with the parameterized versions. While you could still perform the range checking as part of the translation to uAPI, that can more difficult for the user to debug - depending on how many mutators they have applied.

It is a trade-off, but I still lean towards the error-less mutators as it simplifies user code - consolidating the error checking into one place. A parameter being out of range means the user is doing something stupid, or running a future app against an old libgpiod, in which case they should be fine with slightly tougher debugging.

Quoted 111 lines
Quoted 77 lines
Quoted 46 lines

This time the new API is in one big patch for easier review. This changeset doesn't modify the bindings or tests but the tools compile and pass all tests.

---
 include/gpiod.h            | 1222 ++++++++++++++++++-----------------
 lib/Makefile.am            |   13 +-
 lib/chip.c                 |  216 +++++++
 lib/core.c                 | 1240 ------------------------------------
 lib/edge-event.c           |  184 ++++++
 lib/helpers.c              |  302 ---------
 lib/info-event.c           |   83 +++
 lib/internal.c             |   58 ++
 lib/internal.h             |   28 +
 lib/line-config.c          |  674 ++++++++++++++++++++
 lib/line-info.c            |  164 +++++
 lib/line-request.c         |  192 ++++++
 lib/misc.c                 |   63 ++
 lib/request-config.c       |   98 +++
 tools/gpio-tools-test.bats |   12 +-
 tools/gpiodetect.c         |   13 +-
 tools/gpiofind.c           |    3 +-
 tools/gpioget.c            |   66 +-
 tools/gpioinfo.c           |   60 +-
 tools/gpiomon.c            |  133 ++--
 tools/gpioset.c            |   75 ++-
 tools/tools-common.c       |    8 +-
 tools/tools-common.h       |    2 +-
 23 files changed, 2607 insertions(+), 2302 deletions(-)
 create mode 100644 lib/chip.c
 delete mode 100644 lib/core.c
 create mode 100644 lib/edge-event.c
 delete mode 100644 lib/helpers.c
 create mode 100644 lib/info-event.c
 create mode 100644 lib/internal.c
 create mode 100644 lib/line-config.c
 create mode 100644 lib/line-info.c
 create mode 100644 lib/line-request.c
 create mode 100644 lib/request-config.c
include/gpiod.h +0 -0
index a4ce01f..bd4689f 100644

include/gpiod.h line 3

Quoted 3 lines
include/gpiod.h +1 -0
@@ -1,12 +1,12 @@
 /* SPDX-License-Identifier: LGPL-2.1-or-later */
 /* SPDX-FileCopyrightText: 2017-2021 Bartosz Golaszewski <[email protected]> */
+/* SPDX-FileCopyrightText: 2021 Bartosz Golaszewski <[email protected]> */

I'm only going to look at the header here - I'm assuming the other changes just follow from the API changes.

<snip>

Quoted 21 lines
include/gpiod.h +4 -14
 /**
- * @brief Get the handle to the GPIO line at given offset.
- * @param chip The GPIO chip object.
+ * @brief Get the current snapshot of information about the line at given
+ *        offset.
+ * @param chip GPIO chip object.
  * @param offset The offset of the GPIO line.
- * @return Pointer to the GPIO line handle or NULL if an error occured.
- */
-struct gpiod_line *
-gpiod_chip_get_line(struct gpiod_chip *chip, unsigned int offset);
-
-/**
- * @brief Retrieve a set of lines and store them in a line bulk object.
- * @param chip The GPIO chip object.
- * @param offsets Array of offsets of lines to retrieve.
- * @param num_offsets Number of lines to retrieve.
- * @return New line bulk object or NULL on error.
+ * @return New GPIO line info object or NULL if an error occurred.
  */
-struct gpiod_line_bulk *
Quoted 9 lines

include/gpiod.h extern "C" { · line 97

Quoted 5 lines
include/gpiod.h +2 -2
-gpiod_chip_get_lines(struct gpiod_chip *chip, unsigned int *offsets,
-                  unsigned int num_offsets);
+struct gpiod_line_info *gpiod_chip_get_line_info(struct gpiod_chip *chip,
+                                              unsigned int offset);

Caller takes ownership of the gpiod_line_info, or are we peeking into the gpiod_chip internals? Either way, needs a comment.

Caller takes ownership to underline the fact that it's a non-mutable snapshot of the line config at the time when it was retrieved. I'll add a comment.

Quoted 11 lines

<snip>

Quoted 9 lines

/**
- * @brief Get the handle to the GPIO chip controlling this line.
- * @param line The GPIO line object.
- * @return Pointer to the GPIO chip handle controlling this line.
+ * @brief Get the pointer to the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a pointer to the line-info object associated with this event
+ * whose lifetime is tied to the event object. It must not be freed by
+ * the caller.

Quoted 8 lines

include/gpiod.h enum { · line 374

Quoted 5 lines

*/

include/gpiod.h +3 -1
-struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line);
+struct gpiod_line_info *
+gpiod_info_event_peek_line_info(struct gpiod_info_event *event);
+

Rather than the peek/copy you use here, I would rename the peek to get...

Quoted 11 lines

Ha! I think we'll disagree here again. In most cases in low-level linux C libraries, a "get" for complex objects returns a copy (or a new reference if we're using shared objects). I would like to stay consistent with that pattern. To me "peek" is a good way to distinguish those functions that allow you to look into the internals of the parent object. If anything - I'd go with the get/peek pattern where the former returns a new object over whose lifetime the caller takes responsibility and the latter returns a pointer to an object stored in the parent. I went with copy/peek because it hints at a different behavior than regular get but I can live with get/peek.

Not too fussed about the naming of this function (for that matter most of my comments are personal preference - I could live with your way), and distinguishing between get and peek is a valid point, but my main point was that the copy should operate on the contained type, not the container - see below.

Quoted 39 lines
Quoted 24 lines

include/gpiod.h enum {

Quoted 12 lines
include/gpiod.h +10 -0
+/**
+ * @brief Get a copy of the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a copy of the line-info object associated with this event or
+ *         NULL on error. The lifetime of the returned object must be managed
+ *         by the caller and the line-info object must be freed using
+ *         ::gpiod_line_info_free.
+ */
 
+struct gpiod_line_info *
+gpiod_info_event_copy_line_info(struct gpiod_info_event *event);

... and change this to

+struct gpiod_line_info * +gpiod_line_info_copy(struct gpiod_line_info *info);

as that is more generally useful.

Similarly elsewhere you use the peek/copy pattern.

<snip>

Quoted 14 lines

include/gpiod.h enum { · line 695

Quoted 9 lines
include/gpiod.h +9 -0
+/**
+ * @brief Set the output value for a single offset.
+ * @param config Line config object.
+ * @param offset Offset of the line.
+ * @param value Output value to set.
+ */
+void gpiod_line_config_set_output_value(struct gpiod_line_config *config,
+                                     unsigned int offset, int value);
+

I would rename this to gpiod_line_config_set_output() and have it set the direction (to GPIOD_LINE_CONFIG_DIRECTION_OUTPUT of course) as well as the value.

Quoted 2 lines

I like it but how would that plug into the global direction setting?

You mean the default flags?
You can work that out as part of the translation to uAPI. It would be whichever applies to the most lines. No need for the user to know or care.

Quoted 6 lines
Quoted 2 lines

And maybe add a gpiod_line_config_set_input()?

What about "as is" with this pattern? We agreed that input would be the default so we need some way to set "as is" too.

I didn't suggest removing gpiod_line_config_set_direction(), so you would use that. The as-is case isn't sufficiently common to warrant its own short form.

Cheers,
Kent.

Quoted 12 lines

Thanks a lot for the review!

Bart

Quoted 8 lines

<snip>

Those are the only things that jump out at me at the moment. I much prefer this version over the previous. Sorry I haven't had a chance to look at it earlier.

Cheers,
Kent.

#4 lore raw
Quoted 3 lines · Kent Gibson
Quoted 2 lines · Bartosz Golaszewski
Quoted 1 line · Kent Gibson

<snip>

Quoted 18 lines
Quoted 18 lines
Quoted 17 lines
Quoted 10 lines

/**
- * @brief Get the handle to the GPIO chip controlling this line.
- * @param line The GPIO line object.
- * @return Pointer to the GPIO chip handle controlling this line.
+ * @brief Get the pointer to the line-info object associated with this event.
+ * @param event Line info event object.
+ * @return Returns a pointer to the line-info object associated with this event
+ * whose lifetime is tied to the event object. It must not be freed by
+ * the caller.
*/

include/gpiod.h enum { · line 374

Quoted 4 lines
include/gpiod.h +3 -1
-struct gpiod_chip *gpiod_line_get_chip(struct gpiod_line *line);
+struct gpiod_line_info *
+gpiod_info_event_peek_line_info(struct gpiod_info_event *event);
+

Rather than the peek/copy you use here, I would rename the peek to get...

Quoted 12 lines
Quoted 11 lines

Ha! I think we'll disagree here again. In most cases in low-level linux C libraries, a "get" for complex objects returns a copy (or a new reference if we're using shared objects). I would like to stay consistent with that pattern. To me "peek" is a good way to distinguish those functions that allow you to look into the internals of the parent object. If anything - I'd go with the get/peek pattern where the former returns a new object over whose lifetime the caller takes responsibility and the latter returns a pointer to an object stored in the parent. I went with copy/peek because it hints at a different behavior than regular get but I can live with get/peek.

I forgot to ask about where gpiod_line_info_get_name() and others that return char * fit wrt that pattern.
So a string isn't a complex object?
Maybe they should be _peek_ as well?
Either way, it would be nice for their commentary to describe the lifetime of the returned pointer.

Cheers,
Kent.

#5 lore raw
In reply to Kent Gibson
Quoted 1 line · Kent Gibson

[snip]

Quoted 9 lines
Quoted 8 lines

Isn't this inconsistent with the complexity validation that only happens at request-time? You could say that a config could also transition from a state with an invalid value to a one where it's fine. The error code would indicate the reason for the request
failure: either E2BIG for too complex config or EINVAL for invalid values inside it.

Quoted 8 lines

No - they are two different things. Also, this in response to the possibility of exposing validation functions, and if you want that for the parameter ranges then it should be as part of the mutator not as a separate function.

And from a practical standpoint, a range check on a parameter is simple and easy, while the complexity check is hard.

Fair enough.

Quoted 24 lines
Quoted 12 lines
Quoted 11 lines

OTOH, for the active level you provide two error-less mutators, gpiod_line_config_set_active_low() and gpiod_line_config_set_active_high(), which is fine.

Wrt exposing complexity validation functions, I don't see the benefit. The config may transition through complex states, so long as at the time the gpiod_chip_request_lines() or gpiod_line_request_reconfigure_lines() is called it isn't too complex and so can be translated to the uAPI. The check has to be performed as part of those functions either way, and validating a transitional config doesn't prove anything.

Quoted 4 lines

Indeed. OTOH with return values in mutators taking integer values we would throw errors on invalid values passed. I need to think about it some more.

I was assuming separate mutators for each of the enum values, as you do for the active level but, with the offset and subset variants multiplying the number of mutators, I can see why you would go with the parameterized versions. While you could still perform the range checking as part of the translation to uAPI, that can more difficult for the user to debug - depending on how many mutators they have applied.

Quoted 6 lines

It is a trade-off, but I still lean towards the error-less mutators as it simplifies user code - consolidating the error checking into one place. A parameter being out of range means the user is doing something stupid, or running a future app against an old libgpiod, in which case they should be fine with slightly tougher debugging.

Having error-less mutators here would mean something like a hundred functions just for setting the line config. I think that even with mutators taking enums we already have enough symbols. Let's keep them.

[snip]

Quoted 13 lines
Quoted 12 lines

Ha! I think we'll disagree here again. In most cases in low-level linux C libraries, a "get" for complex objects returns a copy (or a new reference if we're using shared objects). I would like to stay consistent with that pattern. To me "peek" is a good way to distinguish those functions that allow you to look into the internals of the parent object. If anything - I'd go with the get/peek pattern where the former returns a new object over whose lifetime the caller takes responsibility and the latter returns a pointer to an object stored in the parent. I went with copy/peek because it hints at a different behavior than regular get but I can live with get/peek.

Quoted 6 lines

Not too fussed about the naming of this function (for that matter most of my comments are personal preference - I could live with your way), and distinguishing between get and peek is a valid point, but my main point was that the copy should operate on the contained type, not the container - see below.

I'm not seeing anything related below but I see what you mean - gpiod_line_event_copy(event). Not sure if this makes sense/is needed though. I'll switch to providing get and peek and have them operate on the container.

[Snippy McSnipface]

Quoted 16 lines
Quoted 16 lines
Quoted 15 lines

include/gpiod.h enum { · line 695

Quoted 10 lines
include/gpiod.h +9 -0
+/**
+ * @brief Set the output value for a single offset.
+ * @param config Line config object.
+ * @param offset Offset of the line.
+ * @param value Output value to set.
+ */
+void gpiod_line_config_set_output_value(struct gpiod_line_config *config,
+                                     unsigned int offset, int value);
+

I would rename this to gpiod_line_config_set_output() and have it set the direction (to GPIOD_LINE_CONFIG_DIRECTION_OUTPUT of course) as well as the value.

Quoted 8 lines
Quoted 2 lines

I like it but how would that plug into the global direction setting?

You mean the default flags?
You can work that out as part of the translation to uAPI. It would be whichever applies to the most lines. No need for the user to know or care.

Eek this sounds vague. If that was part of documentation for this function - as a user I would be confused. Is there any problem with just implying output for any line for which a default value is set?

Quoted 13 lines
Quoted 6 lines
Quoted 2 lines

And maybe add a gpiod_line_config_set_input()?

What about "as is" with this pattern? We agreed that input would be the default so we need some way to set "as is" too.

I didn't suggest removing gpiod_line_config_set_direction(), so you would use that. The as-is case isn't sufficiently common to warrant its own short form.

Quoted 6 lines

I forgot to ask about where gpiod_line_info_get_name() and others that return char * fit wrt that pattern.
So a string isn't a complex object?
Maybe they should be _peek_ as well?
Either way, it would be nice for their commentary to describe the lifetime of the returned pointer.

With strings the common sense is to assume that returning char * means the string is dynamically allocated and must be freed by the caller, returning const char * means the string is stored in the container. I can't really recall seeing any other pattern in any sane C library. In any case - I will add a comment to every function that returns an object that needs lifetime management from the caller in v3.

Thanks!
Bart

#6 lore raw
Quoted 3 lines · Bartosz Golaszewski
Quoted 1 line · Kent Gibson

[snip]

Quoted 15 lines
Quoted 6 lines
Quoted 6 lines
Quoted 5 lines

I would rename this to gpiod_line_config_set_output() and have it set the direction (to GPIOD_LINE_CONFIG_DIRECTION_OUTPUT of course) as well as the value.

Quoted 8 lines
Quoted 2 lines

I like it but how would that plug into the global direction setting?

You mean the default flags?
You can work that out as part of the translation to uAPI. It would be whichever applies to the most lines. No need for the user to know or care.

Quoted 4 lines

Eek this sounds vague. If that was part of documentation for this function - as a user I would be confused. Is there any problem with just implying output for any line for which a default value is set?

What part of "No need for the user to know or care" is too vague? The user does not need to know how libgpiod translates to uAPI - that is your problem not theirs, so don't go there.

But for your benefit...

There is no global direction setting - the lines are treated independently until the translation to uAPI during the request or reconfigure call, at which point the most common flags setting can be used as the global default.

The direction flag is only set for the lines specified in the set_output call, so offset for the singular case, or offsets for the subset case.

Quoted 20 lines
Quoted 13 lines
Quoted 6 lines
Quoted 2 lines

And maybe add a gpiod_line_config_set_input()?

What about "as is" with this pattern? We agreed that input would be the default so we need some way to set "as is" too.

I didn't suggest removing gpiod_line_config_set_direction(), so you would use that. The as-is case isn't sufficiently common to warrant its own short form.

Quoted 6 lines

I forgot to ask about where gpiod_line_info_get_name() and others that return char * fit wrt that pattern.
So a string isn't a complex object?
Maybe they should be _peek_ as well?
Either way, it would be nice for their commentary to describe the lifetime of the returned pointer.

Quoted 7 lines

With strings the common sense is to assume that returning char * means the string is dynamically allocated and must be freed by the caller, returning const char * means the string is stored in the container. I can't really recall seeing any other pattern in any sane C library. In any case - I will add a comment to every function that returns an object that needs lifetime management from the caller in v3.

Sure, but don't assume common sense - document the behaviour - even if the returned object doesn't require lifetime management by the caller. They might assume they do - and free it for you.

And the point was that you still have some gets that return objects while others return a reference - even after renaming some to peek, so the pattern doesn't follow for the whole libgpiod API. Granted that is nitpicking, but I would prefer internal self-consistency over following what other libraries do.

Cheers,
Kent.

#7 lore raw
Quoted 1 line · Kent Gibson

[peek]

Quoted 11 lines
Quoted 6 lines
Quoted 1 line

Eek this sounds vague. If that was part of documentation for this function - as a user I would be confused. Is there any problem with just implying output for any line for which a default value is set?

What part of "No need for the user to know or care" is too vague? The user does not need to know how libgpiod translates to uAPI - that is your problem not theirs, so don't go there.

Quoted 7 lines

But for your benefit...

There is no global direction setting - the lines are treated independently until the translation to uAPI during the request or reconfigure call, at which point the most common flags setting can be used as the global default.

I said "vague" for want of a better word but what I mean is this:
taking the most common setting as the global default does not sound intuitive and - when coding - it would be hard to predict the outcome from just looking at the code. I was actually assuming that we'd have lines begin with a certain sane, default config (INPUT, active-high, no bias, no drive, no edge etc) and every line's config would have to be changed explicitly - either via the global mutators or the ones that work with a subset of lines (where the subset could actually include all the lines - we don't know it before we do the actual request because the list of lines to request is passed in a different struct).

[snip]

Quoted 21 lines
Quoted 9 lines
Quoted 8 lines

I forgot to ask about where gpiod_line_info_get_name() and others that return char * fit wrt that pattern.
So a string isn't a complex object?
Maybe they should be _peek_ as well?
Either way, it would be nice for their commentary to describe the lifetime of the returned pointer.

Quoted 7 lines

With strings the common sense is to assume that returning char * means the string is dynamically allocated and must be freed by the caller, returning const char * means the string is stored in the container. I can't really recall seeing any other pattern in any sane C library. In any case - I will add a comment to every function that returns an object that needs lifetime management from the caller in v3.

Sure, but don't assume common sense - document the behaviour - even if the returned object doesn't require lifetime management by the caller. They might assume they do - and free it for you.

Quoted 6 lines

And the point was that you still have some gets that return objects while others return a reference - even after renaming some to peek, so the pattern doesn't follow for the whole libgpiod API. Granted that is nitpicking, but I would prefer internal self-consistency over following what other libraries do.

I don't want to use "peek" for simple types if that's what you're hinting at because that would be very confusing to anyone experienced with other C linux libraries. I would like to go with "get" for functions returning pointers to opaque structs that need management and peek for those that return pointers to structs stored in other objects. I don't think we need to have additional "copy" functions operating on the copied objects.

[snip]

Quoted 15 lines
Quoted 6 lines
Quoted 1 line

Having error-less mutators here would mean something like a hundred functions just for setting the line config. I think that even with mutators taking enums we already have enough symbols. Let's keep them.

We don't want separate mutators for each enum value as that would explode the symbol space. Agreed.

To be clear, in my "trade-off" paragraph above I was referring to your existing parameterised error-less mutators, not the parameter-less error-less mutators that I had been assuming.
Different paragraph and different things.

Quoted 6 lines

So, to conclude, I would lean towards keeping your existing mutators that don't return error codes, rather than adding error codes.
And only performing the validation when the config is translated to uAPI, not providing some functions to perform interim validation. i.e. wrt error handling I'm fine with the mutators as they are.

Ok got it.

I think we're getting close to an agreement. :)

Bart

#8 lore raw
Quoted 24 lines · Bartosz Golaszewski
Quoted 1 line · Kent Gibson

[peek]

Quoted 11 lines
Quoted 6 lines
Quoted 1 line

Eek this sounds vague. If that was part of documentation for this function - as a user I would be confused. Is there any problem with just implying output for any line for which a default value is set?

What part of "No need for the user to know or care" is too vague? The user does not need to know how libgpiod translates to uAPI - that is your problem not theirs, so don't go there.

Quoted 7 lines

But for your benefit...

There is no global direction setting - the lines are treated independently until the translation to uAPI during the request or reconfigure call, at which point the most common flags setting can be used as the global default.

Quoted 12 lines

I said "vague" for want of a better word but what I mean is this:
taking the most common setting as the global default does not sound intuitive and - when coding - it would be hard to predict the outcome from just looking at the code. I was actually assuming that we'd have lines begin with a certain sane, default config (INPUT, active-high, no bias, no drive, no edge etc) and every line's config would have to be changed explicitly - either via the global mutators or the ones that work with a subset of lines (where the subset could actually include all the lines - we don't know it before we do the actual request because the list of lines to request is passed in a different struct).

Ahh, I forgot that you have the req_config and line_config split. So you have no option but to maintain global flags. That is used as the initial value of the flags for a particular line when that one line is first mutated, either by offset or as part of a subset.
And subsequent changes to the global flags need to be propagated to all the lines in the config at that time.

Taking the most common flags value as the uAPI default is an optimization that minimizes the number of lines requiring custom flag attributes in the uAPI config. It might seem unintuitive to you, but it makes sense to me that it should be the uAPI default, even if the user wasn't aware that it should be.
OTOH there are only a few corner cases where it is of real benefit, so just using the line_config global flags is fine.
FWIW, my Go library doesn't perform that optimization - it uses the global flags :). Not sure why I'm still suggesting it here when I apparently decided it wasn't worth the effort there ¯\_(ツ)_/¯.

Quoted 30 lines

[snip]

Quoted 21 lines
Quoted 9 lines
Quoted 8 lines

I forgot to ask about where gpiod_line_info_get_name() and others that return char * fit wrt that pattern.
So a string isn't a complex object?
Maybe they should be _peek_ as well?
Either way, it would be nice for their commentary to describe the lifetime of the returned pointer.

Quoted 7 lines

With strings the common sense is to assume that returning char * means the string is dynamically allocated and must be freed by the caller, returning const char * means the string is stored in the container. I can't really recall seeing any other pattern in any sane C library. In any case - I will add a comment to every function that returns an object that needs lifetime management from the caller in v3.

Sure, but don't assume common sense - document the behaviour - even if the returned object doesn't require lifetime management by the caller. They might assume they do - and free it for you.

Quoted 6 lines

And the point was that you still have some gets that return objects while others return a reference - even after renaming some to peek, so the pattern doesn't follow for the whole libgpiod API. Granted that is nitpicking, but I would prefer internal self-consistency over following what other libraries do.

Quoted 8 lines

I don't want to use "peek" for simple types if that's what you're hinting at because that would be very confusing to anyone experienced with other C linux libraries. I would like to go with "get" for functions returning pointers to opaque structs that need management and peek for those that return pointers to structs stored in other objects. I don't think we need to have additional "copy" functions operating on the copied objects.

Fair enough - just another of those minor points that I would do differently (I'd just stick with get and live with the fact that returns ownership in some cases and not in others).

Quoted 24 lines

[snip]

Quoted 15 lines
Quoted 6 lines
Quoted 1 line

Having error-less mutators here would mean something like a hundred functions just for setting the line config. I think that even with mutators taking enums we already have enough symbols. Let's keep them.

We don't want separate mutators for each enum value as that would explode the symbol space. Agreed.

To be clear, in my "trade-off" paragraph above I was referring to your existing parameterised error-less mutators, not the parameter-less error-less mutators that I had been assuming.
Different paragraph and different things.

Quoted 6 lines

So, to conclude, I would lean towards keeping your existing mutators that don't return error codes, rather than adding error codes.
And only performing the validation when the config is translated to uAPI, not providing some functions to perform interim validation. i.e. wrt error handling I'm fine with the mutators as they are.

Quoted 4 lines

Ok got it.

I think we're getting close to an agreement. :)

Well that makes one of us ;).

Cheers,
Kent.

#9 lore raw
Quoted 1 line · Kent Gibson

[snip]

Quoted 8 lines
Quoted 5 lines

Ok got it.

I think we're getting close to an agreement. :)

Well that makes one of us ;).

Oh we don't? I thought there are only minor disagreements on naming convention and error handling but for most part we're aligned on the general shape of the API?

Bart

#10 lore raw
Quoted 11 lines · Bartosz Golaszewski
Quoted 1 line · Kent Gibson

[snip]

Quoted 6 lines
Quoted 5 lines

Ok got it.

I think we're getting close to an agreement. :)

Quoted 7 lines
Quoted 2 lines

Well that makes one of us ;).

Oh we don't? I thought there are only minor disagreements on naming convention and error handling but for most part we're aligned on the general shape of the API?

Indeed we are. My apologies for the failed humour.

Cheers,
Kent.

#11 lore raw
In reply to Bartosz Golaszewski
Quoted 3 lines · Bartosz Golaszewski
Quoted 1 line · Kent Gibson

[snip]

I meant to reply to this section as well but managed to snip it out...

Quoted 25 lines
Quoted 18 lines
Quoted 10 lines
Quoted 5 lines

the gpiod_chip_request_lines() or gpiod_line_request_reconfigure_lines() is called it isn't too complex and so can be translated to the uAPI. The check has to be performed as part of those functions either way, and validating a transitional config doesn't prove anything.

Indeed. OTOH with return values in mutators taking integer values we would throw errors on invalid values passed. I need to think about it some more.

I was assuming separate mutators for each of the enum values, as you do for the active level but, with the offset and subset variants multiplying the number of mutators, I can see why you would go with the parameterized versions. While you could still perform the range checking as part of the translation to uAPI, that can more difficult for the user to debug - depending on how many mutators they have applied.

Quoted 6 lines

It is a trade-off, but I still lean towards the error-less mutators as it simplifies user code - consolidating the error checking into one place. A parameter being out of range means the user is doing something stupid, or running a future app against an old libgpiod, in which case they should be fine with slightly tougher debugging.

Quoted 4 lines

Having error-less mutators here would mean something like a hundred functions just for setting the line config. I think that even with mutators taking enums we already have enough symbols. Let's keep them.

We don't want separate mutators for each enum value as that would explode the symbol space. Agreed.

To be clear, in my "trade-off" paragraph above I was referring to your existing parameterised error-less mutators, not the parameter-less error-less mutators that I had been assuming.
Different paragraph and different things.

So, to conclude, I would lean towards keeping your existing mutators that don't return error codes, rather than adding error codes.
And only performing the validation when the config is translated to uAPI, not providing some functions to perform interim validation. i.e. wrt error handling I'm fine with the mutators as they are.

OK?

Cheers,
Kent.