licensing: relicense C++ library code under LGPL-3.0-or-later

Using LGPL-2.1 for C++ library code is an issue raised several times on
the linux-gpio mailing list. Programs using C++ libraries often include
significant portions of code generated behind the scenes from C++ headers
(via templates, default implementations etc.).

Section 3 of LGPL-3.0 clarifies the use of code defined in or generated
from C++ headers so this changset proposes to use LGPL-3.0 for all C++
library code in libgpiod.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Acked-by: Kent Gibson <warthog618@gmail.com>

licensing: relicense non-library code under GPL-2.0-or-later

LGPL-2.1 is a license meant for shared libraries. Because I didn't know
any better I used it for all files in the repository, including programs
linking against libgpiod. The standard approach for many similar projects
is to use LGPL for library code and GPL for programs (and also Makefiles
and other files containing code or configuration).

Relicense all programs, tests, makefiles and autotools files under
GPL-2.0 or later.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Acked-by: Kent Gibson <warthog618@gmail.com>

licensing: make the project REUSE-compliant

In order to make the licensing situation of libgpiod clear and enable
easy reusing of the code, let's make all the files in the repository
compliant with the REUSE v3.0 specification.

In order to achieve that:
  - put all used licenses into a separate LICENSES/ directory
  - add SPDX license identifiers to all files that were missing them with
    regular text files being licensed under CC-BY-SA-4.0, while files
    containing code and configuration are licensed under GPL-2.0-or-later
  - replace custom copyright texts with SPDX-FileCopyrightText
  - update the gpio.h kernel uAPI header with the upstream version where
    the SDPX license identifier was fixed to use 'GPL-2.0-only' variant
    instead of the deprecated 'GPL-2.0'

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Acked-by: Kent Gibson <warthog618@gmail.com>

bindings: python: fix uninitialized default_vals being passed to gpiod_LineBulk_request()

If "default_vals" is not provided in the kwds then default_vals are
passed uninitialized to gpiod_line_request_bulk(), so rename the
existing default_vals to vals and introduce a new default_vals that
points to vals, or NULL if no defaults have been passed.

Fixes: 96c524c4951c (bindings: implement python bindings)
Reported-by: Pedro Botella <pbotella@gmail.com>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: cxx: tests: remove stray tab

Remove an unnecessary tab from the mockup class header.

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

bindings: cxx: fix building with clang's libc++

This fixes the following error with clang 11 with libc++:

 line.cpp:248:39: error: implicit instantiation of undefined template 'std::__1::array<gpiod_line_event, 16>'
         ::std::array<::gpiod_line_event, 16> event_buf;
                                              ^
 /nix/store/vk8ynr4hj2a8w7g1b9m8wknzj39iiv4x-libc++-11.0.1/include/c++/v1/__tuple:219:64: note: template is declared here
 template <class _Tp, size_t _Size> struct _LIBCPP_TEMPLATE_VIS array;

Signed-off-by: Jan Kundrát <jan.kundrat@cesnet.cz>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

core: add the kernel uapi header to the repository

In order to avoid any problems with symbols missing from the host linux
kernel headers (for example: if current version of libgpiod supports
features that were added recently to the kernel but the host headers are
outdated and don't export required symbols) let's add the uapi header to
the repository and include it instead of the one in /usr/include/linux.

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

bindings: cxx: line: reorder bias mapping entries

Reorder the definitions so that they match the order in which they're
declared in the class. This is cosmetic only.

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

treewide: make drive settings an enum

Open-source and open-drain drive settings are mutually exclusive just like
the bias settings. Make them into an enum so that becomes clear.

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

treewide: rename BIAS_DISABLE to BIAS_DISABLED

When we're reading the current bias setting of a line, it is already
disabled so the flag should be named as such. While BIAS_DISABLE would
technically be fine when modifying the setting, let's rename it to
BIAS_DISABLED too for consistency.

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

treewide: rename BIAS_AS_IS to BIAS_UNKNOWN

When inspecting the current bias setting of a GPIO line, the AS_IS name
of one of the possible values really means that the kernel GPIO subsystem
can't determine the bias setting because it didn't set it itself (e.g.
the hardware may have internally initialized pull-up or pull-down
resistors). In this case it's better to change the name to BIAS_UNKNOWN
to reflect that.

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

treewide: simplify the active-low line property

Unlike line direction - where input and output modes are equal, no signal
inversion (active-high) is the natural state of the line while active-low
is less likely. Let's drop the ACTIVE_STATE enum treewide and provide a
boolean property for lines - is_active_low() - to reflect that fact. This
function returning false means the line is "active-high".

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

treewide: remove helpers for opening chips by name & number

Helper wrappers around gpiod_chip_open() shouldn't really be part of
the core, low-level library. They assume that devtmpfs is mounted at
/dev and that GPIO chips follow the gpiochipX naming convention.

This changeset removes all variants of gpiod_chip_open() other than
the one taking the path as argument. We're doing this treewide so
C++ and Python bindings lose the 'how' argument that currently allows
to change the way the chips are opened by the chip's constructors or
the open() method in C++.

The gpio-tools programs still support opening chips by number, name
and path but they implement this functionality locally rather than
using the library code.

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

core: remove unneeded include from gpiod.h

This header is a leftover from previous development. Remove it as nobody
requires it.

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

tests: line: remove a bad test case

The test case for requesting multiple lines exposed by different chips
has never been correct. The request call does indeed fail with EINVAL
but now that we've disallowed adding lines from different chips to
the same bulk object, this happens only because we're using a wrong
constant in the flags field of the request structure.

Remove the entire test as it's no longer required.

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

core: kill chip iterators

Chip iterators require the user to have permission to access all GPIO
chips. They also don't take into account symbolic links. In general
they're badly designed so remove them treewide in favor of scanning /dev
manually using the provided gpiod_is_gpiochip_device() helper.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

build: add a configure switch for building examples

Example code for bindings is currently always built if bindings are
enabled. Make it conditional with a new configure switch.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

core: rework gpiod_chip_find_line()

GPIO line names are not unique and the library has been incorrectly
making such assumption in v1.x series. We've already dropped interfaces
that would be too complicated to maintain when taking this into account.

Let's now rework the remaming API. This introduces a new function to the
C API: gpiod_chip_find_line_unique() which assumes that the line name is
unique and signals an error if it's not. The previous
gpiod_chip_find_line() function now returns a bulk object containing all
matching lines.

Python and C++ bindings are updated: their find_line() functions return
bulk objects (or an ::std::vector> too now and they take an additional
argument specifying whether we're looking for a unique line or not.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

treewide: kill find_lines()

GPIO line names are not unique. Looking up multiple lines by names would
require us to return a list of matching lines for every name. We're
simplifying the library API so drop this interface treewide.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

treewide: kill global line lookup

Global line lookup doesn't really work correctly because GPIO line names
are not unique. We'd have to return a list of matching lines. Also: not
all chips may be accessible by user in which case the chip iterator will
fail. We'll soon be removing chip iterators entirely so for now drop the
global line lookup and let users iterate over chips themselves.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

core: kill gpiod_line_get()

We're dropping all interfaces for global line lookup and accessing. Lines
should be always accessed via their owning chip object.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

core: kill gpiod_line_close_chip()

This helper was supposed to be used together with global line lookup
which will soon be removed so drop this one too.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

API: move gpiod_line_get_chip() to line attributes section

This routine should logically be part of line attributes. Move it out
of the misc line section.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

treewide: kill opening chips by label

Chip labels are not unique - opening chips by label may lead to errors
or to ignoring chips with duplicate labels. Users can easily implement
chip lookup by label themselves so remove this part from the core library
and all bindings.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

core: drop line iterators

Hand-crafted iterators don't make much sense in C and impose an
additional layer of memory allocation and resource releasing. Remove
the line iterators from the core C library.

We're leaving the iterators where they make sense: in C++ and Python
bindings but we convert them to using other means of keeping track of
lines.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

bulk: drop the limit on the max number of lines

The limit of 64 lines max per bulk object is wrong. We may want to
retrieve all lines from a chip exporting more than 64. We'll be reducing
the role of bulk objects soon so drop this limit now.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

core: export gpiod_is_gpiochip_device()

We'll be dropping chip iterators treewide. Instead we'll encourage
scanning /dev for GPIO chip devices. Exporting this function allows
users to easily check if given file represents a GPIO chip character
device.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

build: drop the message about tests having been built successfully

This is a leftover from early times. We now have multiple different
test suites and none prints such a message. Drop it.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

bindings: cxx: check for error from gpiod_line_bulk_new()

We call gpiod_line_bulk_new() in C++ bindings but never check its return
value. This function can fail so add a private method to line_bulk that
calls it and throws an exception if it returns NULL.

Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>

core: improve a comment in is_gpiochip_cdev()

Drop the repetition in the comment in is_gpiochip_cdev() to make it
sound better.

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

doc: remove any referencess to context-less API

Context-less API has been removed. Remove any leftover bits from the
documentation.

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

core: remove unused forward declaration

struct gpiod_line_bulk_iter never made it into the API and its forward
declaration is a leftover. Remove it.

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

treewide: unexport GPIOD_UNUSED

GPIOD_UNUSED symbol isn't used in any public part of the library. We
can unexport it and put it into tools-common.h for use by tools only.

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

ctxless: drop all context-less interfaces

The context-less family of functions seems to be largely unused.
Drop this part of the codebase and convert tools to using the regular
low-level API.

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

core: provide gpiod_line_bulk_reset()

Provide a helper function that allows to reset an existing bulk object.

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

treewide: rework struct gpiod_line_bulk

Current implementation of struct gpiod_line_bulk uses stack memory
excessively. The structure is big: it's an array 64 pointers + 4 bytes
size. That amounts to 260 bytes on 32-bit and 516 bytes on 64-bit
architectures respectively. It's also used everywhere as all functions
dealing with single lines eventually end up calling bulk counterparts.

The rework addresses it by making the bulk structure opaque and
providing appropriate interfaces for library users while retaining a way
for internal users to allocate single line bulks on the stack.

The macro-based loop has been removed. In its place we provide a function
iterating over all lines held by a bulk and calling the provided callback
function for each line.

Since bulk operations can now fail, a bunch of test-cases has been added
to cover the relevant code.

While at it: using the word offset both when referring to line's HW
offset in a chip as well as the offset in a bulk leads to confusion.
This patch renames the bulk offset to index.

Some additional improvements to the patch by:
  Kent Gibson <warthog618@gmail.com>

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

bindings: cxx: demote the line's parent chip reference to a weak_ptr

Currently the line object has the power to control the parent chip's
lifetime because it stores a hard reference (in the form of a shared
pointer) to the underlying struct gpiod_chip. This is wrong from the
relationship point-of-view - the chip should control the exposed lines,
not the other way around.

Demote the parent reference to a weak_ptr. Introduce a sub-class that
allows line and line_bulk objects to lock the chip by temporarily
converting this weak_ptr to a full shared_ptr - this way we don't risk
dropping the last reference to the parent chip when the line is calling
the underlying library functions. Chip deleted during that time will
expire right after the concerned line method returns.

This requires an API change - the global find_line() function now
returns a <line, chip> pair so that the caller gets the chance to grab
the chip's reference.

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

treewide: make linux v5.10 a hard requirement for libgpiod

The library now uses v2 of the GPIO uAPI. The new user interface is
scheduled for release as part of linux v5.10. Linux v5.10-rc1 is now
tagged so make v5.10 headers a requirement for the build and update
all tests to check for the correct version.

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

Merge branch 'for-linux-v5.10-rc1'

doc: fix typo in gpiod_line_request_bulk() documentation

Remove the stray 'the' from the doc.

Signed-off-by: Marc Ferland <marc.ferland@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: fix typo in gpiod_line_request_bulk() documentation

Replace 'prodivided' with 'provided'.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

TODO: add a task for replacing chrono::duration with chrono::time_point

We should store event timestamps in C++ bindings in
::std::chrono::time_point objects rather than in
::std::chrono::duration. Add a task for that to TODO.

Suggested-by: Helmut Grohne <helmut.grohne@intenta.de>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

tests: add check of event offset to wait_multiple

The offset field is added for uAPI v2, so extend the test to check that
the value returned is correct.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

core: Basic port to uAPI v2

Port existing implementation from GPIO uAPI v1 to v2.
The libgpiod external interface remains unchanged, only the internal
implementation switches from uAPI v1 to v2.

This is a minimal port - uAPI v2 features are not used, only the
uAPI v1 calls are switched to the v2 equivalent.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

tests: create mismatch between chip and bulk offsets in wait_multiple

Create a mismatch between the chip offsets and the bulk offsets to ensure
the implementation is not dependent on them matching.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

TODO: remove the task for removing deprecated interfaces

We no longer have any deprecated symbols in libgpiod. This task is
now complete.

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

core: remove deprecated functions

Drop all deprecated interfaces now that we're allowed to change the API
for libgpiod v2.0.

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

bindings: python: remove gpiod.version_string()

We support the standard __version__ module attribute. There's no need
to duplicate this functionality in the form of the version_string()
function.

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

bindings: cxx: tests: rename freq parameter to period_ms

The freq field of struct gpiod_test_event_thread is actually used as a
period measured in milliseconds, so rename it to period_ms in the struct
and wherever it is used as a function parameter.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

build: modernize configure.ac

Replace deprecated macros with recommended counterparts. Require a more
recent autoconf version. Add missing brackets.

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

tests: break tests if line requests fail

In many test-cases we read/set values or try to poll for events after
a failed line request. Some tests even segfault because they don't check
returned values for NULL etc.

Bail out of test cases if a line request failed.

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

bindings: python: fix Line.request() crashing

On an attempt to call the 'request' method of a Line object, the program
crashes with this exception:

> SystemError: ../Objects/dictobject.c:2606: bad argument to internal function
>
> The above exception was the direct cause of the following exception:
>
> Traceback (most recent call last):
>   File "<stdin>", line 1, in <module>
> SystemError: <class 'gpiod.LineBulk'> returned a result with an error set

The problem is that keyword args are NULL (rather than an empty dict) if
they are not present. However, PyDict_Size sets an exception if it gets
NULL.

Fixes: 02a3d0a2ab5e ("bindings: python: fix segfault when calling Line.request()")
Signed-off-by: Jiri Benc <jbenc@upir.cz>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: python: tests: add a test-case exposing a bug in Line.request()

Calling Line.request() with no keyword arguments leads to an exception
being raised by PyDict_Size(). Add a test-case exposing this bug. It
will be fixed in the subsequent commit.

Reported-by: Jiri Benc <jbenc@upir.cz>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: python: fix incorrect object size

tp_basicsize is the size of the allocated object, not of the class.

Fixes: 96c524c4951c ("bindings: implement python bindings")
Signed-off-by: Jiri Benc <jbenc@upir.cz>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

libgpiod: start v2.0 development cycle

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

libgpiod v1.6

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

NEWS: updates for v1.6

Add release notes for libgpiod v1.6.

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

doc: improve the part about non-unique line names

The current comments for functions related to line lookups state that
"lines are not unique" but they're really supposed to say "line names
are not unqiue".

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

core: fix reading subset of available events

Only read the requested number of events from the kernel rather than
reading up to 16 and quietly discarding any surplus.

The previous behavour is particularly bad for reading single events as
userspace must read the events as quickly as they arrive, effectively
negating the presence of the kernel event kfifo.

Fixes: 44921ecc9a00 ("core: provide functions for reading multiple line events at once")
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

tests: event: extend testing to cover reading a subset of available events

Add tests for gpiod_line_event_read(), including reading multiple
entries from the kernel event kfifo, and extend the existing
read_multiple_event tests to read a subset of the available events as
well as all the available events.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: cxx: fix event timestamp calculation for 32bit

Use appropriate C++ chrono library functions to convert the event
timestamp from a struct timespec to ::std::chrono::nanoseconds to
ensure correct conversion independent of platform.

Fixes: 8078a4a2ad90 ("bindings: implement C++ bindings")
Reported-by: Florian Evers <florian-evers@gmx.de>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: add @file to headers

It's necessary to have a file reference linked in the file list.
Also: strip the top_srcdir from paths

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: remove obsolete PERL_PATH

This fixes the following warning:

warning: Tag 'PERL_PATH' at line 110 of file 'Doxyfile' has become obsolete.

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: fix doxygen warning

This fixes the following warning:

warning: argument 'a4wide' for option PAPER_TYPE is not a valid enum value
Using the default: a4!

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: use autotoolized Doxyfile

This has several advantages:
* More simplified Makefile.am
* Actually used doxygen config is available as a file
* Building doc out-of-tree is possible

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
[Bartosz: add a dependency on Doxygen to the doc target in Makefile]
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: fix doxygen warnings

Apparently __<name>__ is not supported for @defgroup commands anymore in
doxygen v1.8.19 (and possibly earlier versions). This results in the
following warning (printed multiple times):

gpiod.h:79: warning: group strong: ignoring title ">high_level</strong> High-level
API" that does not match old title ">common</strong> Common helper macros"

Also the module list is broken.

Fix this my removing the underscores.

Signed-off-by: Alexander Stein <alexander.stein@mailbox.org>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: document the reasons for deprecating interfaces

Use the @deprecated doxygen tag to mark deprecated functions and explain
why their usage is discouraged.

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

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>

TODO: add a task for improving the interface for line lookups

The functions allowing to find GPIO lines by name don't take into
account the fact that line names are not unique in the linux kernel
(neither globally nor per chip). Add a task to address that in v2.0.

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

TODO: clarify the release plan for libgpiod v2.0

Bumping the major version number is now planned to coincide with the
release of the v2 kernel uAPI for the GPIO character device. Update
the appropriate paragraph in the TODO file.

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

TODO: add a task for Rust bindings

I'd like to include Rust bindings in libgpiod at some point. This
is a low-priority task though.

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

bindings: cxx: fix sign-compare compile warnings in tests

Fix sign-compare compile warnings in cxx tests.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

core: fix gpiod_line_get_value_bulk for events

Extend gpiod_line_get_value_bulk so that it works for bulks of
lineevents, not only linehandles.

Reported-by: Gerrit Wyen <ml@ionscale.com>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

tests: event: add tests for gpiod_line_get_value_bulk events

Add tests to verify the behaviour of gpiod_line_get_value_bulk when
applied to a bulk of event lines.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: cxx: tests: add tests for bulk events get_values

Add tests to verify the behaviour of get_values when applied to a bulk
of event lines.

Reported-by: Gerrit Wyen <ml@ionscale.com>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: fix comment mix up in gpiod.h

A couple of the doc comments for GPIOD_LINE_REQUEST_XX values document
the wrong value. Switch them so that they document the appropriate value.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

tests: remove debug asserts

Remove asserts that are a hangover from debugging test cases.

Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: cxx: fix the forward declaration for line_event

line_event is defined as a struct, not a class. Fix the forward
declaration for consistency.

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

gpioinfo: print bias flags if set

When printing line information: check the bias configuration and include
the current value in the 'flags' column of output.

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

tools: unduplicate signalfd() code

The code creating the signal file descriptor in gpiomon and gpioset is
pretty much the same. Move it into tools-common.

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

bindings: cxx: drop a stray newline

Drop an unnecessary newline from struct line_event.

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

doc: improve the description of gpiod_line_event_read()

The description of gpiod_line_event_read() states that it reads the last
event that occurred for this line. This is not true: the kernel stores
the events in a FIFO and this function reads the next event from it.

Fix the confusing statement.

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

TODO: add a list of planned API changes for v2.0

At some point in the future we'll make non-compatible changes to the
API and increase the major version number. Add a list of changes planned
for v2.0 to the TODO file.

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

tools: tests: fix regex patterns for timestamps in gpiomon test cases

Commit f8850206e160 ("gpio: Switch timestamps to ktime_get_ns()") in the
linux kernel (released in v5.7-rc1) changed the clock used to generate
line events from real-time to monotonic. This has the effect of making
the timestamp values much smaller and it uncovered a bug in regex
patterns used to verify gpiomon output: they don't expect there to be
any whitespace characters in the timestamp part of the line.

Fix it by accepting any number of whitespace chars between the opening
'[' and the first digit of the timestamp.

Fixes: 9c5a6f31ebff ("tests: use GLib for library test cases and bats for gpio-tools")
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

doc: add descriptions for doxygen sub-sections

Add additional descriptions fox doxygen sub-sections under the line
section.

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

bindings: python: add the __version__ module attribute

The python module provides the version_string() function that returns
the API version but the standard way to do this according to PEP 396
is by providing the __version__ attribute at the module level.

Add __version__ constant to gpiod module and mark version_string() as
deprecated in the doc.

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

build: use the gnu89 C standard explicitly

We're already using it implicitly but GCC may change the default
standard to gnu99 at some point, so use gnu89 explicitly whenever
building C files.

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

core: reuse the err_close_fd label in gpiod_chip_open()

Remove redundant resource cleanup in error path after is_gpiochip_cdev()
and reuse the already existing label.

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

build: check for realpath() in configure.ac

Core library is now using realpath(). Check its availability in
configure.ac.

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

core: relax gpiod_chip_open() for symbolic links

User may ask device helper tool, for example, udev, to create a specific
symbolic link to a device node. GPIO chip character device node is not
exceptional. However, libgpiod in the commit d9b1c1f14c6b
("core: harden gpiod_chip_open()") went way too far in the hardening device
node check.

Relax that hardening for symbolic link to fix the regression.

Reproducer:

  % gpioinfo /dev/gpiochip5
  gpiochip5 - 16 lines:
      line   0:  "MUX33_DIR" "uart1-rx-oe" output active-high [used]
      ...

  % ln -sf /dev/gpiochip5 /dev/MyGPIO_5

  % gpioinfo /dev/MyGPIO_5
  gpioinfo: looking up chip /dev/MyGPIO_5: Inappropriate ioctl for device

Link: https://stackoverflow.com/questions/60057494/gpio-issue-with-sym-link
Fixes: d9b1c1f14c6b ("core: harden gpiod_chip_open()")
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

bindings: cxx: fix std namespace resolution

We try to always resolve symbols from std starting from the global
namespace by using the '::' prefix but there are a couple places where
this was missed. This patch makes the resolution consistent treewide.

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

tests: misc: fix the version string test case

The current development version is v1.6-devel. The '-' character is
there to differentiate between the "main" version part and the extra
suffix.

The existing test case for the version string is now failing because
we used '.' previously for the extra version suffix. Fix it by extending
the regex pattern.

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

Merge branch 'next'

libgpiod: start v1.6 development cycle

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

libgpiod v1.5

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

README: remove the reference to v4.8 kernel headers

The project now depends on v5.5 kernel headers to build. Drop the
reference to v4.8 headers and instead refer readers to the contents
of configure.ac for the exact required version.

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

iter: remove unnecessary indirection in free_dirs

It is not necessary to pass the address of the 'dirs' variable to
dirs_free(), so this commit removes the unecessary indirection.

Signed-off-by: Chris Nisbet <chris@nisbet.kiwi.nz>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>

configure: move the ABI version definition for libgpiomockup

Having it separated from the other ABI versions already led to it almost
being forgotten when incrementing versions before release. Group all
versions together.

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

build: increment the revision in libgpiomockup's ABI version

This helper library too has a separate ABI version, but we missed it
when incrementing other ABI numbers for v1.5-rc1. Increment the revision
only as no new interfaces were added or old ones removed.

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

libgpiod v1.5-rc2

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