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>
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>
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>
Use the @deprecated doxygen tag to mark deprecated functions and explain
why their usage is discouraged.
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.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
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>
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>
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.
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
The handling of NULL values by gpiod_line_set_value_bulk has been changed
to interpret NULL as low values for all lines. This patch updates the
documentation of the function to describe that.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Extend the libgpiod API to support the setting line configuration using the
GPIO GPIOHANDLE_SET_CONFIG_IOCTL uAPI ioctl.
The core change is the addition of gpiod_line_set_config, which provides a
low level wrapper around the ioctl.
Additionally, higher level helper functions, gpiod_line_set_flags,
gpiod_line_set_direction_input, and gpiod_line_set_direction_output provide
slightly simplified APIs for common use cases.
Bulk forms of all functions are also provided.
Documented the fields of gpiod_line to better identify the purpose of
each where the field name alone is not sufficiently clear, and to
indicate which flags are applicable to each field.
Implementation includes a few helper functions that serve to keep the
code tidier and are consistent with similar helper functions already
present.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Extend the libgpiod API to support the bias flags recently added to the
kernel GPIO uAPI. The core change is the addition of
GPIOD_LINE_REQUEST_FLAG_BIAS_DISABLE, GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_UP
and GPIOD_LINE_REQUEST_FLAG_BIAS_PULL_DOWN flags to be passed into
line_request functions, and the addition of gpiod_line_bias to return the
bias state of lines.
Variants of the ctxless functions that accept an active_low flag
are added to also accept other flags. The variant names add a "_ext"
suffix to the name of the original function.
Based on initial work by Drew Fustini <drew@pdp7.com>.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
This function and the logic behind have been introduced in an early
version of libgpiod for reasons that have been long forgotten.
When updating the line info after a line request fails, just propagate
the error out of the request function instead of setting the internal
needs_update variable. Drop the entire logic behind gpiod_needs_update(),
make this routine always return false and mark it as deprecated in the
header.
Suggested-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Trivial grammar fix. "correspond with" can mean either being in agreement
with, happening at the same time, or communication between parties.
"correspond to" is used to mean equivalance, which is the intended use
throughout the documentation.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Trivial fix to bring gpiod_ctxless_event_monitor_multiple() documentation
into line with gpiod_ctxless_event_monitor_multiple_ext().
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
This variable is called up_to_date which can lead readers to the wrong
conclusion that libgpiod can somehow know when external actors (such as
a different process or a kernel driver) change the state of a GPIO line.
This is not the case and libgpiod only ever knows if a line needs info
update when a previous internal call to gpiod_line_update() fails.
The kernel does not provide any notification mechanism currently.
For that reason: rename the variable to needs_update.
While at it: clarify the documentation for gpiod_line_needs_update().
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Unify the header includes by ordering them alphabetically and always
having local headers in a second group below the global ones (separated
by a newline).
Signed-off-by: Bartosz Golaszewski <bgolaszewski@baylibre.com>
Fix a couple problems in doxygen documentation of the C API.
(Unfortunately no Signed-off-by tag from the submitter...)
[Bartosz: added a proper commit message]
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Mark gpiod_ctxless_event_loop() and gpiod_ctxless_event_loop_multiple()
as deprecated. Those functions suffer from an issue where HW may not
allow setting up both rising and falling egde interrupts. All users
have been converted to using the new event monitor helpers.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
We want to deprecate the badly designed event loop functions. Introduce
a macro that allows marking API routines as deprecated.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Current implementation of gpiod_ctxless_event_loop() (and its variant
for multiple lines) always requests GPIO lines for listening for both
rising and falling edge events. This causes a problem when the
underlying hardware doesn't allow this.
It can e.g. result in the following error raised by the interrupt
controller:
genirq: Setting trigger mode 3 for irq 107 failed (kempld_irq_set_type+0x0/0x130 [gpio_kempld])
For the sake of backward compatibility we're leaving the old
implementation in place and provide two new routines that that take an
additional parameter allowing users to specify the events libgpiod
should listen for.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Make it clear that this function returns the API version as we now have
separate API and ABI versions.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Implement a new helper that allows to look-up multiple GPIO lines by
their names. Include a set of test cases.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Use the SPDX license identifier for LGPLv2.1 or later in the public
API header and the corresponding Makefile.am.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Add two new public functions that allow to retrieve multiple lines from
GPIO chips at once. Include test cases.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
For enums describing direction & active state, event types etc. use 1
as the first value as it's easier to debug when all valid values are
different than in a zero-initialized data structure.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Users report being confused by the name 'default_val(s)' for function
parameters. Because it's in line with the kernel uAPI, we'll leave it
like this, but let's improve the documentation a bit by stating
explicitly that this parameter represents the initial values for
requested GPIO lines.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
When breaking the line in doxygen's @param descriptions, start the
next one after the param's name.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
As suggested by Linus Walleij: the word 'simple' is generally
subjective and the high-level routines provided by libgpiod are not
necessarily simple, but rather contextless, as they don't require any
resource managemend. Use 'gpiod_ctxless_' as prefix for all high-level
symbols.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
This project contains both a library and executables so it's better to
use an umbrella term "This program ..." than "This library ..." in all
the source files.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
The license type of COPYING file is "LGPL-2.1+", but it is declared
as "LGPL-2.1" in the preamble of source files.
This patch fixes license type inconsistency issue in each source file.
Signed-off-by: SZ Lin <sz.lin@moxa.com>
[Bartosz: tweaked the commit message]
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
The changes roughly correspond with what we did for chip iterators.
Only perform operations that can fail in gpiod_line_iter_new(), so
that there's no need to check for errors after every call to
gpiod_line_iter_next().
Make gpiod_line_iter an opaque pointer and provide 'new' and 'free'
functions.
Update all users and relevant test cases. Extend the test API with
a new cleanup function.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
The 'next' routines for chip iterators can no longer fail. Update
the docs accordingly. Also: turn the extended description into a note
for the noclose variant.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
We can significantly simplify the chip iterators by performing all
actions that can yield an error in gpiod_chip_iter_new(). Instead of
opening each subsequent chip in gpiod_chip_iter_next(), open them all
in the new function and make next just return an active handle.
Fix relevant test cases and macros, remove related routines that are
no longer needed.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Fix some minor issues and tweak the style and doxygen markup.
Describe in detail the way the simple event loop works.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Add some additional info about the way the API is logically ordered
and a note on error handling.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
Implement a variant of gpiod_line_bulk_foreach_line() which allows to
store the loop state in an integer counter variable.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
