From: Bartosz Golaszewski Date: Tue, 24 Oct 2017 09:31:16 +0000 (+0200) Subject: doc: extend the documentation of the simple API X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=5808092cbc284b44a95598e9b4f92e9c1c0f104c;p=qemu-gpiodev%2Flibgpiod.git doc: extend the documentation of the simple API Fix some minor issues and tweak the style and doxygen markup. Describe in detail the way the simple event loop works. Signed-off-by: Bartosz Golaszewski --- diff --git a/include/gpiod.h b/include/gpiod.h index b1050f6..24a39e3 100644 --- a/include/gpiod.h +++ b/include/gpiod.h @@ -82,8 +82,8 @@ struct gpiod_chip_iter; /** * @brief Read current value from a single GPIO line. - * @param device Name, path or number of the gpiochip. - * @param offset GPIO line offset on the chip. + * @param device Name, path, number or label of the gpiochip. + * @param offset Offset of the GPIO line. * @param active_low The active state of this line - true if low. * @param consumer Name of the consumer. * @return 0 or 1 (GPIO value) if the operation succeeds, -1 on error. @@ -93,9 +93,9 @@ int gpiod_simple_get_value(const char *device, unsigned int offset, /** * @brief Read current values from a set of GPIO lines. - * @param device Name, path or number of the gpiochip. - * @param offsets An array of offsets of lines whose values should be read. - * @param values A buffer in which the values will be stored. + * @param device Name, path, number or label of the gpiochip. + * @param offsets Array of offsets of lines whose values should be read. + * @param values Buffer in which the values will be stored. * @param num_lines Number of lines, must be > 0. * @param active_low The active state of the lines - true if low. * @param consumer Name of the consumer. @@ -113,9 +113,9 @@ typedef void (*gpiod_simple_set_value_cb)(void *); /** * @brief Set value of a single GPIO line. - * @param device Name, path or number of the gpiochip. - * @param offset GPIO line offset on the chip. - * @param value New value. + * @param device Name, path, number or label of the gpiochip. + * @param offset The offset of the GPIO line. + * @param value New value (0 or 1). * @param active_low The active state of this line - true if low. * @param consumer Name of the consumer. * @param cb Callback function that will be called right after the value is @@ -130,14 +130,14 @@ int gpiod_simple_set_value(const char *device, unsigned int offset, int value, /** * @brief Set values of a set of a set of GPIO lines. - * @param device Name, path or number of the gpiochip. - * @param offsets An array of offsets of lines whose values should be set. - * @param values An array of integers containing new values. + * @param device Name, path, number or label of the gpiochip. + * @param offsets Array of offsets of lines whose values should be set. + * @param values Array of integers containing new values. * @param num_lines Number of lines, must be > 0. * @param active_low The active state of the lines - true if low. * @param consumer Name of the consumer. * @param cb Callback function that will be called right after the values are - * set. + * set. Works the same as in ::gpiod_simple_set_value. * @param data User data that will be passed to the callback function. * @return 0 if the operation succeeds, -1 on error. */ @@ -178,6 +178,10 @@ enum { * The callback function takes the following arguments: event type (int), * GPIO line offset (unsigned int), event timestamp (const struct timespec *) * and a pointer to user data (void *). + * + * This callback is called by the simple event loop functions for each GPIO + * event. If the callback returns ::GPIOD_SIMPLE_EVENT_CB_RET_ERR, it should + * also set errno. */ typedef int (*gpiod_simple_event_handle_cb)(int, unsigned int, const struct timespec *, void *); @@ -225,18 +229,18 @@ typedef int (*gpiod_simple_event_poll_cb)(unsigned int, /** * @brief Wait for events on a single GPIO line. - * @param device Name, path or number of the gpiochip. + * @param device Name, path, number or label of the gpiochip. * @param offset GPIO line offset to monitor. * @param active_low The active state of this line - true if low. * @param consumer Name of the consumer. * @param timeout Maximum wait time for each iteration. * @param poll_cb Callback function to call when waiting for events. - * @param event_cb Callback function to call on event occurrence. + * @param event_cb Callback function to call for each line event. * @param data User data passed to the callback. - * @return 0 no errors were encountered, -1 if an error occurred. - * - * The poll callback can be NULL in which case the routine will fall back to - * a basic, ppoll() based callback. + * @return 0 if no errors were encountered, -1 if an error occurred. + * @note The way the simple event loop works is described in detail in + * ::gpiod_simple_event_loop_multiple - this is just a wrapper aound + * this routine which calls it for a single GPIO line. */ int gpiod_simple_event_loop(const char *device, unsigned int offset, bool active_low, const char *consumer, @@ -247,7 +251,7 @@ int gpiod_simple_event_loop(const char *device, unsigned int offset, /** * @brief Wait for events on multiple GPIO lines. - * @param device Name, path or number of the gpiochip. + * @param device Name, path, number or label of the gpiochip. * @param offsets Array of GPIO line offsets to monitor. * @param num_lines Number of lines to monitor. * @param active_low The active state of this line - true if low. @@ -257,8 +261,20 @@ int gpiod_simple_event_loop(const char *device, unsigned int offset, * @param event_cb Callback function to call on event occurrence. * @param data User data passed to the callback. * @return 0 no errors were encountered, -1 if an error occurred. + * @note The poll callback can be NULL in which case the routine will fall + * back to a basic, ppoll() based callback. + * + * Internally this routine opens the GPIO chip, requests the set of lines for + * both-edges events and calls the polling callback in a loop. The role of the + * polling callback is to detect input events on a set of file descriptors and + * notify the caller about the fds ready for reading. * - * The callback functions work just like in the single line variant. + * The simple event loop then reads each queued event from marked descriptors + * and calls the event callback. Both callbacks can stop the loop at any + * point. + * + * The poll_cb argument can be NULL in which case the function falls back to + * a default, ppoll() based callback. */ int gpiod_simple_event_loop_multiple(const char *device, const unsigned int *offsets, @@ -278,8 +294,7 @@ int gpiod_simple_event_loop_multiple(const char *device, * @return -1 on error, 0 if the line with given name doesn't exist and 1 if * the line was found. In the first two cases the contents of chipname * and offset remain unchanged. - * - * The chip name is truncated if the buffer can't hold its entire size. + * @note The chip name is truncated if the buffer can't hold its entire size. */ int gpiod_simple_find_line(const char *name, char *chipname, size_t chipname_size,