@@ -25,7 +25,7 @@ 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 that
+ * <p>General note on error handling: all functions 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
@@ -62,105 +62,108 @@ struct gpiod_edge_event_buffer;
*/
/**
- * @brief Open a GPIO chip by path.
+ * @brief Open a chip by path.
* @param path Path to the gpiochip device file.
* @return GPIO chip request or NULL if an error occurred.
*/
struct gpiod_chip *gpiod_chip_open(const char *path);
/**
- * @brief Close a GPIO chip and release all associated resources.
+ * @brief Close the chip and release all associated resources.
* @param chip Chip to close.
*/
void gpiod_chip_close(struct gpiod_chip *chip);
/**
- * @brief Get the GPIO chip name as represented in the kernel.
+ * @brief Get the name of the chip as represented in the kernel.
* @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.
+ * @brief Get the label of the chip as represented in the kernel.
* @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 path used to open this GPIO chip.
+ * @brief Get the path used to open the chip.
* @param chip GPIO chip object.
* @return Path to the file passed as argument to ::gpiod_chip_open.
*/
const char *gpiod_chip_get_path(struct gpiod_chip *chip);
/**
- * @brief Get the number of GPIO lines exposed by this chip.
+ * @brief Get the number of lines exposed by the chip.
* @param chip GPIO chip object.
* @return Number of GPIO lines.
*/
size_t gpiod_chip_get_num_lines(struct gpiod_chip *chip);
/**
- * @brief Get the current snapshot of information about the line at given
- * offset.
+ * @brief Get a snapshot of information about a line.
* @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. The returned
- * object must be freed by the caller using ::gpiod_line_info_free.
+ * object must be freed by the caller using ::gpiod_line_info_free.
*/
struct gpiod_line_info *gpiod_chip_get_line_info(struct gpiod_chip *chip,
unsigned int offset);
/**
- * @brief Get the current snapshot of information about the line at given
- * offset and start watching it for future changes.
+ * @brief Get a snapshot of the status of a line 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. The returned
- * object must be freed by the caller using ::gpiod_line_info_free.
+ * object must be freed by the caller using ::gpiod_line_info_free.
+ * @note Line status does not include the line value. To monitor the line
+ * value the line must be requested as an input with edge detection set.
*/
struct gpiod_line_info *gpiod_chip_watch_line_info(struct gpiod_chip *chip,
unsigned int offset);
/**
- * @brief Stop watching the line at given offset for status changes.
+ * @brief Stop watching a line for status changes.
* @param chip GPIO chip object.
- * @param offset The offset of the GPIO line.
+ * @param offset The offset of the line to stop watching.
* @return 0 on success, -1 on failure.
*/
int gpiod_chip_unwatch_line_info(struct gpiod_chip *chip, unsigned int offset);
/**
- * @brief Get the file descriptor associated with this chip.
+ * @brief Get the file descriptor associated with the chip.
* @param chip GPIO chip object.
- * @return File descriptor number. This function never fails. The returned file
- * descriptor must not be closed by the caller.
+ * @return File descriptor number for the chip.
+ * This function never fails.
+ * The returned file descriptor must not be closed by the caller.
+ * Call ::gpiod_chip_close to close the file descriptor.
*/
int gpiod_chip_get_fd(struct gpiod_chip *chip);
/**
- * @brief Wait for line status events on any of the watched lines exposed by
- * this chip.
+ * @brief Wait for line status change events on any of the watched lines
+ * on the chip.
* @param chip GPIO chip object.
* @param timeout_ns Wait time limit in nanoseconds.
* @return 0 if wait timed out, -1 if an error occurred, 1 if an event is
- * pending.
+ * pending.
*/
int gpiod_chip_info_event_wait(struct gpiod_chip *chip, uint64_t timeout_ns);
/**
- * @brief Read a single line status change event from this chip.
+ * @brief Read a single line status change event from the chip.
* @param chip GPIO chip object.
* @return Newly read watch event object or NULL on error. The event must be
- * freed by the caller using ::gpiod_info_event_free.
+ * freed by the caller using ::gpiod_info_event_free.
* @note If no events are pending, this function will block.
*/
struct gpiod_info_event *gpiod_chip_info_event_read(struct gpiod_chip *chip);
/**
- * @brief Map a GPIO line's name to its offset within the chip.
+ * @brief Map a 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.
@@ -175,9 +178,9 @@ int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name);
* @param req_cfg Request config object.
* @param line_cfg Line config object.
* @return New line request object or NULL if an error occurred. The request
- * must be released by the caller using ::gpiod_line_request_release.
- * @note Line configuration overrides set for offsets that don't end up being
- * requested are silently ignored.
+ * must be released by the caller using ::gpiod_line_request_release.
+ * @note Line configuration overrides for lines that are not requested are
+ * silently ignored.
*/
struct gpiod_line_request *
gpiod_chip_request_lines(struct gpiod_chip *chip,
@@ -206,11 +209,11 @@ enum {
*/
enum {
GPIOD_LINE_DIRECTION_AS_IS = 1,
- /**< Request the line(s), but don't change current direction. */
+ /**< Request the line(s), but don't change direction. */
GPIOD_LINE_DIRECTION_INPUT,
- /**< Direction is input - we're reading the state of a GPIO line. */
+ /**< Direction is input - for reading the value of an externally driven GPIO line. */
GPIOD_LINE_DIRECTION_OUTPUT
- /**< Direction is output - we're driving the GPIO line. */
+ /**< Direction is output - for driving the GPIO line. */
};
/**
@@ -250,7 +253,7 @@ enum {
GPIOD_LINE_EDGE_RISING,
/**< Line detects rising edge events. */
GPIOD_LINE_EDGE_FALLING,
- /**< Line detect falling edge events. */
+ /**< Line detects falling edge events. */
GPIOD_LINE_EDGE_BOTH
/**< Line detects both rising and falling edge events. */
};
@@ -274,8 +277,17 @@ enum {
* Functions for retrieving kernel information about both requested and free
* lines.
*
- * Line info object contains an immutable snapshot of the line's state at the
- * time when it was created.
+ * Line info object contains an immutable snapshot of a line's status.
+ *
+ * The line info contains all the publicly available information about a
+ * line, which does not include the line value. The line must be requested
+ * to access the line value.
+ *
+ * Some accessor methods return pointers. Those pointers refer to internal
+ * fields. The lifetimes of those fields are tied to the lifetime of the
+ * containing line info object.
+ * Such pointers remain valid until ::gpiod_line_info_free is called on the
+ * containing line info object. They must not be freed by the caller.
*/
/**
@@ -285,108 +297,116 @@ enum {
void gpiod_line_info_free(struct gpiod_line_info *info);
/**
- * @brief Copy the line info object.
+ * @brief Copy a line info object.
* @param info Line info to copy.
* @return Copy of the line info or NULL on error. The returned object must
- * be freed by the caller using :gpiod_line_info_free.
+ * be freed by the caller using :gpiod_line_info_free.
*/
struct gpiod_line_info *gpiod_line_info_copy(struct gpiod_line_info *info);
/**
- * @brief Get the hardware offset of the line.
+ * @brief Get the offset of the line.
* @param info GPIO line info object.
* @return Offset of the line within the parent chip.
+ *
+ * The offset uniquely identifies the line on the chip.
+ * The combination of the chip and offset uniquely identifies the line within
+ * the system.
*/
unsigned int gpiod_line_info_get_offset(struct gpiod_line_info *info);
/**
- * @brief Read the GPIO line name.
+ * @brief Get the name of the line.
* @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.
+ * @return Name of the GPIO line as it is represented in the kernel.
+ * This function returns a pointer to a null-terminated string
+ * or NULL if the line is unnamed.
*/
const char *gpiod_line_info_get_name(struct gpiod_line_info *info);
/**
- * @brief Check if the line is currently in use.
+ * @brief Check if the line is 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.
+ * The exact reason a line is busy cannot be determined from user space.
+ * It may have been requested by another process or hogged by the kernel.
+ * It only matters that the line is used and can't be requested until
+ * released by the existing consumer.
*/
bool gpiod_line_info_is_used(struct gpiod_line_info *info);
/**
- * @brief Read the GPIO line consumer name.
+ * @brief Get the name of the consumer of the line.
* @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.
+ * @return Name of the GPIO consumer as it is represented in the kernel.
+ * This function returns a pointer to a null-terminated string
+ * or NULL if the consumer name is not set.
*/
const char *gpiod_line_info_get_consumer(struct gpiod_line_info *info);
/**
- * @brief Read the GPIO line direction setting.
+ * @brief Get the direction setting of the line.
* @param info GPIO line info object.
- * @return Returns GPIOD_LINE_DIRECTION_INPUT or GPIOD_LINE_DIRECTION_OUTPUT.
+ * @return Returns ::GPIOD_LINE_DIRECTION_INPUT or
+ * ::GPIOD_LINE_DIRECTION_OUTPUT.
*/
int gpiod_line_info_get_direction(struct gpiod_line_info *info);
/**
- * @brief Check if the signal of this line is inverted.
+ * @brief Check if the logical value of the line is inverted compared to the
+ * physical.
* @param info GPIO line object.
- * @return True if this line is "active-low", false otherwise.
+ * @return True if the line is "active-low", false otherwise.
*/
bool gpiod_line_info_is_active_low(struct gpiod_line_info *info);
/**
- * @brief Read the GPIO line bias setting.
+ * @brief Get the bias setting of the line.
* @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.
+ * @return Returns ::GPIOD_LINE_BIAS_PULL_UP, ::GPIOD_LINE_BIAS_PULL_DOWN,
+ * ::GPIOD_LINE_BIAS_DISABLED or ::GPIOD_LINE_BIAS_UNKNOWN.
*/
int gpiod_line_info_get_bias(struct gpiod_line_info *info);
/**
- * @brief Read the GPIO line drive setting.
+ * @brief Get the drive setting of the line.
* @param info GPIO line info object.
- * @return Returns GPIOD_LINE_DRIVE_PUSH_PULL, GPIOD_LINE_DRIVE_OPEN_DRAIN or
- * GPIOD_LINE_DRIVE_OPEN_SOURCE.
+ * @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.
+ * @brief Get the edge detection setting of the 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.
+ * @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 Read the current event clock setting used for edge event timestamps.
+ * @brief Get the event clock setting used for edge event timestamps for the
+ * line.
* @param info GPIO line info object.
- * @return Returns GPIOD_LINE_EVENT_CLOCK_MONOTONIC or
- * GPIOD_LINE_EVENT_CLOCK_REALTIME.
+ * @return Returns ::GPIOD_LINE_EVENT_CLOCK_MONOTONIC or
+ * ::GPIOD_LINE_EVENT_CLOCK_REALTIME.
*/
int gpiod_line_info_get_event_clock(struct gpiod_line_info *info);
/**
- * @brief Check if this line is debounced (either by hardware or by the kernel
- * software debouncer).
+ * @brief Check if the 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.
+ * @brief Get the debounce period of the line, in microseconds.
* @param info GPIO line info object.
- * @return Current debounce period in microseconds, 0 if the line is not
- * debounced.
+ * @return Debounce period in microseconds.
+ * 0 if the line is not debounced.
*/
unsigned long
gpiod_line_info_get_debounce_period_us(struct gpiod_line_info *info);
@@ -398,11 +418,11 @@ gpiod_line_info_get_debounce_period_us(struct gpiod_line_info *info);
* @{
*
* Accessors for the info event objects allowing to monitor changes in GPIO
- * line state.
+ * line status.
*
- * Callers can be notified about changes in line's state using the interfaces
- * exposed by GPIO chips. Each info event contains information about the event
- * itself (timestamp, type) as well as a snapshot of line's state in the form
+ * Callers are notified about changes in a line's status due to GPIO uAPI
+ * calls. Each info event contains information about the event itself
+ * (timestamp, type) as well as a snapshot of line's status in the form
* of a line-info object.
*/
@@ -425,27 +445,27 @@ enum {
void gpiod_info_event_free(struct gpiod_info_event *event);
/**
- * @brief Get the event type of this status change event.
+ * @brief Get the event type of the 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.
+ * ::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.
+ * @return Timestamp in nanoseconds, read from the monotonic clock.
*/
uint64_t gpiod_info_event_get_timestamp(struct gpiod_info_event *event);
/**
- * @brief Get the pointer to the line-info object associated with this event.
+ * @brief Get the snapshot of line-info associated with the 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.
+ * @return Returns a pointer to the line-info object associated with the event
+ * whose lifetime is tied to the event object. It must not be freed by
+ * the caller.
*/
struct gpiod_line_info *
gpiod_info_event_get_line_info(struct gpiod_info_event *event);
@@ -458,39 +478,39 @@ gpiod_info_event_get_line_info(struct gpiod_info_event *event);
*
* Functions for manipulating line configuration objects.
*
- * The line-config object stores the configuration for lines that can be used
- * in two cases: when making a line request and when reconfiguring a set of
- * already requested lines.
+ * The line-config object contains the configuration for lines that can be
+ * used in two cases:
+ * - when making a line request
+ * - when reconfiguring a set of already requested lines.
*
- * A new line-config object is instantiated containing a set of sane defaults
+ * A new line-config object is instantiated with a set of sane defaults
* for all supported configuration settings. Those defaults can be modified by
* the caller. Default values can be overridden by applying different values
- * for specific line offsets. When making a request or reconfiguring an
- * existing one, the overridden settings for specific offsets will be taken
- * into account first and for every other offset and setting the defaults will
- * be used.
+ * for specific lines. When making a request or reconfiguring an existing one,
+ * the overridden settings for specific lines take precedance. For lines
+ * without an override the requested default settings are used.
*
* For every setting there are two mutators (one setting the default and one
- * for the per-offset override), two getters (one for reading the global
- * default and one for retrieving the effective value for the line at given
- * offset), a function for testing if a setting is overridden for the line at
- * given offset and finally a function for clearing the overrides (per offset).
+ * for the per-line override), two getters (one for reading the global
+ * default and one for retrieving the effective value for the line),
+ * a function for testing if a setting is overridden for the line
+ * and finally a function for clearing the overrides (per line).
*
* The mutators don't return errors. If the set of options is too complex to
- * be translated into kernel uAPI structures - the error will be returned at
+ * be translated into kernel uAPI structures then an error will be returned at
* the time of the request or reconfiguration. If an invalid value was passed
- * to any of the mutators - the default value will be silently used instead.
+ * to any of the mutators then the default value will be silently used instead.
*
- * Operating on offsets in struct line_config has no effect on real GPIOs. It
- * only manipulates the object in memory and is only applied to the hardware
- * at the time of the request or reconfiguration.
+ * Operating on lines in struct line_config has no immediate effect on real
+ * GPIOs, it only manipulates the config object in memory. Those changes are
+ * only applied to the hardware at the time of the request or reconfiguration.
*
- * Overrides set for offsets that don't end up being requested are silently
- * ignored both in ::gpiod_chip_request_lines as well as in
+ * Overrides for lines that don't end up being requested are silently ignored
+ * both in ::gpiod_chip_request_lines as well as in
* ::gpiod_line_request_reconfigure_lines.
*
- * In cases where all requested lines are using the global defaults, the
- * offsets can be entirely ignored when preparing the line configuration.
+ * In cases where all requested lines are using the one configuration, the
+ * line overrides can be entirely ignored when preparing the configuration.
*/
/**
@@ -509,13 +529,13 @@ void gpiod_line_config_free(struct gpiod_line_config *config);
* @brief Reset the line config object.
* @param config Line config object to free.
*
- * Resets the entire configuration stored in this object. This is useful if
+ * Resets the entire configuration stored in the object. This is useful if
* the user wants to reuse the object without reallocating it.
*/
void gpiod_line_config_reset(struct gpiod_line_config *config);
/**
- * @brief Set the default direction setting.
+ * @brief Set the default line direction.
* @param config Line config object.
* @param direction New direction.
*/
@@ -523,30 +543,30 @@ void gpiod_line_config_set_direction_default(struct gpiod_line_config *config,
int direction);
/**
- * @brief Set the direction override at given offset.
+ * @brief Set the direction override for a line.
* @param config Line config object.
* @param direction New direction.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void gpiod_line_config_set_direction_override(struct gpiod_line_config *config,
int direction,
unsigned int offset);
/**
- * @brief Clear the direction override at given offset.
+ * @brief Clear the direction override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void
gpiod_line_config_clear_direction_override(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the direction setting is overridden at given offset.
+ * @brief Check if the direction is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if direction is overridden at this offset, false otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if direction is overridden on the line, false otherwise.
*/
bool gpiod_line_config_direction_is_overridden(struct gpiod_line_config *config,
unsigned int offset);
@@ -554,18 +574,16 @@ bool gpiod_line_config_direction_is_overridden(struct gpiod_line_config *config,
/**
* @brief Get the default direction setting.
* @param config Line config object.
- * @return Direction setting that would have been used for any non-overridden
- * offset.
+ * @return Direction setting used for any non-overridden line.
*/
int gpiod_line_config_get_direction_default(struct gpiod_line_config *config);
/**
- * @brief Get the direction setting for the line at given offset.
+ * @brief Get the direction setting for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to read the direction setting.
- * @return Direction setting that would have been used for the line at given
- * offset if the config object was used in a request at the time of the
- * call.
+ * @param offset The offset of the line for which to read the direction.
+ * @return Direction setting for the line if the config object were used
+ * in a request.
*/
int gpiod_line_config_get_direction_offset(struct gpiod_line_config *config,
unsigned int offset);
@@ -580,30 +598,30 @@ gpiod_line_config_set_edge_detection_default(struct gpiod_line_config *config,
int edge);
/**
- * @brief Set the edge detection override at given offset.
+ * @brief Set the edge detection override for a line.
* @param config Line config object.
* @param edge Type of edge events to detect.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void
gpiod_line_config_set_edge_detection_override(struct gpiod_line_config *config,
int edge, unsigned int offset);
/**
- * @brief Clear the edge detection override at given offset.
+ * @brief Clear the edge detection override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void
gpiod_line_config_clear_edge_detection_override(
struct gpiod_line_config *config, unsigned int offset);
/**
- * @brief Check if the edge detection setting is overridden at given offset.
+ * @brief Check if the edge detection setting is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if edge detection is overridden at this offset, false otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if edge detection is overridden for the line, false otherwise.
*/
bool
gpiod_line_config_edge_detection_is_overridden(struct gpiod_line_config *config,
@@ -612,20 +630,18 @@ gpiod_line_config_edge_detection_is_overridden(struct gpiod_line_config *config,
/**
* @brief Get the default edge detection setting.
* @param config Line config object.
- * @return Edge detection setting that would have been used for any offset not
- * assigned its own direction value.
+ * @return Edge detection setting used for any non-overridden line.
*/
int
gpiod_line_config_get_edge_detection_default(struct gpiod_line_config *config);
/**
- * @brief Get the edge event detection setting for a given offset.
+ * @brief Get the edge event detection setting for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to read the edge event detection
- * setting.
- * @return Edge event detection setting that would have been used for given
- * offset if the config object was used in a request at the time of
- * the call.
+ * @param offset The offset of the line for which to read the edge event detection
+ * setting.
+ * @return Edge event detection setting for the line if the config object
+ * were used in a request.
*/
int
gpiod_line_config_get_edge_detection_offset(struct gpiod_line_config *config,
@@ -640,45 +656,44 @@ void gpiod_line_config_set_bias_default(struct gpiod_line_config *config,
int bias);
/**
- * @brief Set the bias override at given offset.
+ * @brief Set the bias override for a line.
* @param config Line config object.
* @param bias New bias setting.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void gpiod_line_config_set_bias_override(struct gpiod_line_config *config,
int bias, unsigned int offset);
/**
- * @brief Clear the bias override at given offset.
+ * @brief Clear the bias override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void gpiod_line_config_clear_bias_override(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the bias setting is overridden at given offset.
+ * @brief Check if the bias setting is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if bias is overridden at this offset, false otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if bias is overridden for the line, false otherwise.
*/
bool gpiod_line_config_bias_is_overridden(struct gpiod_line_config *config,
unsigned int offset);
/**
* @brief Get the default bias setting.
* @param config Line config object.
- * @return Bias setting that would have been used for any offset not assigned
- * its own direction value.
+ * @return Bias setting used for any non-overridden line.
*/
int gpiod_line_config_get_bias_default(struct gpiod_line_config *config);
/**
- * @brief Get the bias setting for a given offset.
+ * @brief Get the bias setting for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to read the bias setting.
- * @return Bias setting that would have been used for the line at given offset
- * if the config object was used in a request at the time of the call.
+ * @param offset The offset of the line for which to read the bias setting.
+ * @return Bias setting used for the line if the config object were used
+ * in a request.
*/
int gpiod_line_config_get_bias_offset(struct gpiod_line_config *config,
unsigned int offset);
@@ -692,28 +707,28 @@ void gpiod_line_config_set_drive_default(struct gpiod_line_config *config,
int drive);
/**
- * @brief Set the drive override at given offset.
+ * @brief Set the drive override for a line.
* @param config Line config object.
* @param drive New drive setting.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void gpiod_line_config_set_drive_override(struct gpiod_line_config *config,
int drive, unsigned int offset);
/**
- * @brief Clear the drive override at given offset.
+ * @brief Clear the drive override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void gpiod_line_config_clear_drive_override(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the drive setting is overridden at given offset.
+ * @brief Check if the drive setting is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if drive is overridden at this offset, false otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if drive is overridden for the line, false otherwise.
*/
bool gpiod_line_config_drive_is_overridden(struct gpiod_line_config *config,
unsigned int offset);
@@ -721,23 +736,22 @@ bool gpiod_line_config_drive_is_overridden(struct gpiod_line_config *config,
/**
* @brief Get the default drive setting.
* @param config Line config object.
- * @return Drive setting that would have been used for any offset not assigned
- * its own direction value.
+ * @return Drive setting for any non-overridden line.
*/
int gpiod_line_config_get_drive_default(struct gpiod_line_config *config);
/**
- * @brief Get the drive setting for a given offset.
+ * @brief Get the drive setting for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to read the drive setting.
- * @return Drive setting that would have been used for the line at given offset
- * if the config object was used in a request at the time of the call.
+ * @param offset The offset of the line for which to read the drive setting.
+ * @return Drive setting for the line if the config object were used in a
+ * request.
*/
int gpiod_line_config_get_drive_offset(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Set lines to active-low by default.
+ * @brief Set the default active-low setting.
* @param config Line config object.
* @param active_low New active-low setting.
*/
@@ -745,30 +759,30 @@ void gpiod_line_config_set_active_low_default(struct gpiod_line_config *config,
bool active_low);
/**
- * @brief Override the active-low setting at given offset.
+ * @brief Override the active-low setting for a line.
* @param config Line config object.
* @param active_low New active-low setting.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void gpiod_line_config_set_active_low_override(struct gpiod_line_config *config,
bool active_low,
unsigned int offset);
/**
- * @brief Clear the active-low override at given offset.
+ * @brief Clear the active-low override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void
gpiod_line_config_clear_active_low_override(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the active-low setting is overridden at given offset.
+ * @brief Check if the active-low setting is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if active-low is overridden at this offset, false otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if active-low is overridden for the line, false otherwise.
*/
bool
gpiod_line_config_active_low_is_overridden(struct gpiod_line_config *config,
@@ -777,18 +791,16 @@ gpiod_line_config_active_low_is_overridden(struct gpiod_line_config *config,
/**
* @brief Check if active-low is the default setting.
* @param config Line config object.
- * @return Active-low setting that would have been used for any offset not
- * assigned its own value.
+ * @return Active-low setting for any non-overridden line.
*/
bool gpiod_line_config_get_active_low_default(struct gpiod_line_config *config);
/**
- * @brief Check if the line at given offset was configured as active-low.
+ * @brief Check if a line is configured as active-low.
* @param config Line config object.
- * @param offset Offset of the line for which to read the active-low setting.
- * @return Active-low setting that would have been used for the line at given
- * offset if the config object was used in a request at the time of the
- * call.
+ * @param offset The offset of the line for which to read the active-low setting.
+ * @return Active-low setting for the line if the config object were used in
+ * a request.
*/
bool gpiod_line_config_get_active_low_offset(struct gpiod_line_config *config,
unsigned int offset);
@@ -796,16 +808,19 @@ bool gpiod_line_config_get_active_low_offset(struct gpiod_line_config *config,
/**
* @brief Set the default debounce period.
* @param config Line config object.
- * @param period New debounce period. Disables debouncing if 0.
+ * @param period New debounce period in microseconds. Disables debouncing if 0.
+ * @note Debouncing is only useful on input lines with edge detection.
+ * Its purpose is to filter spurious events due to noise during the
+ * edge transition. It has no effect on normal get or set operations.
*/
void gpiod_line_config_set_debounce_period_us_default(
struct gpiod_line_config *config, unsigned long period);
/**
- * @brief Override the debounce period setting at given offset.
+ * @brief Override the debounce period setting for a line.
* @param config Line config object.
* @param period New debounce period in microseconds.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void
gpiod_line_config_set_debounce_period_us_override(
@@ -814,21 +829,21 @@ gpiod_line_config_set_debounce_period_us_override(
unsigned int offset);
/**
- * @brief Clear the debounce period override at given offset.
+ * @brief Clear the debounce period override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void gpiod_line_config_clear_debounce_period_us_override(
struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the debounce period setting is overridden at given offset.
+ * @brief Check if the debounce period setting is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if debounce period is overridden at this offset, false
- * otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if debounce period is overridden for the line, false
+ * otherwise.
*/
bool gpiod_line_config_debounce_period_us_is_overridden(
struct gpiod_line_config *config,
@@ -837,19 +852,21 @@ bool gpiod_line_config_debounce_period_us_is_overridden(
/**
* @brief Get the default debounce period.
* @param config Line config object.
- * @return Debounce period that would have been used for any offset not
- * assigned its own debounce period. 0 if not debouncing is disabled.
+ * @return Debounce period for any non-overridden line.
+ * Measured in microseconds.
+ * 0 if debouncing is disabled.
*/
unsigned long gpiod_line_config_get_debounce_period_us_default(
struct gpiod_line_config *config);
/**
- * @brief Get the debounce period for a given offset.
+ * @brief Get the debounce period for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to read the debounce period.
- * @return Debounce period that would have been used for the line at given
- * offset if the config object was used in a request at the time of
- * the call. 0 if debouncing is disabled.
+ * @param offset The offset of the line for which to read the debounce period.
+ * @return Debounce period for the line if the config object were used in a
+ * request.
+ * Measured in microseconds.
+ * 0 if debouncing is disabled.
*/
unsigned long
gpiod_line_config_get_debounce_period_us_offset(
@@ -864,31 +881,31 @@ void gpiod_line_config_set_event_clock_default(struct gpiod_line_config *config,
int clock);
/**
- * @brief Override the event clock setting at given offset.
+ * @brief Override the event clock setting for a line.
* @param config Line config object.
* @param clock New event clock to use.
- * @param offset Offset of the line for which to set the override.
+ * @param offset The offset of the line for which to set the override.
*/
void
gpiod_line_config_set_event_clock_override(struct gpiod_line_config *config,
int clock, unsigned int offset);
/**
- * @brief Clear the event clock override at given offset.
+ * @brief Clear the event clock override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void
gpiod_line_config_clear_event_clock_override(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the event clock setting is overridden at given offset.
+ * @brief Check if the event clock setting is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if event clock period is overridden at this offset, false
- * otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if event clock period is overridden for the line, false
+ * otherwise.
*/
bool
gpiod_line_config_event_clock_is_overridden(struct gpiod_line_config *config,
@@ -897,18 +914,16 @@ gpiod_line_config_event_clock_is_overridden(struct gpiod_line_config *config,
/**
* @brief Get the default event clock setting.
* @param config Line config object.
- * @return Event clock setting that would have been used for any offset not
- * assigned its own direction value.
+ * @return Event clock setting for any non-overridden line.
*/
int gpiod_line_config_get_event_clock_default(struct gpiod_line_config *config);
/**
- * @brief Get the event clock setting for a given offset.
+ * @brief Get the event clock setting for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to read the event clock setting.
- * @return Event clock setting that would have been used for the line at given
- * offset if the config object was used in a request at the time of the
- * call.
+ * @param offset The offset of the line for which to read the event clock setting.
+ * @return Event clock setting for the line if the config object were used in a
+ * request.
*/
int gpiod_line_config_get_event_clock_offset(struct gpiod_line_config *config,
unsigned int offset);
@@ -917,15 +932,18 @@ int gpiod_line_config_get_event_clock_offset(struct gpiod_line_config *config,
* @brief Set the default output value.
* @param config Line config object.
* @param value New value.
+ *
+ * The default output value applies to all non-overridden output lines.
+ * It does not apply to input lines or overridden lines.
*/
void
gpiod_line_config_set_output_value_default(struct gpiod_line_config *config,
int value);
/**
- * @brief Override the output value for a single offset.
+ * @brief Override the output value for a line.
* @param config Line config object.
- * @param offset Offset of the line.
+ * @param offset The offset of the line for which to override the output value.
* @param value Output value to set.
*/
void
@@ -933,12 +951,13 @@ gpiod_line_config_set_output_value_override(struct gpiod_line_config *config,
unsigned int offset, int value);
/**
- * @brief Override the output values for multiple offsets.
+ * @brief Override the output values for multiple lines.
* @param config Line config object.
* @param num_lines Number of lines for which to override values.
- * @param offsets Array of line offsets to override values for.
- * @param values Array of output values associated with the offsets passed in
- * the previous argument.
+ * @param offsets Array of offsets indentifying the lines for which to override
+ * values, containing \p num_lines entries.
+ * @param values Array of output values corresponding to the lines identified in
+ * \p offsets, also containing \p num_lines entries.
*/
void gpiod_line_config_set_output_values(struct gpiod_line_config *config,
size_t num_lines,
@@ -946,21 +965,20 @@ void gpiod_line_config_set_output_values(struct gpiod_line_config *config,
const int *values);
/**
- * @brief Clear the output value override at given offset.
+ * @brief Clear the output value override for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to clear the override.
- * @note Does nothing if no override is set for this line.
+ * @param offset The offset of the line for which to clear the override.
+ * @note Does nothing if no override is set for the line.
*/
void
gpiod_line_config_clear_output_value_override(struct gpiod_line_config *config,
unsigned int offset);
/**
- * @brief Check if the output value is overridden at given offset.
+ * @brief Check if the output value is overridden for a line.
* @param config Line config object.
- * @param offset Offset of the line for which to check the override.
- * @return True if output value period is overridden at this offset, false
- * otherwise.
+ * @param offset The offset of the line to check for the override.
+ * @return True if output value is overridden for the line, false otherwise.
*/
bool
gpiod_line_config_output_value_is_overridden(struct gpiod_line_config *config,
@@ -969,18 +987,17 @@ gpiod_line_config_output_value_is_overridden(struct gpiod_line_config *config,
/**
* @brief Get the default output value.
* @param config Line config object.
- * @return Output value that would have been used for any offset not
- * assigned its own output value.
+ * @return Output value for any non-overridden line.
*/
int
gpiod_line_config_get_output_value_default(struct gpiod_line_config *config);
/**
- * @brief Get the output value configured for a given line.
+ * @brief Get the configured output value for a line.
* @param config Line config object.
* @param offset Line offset for which to read the value.
- * @return Output value that would have been used for the line at given offset
- * if the config object was used in a request at the time of the call.
+ * @return Output value for the line if the config object were used in a
+ * request.
*/
int gpiod_line_config_get_output_value_offset(struct gpiod_line_config *config,
unsigned int offset);
@@ -1012,8 +1029,8 @@ enum {
};
/**
- * @brief Get the total number of overridden settings currently stored by this
- * line config object.
+ * @brief Get the total number of overridden settings stored in the line config
+ * object.
* @param config Line config object.
* @return Number of individual overridden settings.
*/
@@ -1021,17 +1038,17 @@ size_t gpiod_line_config_get_num_overrides(struct gpiod_line_config *config);
/**
* @brief Get the list of overridden offsets and the corresponding types of
- * overridden settings.
+ * overridden settings.
* @param config Line config object.
- * @param offsets Array to store the overidden offsets. Must hold at least the
- * number of unsigned integers returned by
- * ::gpiod_line_config_get_num_overrides.
- * @param props Array to store the types of overridden settings. Must hold at
- * least the number of integers returned by
- * ::gpiod_line_config_get_num_overrides.
+ * @param offsets Array to store the overidden offsets. Must be sized to hold
+ * the number of unsigned integers returned by
+ * ::gpiod_line_config_get_num_overrides.
+ * @param props Array to store the types of overridden settings. Must be sized
+ * to hold the number of integers returned by
+ * ::gpiod_line_config_get_num_overrides.
*
- * The overridden offsets are stored in the offsets array with the array index
- * corresponding with the property stored in the props array at the same index.
+ * The overridden (offset, prop) pairs are stored in the \p offsets and
+ * \p props arrays, with the pairs having the same index.
*/
void
gpiod_line_config_get_overrides(struct gpiod_line_config *config,
@@ -1045,10 +1062,10 @@ gpiod_line_config_get_overrides(struct gpiod_line_config *config,
*
* Functions for manipulating request configuration objects.
*
- * Request config object is used to pass a set of options to the kernel at the
- * time of the line request. Similarly to the line-config - the mutators don't
- * return error values. If the values are invalid, in general they are silently
- * adjusted to acceptable ranges.
+ * Request config objects are used to pass a set of options to the kernel at
+ * the time of the line request. Similarly to the line-config - the mutators
+ * don't return error values. If the values are invalid, in general they are
+ * silently adjusted to acceptable ranges.
*/
/**
@@ -1064,7 +1081,7 @@ struct gpiod_request_config *gpiod_request_config_new(void);
void gpiod_request_config_free(struct gpiod_request_config *config);
/**
- * @brief Set the consumer string.
+ * @brief Set the consumer name for the request.
* @param config Request config object.
* @param consumer Consumer name.
* @note If the consumer string is too long, it will be truncated to the max
@@ -1074,57 +1091,60 @@ void gpiod_request_config_set_consumer(struct gpiod_request_config *config,
const char *consumer);
/**
- * @brief Get the consumer string.
+ * @brief Get the consumer name configured in the request config.
* @param config Request config object.
- * @return Current consumer string stored in this request config.
+ * @return Consumer name stored in the request config.
*/
const char *
gpiod_request_config_get_consumer(struct gpiod_request_config *config);
/**
- * @brief Set line offsets for this request.
+ * @brief Set the offsets of the lines to be requested.
* @param config Request config object.
- * @param num_offsets Number of offsets.
- * @param offsets Array of line offsets.
- * @note If too many offsets were specified, the offsets above the limit
+ * @param num_lines Number of lines, which specifies the size of the offsets
+ * array.
+ * @param offsets Array of offsets of the lines.
+ * @note If too many lines were specified, the offsets above the limit
* accepted by the kernel (64 lines) are silently dropped.
*/
void gpiod_request_config_set_offsets(struct gpiod_request_config *config,
- size_t num_offsets,
+ size_t num_lines,
const unsigned int *offsets);
/**
- * @brief Get the number of lines configured in this request config.
+ * @brief Get the number of lines configured in the request config.
* @param config Request config object.
- * @return Number of lines to be requested by this config.
+ * @return Number of lines to be requested by the config.
*/
size_t
gpiod_request_config_get_num_lines(struct gpiod_request_config *config);
/**
- * @brief Get the hardware offsets of lines in this request config.
+ * @brief Get the offsets of lines configured in the request config.
* @param config Request config object.
- * @param offsets Array to store offsets. Must hold at least the number of
- * lines returned by ::gpiod_request_config_get_num_offsets.
+ * @param offsets Array to store offsets. Must be sized to hold the number of
+ * lines returned by ::gpiod_request_config_get_num_lines.
*/
void gpiod_request_config_get_offsets(struct gpiod_request_config *config,
- unsigned int *offsets);
+ unsigned int *offsets);
/**
- * @brief Set the size of the kernel event buffer.
+ * @brief Set the size of the kernel event buffer for the request.
* @param config Request config object.
* @param event_buffer_size New event buffer size.
* @note The kernel may adjust the value if it's too high. If set to 0, the
* default value will be used.
+ * @note The kernel buffer is distinct from and independent of the user space
+ * buffer (::gpiod_edge_event_buffer_new).
*/
void
gpiod_request_config_set_event_buffer_size(struct gpiod_request_config *config,
size_t event_buffer_size);
/**
- * @brief Get the edge event buffer size from this request config.
+ * @brief Get the edge event buffer size for the request config.
* @param config Request config object.
- * @return Current edge event buffer size setting.
+ * @return Edge event buffer size setting from the request config.
*/
size_t
gpiod_request_config_get_event_buffer_size(struct gpiod_request_config *config);
@@ -1135,7 +1155,7 @@ gpiod_request_config_get_event_buffer_size(struct gpiod_request_config *config);
* @defgroup request_request Line request operations
* @{
*
- * Functions allowing interaction with a set of requested lines.
+ * Functions allowing interactions with requested lines.
*/
/**
@@ -1145,37 +1165,39 @@ gpiod_request_config_get_event_buffer_size(struct gpiod_request_config *config);
void gpiod_line_request_release(struct gpiod_line_request *request);
/**
- * @brief Get the number of lines in this request.
+ * @brief Get the number of lines in the request.
* @param request Line request object.
* @return Number of requested lines.
*/
size_t gpiod_line_request_get_num_lines(struct gpiod_line_request *request);
/**
- * @brief Get the hardware offsets of lines in this request.
+ * @brief Get the offsets of the lines in the request.
* @param request Line request object.
- * @param offsets Array to store offsets. Must hold at least the number of
- * lines returned by ::gpiod_line_request_get_num_lines.
+ * @param offsets Array to store offsets. Must be sized to hold the number of
+ * lines returned by ::gpiod_line_request_get_num_lines.
*/
void gpiod_line_request_get_offsets(struct gpiod_line_request *request,
unsigned int *offsets);
/**
- * @brief Read the value of a single line associated with this request.
+ * @brief Get the value of a single requested line.
* @param request Line request object.
- * @param offset Offset of the line of which the value should be read.
+ * @param offset The 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_request_get_value(struct gpiod_line_request *request,
unsigned int offset);
/**
- * @brief Read values of a subset of lines associated with this request.
+ * @brief Get the values of a subset of requested lines.
* @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.
+ * @param offsets Array of offsets identifying the subset of requested lines
+ * from which to read values.
+ * @param values Array in which the values will be stored. Must be sized
+ * to hold \p num_lines entries. Each value is associated with the
+ * line identified by the corresponding entry in \p offsets.
* @return 0 on success, -1 on failure.
*/
int gpiod_line_request_get_values_subset(struct gpiod_line_request *request,
@@ -1184,35 +1206,38 @@ int gpiod_line_request_get_values_subset(struct gpiod_line_request *request,
int *values);
/**
- * @brief Read values of all lines associated with this request.
+ * @brief Get the values of all requested lines.
* @param request GPIO line request.
- * @param values Array in which the values will be stored. Must hold at least
- * the number of lines returned by
- * ::gpiod_line_request_get_num_lines. The index of each value
- * will be associated with the offset at the same index in the
- * offset array returned by ::gpiod_line_request_get_offsets.
+ * @param values Array in which the values will be stored. Must be sized to
+ * hold the number of lines returned by
+ * ::gpiod_line_request_get_num_lines.
+ * Each value is associated with the line identified by the
+ * corresponding entry in the offset array returned by
+ * ::gpiod_line_request_get_offsets.
* @return 0 on success, -1 on failure.
*/
int gpiod_line_request_get_values(struct gpiod_line_request *request,
int *values);
/**
- * @brief Set the value of a single line associated with this request.
+ * @brief Set the value of a single requested line.
* @param request Line request object.
- * @param offset Offset of the line of which the value should be set.
+ * @param offset The offset of the line for which the value should be set.
* @param value Value to set.
*/
int gpiod_line_request_set_value(struct gpiod_line_request *request,
unsigned int offset, int value);
/**
- * @brief Set values of a subset of lines associated with this line request.
+ * @brief Set the values of a subset of requested lines.
* @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.
+ * @param offsets Array of offsets, containing the number of entries specified
+ * by \p num_lines, identifying the requested lines for
+ * which to set values.
+ * @param values Array of values to set, containing the number of entries
+ * specified by \p num_lines. Each value is associated with the
+ * line identified by the corresponding entry in \p offsets.
* @return 0 on success, -1 on failure.
*/
int gpiod_line_request_set_values_subset(struct gpiod_line_request *request,
@@ -1221,42 +1246,51 @@ int gpiod_line_request_set_values_subset(struct gpiod_line_request *request,
const int *values);
/**
- * @brief Set values of all lines associated with this request.
+ * @brief Set the values of all lines associated with a request.
* @param request GPIO line request.
- * @param values Array containing the values to set. Must hold at least the
- * number of lines returned by ::gpiod_line_request_get_num_lines.
- * The index of each value be associated with the offset at the
- * same index in the offset array returned by
- * ::gpiod_line_request_get_offsets.
+ * @param values Array containing the values to set. Must be sized to
+ * contain the number of lines returned by
+ * ::gpiod_line_request_get_num_lines.
+ * Each value is associated with the line identified by the
+ * corresponding entry in the offset array returned by
+ * ::gpiod_line_request_get_offsets.
*/
int gpiod_line_request_set_values(struct gpiod_line_request *request,
const int *values);
/**
- * @brief Update the configuration of lines associated with this line request.
+ * @brief Update the configuration of lines associated with a line request.
* @param request GPIO line request.
* @param config New line config to apply.
* @return 0 on success, -1 on failure.
- * @note Line configuration overrides set for offsets that don't end up being
- * requested are silently ignored.
+ * @note The new line configuration completely replaces the old.
+ * @note Any requested lines without overrides are configured to the requested
+ * defaults.
+ * @note Any configured overrides for lines that have not been requested
+ * are silently ignored.
*/
int gpiod_line_request_reconfigure_lines(struct gpiod_line_request *request,
struct gpiod_line_config *config);
/**
- * @brief Get the file descriptor associated with this line request.
+ * @brief Get the file descriptor associated with a line request.
* @param request GPIO line request.
- * @return Number of the file descriptor associated with this request. This
- * function never fails.
+ * @return The file descriptor associated with the request.
+ * This function never fails.
+ * The returned file descriptor must not be closed by the caller.
+ * Call ::gpiod_line_request_release to close the file.
*/
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.
+ * @brief Wait for edge events on any of the requested lines.
* @param request GPIO line request.
* @param timeout_ns Wait time limit in nanoseconds.
* @return 0 if wait timed out, -1 if an error occurred, 1 if an event is
- * pending.
+ * pending.
+ *q
+ * Lines must have edge detection set for edge events to be emitted.
+ * By default edge detection is disabled.
*/
int gpiod_line_request_wait_edge_event(struct gpiod_line_request *request,
uint64_t timeout_ns);
@@ -1264,11 +1298,13 @@ int gpiod_line_request_wait_edge_event(struct gpiod_line_request *request,
/**
* @brief Read a number of edge events from a line request.
* @param request GPIO line request.
- * @param buffer Edge event buffer.
+ * @param buffer Edge event buffer, sized to hold at least \p max_events.
* @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.
+ * descriptor, on failure return -1.
+ * @note This function will block if no event was queued for the line request.
+ * @note Any exising events in the buffer are overwritten. This is not an
+ * append operation.
*/
int gpiod_line_request_read_edge_event(struct gpiod_line_request *request,
struct gpiod_edge_event_buffer *buffer,
@@ -1282,13 +1318,14 @@ int gpiod_line_request_read_edge_event(struct gpiod_line_request *request,
*
* Functions and data types for handling edge events.
*
- * An edge event object contains information about a single line event. It
- * contains the event type, timestamp and the offset of the line on which the
- * event occurred as well as two seqential numbers (global for all lines
- * associated with the parent chip and local for this line only).
+ * An edge event object contains information about a single line edge event.
+ * It contains the event type, timestamp and the offset of the line on which
+ * the event occurred as well as two sequence numbers (global for all lines
+ * in the associated request and local for this line only).
*
- * For performance and to limit the number of memory allocations when a lot of
- * events are being read, edge events are stored in an edge-event buffer object.
+ * Edge events are stored into an edge-event buffer object to improve
+ * performance and to limit the number of memory allocations when a large
+ * number of events are being read.
*/
/**
@@ -1311,7 +1348,7 @@ void gpiod_edge_event_free(struct gpiod_edge_event *event);
* @brief Copy the edge event object.
* @param event Edge event to copy.
* @return Copy of the edge event or NULL on error. The returned object must
- * be freed by the caller using :gpiod_edge_event_free.
+ * be freed by the caller using ::gpiod_edge_event_free.
*/
struct gpiod_edge_event *gpiod_edge_event_copy(struct gpiod_edge_event *event);
@@ -1319,7 +1356,7 @@ struct gpiod_edge_event *gpiod_edge_event_copy(struct gpiod_edge_event *event);
* @brief Get the event type.
* @param event GPIO edge event.
* @return The event type (::GPIOD_EDGE_EVENT_RISING_EDGE or
- * ::GPIOD_EDGE_EVENT_FALLING_EDGE).
+ * ::GPIOD_EDGE_EVENT_FALLING_EDGE).
*/
int gpiod_edge_event_get_event_type(struct gpiod_edge_event *event);
@@ -1327,45 +1364,52 @@ int gpiod_edge_event_get_event_type(struct gpiod_edge_event *event);
* @brief Get the timestamp of the event.
* @param event GPIO edge event.
* @return Timestamp in nanoseconds.
+ * @note The source clock for the timestamp depends on the event_clock
+ * setting for the line.
*/
uint64_t gpiod_edge_event_get_timestamp(struct gpiod_edge_event *event);
/**
- * @brief Get the hardware offset of the line on which the event was triggered.
+ * @brief Get the offset of the line which triggered the event.
* @param event GPIO edge event.
* @return Line offset.
*/
unsigned int gpiod_edge_event_get_line_offset(struct gpiod_edge_event *event);
/**
- * @brief Get the global sequence number of this event.
+ * @brief Get the global sequence number of the event.
* @param event GPIO edge event.
- * @return Sequence number of the event relative to all lines in the associated
- * line request.
+ * @return Sequence number of the event in the series of events for all lines
+ * in the associated line request.
*/
unsigned long gpiod_edge_event_get_global_seqno(struct gpiod_edge_event *event);
/**
- * @brief Get the event sequence number specific to concerned line.
+ * @brief Get the event sequence number specific to the line.
* @param event GPIO edge event.
- * @return Sequence number of the event relative to this line within the
- * lifetime of the associated line request.
+ * @return Sequence number of the event in the series of events only for this
+ * line within the lifetime of the associated line request.
*/
unsigned long 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).
+ * @param capacity Number of events the buffer can store (min = 1, max = 1024).
* @return New edge event buffer or NULL on error.
* @note If capacity equals 0, it will be set to a default value of 64. If
- * capacity is larger than 1024, it will be limited to 1024.
+ * capacity is larger than 1024, it will be limited to 1024.
+ * @note The user space buffer is independent of the kernel buffer
+ * (::gpiod_request_config_set_event_buffer_size). As the user space
+ * buffer is filled from the kernel buffer, there is no benefit making
+ * the user space buffer larger than the kernel buffer.
+ * The default kernel buffer size for each request is 16*num_lines.
*/
struct gpiod_edge_event_buffer *
gpiod_edge_event_buffer_new(size_t capacity);
/**
* @brief Get the capacity (the max number of events that can be stored) of
- * the event buffer.
+ * the event buffer.
* @param buffer Edge event buffer.
* @return The capacity of the buffer.
*/
@@ -1379,21 +1423,21 @@ gpiod_edge_event_buffer_get_capacity(struct gpiod_edge_event_buffer *buffer);
void gpiod_edge_event_buffer_free(struct gpiod_edge_event_buffer *buffer);
/**
- * @brief Get a pointer to an event stored in the buffer.
+ * @brief Get an event stored in the buffer.
* @param buffer Edge 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 free the event
- * returned by this function.
+ * @return Pointer to an event stored in the buffer. The lifetime of the
+ * event is tied to the buffer object. Users must not free the event
+ * returned by this function.
*/
struct gpiod_edge_event *
gpiod_edge_event_buffer_get_event(struct gpiod_edge_event_buffer *buffer,
unsigned long index);
/**
- * @brief Get the number of events this buffers stores.
+ * @brief Get the number of events a buffer has stored.
* @param buffer Edge event buffer.
- * @return Number of events stored in this buffer.
+ * @return Number of events stored in the buffer.
*/
size_t
gpiod_edge_event_buffer_get_num_events(struct gpiod_edge_event_buffer *buffer);
@@ -1410,8 +1454,8 @@ gpiod_edge_event_buffer_get_num_events(struct gpiod_edge_event_buffer *buffer);
/**
* @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.
+ * @return True if the file exists and is either a GPIO chip character device
+ * or a symbolic link to one.
*/
bool gpiod_is_gpiochip_device(const char *path);
A collection of tweaks to the API documentation in gpiod.h Signed-off-by: Kent Gibson <warthog618@gmail.com> --- include/gpiod.h | 702 +++++++++++++++++++++++++----------------------- 1 file changed, 373 insertions(+), 329 deletions(-)