bindings: cxx: tests: don't use the same chip from different threads

There are no thread-safety guarantees in libgpiod. Let's not reuse the
chip object created in one thread to generate info events in another but
create a second chip for that purpose instead.

Reported-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>

tests: don't use the same chip object from different threads

There are no thread-safety guarantees in libgpiod. Let's not reuse the
chip object created in one thread to generate info events in another but
create a second chip for that purpose instead.

Reported-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>

tests: add missing return value check

One of the line-request test cases is missing the return value check
after the call to gpiod_line_request_set_values_subset(). Add it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

examples: simplify find_line_by_name

Simplify the find_line_by_name example by using
gpiod_chip_get_line_offset_from_name() rather than iterating over each
line in a chip.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: provide LineRequest::chip_name()

Provide a wrapper around gpiod_line_request_get_chip_name() for Rust
bindings and add a test-case.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>

bindings: python: provide the chip_name property in line_request

Provide a wrapper around gpiod_line_request_get_chip_name() for Python
bindings and update the tests.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: provide line_request::chip_name()

Provide a wrapper around gpiod_line_request_get_chip_name() for C++
bindings and update the tests.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: add a test-case for gpiod_line_request_get_chip_name()

Add a test case for the chip name getter on line-request objects.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

core: provide gpiod_line_request_get_chip_name()

While we can get the list of requested offsets from a line-request object,
this information lacks context if we don't provide any data about the GPIO
chip the request was made on. Add a helper allowing users to get the name
of the parent chip.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: mention the libgpiod crate from libgpiod-sys

If people view this README.md on crates.io [1], they likely want to
use the safe wrapper instead. So this hints the existence of that other
crate.

[1] https://crates.io/crates/libgpiod-sys

Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: add README.md for libgpiod crate

crates.io treats the README as landing page for a crate [1]. Since
we have none, it currently displays a blank page. Lets add at least a
little bit of info here so people can figure out what they are dealing
with.

[1] https://crates.io/crates/libgpiod

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: print additional info when regex matching fails

Add shunit assert messages when testing the result of regex matches,
otherwise we're left with a not very useful: "expected:<0> but was:<1>".

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

build: remove redundant SOURCES assignments

For any given target (let's say foobar), automake defaults to looking for
foobar.c if foobar_SOURCES are not specified. Remove redundant assignments
as we've seen multiple hidden typos in makefiles already.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>

core: examples: fix warning for u64 formatting on 32bit

The watch_line_info example prints the u64 timestamps using "%ld" which
produces a warning for 32bit.  Replace it with PRIu64.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: clippy: silence false-positive on iterator

This was fixed on clippy master [1], but it is still broken on 0.1.70. So
lets silence it until the clippy fix is widely available.

clippy version: clippy 0.1.70 (90c5418 2023-05-31).

[1] https://github.com/rust-lang/rust-clippy/commit/9fa40894103e32364fdbade539d4ecb3d40f3d7f

Reported-by: Kent Gibson <warthog618@gmail.com>
Link: https://lore.kernel.org/r/20230612154055.56556-1-warthog618@gmail.com
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: clippy: drop unneeded conversions

Fixes clippy warnings on these lines.

Applied the suggested fix using:

    cargo clippy --fix

clippy version: clippy 0.1.70 (90c5418 2023-05-31).

Reported-by: Kent Gibson <warthog618@gmail.com>
Link: https://lore.kernel.org/r/20230612154055.56556-1-warthog618@gmail.com
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: clippy: silence false-positives on casts

clippy falsely complains about these lines. The problem is known, but
unfixed [1]. So lets silence the warning until a fix is widely available.

clippy version: clippy 0.1.70 (90c5418 2023-05-31).

[1] https://github.com/rust-lang/rust-clippy/issues/10555

Reported-by: Kent Gibson <warthog618@gmail.com>
Link: https://lore.kernel.org/r/20230612154055.56556-1-warthog618@gmail.com
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: clippy: drop unnecessary casts

Fixes clippy warnings on these lines.

Applied the suggested fix using:

    cargo clippy --fix

clippy version: clippy 0.1.70 (90c5418 2023-05-31).

Reported-by: Kent Gibson <warthog618@gmail.com>
Link: https://lore.kernel.org/r/20230612154055.56556-1-warthog618@gmail.com
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: fix unclear resolver warning

Fix the following warning:

"some crates are on edition 2021 which defaults to `resolver = "2"`,
 but virtual workspaces default to `resolver = "1"`"

Clarify the resolver selection as the 2021 edition by setting the
workspace.resolver to "2".

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: use () instead of (void) in line_settings::reset()

While () and (void) are synonymous in C++, we use () everywhere else so
fix the only exception. This DOES NOT change the ABI as the generated
symbol is the same (at least as verified on gcc and clang).

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: examples: consistently use () for functions taking no args

While () and (void) are synonymous in C++, we use () everywhere else so
stick to that pattern in examples.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

gpiosim: fix data race that corrupts heap

Hit this while seeing some heap corruptions when running cargo test on
the Rust bindings.

Took a bit to track down since I first used address sanitizers, but with
the thread sanitizer it becomes obvious immediately (output simplified):

    ==================
    WARNING: ThreadSanitizer: data race (pid=288119)
      Write of size 8 at 0x0000018f1e78 by thread T6:
        #0 id_free /libgpiod/tests/gpiosim/gpiosim.c:141:17
        #1 dev_release /libgpiod/tests/gpiosim/gpiosim.c:600:2
        #2 refcount_dec /libgpiod/tests/gpiosim/gpiosim.c:176:3
        #3 gpiosim_dev_unref /libgpiod/tests/gpiosim/gpiosim.c:671:2
        #4 bank_release /libgpiod/tests/gpiosim/gpiosim.c:873:2
        #5 refcount_dec /libgpiod/tests/gpiosim/gpiosim.c:176:3
        #6 gpiosim_bank_unref /libgpiod/tests/gpiosim/gpiosim.c:941:2
        [...]

      Previous write of size 8 at 0x0000018f1e78 by thread T1:
        #0 id_free /libgpiod/tests/gpiosim/gpiosim.c:141:17
        #1 bank_release /libgpiod/tests/gpiosim/gpiosim.c:878:2
        #2 refcount_dec /libgpiod/tests/gpiosim/gpiosim.c:176:3
        #3 gpiosim_bank_unref /libgpiod/tests/gpiosim/gpiosim.c:941:2
        [...]

      Location is global 'id_del_ctx' of size 16 at 0x0000018f1e70

      Thread T6 'chip::verify::f' (tid=288126, running) created by main thread at:
        #7 test::run_tests::hd53a07a011bd771f /.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/test/src/lib.rs:407:21
        [...]

      Thread T1 'chip::open::gpi' (tid=288121, finished) created by main thread at:
        #7 test::run_tests::hd53a07a011bd771f /.rustup/toolchains/nightly-x86_64-unknown-linux-gnu/lib/rustlib/src/rust/library/test/src/lib.rs:407:21
        [...]

    SUMMARY: ThreadSanitizer: data race /libgpiod/tests/gpiosim/gpiosim.c:141:17 in id_free
    ==================

This eventually can either lead to leaks or double free's that corrupt
the heap and lead to crashes.

The issue got introduced when a previously local variable that did not
require protection was turned into a global variable.

Fixes: 5e111df2fca5 ("gpiosim: use twalk() instead of twalk_r()")
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: examples: replace tools examples with use case examples

Replace tool examples with use case examples drawn from the tools.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

rust: examples: file comment consistency

Make the file comment for reconfigure_input_to_output consistent with
other language examples.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

cxx: examples: file comment consistency

Make the file comment for reconfigure_input_to_output consistent with
other language examples.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

core: examples: fix file comments

Some of the file comments are cut-and-paste errors, so replace them
with the correct comment.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: examples: replace tools examples with use case examples

Replace tool examples with use case examples drawn from the tools,
gpio_events example with buffered_event_lifetimes, and
gpio_threaded_info_events with reconfigure_input_to_output.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: examples: consistency cleanup

A collection of minor changes to be more consistent with other examples:
 - capitalize comments
 - add line offset to value outputs
 - drop comma from edge event outputs

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: examples: consistency cleanup

A collection of minor changes to be more consistent with other examples:
 - capitalize comments
 - add line offset to value outputs
 - drop comma from edge event outputs
 - improve behaviour if run on a platform that does not match the
   example configuration
 - use with to cleanup request in toggle_line_value.py

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: examples: replace tools examples with use case examples

Replace tool examples with use case examples drawn from the tools.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: examples: consistency cleanup

A collection of minor changes to be more consistent with other examples:
 - capitalize comments
 - add line offset to value outputs
 - drop comma from edge event outputs
 - drop trailing return where example loops indefintely
 - sort includes

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

core: examples: add more use case examples

Add examples for use cases drawn from the tools.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

core: examples: consistency cleanups

A collection of minor cleanups to make the examples more consistent and
ease the addition of more examples:
 - reformat Makefile.am to simplify adding more examples
 - add line offset to value output
 - remove commas from edge event output
 - replace while(1) with for (;;)
 - fix a typo in Makefile.am
 - fix an error handling goto in toggle_line_value.c

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: remove a stray newline

There's an unnecessary double newline in one of the test cases. Drop it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: port tests to shunit2

BATS has been confirmed to run much more slowly that shunit2. This is
most likely caused by the way BATS evaluates each test file n+1 times
where n is the number of tests[1].

Port tests to using shunit2 which executes as a regular shell script
which, in addition to higher speed, allows for easier debugging as
standard shell flags like -x now work.

[1] https://bats-core.readthedocs.io/en/stable/writing-tests.html

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>

tools: tests: add short sleeps between generating edge events

Toggling the gpio-sim pull too fast can lead to losing events by gpiomon.
Add short sleeps between the calls to gpiosim_set_pull.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: bump MSRV to 1.60

Specifying MSRV (minimum supported rust version) was introduced with
Rust 1.56. So old versions of libraries do not have this restriction
spelled out in their Cargo.toml.

This means that even if we claimed a MSRV of 1.56 until now, that did
not mean that things were actually buildable with 1.56 practically
(without manually researching compatible versions and pinning them
down).

`bindgen` started listing a MSRV from v0.61 (requiring Rust 1.57) [1].
So that may seem like an obvious choice. But if one attempts to build
it with such an old version one will realize that `log` only started
requesting a MSRV with 0.4.19 (requesting Rust 1.60) [2]. Hence, we
would either need to manually restrict log to an old, but compatible
release (which would unnecessarily restrict everyone on newer Rust
versions) or just also bump our MSRV to 1.60.

Rust 1.60 was released on 2022-04-07 [3] and seems like an acceptable
choice if core components such as `log` started their MSRV tracking with
that version. If someone is determined wanting to use this with an older
version of Rust, thats still possible. If one has done the necessary
manual research and pinned their versions down, one can use
--ignore-rust-version (or a < 1.56 version of Rust that does not check
the MSRV yet).

Thanks to Manos Pitsidianakis <manos.pitsidianakis@linaro.org> for
helping me out when I successfully confused myself somewhere.

[1] https://github.com/rust-lang/rust-bindgen/blob/v0.61.0/bindgen/Cargo.toml
[2] https://github.com/rust-lang/log/blob/0.4.19/Cargo.toml
[3] https://blog.rust-lang.org/2022/04/07/Rust-1.60.0.html

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: package new examples in the distro tarball

Add new example files to EXTRA_DIST in the Makefile so that they end up
being shipped with the rest of the code.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: package new examples in the distro tarball

Add new example scripts to EXTRA_DIST in the Makefile so that they end up
being shipped with the rest of the code.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: examples: add dedicated examples

Add rust equivalents of the core examples.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: examples: add dedicated examples

Add python equivalents of the core examples.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: examples: add dedicated examples

Add cxx equivalents of the core examples.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

examples: add dedicated examples

The tools have served as example code, but have become too complicated
to serve that purpose.

Add a set of examples that have no purpose other than providing minimal
examples of common use cases.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: examples: fix potential glitch in gpiosetcxx

gpiosetcxx requests lines without setting their output value, and so
sets them all inactive, and subsequently sets them to their requested
value. This can result in glitches on lines which were active and
are set active.

As this is example code, it is also important to demonstrate that the
output value can be set by the request itself.

Request the lines with the correct output values set in the request
itself.

Suggested-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>

bindings: cxx: provide request_builder::set_output_values()

Implement a new method in the request_builder class that allows to set
output values at request-time by calling the set_output_values() method
of the internal line_config object.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>

doc: add configuration to generate doxygen documentation on readthedocs

Having the libgpiod documentation available online would be helpful, so
add the configuration required to generate the existing docygen C/C++
documentation on readthedocs.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: document build without install

While the Makefile does this automatically, a user may want to do
something similar for other cargo commands.

Reported-by: Kent Gibson <warthog618@gmail.com>
Link: https://lore.kernel.org/r/ZIQJquwzNacp1Nuh@sol/
Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: exclude Makefile.am from package

We do not use those when building from crates.io.

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: add version number to dependencies

When publishing to crates.io, all dependencies need to have a version
number. When building from crates.io the version number will be used,
otherwise the `path` is effective for builds when checking out the
repository.

As discussed on the maillinglist [1], each crate will have their own
version number (like the other language bindings) that will be bumped as
needed to fulfill the Rust SemVer requirements.

[1] https://lore.kernel.org/r/CACMJSes5+vT=NBqSe7xpSEPAEMmkgrZvJ8iKx7oBCKZQaGB_rg@mail.gmail.com/

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: add missing license and copyright boilerplate

Make reuse happy again by adding appropriate license and copyright info.

Fixes: 1f8085953086 ("bindings: rust: build against pkg-config info")
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Acked-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: remove implicit run-time dependency on ncurses

bats has an implicit depencency on ncurses, as I found when trying to
run the tests on a minimal install that lacked ncurses. Rather than make
the dependency explicit, force the output formatting to use the TAP
format which does not require ncurses.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: speed up continuous toggle test

The continuous toggle test was recently changed to poll the line to
check for toggles, and so increase test reliability. Tighten up the
test timings so the test can now also run in a significantly shorter
time.

And, as it is now faster, add an extra edge just to be sure.

Note that the test does not need to catch every edge, it only has to
check that the line is in fact toggling.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: add tests for idle-timeout and debounce period.

There are no tests for the --debounce-period for gpiomon, or the new
idle-timeout option for gpiomon and gpionotify, so add some.

In both cases the focus of the test is not the period itself, which is
problematic to test reliably, but that the options are supported and
have the otherwise anticipated effects.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: gpiomon/gpionotify: add idle-timeout option

Add an idle timeout option to gpiomon and gpionotify to exit gracefully
when no event has been detected for a given period.

Signed-off-by: Gabriel Matni <gabriel.matni@exfo.com>
Reviewed-by: Kent Gibson <warthog618@gmail.com>
Tested-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: examples: gpioset: drop redundant []

dict() accepts an iterable, so the [] brackets are redundant.

Suggested-by: Andy Shevchenko <andy.shevchenko@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: examples: fix potential glitch in gpioset.py

gpioset.py requests lines without setting their output value, and so
sets them all inactive, and subsequently sets them to their requested
value. This can result in glitches on lines which were active and
are set active.

As this is example code, it is also important to demonstrate that the
output value can be set by the request itself.

Request the lines with the correct output values set in the request
itself.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

doc: add doc for opaque structs to link to the relevant page

The C doxygen documentation is difficult to navigate as the opaque types
do not get linked to anything.

Add doc for each opaque struct that references the relevant page.

While at it: fix a typo in the line-request group.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

doc: fix line_config documentation generation

The line configuration is missing from the generated documentation as the
comment for the defgroup is a normal comment, not a doc comment.

Add the asterisk to make the section a doc comment.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: modify delays in toggle test

The test "gpioset: toggle (continuous)" uses fixed delays to test
toggling values. This is not reliable, so we switch to looking
for transitions from one value to another.

We wait for a transition up to 1.5 seconds.

Signed-off-by: Joe Slater <joe.slater@windriver.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

build: drop a reference to libgpiomockup from a comment in Makefile

We no longer use libgpiomockup. Replace the reference to it with
libgpiosim.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: replace egrep with grep -E

Since version 3.11 egrep emits the following warning to stderr on startup:

  egrep: warning: egrep is obsolescent; using grep -E

This makes the tests fail (though that seems to depend on BATS version)
so replace egrep with grep -E as suggested.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

doc: remove a stray letter

There's a stray 'q' in the docs, remove it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

doc: add missing @return entries

There are two line-request functions that don't have their return values
documented. Fix it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: build against pkg-config info

This change replaces building against "bundled" headers by always
building agains system headers (while following standard conventions to
allow users to specify the version to build against).

Reasoning:

Previously, the code generated the bindings based on the headers, but
then links against `-lgpiod` without further specifying where that is
coming from.

This results in some challenges and problems:

1. Packaging a Rust crate with `cargo package` requires the folder
   containing the Cargo.toml to be self-contained. Essentially, a tar
   ball with all the sources of that folder is created. Building against
   that tar ball fails, since the headers files passed to bindgen are
   a relative path pointing outside of that folder.

2. While, for example, the cxx bindings are built AND linked against
   the build results, the packaging situation for C++ libraries is a
   bit different compared to Rust libs. The C++ libs will likely get
   built as part of the larger libgpiod build and published together
   with the C variant.

   In Rust, the vast majority of people will want to build the glue-code
   during the compilation of the applications that consume this lib.

   This may lead to inconsistencies between the bundled headers and the
   libraries shipped by the user's distro. While ABI should hopefully
   be forward-compatible within the same MAJOR number of the .so,
   using too new headers will likely quickly lead to mismatches with
   symbols defined in the lib.

3. Trying to build the core lib as part of the Rust build quickly runs
   into similar packaging issues as the existing solution. The source
   code of the C lib would need to become part of some package
   (often people opt to pull it in as a submodule under their -sys crate
   or even create a separate -src package [1]). This clearly does not
   work well with the current setup...

Since building against system libs is probably? what 90%+ of the people
want, this change hopefully addresses the problems above. The
system-deps dependency honors pkg-config conventions, but also allows
users flexible ways to override the defaults [2]. Overall, this keeps
things simple while still allowing maximum flexibility.

Since the pkg-config interface is just telling us which include paths to
use, we switch back to a wrapper.h file that includes the real gpiod.h.

Once Rust bindings require a lower version floor, the version metadata
can also be updated to help telling users that their system library is
too old.

In order to support people hacking on the Rust bindings, building with
make will automatically set the right set of environment variables.
In case people want to customize it when building without `make`, a
reference to the system_deps documentation is given in the README.md.

[1] https://github.com/alexcrichton/openssl-src-rs
[2] https://docs.rs/system-deps/latest/system_deps/#overriding-build-flags

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

rust: bindings: turn SPDX tags into comments

In markdown `# Foo` generates a top-level heading. This leads to to some
weird, huge SPDX tags being rendered before the start of the actual
content.

Lacking good examples, I just took the syntax that `reuse addheader`[1]
outputs.

[1] https://github.com/fsfe/reuse-tool

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: specify the symbols to export explicitly

We're currently unintentionally exporting a bunch of symbols that should
remain local to sub-modules. Use __all__ where appropriate so that we
don't re-export standard library functions such as select() etc. in the
gpiod module.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: remove unneeded cc dependency

It was never used in upstream. The use was dropped during review [1], but
this dependency did not get removed.

[1] https://lore.kernel.org/r/cover.1659442066.git.viresh.kumar@linaro.org/

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: drop legacy extern crate syntax

This is a relict from old Rust standards and no longer requires [1].

[1] https://doc.rust-lang.org/edition-guide/rust-2018/path-changes.html#no-more-extern-crate

Signed-off-by: Erik Schilling <erik.schilling@linaro.org>
Acked-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: change the interpretation of None in event wait

The docs don't mention it but currently passing None as the timeout to
one of the event wait methods works like passing 0 to select() - the wait
method returns immediately. Change it to a more standard behavior - None
makes the method block indefinitely until an event becomes available for
reading.

This is a slight change in the behavior but let's hope nobody complains
as libgpiod v2 is still pretty recent and its adoption is (hopegully)
not wide-spread yet.

Reported-by: Nicolas Frattaroli <frattaroli.nicolas@gmail.com>
Suggested-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Reviewed-by: Kent Gibson <warthog618@gmail.com>

bindings: cxx: clarify the meaning of negative timeouts in event wait

chip::wait_info_event() and line_request::wait_edge_events() behave the
same as their C counterparts in that they block indefinitely when passed
a negative timeout value. State it explicitly in the docs.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

README: provide more info in Contributing

Add more detail to Contributing to make it easier for new users to
contribute.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: fix typo "SPDX-FileCopyrightTest" in copyright headers

It should be SPDX-FileCopyrightText instead. Fix it.

Reported-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
Reviewed-by: Erik Schilling <erik.schilling@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: shrink the doxygen conditional section

The conditional section around the GPIOD_CXX_API symbol should end right
after its definition, not wrap around the sub-headers inclusions.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: rust: skip building all rust crates by default

We don't really need to build all the available rust crates here by
default, but only what's required by the libgpiod crate.

Currently we try to build gpiosim-sys crate as well, even if
"--enable-tests" isn't passed to autogen.sh, which results in following
build failure:

  error: could not find native static library `gpiosim`, perhaps an -L flag is missing?

Fix this by building just the libgpiod crate instead, which can force
building of the other crates based on the enabled configuration options.

Reported-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
Signed-off-by: Viresh Kumar <viresh.kumar@linaro.org>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: move the test case for duplicate configured offsets

This test case lives in tests-line-request.c but it doesn't really test
request functionality but rather only the behavior of line-config. Limit
it to only testing struct gpiod_line_config and move it to
tests-line-config.c.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: add MANIFEST.in to EXTRA_DIST

The manifest is not being bundled with the distribution tarball. Add it
to EXTRA_DIST.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: don't segfault if gpio-sim is unavailable

The GLib wrapper for libgpiosim tries to create the gpiosim context and
bank objects in the class's init() function but the constructed()
callback doesn't check if that operation succeeded, leading to a crash
when it dereferences the bank pointer.

As init() should only perform operations that cannot fail, let's move all
the gpiosim initialization code to constructed() and bail-out of it if
any of the steps fails.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: don't install test-specific C extension binaries

We want to ship the source code for C extensions used by the test suite
but not install the built shared objects or put them into the bdist.
Extend the build_ext command to delete the tests from the build directory
right after the extensions have been built and - possibly - installed
into the source tree (if --inplace is set).

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

Revert "bindings: python: fix out-of-tree build"

This reverts commit addf968c7321132a8c659e06cc06c76534ec31f5.

We're moving towards being compatible with PEP 517 for building and
currently the following error happens when running setup.py build_py:

running build_py
error: Error: setup script specifies an absolute path:

    <snip>/libgpiod/bindings/python/./gpiod/ext/chip.c

setup() arguments must *always* be /-separated paths relative to the
setup.py directory, *never* absolute paths.

As the Makefile build should only be used for development purposes, I
think we can safely drop support for out-of-tree build. Python bindings
have now been spun out into their own tarball and are available to
install from pip.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: exclude test submodules from the package list

We already exclude 'tests' but 'tests.*' must be excluded as well if we
don't want to install the gpiosim and procname submodules.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: don't install test executables

I'm not sure what historical reasons there were to install test programs
if they are built but now I can't see any anymore. Tests can be run from
the build directory and users such as meta-openembedded can install them
and the relevant libraries (libgpiosim) manually into the filesystem as
they don't usually live in ${bindir} anyway. Installing test binaries just
pollutes the filesystem now so stop doing it.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: update .gitignore

The name of the project has changed so the egg-info directory is no
longer ignored. Update .gitignore but make the entry more general.

Fixes: d5a454cda504 ("bindings: python: change the project name to libgpiod")
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: check the return value of gpiod_line_config_add_line_settings()

The call to gpiod_line_config_add_line_settings() can fail in the thread
function used by info-event test cases so check its return value and act
accordingly.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: bump version to v2.0.1

Update the version of python bindings to v2.0.1. I treat it as a bug-fix
release as the changes only apply to packaging and building (in
preparation for making the package available on pypi) and there are no
functional changes in the bindings.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: add missing test package files to the manifest

__main__.py and __init__.py are omitted with the default source discovery
so add an explicit recursive include for tests in order to package them.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: add a long description to setup.py

Add a long description that will be displayed on the main page once we
make the project available on pypi.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: add test extension sources to the manifest

We want to package the .c sources for test-specific extensions so add
them to the manifest.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: exclude tests from the wheel

We currently "include" the gpiod package in find_packages() which does
nothing as it would be discovered anyway. We want to package the test
sources but exclude it from the binary wheel so use the "exclude"
argument.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: change the project name to libgpiod

The name 'gpiod' is already taken on pypi. Switch to using 'libgpiod'
as the name of the project. Keep 'gpiod' as the package name which
maintains code compatibility.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: python: add MANIFEST.in

In order to allow building sdist and wheel packages for python bindings
with python3-build, add a proper MANIFEST.in file.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: fix the test case for gpiod_line_config_get_line_settings()

We should compare the values stored by the 'retrieved' line settings
object, not the original 'settings'.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: simplify and reduce the strictness of version string regex patterns

It seems like every release there's some new problem with parsing the
version strings in tests. Let's reduce the strictness of the patterns
to avoid future test failures and accept the following version schemes:

X.Y
X.Y.Z
X.Y-devel
X.Y-rcZ

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: fix version regex treewide

The square bracket is in the wrong place which makes the regex not match
version strings of the form: x.y.z. Fix the pattern in core and bindings
tests.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: provide and use gpiod_test_chip_watch_line_info_or_fail()

We can shrink the code a bit by wrapping the call to
gpiod_chip_watch_line_info() and the subsequent checks in a helper macro.
This also fixes a potential null-pointer dereference in one of the info
event test cases.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tests: fix inconsistent naming of test helpers

Some of the helpers' names don't refer to the objects they're acting
upon. Make the naming consistent. While at it: fix line breaking in the
helpers header.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: replace alphasort() with versionsort()

Sorting chip names with alphasort() results in gpiochip2 coming after
gpiochip19 as it only find the lexicographic order of strings. Switching
to using versionsort() makes it look better and the order is more logical
with the numbering being taken into account.

Reviewed-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

tools: tests: update the kernel version required to run tests

The v5.16 kernel requirement is a leftover from when the tests were
developed to work with gpio-sim before the module was actually released
in v5.17. Update the kernel requirement to v5.17.4 which includes fixes
to set/get_multiple() callbacks in gpio-sim.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

man: update the email address shown on man pages

I mainly use brgl@bgdev.pl for my open-source work so update the man
pages accordingly.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

build: use AM_V_GEN when calling external programs

In order to output a status line in silent mode and the whole command in
default mode, use the AM_V_GEN predefined automake variable when executing
external programs like doxygen and help2man.

Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>

bindings: cxx: tests: fix the test case for chip::unwatch_line_info()

We need to actually trigger a line-info event before making sure the watch
has been disabled.

Fixes: f2245fa32c1b ("bindings: cxx: tests: add a test case for chip::unwatch_line_info()")
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>