[libgpiod,v2,0/4] tools: line name focussed rework

This patch series is an optimistic reimagining of the tools intended to
simplify usage for well configured systems, i.e. for systems where lines
can be uniquely identified by name.  In such systems the chip and offset
location of the line is no longer of relevance to the user, so the tools
should be able to operate without mentioning them.
e.g.
  gpioget GPIO17

  gpioset GPIO17=active

  gpiomon --localtime GPIO17 GPIO18 

It is accepted that the kernel does not guarantee line name uniqueness
within the system, or even within a chip, and not all systems are well
configured, so the tools retain the option to identify lines by chip
and offset.  The hope and expectation is that over time systems will
become more well configured, not less, and identification of GPIO lines
by name will become the norm.

The core of the series is patch 1 which is a reworking of the tools to
support identifying lines by name, and to operate across multiple GPIO
chips if named lines are located on different chips.
The gpioset tool is extended to support toggling lines and interactive
control of line values, so some common use cases can be trivially
implemented from the command line.
e.g.
  gpioset --toggle 500ms LED=on

will blink the LED line at 1Hz, indefinitely.
More complex outputs can be generated by adding more entries to the
toggle sequence:
  gpioset --toggle 1s,2s,1s,300ms LED=on

Even more complex outputs can be generated by driving gpioset in
interactive mode from another script.

Those are the major changes.  A more complete list of the changes can be
found in the patch description.

Patch 2 updates and extends the tool tests to cover the reworked tools,
including demonstrating gpioset being driven interactively via a script.

The final two patches add a gpiowatch tool that monitors changes to 
the state line information, similar to the gpio-watch tool in the kernel,
and extend the test suite to cover it.

Cheers,
Kent.

Kent Gibson (4):
  tools: line name focussed rework
  tools: tests for line name focussed rework
  tools: add gpiowatch
  tools: gpiowatch tests

 configure.ac               |    9 +-
 man/Makefile.am            |    2 +-
 tools/.gitignore           |    1 +
 tools/Makefile.am          |    4 +-
 tools/gpio-tools-test      |    3 -
 tools/gpio-tools-test.bats | 2189 ++++++++++++++++++++++++++++--------
 tools/gpiodetect.c         |  108 +-
 tools/gpiofind.c           |  126 ++-
 tools/gpioget.c            |  200 ++--
 tools/gpioinfo.c           |  356 +++---
 tools/gpiomon.c            |  493 ++++----
 tools/gpioset.c            |  861 ++++++++++----
 tools/gpiowatch.c          |  214 ++++
 tools/tools-common.c       |  640 ++++++++++-
 tools/tools-common.h       |   59 +-
 15 files changed, 3927 insertions(+), 1338 deletions(-)
 create mode 100644 tools/gpiowatch.c

On Mon, Jun 27, 2022 at 09:44:43PM +0800, Kent Gibson wrote:
> This patch series is an optimistic reimagining of the tools intended to
> simplify usage for well configured systems, i.e. for systems where lines
> can be uniquely identified by name.  In such systems the chip and offset
> location of the line is no longer of relevance to the user, so the tools
> should be able to operate without mentioning them.
> e.g.
>   gpioget GPIO17
> 
>   gpioset GPIO17=active
> 
>   gpiomon --localtime GPIO17 GPIO18 
> 
> It is accepted that the kernel does not guarantee line name uniqueness
> within the system, or even within a chip, and not all systems are well
> configured, so the tools retain the option to identify lines by chip
> and offset.  The hope and expectation is that over time systems will
> become more well configured, not less, and identification of GPIO lines
> by name will become the norm.
> 
> The core of the series is patch 1 which is a reworking of the tools to
> support identifying lines by name, and to operate across multiple GPIO
> chips if named lines are located on different chips.
> The gpioset tool is extended to support toggling lines and interactive
> control of line values, so some common use cases can be trivially
> implemented from the command line.
> e.g.
>   gpioset --toggle 500ms LED=on
> 
> will blink the LED line at 1Hz, indefinitely.
> More complex outputs can be generated by adding more entries to the
> toggle sequence:
>   gpioset --toggle 1s,2s,1s,300ms LED=on
> 
> Even more complex outputs can be generated by driving gpioset in
> interactive mode from another script.
> 
> Those are the major changes.  A more complete list of the changes can be
> found in the patch description.
> 
> Patch 2 updates and extends the tool tests to cover the reworked tools,
> including demonstrating gpioset being driven interactively via a script.
> 
> The final two patches add a gpiowatch tool that monitors changes to 
> the state line information, similar to the gpio-watch tool in the kernel,
> and extend the test suite to cover it.
> 

I forgot to mention that gpiofind is effectively redundant now its
functionality has been absorbed into the other tools.
I kept it in the patch for completeness but would be happy to remove
it.

I am also reconsidering gpioset's interactive get command.
The get currently returns the requested set values - it does not
query the kernel.  It may be useful to be able to do both for open-drain
outputs.
How about the get does a GET_VALUES, while a bare set displays the
requested set values?
Or would a flag on the get be clearer?

Cheers,
Kent.