bindings: python: fix a warning

On some architectures we get a 'comparison between signed and unsigned
integer' warning when building python bindings. Fix it by changing the
type of the variable used for offset to unsigned int.

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

bindings: python: add a test case for line_event's __repr__

Check if an event's representation string is generated correctly.

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

bindings: python: avoid calling object method callbacks directly

Where it's impossible to use PyObject_CallMethod() (e.g. when we want
to pass args and kwargs unchanged to the method being called), use
a combination of PyObject_GetAttrString() and PyObject_Call().

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

bindings: python: use PyObject_CallMethod() where possible

Avoid directly calling method callbacks. Use the routine provided by
Python API instead where possible.

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

libgpiod: start v1.2 development cycle

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

libgpiod v1.1

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

NEWS: updates for v1.1

Add release notes for libgpiod v1.1.

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

bindings: cxx: set the ABI version to 1.0.0

The C++ bindings ABI that will be released in v1.1 is considered
stable. Set it to 1.0.0 for the release.

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

bindings: python: add support for controlled execution

Provide __enter__ and __exit__ callbacks for Chip so that it can be
used with the 'with' statement.

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

bindings: python: provide better resource control

So far we rely on cpython's reference counting for closing the GPIO
chips and freeing the underlying resources. This is however wrong.
Python doesn't guarantee anything regarding the lifetime of an object.

Provide a method for closing the underlying chip handle and add
relevant checks to all methods using the resources associated with
a GPIO chip, so that we raise an error should the user use a chip
after closing it.

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

bindings: python: provide gpiod.version_string()

Implement a python wrapper around gpiod_version_string().

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

doc: tweak the comment for gpiod_version_string()

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>

bindings: python: test case for line flags

Add a new test case verifying that line flags work as expected.

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

bindings: python: provide Line.is_requested()

Add a python wrapper around gpiod_line_is_requested().

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

bindings: python: improve readability in test cases

Mostly just add new lines for improved readability.

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

bindings: python: new test cases/examples

Add more test cases/code examples for python bindings.

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

bindings: python: provide Chip.get_all_lines()

Add a method for retrieving all GPIO lines exposed by a chip.

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

bindings: python: improve readability

Order the arguments in a reverse christmas tree shape in
gpiod_Chip_find_lines();

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

bindings: python: code shrink

Provide a helper for converting a list of lines into a LineBulk object
in a single call.

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

bindings: python: implement Chip.find_lines()

Provide a method for looking up multiple lines by name at once.

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

bindings: python: extend tests

Add more test cases/examples, implement some helper functions, tweak
the output messages, mention the need for a dummy chip in the system
in the module's pydoc string.

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

bindings: python: change the return value of gpiod_LineBulk_event_wait()

gpiod_Line_event_wait() works differently than its LineBulk
counterpart. While the latter returns either a list of lines or False,
the former returns True if an event occurred on this line or False
otherwise.

False is not a good counterpart for an actual object, so instead return
None if no events occurred on any of the monitored lines.

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

bindings: python: fix a memory leak in gpiod_Line_event_wait()

We don't return the object returned from gpiod_LineBulk_event_wait()
back to the interpreter. We need to collect it before returning True.

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

bindings: cxx: fix the return value of line_bulk::find_lines()

We should return an invalid line_bulk object if we failed to look up at
least one line from the provided list of names.

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

bindings: python: fix a memory leak in Line.set_value()

We're not collecting the bulk object we're creating in this method. Add
Py_DECREF() where needed.

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

helpers: provide gpiod_chip_find_lines()

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>

bindings: python: return None if line can't be found by name

For both find_line() variants (Chip's method and global function)
return None if the internal call to the C find_line function fails
with ENOENT. This is not an error so don't raise an exception.

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

bindings: python: decref the chip object in gpiod_Module_find_line()

When returning back to the interpreter from gpiod_Module_find_line(),
there's only one chip object reference holder, but we set the refcount
to 2 (as if the chip object existed separately in the interpreter).

Fix it by decreasing the chip's refcount by one before returning the
line object.

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

bindings: cxx: add test cases for iterators

Add simple tests for chip and line iterators.

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

bindings: cxx: new test cases

Implement more test cases for C++ bindings and extend the existing
ones.

While we're at it: use auto where applicable and log to stderr instead
of stdout.

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

bindings: cxx: add a comment about the need for a dummy chip to run tests

In order to run the C++ tests/examples, we need at least one dummy chip
to be present in the system. It also needs to be the first GPIO chip.

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

bindings: cxx: initialize the line_request flags before using them

We store the flag values in the request flags mapping before
initializing them so flags don't get translated correctly in
line_bulk::request(). Fix it by moving the flag definitions above the
mapping initialization.

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

bindings: cxx: export static members of gpiod::line_request

The static flags definitions of gpiod::line_request are not exported.
Add the missing GPIOD_API attributes.

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

bindings: cxx: fix SPDX license identifiers in examples

The source files in bindings/cxx/examples still use C-style comments
for SPDX license identifiers. Use C++-style comments for consistency
with all other source files in the repository.

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

bindings: python: release the GIL during blocking I/O operations

We should release the python global interpreter lock when performing
blocking operations and reacquire it again when we're done. Use the
relevant APIs provided by libpython.

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

README: add info about building from release tarballs

There's no need to use autogen.sh if building from release tarballs as
the configure script is already provided. Only git builds need
autoreconf.

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

README: add info about high-level bindings

Briefly describe C++ and python bindings.

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

build: fix cross-compilation of python bindings

AX_PYTHON_DEVEL macro from the autoconf-archive collection doesn't work
when we're trying to cross-compile python bindings in environments such
as buildroot or yocto. It can't properly detect the location of python
headers.

Let's use AM_PATH_PYTHON to detect the python3 interpreter and then
either take the PYTHON_CPPFLAGS and PYTHON_LIBS variables from the
environment (so that cross-compiling build systems can pass their
custom locations to autotools) or try to detect them ourselves using
the python3-config tool.

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

build: check for unexpanded macros in configure.ac

We're now using m4 macros from the autoconf-archive collection. The
user may be missing this package so check for unexpanded AX_* macros
and bail-out if any are found.

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

bindings: implement python bindings

Create a C extension module wrapping the functionality of libgpiod
in a set of Python classes.

Add code examples including simplified reimplementations of gpio-tools
in Python.

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

core: events: correctly handle POLLNVAL in gpiod_line_event_wait()

The only error that can be indicated by ppoll() in the revents field
of struct pollfd when polling a line events file descriptor is
POLLNVAL. It can happen if the user calls close() on said descriptor
after retrieving it with gpiod_line_event_get_fd().

Currently we would act as if there's a line event to read. Make
gpiod_line_event_wait() and its bulk variant return -1 and set errno
to EINVAL in this case.

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

tools: fix the copyright notice

The copyright notice displayed together with the package version using
the --version argument got accidentally modified by commit 0704bcdbbf56
("all: update the copyright notice") and is now incorrect. Fix it.

Fixes: 0704bcdbbf56 ("all: update the copyright notice")
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

build: tweak the message emitted after building tests

The kernel version displayed in the message has not been updated the
last time we bumped the kernel version required for running tests.

We don't need to print this version here - the test suite will bail-out
anyway if the kernel is too old. Drop it from the message.

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

core: use reference counting for line file descriptors

In v0.x series we were using a separate, refcounted structure for
storing the file descriptor returned by the linehandle request ioctl().
We also had a separate mechanism for event file descriptors. This was
quite complicated and was replaced by a simpler structure in v1.x
series.

It turned out however that we're now calling close() on already closed
descriptors when releasing a set of simultaneously requested lines.

In order to fix that we need to go back to having a refcounted file
descriptor handle. This time we're using the same structure for storing
both values and events file descriptors (even though there can't be
more than one line per descriptor requested for events) for simplicity.

This patch also adds a test case that verifies the reference counting
works as expected.

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

license: use C++-style comments for SPDX headers in source files

Follow the linux kernel licensing style and only use C-style comments
in C headers.

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

tests: gpioinfo: expect default direction to be input

Starting with linux v4.16 the direction of gpio-mockup lines is input
by default as is the case for all real gpio drivers.

Modify the expected strings in test cases for gpioinfo and make v4.16
the minimum kernel version to run libgpiod tests.

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

build: use separate versioning schemes for API & ABI

Commit 783ff2e3c707 ("API: start certain enums from 1") broke the ABI
compatibility (while keeping the source compatibility). We need to
indicate that to the users by changing the SONAME string. Up until now
the SONAME would correspond with the major release number. We now need
to have a separate versioning schemes for API and ABI.

Keep using the same MAJOR.MINOR.RELEASE scheme for the API, but switch
to using the libtool versioning - CURRENT.REVISION.AGE - for ABI. Start
the ABI version from 2.0.0 to indicate that it changed since 1.0.0.

Define a separate ABI version for the C++ bindings, but start with 0.0.0
since it was not a part of any release yet.

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

build: user SPDX license identifier

Use the SPDX license identifier for LGPLv2.1 or later in the remaining
build and helper files.

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

bindings: cxx: use SPDX license identifier

Use the SPDX license identifier for LGPLv2.1 or later in C++ bindings
directory.

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

include: use SPDX license identifier

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>

core: use SPDX license identifier

Use the SPDX license identifier for LGPLv2.1 or later in core source
files.

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

tests: use SPDX license identifier

Use the SPDX license identifier for LGPLv2.1 or later in source files
of the testing framework.

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

bindings: cxx: rename the C++ tests executable

Include the project's prefix in the executable name.

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

bindings: cxx: rename line_bulk::add() to line_bulk::append()

This routine adds the line at the end of the internal list of lines.
Rename it to append() in case we ever want to introduce prepend().

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

bindings: cxx: don't check the chip's label and name for empty strings

The core library guarantees that a GPIO chip will have a name and
a label. No need to check if the returned strings are empty.

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

bindings: cxx: provide chip::get_all_lines()

This is a C++ method for getting all lines exposed by a GPIO chip. It
corresponds with the helper function recently added to the C API.

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

tests: add a new cleanup macro

The most commonly used cleanup attribute is the one used for automatic
closing of GPIO chips. For brevity: hide the long TEST_CLEANUP(...)
invocation behind a shorter TEST_CLEANUP_CHIP macro.

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

API: provide new line accessors

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>

bindings: cxx: rename line and chip iterator classes

Use a shorter name for code brevity. Change chip_iterator to chip_iter
and line_iterator to line_iter.

Rename the helper functions as well.

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

bindings: cxx: add pkg-config support

This will allow to use PKG_CHECK_MODULES() for C++ bindings as well.

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

tools: move function attributes to the header file

The attributes must be located next to function declarations in the
header file. Otherwise, the NORETURN attribute seems to have no effect
and GCC emits several Wimplicit-fallthrough warnings when compiling
libgpiod. This patch fixes those warnings.

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

bindings: cxx: allow empty default values in line_bulk::request()

The core library now supports NULL default values in output requests.

Update the C++ bindings and the relevant example.

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

core: allow NULL default_vals for output requests

Explicitly allow default_vals to be NULL for output requests, in which
case the actual default values passed to the kernel are set to 0.

Add a test case that verifies that this works correctly.

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

core: use gpiod_line_bulk_foreach_line_off() in line_request_values()

Use the provided helper macro instead of a manual for loop.

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

bindings: cxx: new example

Add a test case to C++ examples demonstrating the manipulation of
several lines held by a line_bulk object.

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

bindings: cxx: provide methods for releasing requested lines

Add release methods to line and line_bulk classes. This allows to
release requested lines without having to destroy the owning objects.

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

bindings: cxx: require default values for output requests

Require users to provide default values to line_bulk::request() when
direction is output.

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

bindings: cxx: constify default_vals in line_bulk::request()

The default values should be passed by const reference similarly to
how it's done in line_bulk::set_values().

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

API: start certain enums from 1

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>

bindings: implement C++ bindings

Wrap the C API in a set of C++ classes which allow to use all libgpiod
functionalities in an object-oriented manner.

Include simplified reimplementations of gpio-tools and a set of
tests/examples showing how to use the C++ interface.

The C++ API is fully documented in doxygen.

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

tests: event: new test case

Verify that the active-low flag is respected when reading line values
from lines configured for events.

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

dist: include Doxyfile in the release tarball

Doxyfile was missing from release tarballs. Include it.

Reported-by: SZ Lin <sz.lin@moxa.com>
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>

libgpiod: start v1.1 development cycle

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

libgpiod v1.0

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

NEWS: updates for v1.0

Add release notes for v1.0.

Also: the master branch doesn't contain the tags for bugfix releases so
documenting them in this branche's NEWS makes no sense.

Fold all the info about bugfix releases into the next minor release and
only keep major and minor releases in NEWS on the master branch. Bugfix
releases will only be documented in their respective minor branches
from now on.

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

core: constify *values in gpiod_line_set_value_bulk()

The values in the array passed as argument to this routine are never
modified.

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

doc: improve the doxygen description of default_val(s)

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>

doc: consistently break lines in @param's descriptions

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>

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>