From: Bartosz Golaszewski Date: Mon, 2 Oct 2017 13:04:12 +0000 (+0200) Subject: doc: split the documentation for GPIO lines into smaller chunks X-Git-Url: http://git.maquefel.me/?a=commitdiff_plain;h=8eb243de969960539711e353ae445f15d17a5f21;p=qemu-gpiodev%2Flibgpiod.git doc: split the documentation for GPIO lines into smaller chunks Create separate sections for bulk, info, requests, values, events and misc routines and data structures for GPIO lines. Signed-off-by: Bartosz Golaszewski --- diff --git a/include/gpiod.h b/include/gpiod.h index 2e23b5c..6e13c64 100644 --- a/include/gpiod.h +++ b/include/gpiod.h @@ -366,58 +366,11 @@ gpiod_chip_find_line(struct gpiod_chip *chip, const char *name) GPIOD_API; * @{ * * Functions and data structures dealing with GPIO lines. + * + * @defgroup __line_bulk__ Operating on multiple lines + * @{ */ -/** - * @brief Available types of requests. - */ -enum { - GPIOD_LINE_REQUEST_DIRECTION_AS_IS, - /**< Request the line(s), but don't change current direction. */ - GPIOD_LINE_REQUEST_DIRECTION_INPUT, - /**< Request the line(s) for reading the GPIO line state. */ - GPIOD_LINE_REQUEST_DIRECTION_OUTPUT, - /**< Request the line(s) for setting the GPIO line state. */ - GPIOD_LINE_REQUEST_EVENT_FALLING_EDGE, - /**< Monitor both types of events. */ - GPIOD_LINE_REQUEST_EVENT_RISING_EDGE, - /**< Only watch rising edge events. */ - GPIOD_LINE_REQUEST_EVENT_BOTH_EDGES, - /**< Only watch falling edge events. */ -}; - -/** - * @brief Miscellaneous GPIO flags. - */ -enum { - GPIOD_LINE_REQUEST_OPEN_DRAIN = GPIOD_BIT(0), - /**< The line is an open-drain port. */ - GPIOD_LINE_REQUEST_OPEN_SOURCE = GPIOD_BIT(1), - /**< The line is an open-source port. */ - GPIOD_LINE_REQUEST_ACTIVE_LOW = GPIOD_BIT(2), - /**< The active state of the line is low (high is the default). */ -}; - -/** - * @brief Possible direction settings. - */ -enum { - GPIOD_LINE_DIRECTION_INPUT, - /**< Direction is input - we're reading the state of a GPIO line. */ - GPIOD_LINE_DIRECTION_OUTPUT, - /**< Direction is output - we're driving the GPIO line. */ -}; - -/** - * @brief Possible active state settings. - */ -enum { - GPIOD_LINE_ACTIVE_STATE_HIGH, - /**< The active state of a GPIO is active-high. */ - GPIOD_LINE_ACTIVE_STATE_LOW, - /**< The active state of a GPIO is active-low. */ -}; - /** * @brief Maximum number of GPIO lines that can be requested at once. */ @@ -478,6 +431,33 @@ gpiod_line_bulk_get_line(struct gpiod_line_bulk *bulk, unsigned int offset) return bulk->lines[offset]; } +/** + * @} + * + * @defgroup __line_info__ Line info + * @{ + */ + +/** + * @brief Possible direction settings. + */ +enum { + GPIOD_LINE_DIRECTION_INPUT, + /**< Direction is input - we're reading the state of a GPIO line. */ + GPIOD_LINE_DIRECTION_OUTPUT, + /**< Direction is output - we're driving the GPIO line. */ +}; + +/** + * @brief Possible active state settings. + */ +enum { + GPIOD_LINE_ACTIVE_STATE_HIGH, + /**< The active state of a GPIO is active-high. */ + GPIOD_LINE_ACTIVE_STATE_LOW, + /**< The active state of a GPIO is active-low. */ +}; + /** * @brief Read the GPIO line offset. * @param line GPIO line object. @@ -569,6 +549,43 @@ int gpiod_line_update(struct gpiod_line *line) GPIOD_API; */ bool gpiod_line_needs_update(struct gpiod_line *line) GPIOD_API; +/** + * @} + * + * @defgroup __line_request__ Line requests + * @{ + */ + +/** + * @brief Available types of requests. + */ +enum { + GPIOD_LINE_REQUEST_DIRECTION_AS_IS, + /**< Request the line(s), but don't change current direction. */ + GPIOD_LINE_REQUEST_DIRECTION_INPUT, + /**< Request the line(s) for reading the GPIO line state. */ + GPIOD_LINE_REQUEST_DIRECTION_OUTPUT, + /**< Request the line(s) for setting the GPIO line state. */ + GPIOD_LINE_REQUEST_EVENT_FALLING_EDGE, + /**< Monitor both types of events. */ + GPIOD_LINE_REQUEST_EVENT_RISING_EDGE, + /**< Only watch rising edge events. */ + GPIOD_LINE_REQUEST_EVENT_BOTH_EDGES, + /**< Only watch falling edge events. */ +}; + +/** + * @brief Miscellaneous GPIO request flags. + */ +enum { + GPIOD_LINE_REQUEST_OPEN_DRAIN = GPIOD_BIT(0), + /**< The line is an open-drain port. */ + GPIOD_LINE_REQUEST_OPEN_SOURCE = GPIOD_BIT(1), + /**< The line is an open-source port. */ + GPIOD_LINE_REQUEST_ACTIVE_LOW = GPIOD_BIT(2), + /**< The active state of the line is low (high is the default). */ +}; + /** * @brief Structure holding configuration of a line request. */ @@ -851,6 +868,13 @@ bool gpiod_line_is_requested(struct gpiod_line *line) GPIOD_API; */ bool gpiod_line_is_free(struct gpiod_line *line) GPIOD_API; +/** + * @} + * + * @defgroup __line_value__ Reading & setting line values + * @{ + */ + /** * @brief Read current value of a single GPIO line. * @param line GPIO line object. @@ -896,46 +920,11 @@ int gpiod_line_set_value_bulk(struct gpiod_line_bulk *bulk, int *values) GPIOD_API; /** - * @brief Get a GPIO line handle by GPIO chip description and offset. - * @param device String describing the gpiochip. - * @param offset The offset of the GPIO line. - * @return GPIO line handle or NULL if an error occurred. - * - * This routine provides a shorter alternative to calling - * ::gpiod_chip_open_lookup and ::gpiod_chip_get_line. - * - * If this function succeeds, the caller is responsible for closing the - * associated GPIO chip. - */ -struct gpiod_line * -gpiod_line_get(const char *device, unsigned int offset) GPIOD_API; - -/** - * @brief Find a GPIO line by its name. - * @param name Name of the GPIO line. - * @return Returns the GPIO line handle if the line exists in the system or - * NULL if it couldn't be located or an error occurred. - * - * If this routine succeeds, the user must manually close the GPIO chip owning - * this line to avoid memory leaks. If the line could not be found, this - * functions sets errno to ENOENT. - */ -struct gpiod_line * gpiod_line_find(const char *name) GPIOD_API; - -/** - * @brief Close a GPIO chip owning this line and release all resources. - * @param line GPIO line object + * @} * - * After this function returns, the line must no longer be used. - */ -void gpiod_line_close_chip(struct gpiod_line *line) GPIOD_API; - -/** - * @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. + * @defgroup __line_event__ Line events handling + * @{ */ -struct gpiod_chip * gpiod_line_get_chip(struct gpiod_line *line) GPIOD_API; /** * @brief Event types. @@ -1012,6 +1001,57 @@ int gpiod_line_event_get_fd(struct gpiod_line *line) GPIOD_API; int gpiod_line_event_read_fd(int fd, struct gpiod_line_event *event) GPIOD_API; /** + * @} + * + * @defgroup __line_misc__ Misc line functions + * @{ + */ + +/** + * @brief Get a GPIO line handle by GPIO chip description and offset. + * @param device String describing the gpiochip. + * @param offset The offset of the GPIO line. + * @return GPIO line handle or NULL if an error occurred. + * + * This routine provides a shorter alternative to calling + * ::gpiod_chip_open_lookup and ::gpiod_chip_get_line. + * + * If this function succeeds, the caller is responsible for closing the + * associated GPIO chip. + */ +struct gpiod_line * +gpiod_line_get(const char *device, unsigned int offset) GPIOD_API; + +/** + * @brief Find a GPIO line by its name. + * @param name Name of the GPIO line. + * @return Returns the GPIO line handle if the line exists in the system or + * NULL if it couldn't be located or an error occurred. + * + * If this routine succeeds, the user must manually close the GPIO chip owning + * this line to avoid memory leaks. If the line could not be found, this + * functions sets errno to ENOENT. + */ +struct gpiod_line * gpiod_line_find(const char *name) GPIOD_API; + +/** + * @brief Close a GPIO chip owning this line and release all resources. + * @param line GPIO line object + * + * After this function returns, the line must no longer be used. + */ +void gpiod_line_close_chip(struct gpiod_line *line) GPIOD_API; + +/** + * @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. + */ +struct gpiod_chip * gpiod_line_get_chip(struct gpiod_line *line) GPIOD_API; + +/** + * @} + * * @} * * @defgroup __iterators__ Iterators for GPIO chips and lines