[PATCH] API: rename gpiod_chip_find_line()

[PATCH] API: rename gpiod_chip_find_line()

[Bartosz Golaszewski]

The name "find_line" is quite ambigous. We should indicate that the
purpose of this routine is to map the line name to its HW offset.
Kent suggested get_line_get_offset_from_name() which is hard to beat
when it comes to being explicit.

Signed-off-by: Bartosz Golaszewski <brgl@bgdev.pl>
---
 include/gpiod.h    |  3 ++-
 lib/chip.c         |  3 ++-
 tests/tests-chip.c | 10 +++++++---
 tools/gpiofind.c   |  2 +-
 4 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/include/gpiod.h b/include/gpiod.h
index c605da8..344a8fc 100644
--- a/include/gpiod.h
+++ b/include/gpiod.h
@@ -158,7 +158,8 @@ struct gpiod_info_event *gpiod_chip_read_info_event(struct gpiod_chip *chip);
  * @note If a line with given name is not exposed by the chip, the function
  *       sets errno to ENOENT.
  */
-int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name);
+int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip,
+					 const char *name);
 
 /**
  * @brief Request a set of lines for exclusive usage.
diff --git a/lib/chip.c b/lib/chip.c
index edb2dfd..eef3be2 100644
--- a/lib/chip.c
+++ b/lib/chip.c
@@ -156,7 +156,8 @@ gpiod_chip_read_info_event(struct gpiod_chip *chip)
 	return gpiod_info_event_read_fd(chip->fd);
 }
 
-GPIOD_API int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name)
+GPIOD_API int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip,
+						   const char *name)
 {
 	struct gpio_v2_line_info linfo;
 	struct gpiochip_info chinfo;
diff --git a/tests/tests-chip.c b/tests/tests-chip.c
index 3fad16d..efb4f74 100644
--- a/tests/tests-chip.c
+++ b/tests/tests-chip.c
@@ -88,7 +88,9 @@ GPIOD_TEST_CASE(find_line_bad)
 
 	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
 
-	g_assert_cmpint(gpiod_chip_find_line(chip, "nonexistent"), ==, -1);
+	g_assert_cmpint(
+		gpiod_chip_get_line_offset_from_name(chip,
+						     "nonexistent"), ==, -1);
 	gpiod_test_expect_errno(ENOENT);
 }
 
@@ -112,7 +114,8 @@ GPIOD_TEST_CASE(find_line_good)
 
 	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
 
-	g_assert_cmpint(gpiod_chip_find_line(chip, "baz"), ==, 4);
+	g_assert_cmpint(gpiod_chip_get_line_offset_from_name(chip, "baz"),
+			==, 4);
 }
 
 /* Verify that for duplicated line names, the first one is returned. */
@@ -136,5 +139,6 @@ GPIOD_TEST_CASE(find_line_duplicate)
 
 	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
 
-	g_assert_cmpint(gpiod_chip_find_line(chip, "baz"), ==, 2);
+	g_assert_cmpint(gpiod_chip_get_line_offset_from_name(chip, "baz"),
+			==, 2);
 }
diff --git a/tools/gpiofind.c b/tools/gpiofind.c
index 36eba86..03b15c9 100644
--- a/tools/gpiofind.c
+++ b/tools/gpiofind.c
@@ -75,7 +75,7 @@ int main(int argc, char **argv)
 			die_perror("unable to open %s", entries[i]->d_name);
 		}
 
-		offset = gpiod_chip_find_line(chip, argv[0]);
+		offset = gpiod_chip_get_line_offset_from_name(chip, argv[0]);
 		if (offset >= 0) {
 			info = gpiod_chip_get_info(chip);
 			if (!info)
-- 
2.32.0

Re: [PATCH] API: rename gpiod_chip_find_line()

[Bartosz Golaszewski]

On Tue, Apr 5, 2022 at 3:22 PM Bartosz Golaszewski <brgl@bgdev.pl> wrote:
>
> The name "find_line" is quite ambigous. We should indicate that the
> purpose of this routine is to map the line name to its HW offset.
> Kent suggested get_line_get_offset_from_name() which is hard to beat
> when it comes to being explicit.
>
> Signed-off-by: Bartosz Golaszewski <brgl@bgdev.pl>
> ---

Ugh, this was of course supposed to be [libgpiod v2]. Sorry.

Bart

Re: [PATCH] API: rename gpiod_chip_find_line()

[Kent Gibson]

On Tue, Apr 05, 2022 at 03:21:58PM +0200, Bartosz Golaszewski wrote:
> The name "find_line" is quite ambigous. We should indicate that the
> purpose of this routine is to map the line name to its HW offset.
> Kent suggested get_line_get_offset_from_name() which is hard to beat
> when it comes to being explicit.
> 

My suggestion was actually gpiod_chip_line_offset_from_name().
But gpiod_chip_get_line_offset_from_name() is even more explicit.
And both make more sense than your misquote above ;-).

So that works for me - assuming you fix the quote.

Cheers,
Kent.

> Signed-off-by: Bartosz Golaszewski <brgl@bgdev.pl>
> ---
>  include/gpiod.h    |  3 ++-
>  lib/chip.c         |  3 ++-
>  tests/tests-chip.c | 10 +++++++---
>  tools/gpiofind.c   |  2 +-
>  4 files changed, 12 insertions(+), 6 deletions(-)
> 
> diff --git a/include/gpiod.h b/include/gpiod.h
> index c605da8..344a8fc 100644
> --- a/include/gpiod.h
> +++ b/include/gpiod.h
> @@ -158,7 +158,8 @@ struct gpiod_info_event *gpiod_chip_read_info_event(struct gpiod_chip *chip);
>   * @note If a line with given name is not exposed by the chip, the function
>   *       sets errno to ENOENT.
>   */
> -int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name);
> +int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip,
> +					 const char *name);
>  
>  /**
>   * @brief Request a set of lines for exclusive usage.
> diff --git a/lib/chip.c b/lib/chip.c
> index edb2dfd..eef3be2 100644
> --- a/lib/chip.c
> +++ b/lib/chip.c
> @@ -156,7 +156,8 @@ gpiod_chip_read_info_event(struct gpiod_chip *chip)
>  	return gpiod_info_event_read_fd(chip->fd);
>  }
>  
> -GPIOD_API int gpiod_chip_find_line(struct gpiod_chip *chip, const char *name)
> +GPIOD_API int gpiod_chip_get_line_offset_from_name(struct gpiod_chip *chip,
> +						   const char *name)
>  {
>  	struct gpio_v2_line_info linfo;
>  	struct gpiochip_info chinfo;
> diff --git a/tests/tests-chip.c b/tests/tests-chip.c
> index 3fad16d..efb4f74 100644
> --- a/tests/tests-chip.c
> +++ b/tests/tests-chip.c
> @@ -88,7 +88,9 @@ GPIOD_TEST_CASE(find_line_bad)
>  
>  	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
>  
> -	g_assert_cmpint(gpiod_chip_find_line(chip, "nonexistent"), ==, -1);
> +	g_assert_cmpint(
> +		gpiod_chip_get_line_offset_from_name(chip,
> +						     "nonexistent"), ==, -1);
>  	gpiod_test_expect_errno(ENOENT);
>  }
>  
> @@ -112,7 +114,8 @@ GPIOD_TEST_CASE(find_line_good)
>  
>  	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
>  
> -	g_assert_cmpint(gpiod_chip_find_line(chip, "baz"), ==, 4);
> +	g_assert_cmpint(gpiod_chip_get_line_offset_from_name(chip, "baz"),
> +			==, 4);
>  }
>  
>  /* Verify that for duplicated line names, the first one is returned. */
> @@ -136,5 +139,6 @@ GPIOD_TEST_CASE(find_line_duplicate)
>  
>  	chip = gpiod_test_open_chip_or_fail(g_gpiosim_chip_get_dev_path(sim));
>  
> -	g_assert_cmpint(gpiod_chip_find_line(chip, "baz"), ==, 2);
> +	g_assert_cmpint(gpiod_chip_get_line_offset_from_name(chip, "baz"),
> +			==, 2);
>  }
> diff --git a/tools/gpiofind.c b/tools/gpiofind.c
> index 36eba86..03b15c9 100644
> --- a/tools/gpiofind.c
> +++ b/tools/gpiofind.c
> @@ -75,7 +75,7 @@ int main(int argc, char **argv)
>  			die_perror("unable to open %s", entries[i]->d_name);
>  		}
>  
> -		offset = gpiod_chip_find_line(chip, argv[0]);
> +		offset = gpiod_chip_get_line_offset_from_name(chip, argv[0]);
>  		if (offset >= 0) {
>  			info = gpiod_chip_get_info(chip);
>  			if (!info)
> -- 
> 2.32.0
> 

Re: [PATCH] API: rename gpiod_chip_find_line()

[Andy Shevchenko]

On Tue, Apr 05, 2022 at 09:44:24PM +0800, Kent Gibson wrote:
> On Tue, Apr 05, 2022 at 03:21:58PM +0200, Bartosz Golaszewski wrote:
> > The name "find_line" is quite ambigous. We should indicate that the
> > purpose of this routine is to map the line name to its HW offset.
> > Kent suggested get_line_get_offset_from_name() which is hard to beat
> > when it comes to being explicit.
> > 
> 
> My suggestion was actually gpiod_chip_line_offset_from_name().
> But gpiod_chip_get_line_offset_from_name() is even more explicit.
> And both make more sense than your misquote above ;-).
> 
> So that works for me - assuming you fix the quote.

I also like this. Thanks!

-- 
With Best Regards,
Andy Shevchenko