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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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.
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.
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>
Kent Gibson [Wed, 14 Oct 2020 11:30:52 +0000 (19:30 +0800)]
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>
Kent Gibson [Wed, 14 Oct 2020 03:45:50 +0000 (11:45 +0800)]
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>
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.
Jiri Benc [Tue, 6 Oct 2020 17:17:08 +0000 (19:17 +0200)]
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.
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.
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".
Kent Gibson [Sat, 12 Sep 2020 08:11:05 +0000 (16:11 +0800)]
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>
Kent Gibson [Sat, 12 Sep 2020 08:11:04 +0000 (16:11 +0800)]
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>
Kent Gibson [Wed, 9 Sep 2020 01:40:03 +0000 (09:40 +0800)]
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>
Alexander Stein [Sat, 8 Aug 2020 09:59:41 +0000 (11:59 +0200)]
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>
Alexander Stein [Sat, 8 Aug 2020 09:59:40 +0000 (11:59 +0200)]
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>
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.
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.
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.
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.
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.
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>
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.
Andy Shevchenko [Thu, 6 Feb 2020 18:13:58 +0000 (20:13 +0200)]
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.
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.
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.
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.
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.
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.
bindings: python: tests: package the python test-suite in the dist tarball
The test-suite python scripts is added to bin_SCRIPTS in Makefile.am.
This means it's not distributed by default. Add it to dist_bin_SCRIPTS
and make it part of the distribution tarball.
Fixes: 452696601ae5 ("bindings: python: use unittest to implement a proper test-suite") Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Cleanup the main .gitignore: remove explicit filenames which are already
implicitly ignored with pattern entries and move all the specific
entries into appropriate sub-directories.
core: provide functions for reading multiple line events at once
The kernel allows us to read multiple (up to 16) line events with
a single read() call, but up to this point libgpiod only supported
reading one event at a time. Add two new functions that allow users
to read more events at the same time.
core: use gpiod_line_event_get_fd() in gpiod_line_event_read()
We can drop the redundant line state check if we directly call
gpiod_line_event_get_fd() from gpiod_line_event_read(). As opposed
to line_get_fd() it checks if the line was requested for events.
gitignore: ignore libtool scripts created when cross-compiling
When '--host' option is passed to configure, the name of the generated
libtool script will be prefixed with the value used as argument for
'--host'. Add a pattern for prefixed 'libtool' scripts to .gitignore.
Original libgpiod relied on linux headers v4.8 to build but it was only
documented in README and not enforced at build-time. We now support
features first available in linux v5.5. Add a check to configure.ac that
verifies if recent enough kernel headers are available - otherwise we'd
fail only when trying to build the library.
projects / qemu-gpiodev / libgpiod.git / log