doc: document the caveat concerning line lookups

GPIO line names in the kernel aren't unique - neither globally nor
within a single chip. The current API doesn't take this into
consideration and simply returns the first matching line in
gpiod_line_find() and co.

This will be addressed in v2.0 but we can't fix it in v1.x without
introducing new interfaces and deprecating the ones that already exist.

Let's document this behavior in doxygen comments for all affected
routines.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

diff --git a/include/gpiod.h b/include/gpiod.h
index f03ce95798a1a3555dcbd2daacad7ed610df50f9..67b06c708f07e1312a0efd7061e252892abd93dd 100644 (file)
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -531,6 +531,9 @@ int gpiod_ctxless_event_monitor_multiple_ext(
  *         the line was found. In the first two cases the contents of chipname
  *         and offset remain unchanged.
  * @note The chip name is truncated if the buffer can't hold its entire size.
+ * @attention GPIO lines are not unique in the linux kernel, neither globally
+ *            nor within a single chip. This function finds the first line with
+ *            given name.
  */
 int gpiod_ctxless_find_line(const char *name, char *chipname,
                            size_t chipname_size,
@@ -656,6 +659,9 @@ int gpiod_chip_get_all_lines(struct gpiod_chip *chip,
  *         found or an error occurred.
  * @note In case a line with given name is not associated with given chip, the
  *       function sets errno to ENOENT.
+ * @attention GPIO lines are not unique in the linux kernel, neither globally
+ *            nor within a single chip. This function finds the first line with
+ *            given name.
  */
 struct gpiod_line *
 gpiod_chip_find_line(struct gpiod_chip *chip, const char *name) GPIOD_API;
@@ -669,6 +675,9 @@ gpiod_chip_find_line(struct gpiod_chip *chip, const char *name) GPIOD_API;
  * @return 0 if all lines were located, -1 on error.
  * @note If at least one line from the list could not be found among the lines
  *       exposed by this chip, the function sets errno to ENOENT.
+ * @attention GPIO lines are not unique in the linux kernel, neither globally
+ *            nor within a single chip. This function finds the first line with
+ *            given name.
  */
 int gpiod_chip_find_lines(struct gpiod_chip *chip, const char **names,
                          struct gpiod_line_bulk *bulk) GPIOD_API;
@@ -1577,6 +1586,9 @@ gpiod_line_get(const char *device, unsigned int offset) GPIOD_API;
  * @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.
+ * @attention GPIO lines are not unique in the linux kernel, neither globally
+ *            nor within a single chip. This function finds the first line with
+ *            given name.
  *
  * 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