v2 replacements for gpiod_line_find() or gpiod::find_line()?

[LeSpocky]

After some distributions/build systems made the hard switch from libgpiod v1.6.x to v2.x I'm challenged to adapt my applications now. Previously I used gpiod_line_find() in C and gpiod::find_line() in C++ and proceeded from there. This was especially handy, because some of that application code runs on different platforms and I just don't know in advance which chip and line a certain GPIO is on, but using distinct line-names in .dts allowed for easy and reproducible selecting the correct line.

Now with API v2 those functions are gone, and all I can find in the sources are some examples like examples/find_line_by_name.c and bindings/cxx/examples/find_line_by_name.cpp which essentially do what was part of the public API before. The C code is even duplicated 100% the same to tools/tools-common.c and used by the tools for the same purpose: finding a line just by name regardless to which chip it belongs.

Is there a plan to add such functions to the API, or is every user now expected to repeat that code over and over again, carefully circumventing any possible license issues from the GPL-2.0-or-later licensed example code we have all seen now? I think adding such helper functions to the API could benefit all users. What's the maintainers opinion on that?

Besides: the documentation is nice in listing every new API function, but it lacks any more general guidance on what the parts are supposed to do and there's no big picture how it should be used. What do I need to set a GPIO line to a specific output value? Is it gpiod_line_settings_set_output_value() or gpiod_line_request_set_value() and what are the steps I need to do before I can actually call that? Some kind of simple HowTo with explanations instead of undocumented example code would be nice. Or some words on how the different objects relate to each other, rather the design idea than only naming the pieces. 😉

[brgl]

After some distributions/build systems made the hard switch from libgpiod v1.6.x to v2.x I'm challenged to adapt my applications now. Previously I used gpiod_line_find() in C and gpiod::find_line() in C++ and proceeded from there. This was especially handy, because some of that application code runs on different platforms and I just don't know in advance which chip and line a certain GPIO is on, but using distinct line-names in .dts allowed for easy and reproducible selecting the correct line.

Now with API v2 those functions are gone, and all I can find in the sources are some examples like examples/find_line_by_name.c and bindings/cxx/examples/find_line_by_name.cpp which essentially do what was part of the public API before. The C code is even duplicated 100% the same to tools/tools-common.c and used by the tools for the same purpose: finding a line just by name regardless to which chip it belongs.

My goal for libgpiod v2 was to have a very lean library that only exposes the functionalities of the kernel uAPI. That's why I decided to drop all the high-level interfaces.

Is there a plan to add such functions to the API, or is every user now expected to repeat that code over and over again, carefully circumventing any possible license issues from the GPL-2.0-or-later licensed example code we have all seen now? I think adding such helper functions to the API could benefit all users. What's the maintainers opinion on that?

I don't have such a plan but I've had it in the back of my head to expose what is currently the static tools-common library as an actual shared library used by the official gpio-tools and also available to other users via a public header. I think this part is mature enough to do it. Adding a prefix to all symbols and modifying the build scripts is easy. Kent Gibson would have to sign off on the license change to LGPL-v2.1. Finally we could use some docs but can also make without for the time being.

Besides: the documentation is nice in listing every new API function, but it lacks any more general guidance on what the parts are supposed to do and there's no big picture how it should be used. What do I need to set a GPIO line to a specific output value? Is it gpiod_line_settings_set_output_value() or gpiod_line_request_set_value() and what are the steps I need to do before I can actually call that? Some kind of simple HowTo with explanations instead of undocumented example code would be nice. Or some words on how the different objects relate to each other, rather the design idea than only naming the pieces. 😉

Sigh... Yeah it would be great, wouldn't it? Unfortunately my time is quite limited and my TODO list runneth over. :( I would love it, if someone, who spent time on figuring out how the library works, could also contribute back and make the docs better for beginners. I can't promise, I'll find time to improve them soon.

[LeSpocky]

Okay thanks for elaborating. Documentation writing is hard, especially for beginners if you are deep into the topic and would not stumble over the same things. Sounds like you would happily accept patches for both, and I'm fine with that for now.

[brgl]

It's even harder with English not being my first language. I may find the time to convert tools-common into a shared library soon(ish).

[brgl]

Formal patch series: https://lore.kernel.org/all/20260513-tools-common-shared-lib-v1-0-58ac28a9f1d5@oss.qualcomm.com/

[brgl]

https://github.com/brgl/libgpiod/tree/b4/tools-common-shared-lib First working draft of the refactoring into libgpiotools

[brgl]

v2.3 release contains libgpiotools so I'm closing this.