doc: explicitly state that the ctxless event poll callback can be NULL

This is mentioned later in the text, but state it in the argument's
description too.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

doc: clarify that the high-level set value callback is optional

Users have reported it as confusing so make it clear.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

API: use gpiod_ctxless_ as prefix for the high-level API

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>

gitignore: add libgpiod.pc

Add the automatically generated libgpiod.pc to .gitignore.

Fixes: 819e2f5ee3e6 ("build: add pkg-config support")
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

build: add pkg-config support

Create a libgpiod.pc file for pkg-config. Allows to use
PKG_CHECK_MODULES([gpiod], [libgpiod >= 1.0],,) in other
autoconf-based projects.

Signed-off-by: Clemens Gruber <clemens.gruber@pqgruber.com>
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

gpiomon: initialize the active low variable

The variable active_low is not initialized, so the value is undefined
and if the -l argument is not passed, the undefined value remains. Fix
it by initializing it to false.

Signed-off-by: Clemens Gruber <clemens.gruber@pqgruber.com>
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: kill test_free_str()

This function is no longer used - all strings are created using
test_build_str().

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

all: fix various coding style issues

Make the entire code base more consistent with the linux kernel
coding style.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

all: update the copyright notice

All these files have been updated in 2018.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

all: modify the license preamble in files

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>

doc: minor documentation tweaks

Fix/tweak the in-code API documentation in a couple places.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: remove an unnecessary else

This else is not useful as all other if (else)'s in this block return.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

all: make license type consistent between source files and COPYING file

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>

core: don't allow open-source and open-drain flags at the same time

If the hardware actually allowed it, the electrical result would be
disastrous. This has only recently been fixed in the kernel, so add
a relevant check to the library as well.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: change the prefix for line request flags

Make it clear that these are flags and that more than one can be used
simultaneously.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: coding style tweak

Remove one tab from the GPIOD_LINE_BULK_MAX_LINES definition.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: line: remove unnecessary line releases

We don't need to release lines manually - line resources are managed
by GPIO chip objects. Remove the calls to release functions wherever
they don't make sense for any subsequent test code.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: improve error handling

Rework the way we verify that line bulk objects are consistent: split
the verify_line_bulk() function into sub-routines, make the names more
self-explanatory and add other minor fixes & tweaks.

Improve the consistency of errno codes: set errno to EPERM if the line
for which gpiod_line_event_get_fd() is called is not configured for
event monitoring.

We were already testing that line requests fail if we pass them a line
bulk containing lines from different chips, but add an analogous test
for gpiod_line_get_value_bulk().

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: make the devpath check less strict

We plan to change the way gpio-mockup platform devices are registered
in the kernel. This change will add an ID to the gpio-mockup platform
device name and will result in the devpath being changed to
'/devices/platform/gpio-mockup.X/gpiochip'.

When checking the devpath during the test case setup, it's enough to
verify that we got an event from the correct platform device - we
don't need to check the gpiochip name. Shorten the string against
which we check to skip whatever comes after the platform device name.

While we're at it: move the string definition into the function which
is the only user.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

iter: fix a crash occurring if no GPIO chips are present

If no GPIO chips are present in the system, we bail out from
gpiod_chip_iter_new() before allocating the chips array. Add a check
in gpiod_chip_iter_free() to avoid calling free() for iter->chips in
that case.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

iter: rework line iterator API

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>

doc: update the descriptions for chip iterators

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>

tests: use test_build_str() in test cases

Shrink the test code by using the newly provided helper function for
building custom strings wherever asprintf() was used before.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: provide test_build_str()

Many test cases use asprintf() to build custom strings. This routine
can fail and the return value is tested using the TEST_ASSERT macros
but this is not the subject of the actual testing. The test case must
also free the string allocated by this function.

As a simplification: pull this functionality into the testing
framework so that we can build custom strings without keeping track of
resources. The new function will also make the whole test suite die if
the internal asprintf() call fails.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

iter: rework chip iterators

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>

tests: gpioinfo: don't use static names for GPIO chips

We need to construct the pattern strings using the names supplied by
the testing framework - otherwise we may end up getting false
negatives from these test cases if the chip layout in the system is
different than expected.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

doc: update the documentation for events and iterators

Various documentation updates for iterator and event routines.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

iter: use scandir() for chip iterators

Using scandir() instead of opendir() allows us to scan for all
gpiochip devices already when creating the iterator. This simplifies
the code and doesn't require keeping the directory open when
iterating.

Storing the array of all found GPIO chips will also make it easier if
we ever want to implement a reverse iterator (e.g. for C++ bindings).

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

NEWS: updates for v0.3.2

Add release notes for libgpiod v0.3.2.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

build: tools: use absolute path in LDADD

Specify the path to libgpiod starting from the top project directory.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: simplify consumer, label & name strings handling

The separate buffers make the code less readable for no real benefit.

Remove them and simplify the strings handling. Also: improve the way
we're handling the chip names and labels.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

doc: minor fix for line bulk loop macros

Make it clear in the @brief section what the difference is between the
two variants.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

doc: improvements for the chip operations

Tweak the docs for the low-level chip API a bit.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

helpers: set errno in gpiod_chip_open_by_label()

If a GPIO chip with given label cannot be found but no other error
occurred, set errno to ENOENT before returning a NULL pointer.

Update the relevant test case.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

doc: extend the documentation of the simple API

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>

doc: extend the introduction

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>

tests: remove the MALLOC attribute from xappend()

The internally called realloc() doesn't have this attribute so we
can't propagate it up the stack.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: event: new test case

Add a test case which verifies that we can't request line events for
a set of lines if one of them has already been requested for values.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: fix an error path in line event requests

Correctly release already requested lines in case of an error
in line_request_event_single().

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: use gpiod_line_bulk_foreach_line_off()

Use the newly introduced iterator macro wherever there's a need to
access the line offset while looping over a bulk object.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: implement gpiod_line_bulk_foreach_line_off()

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>

core: code shrink for name, label & consumer strings handling

Create a helper function that implements a uniform way of copying the
info strings from the kernel data structures to gpiod_line and
gpiod_chip objects.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: update line info after requesting the event handle

Just as we do when requesting the regular line handle - update line
info to reflect the changes after the event request.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

helpers: fix a crash in gpiod_chip_find_line()

The name of a line can be NULL in which case we must check it and skip
the call to strcmp() to avoid a NULL pointer dereference.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: remove kernel data structures from struct gpiod_line

The structures defined in linux/gpio.h use non-standard data types.

Use them only when calling relevant ioctl()s and then copy the
necessary info to separate fields in struct gpiod_line.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: remove kernel data structures from struct gpiod_chip

The structures defined in linux/gpio.h use non-standard data types.

Use them only when calling relevant ioctl()s and then copy the
necessary info to separate fields in struct gpiod_chip.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: line: coding style fix

Put local variables in correct order - from longest to shortest lines.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: rename a field in struct gpiod_chip

Initially 'cinfo' stood for chip info, but since there's no other
field in this struct to confuse it with, just rename it to 'info'.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: coding style fix

Break the lines according to the kernel coding style.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: move helpers to a separate file

Create a new source file for helper functions that don't need to know
the internal data structures or use any symbols exported by the kernel.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: remove unnecessary setters and getters

These routines only obscure the code. We don't need them for simple,
internal data structures.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

event: improve gpiod_line_event_get_fd()

Set errno to EINVAL when the user calls this routine for a line
requested for values. Verify correct behavior with a test case.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: move line-related static functions to more suitable places

Group the line state routines together and put line_bulk_is_requested()
next to verify_line_bulk().

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: remove line_set_offset()

This function is not used and should have been static anyway.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: simplify the internal line context structs

The kernel uapi line handle and event request structures are only
needed for relevant ioctl() calls. After that they can be discarded as
all we need is the file descriptor.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: set errno to 0 before running each test case

Just to make sure we start with a clean environment, set errno
to 0 before running the test callback.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: don't allow OPEN_DRAIN & OPEN_SOURCE flags for input

OPEN_DRAIN and OPEN_SOURCE flags only affect the way we drive a GPIO
line, so they only make sense for output mode.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: line: fix the misc flags test case

Setting the open-drain or open-source flags for input doesn't make any
sense as these flags are only valid for output mode. This should
actually be checked in the kernel. For now fix the test case.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: modify the order of arguments in simple loop routines

Move the consumer string after the active_low property.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: modify the order of arguments in set value routines

Move the consumer string after the active_low property.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: modify the order of arguments in get value routines

Move the consumer string to the end of the argument list as the least
significant option.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: allow the simple event loop callback to indicate an error

Add a new return value for the simple event loop callback which, when
returned, makes the loop function return a negative value indicating
an error.

Include new test cases.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: improve documentation

Mention the meaning of a positive value returned from the polling
callback of the simple event loop routines.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: handle receiving multiple events

Make the simple event loop poll callback capable of signalling to the
caller that more than one event occurred. Make the event loop routine
for multiple lines aware of that so that it reads all the event data
queued up instead of needlessly polling in that case.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: use correct prefixes for callback typedefs

We want to have all simple-api-related symbols prefixed with
gpiod_simple_.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: remove double whitespace

Should be 'return NULL', not 'return  NULL'.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

event: rework gpiod_line_event_wait_bulk()

When monitoring more than one line, it's possible for two or more
events to be queued at the same time in the kernel, so the internal
call to ppoll() will return a value greater than 1. If we always only
read one event at most, we end up calling ppoll() needlessly, as we
already know more events are pending.

Allow gpiod_line_event_wait_bulk() to pass a list of all lines on
which events occurred via a line bulk object.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

build: fix building with static libraries

We call gpiod_version_string() from tools-common.c but adding
libgpiod.la to LDADD before libtools-common.la makes the linker
discard this symbol as unused.

Invert the LDADD order to fix the static build.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

gpioset: fix checking mutually exclusive options

Certain options are mutually exclusive but they're checked in a way
that doesn't always guarantee gpioset to bail out. Fix it by checking
the options that don't work together after all command-line parsing is
done.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

build: fix warnings when building with clang

Clang complains about "missing field 'has_arg' initializer" when
zeroing the last element of the struct option array with "{ 0 }".

Use a complete initializer to fix this warning.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: use line bulk accessors

Use provided routines for retrieving the line handles from line bulk
objects.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

line: provide gpiod_line_bulk_foreach_line()

Add a macro allowing to easily iterate over all lines held by a line
bulk object.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: drop unnecessary checks

The getter functions retrieving the file descriptors (both for events
and line values) check the line state internally but we don't check
their return values and just pass them on to ioctl()s. Drop the checks
altogether.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: provide gpiod_line_bulk_num_lines()

Add an inline routine allowing to retrieve the number of lines held by
a line bulk object.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

doc: split the documentation for GPIO lines into smaller chunks

Create separate sections for bulk, info, requests, values, events and
misc routines and data structures for GPIO lines.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: group the GCC attributes together

Put the defines wrapping the gcc attributes in the same place
in gpiod.h.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

iter: improve the naming of line iterator constants

These three constants define the possible line iterator states. Make
their names reflect that.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

line: rename the constant defining the max size of a bulk line object

Stay in line with other prefixes and change it to
GPIOD_LINE_BULK_MAX_LINES.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

line: use a common prefix for all line defines

Prefix all constants used by line functions with GPIOD_LINE_.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

gpiofind: use gpiod_simple_find_line() internally

Switch to using the simple API in gpiofind.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: provide gpiod_simple_find_line()

Implement a simple API function for looking up GPIO lines. Include
a set of test cases.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: provide gpiod_line_get()

Provide a routine which simplifies the process of getting the handle
for a single GPIO line by encapsulating the calls opening the chip and
retrieving the line handle in a single function.

Implement test cases as well.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: rework gpiod_line_find()

Use gpiod_chip_find_line() internally for smaller code. Return NULL
if an error occurrs during the lookup. Update the documentation.

While we're at it: update the tests for line lookups.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: rename gpiod_line_find_by_name()

Shorten the name of the line lookup routine as any other type of
lookup wouldn't make sense anyway.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: add parentheses in assert macros

Use parentheses around arguments wherever they can be numerical
values.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: chip: add test cases for gpiod_chip_find_line()

Test two use cases: correct lookup and a search for a non-existent
line.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: use TEST_ASSERT_ERRNO_IS()

Use the new assert macro wherever we're checking the errno value.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: new assertion

Add a helper for checking the current errno value.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: implement gpiod_chip_find_line()

The low-level line lookup should be more fine-grained. As the first
step: introduce a routine performing a line lookup for specific chip.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

gpiomon: fix event counting

We must not increment the events_done variable for events we're not
watching.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

gpiomon: correctly handle poll timeouts

We don't check for timeout events in the simple loop event handler.

Fix it and return a correct value.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: line: use test_line_close_chip()

Drop the unnecessary chip object.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: new cleanup function

Add a new cleanup function which calls gpiod_line_close_chip().

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: implement gpiod_line_close_chip()

This function works nicely with gpiod_line_find_by_name() which
returns a line object whose owning chip must be later freed by the
caller. With this routine the caller can skip creating a temporary
chip object.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tools: remove the redundant UNUSED define

Use GPIOD_UNUSED instead.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple-api: improve the naming convention

Discern between the callback arguments and return values by renaming
relevant defines.

Also: prefix all simple API defines with GPIOD_SIMPLE_.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

core: new public macro

Export GPIOD_UNUSED in gpiod.h as it may be useful for users not
using all arguments in certain callback functions.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

tests: simple-api: new test case

Add a test case for gpiod_simple_event_loop_multiple().

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

gpiomon: use the simple event loop

Switch to using the high-level API. This significantly shrinks the
code while keeping all the functionality.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

simple: rework the event loop

Implement a new routine for monitoring multiple lines with the simple
event loop and extend the simple loop interface with custom polling
capabilities.

Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>