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>

simple: event-loop: fix EINTR handling

We want to handle EINTR as a timeout event. Don't return here.

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

core: add gpiod_line_bulk_get_line()

Add a getter function for retrieving line handles from bulk objects.

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

simple: remove redundant line releases

We're closing the chip right after calling the release routines in all
three cases. The chip close function releases all line resources
anyway so no need to do it twice.

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

simple: fix the active_low switch in gpiod_simple_event_loop()

We're incorrectly passing the boolean active_low argument to
gpiod_line_request_both_edges_events_flags() as flags. Add the same
conversion as in the other simple API routines.

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

build: fix the kernel version in the 'make check' message

The minimum kernel version for running tests is now 4.12.6. Reflect
that in the message displayed after building the test suite.

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

core: rename gpiod_line_is_used_by_kernel()

The UAPI flag checked by this routine is called GPIOLINE_FLAG_KERNEL
but its name may be a bit misleading. When set, it can mean that the
line is used by the kernel or by another user space process.

Use a more general name: gpiod_line_is_used().

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

README: add info about the subject line for e-mails sent to linux-gpio

For libgpiod-related e-mails the subject line should be prefixed
with [libgpiod].

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

README: update the section about contributing

The development will no longer happen on github, but on the linux-gpio
mailing list instead.

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

build: silence an ar warning

In some configurations ar prints the following warnings:

  ar: `u' modifier ignored since `D' is the default (see `U')

Silence it by setting the ar flags to 'cr' instead of 'cru' which is
the default.

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

NEWS: updates for v0.3.1

Add release notes for libgpiod v0.3.1.

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

README.md: rename to README

We now host libgpiod at kernel.org, so no need for the .md file.

This also fixes 'make dist' as README.md was not being packaged by
autotools.

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

tests: gpioset: fix a typo

Fix the spelling of the test case function name.

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

tests: re-enable a test case for gpiomon

The test case in which we verify if falling-edge events are correctly
ignored was failing due to a bug in the kernel. This has now been
fixed with commit df1e76f28ffe ("gpiolib: skip unwanted events, don't
convert them to opposite edge") and released in linux v4.12.6.

Re-enable the test and make this version a hard requirement for
running the test suite.

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

tools: use program_invocation_name

Remove set_progname() from tools-common and use the global
program_invocation_name variable.

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

tests: use program_invocation_name

We're using _GNU_SOURCE, so it's ok to use program_invocation_name
instead of storing it manually.

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

gpiod.h: improve the documentation for gpiod_line_iter_last_offset()

Mention the undefined behavior if gpiod_line_iter_last_offset() is
ever called before gpiod_line_iter_next().

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

gpiod.h: extend the introduction to the simple API

Add more info on the simple API functions.

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

gpiod.h: move the mainpage doxygen comment down

Move it to where the libgpiod declarations begin.

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

core: readability tweak

Create separate static functions for checking the request type.

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

core: add the offset argument to the simple event loop callback

In preparation for introducing a multiple lines variant of the simple
event loop routine, add the offset argument to the callback prototype.

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

core: fix single line event requests with flags

We currently always request rising edge events for the 'flags'
variants. Request correct event types.

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

core: add bulk event requests

Add functions for requesting events for line bulk objects. Both with
and without additional flags.

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

core: remove the active_low argument from line bulk requests

We previously removed this argument from routines dealing with single
line requests. Do the same for bulk requests.

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

core: group the line request code together

Put both the regular input & output requests as well as event requests
together in the same place in core.c.

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

core: move the chip-related code to the top of core.c

Just as with the public header - move the chip code above the line
definitions.

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

core: remove the active_low boolean argument from single-line requests

Remove the separate argument for setting the active-state to low in
helper functions doing the single GPIO line requests.

Introduce new variants of these helpers that allow to pass
a combination of all available flags to the request.

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

core: set the active state using the request flags

Having to always set the active state in the line request config
structure makes users create unnecessary boilerplate code. Remove the
active state field from the config structure and add a new flag, which
when set, sets the active state to low, while high is the default.

This patch updates the main request function and all the callers - we
still need to update all the helper request routines.

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

line: add a test case for empty consumer strings

Check that both libgpiod and the kernel behave correctly when passed
an empty string as the consumer name.

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

core: accept NULL consumer strings

If the user passes a NULL pointer as the consumer name to any of the
line request functions, pass an empty string to the kernel instead of
segfaulting. The kernel code will then set the consumer string to "?".

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

gpiod.h: remove the separate doxygen group for events

Much of the event functionality has been merged with regular GPIO line
definitions. We no longer need a separate group for events in the
documentation.

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

gpiod.h: move the chip operations before line definitions

Chip operations should come earlier in the public header.

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

core: merge chip.c and line.c

Splitting the line and chip functionality led to unnecessary bloat.
Just put the code together into a single file.

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

libgpiod: unify the header comments

Make the header comment look the same in every file. Move additional
descriptions of files' contents below the header.

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

event: rename event requests routines

The event request functionality is now merged with the regular
requests. Change the naming pattern for event requests and move the
prototypes under the input and output requests.

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

core: merge event requests with regular line requests

Requesting the lines both for reading/setting values as well as for
watching events will now be done using the gpiod_line_request_*()
family of functions.

This is the first part of changes required to fully convert the API.

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

chip: lazily allocate lines

Only allocate the array of line pointers is they're actually needed.

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

core: don't duplicate chip-related data structures

Introduce an internal structure - line_chip_ctx - used to store the
chip-related information. This structure is shared among all line
objects exposed by a single chip.

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

simple-api: reposition the prototypes in the public header

Move the 'multiple' variants below the single value ones.

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

tests: line: new test case

Verify that a consumer string over 31 characters long is correctly
cropped.

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

line: remove an unnecessary check

We have changed the way line objects are allocated. This check is no
longer needed.

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

chip: use a temporary variable in gpiod_chip_close()

The code looks better if we use a temporary pointer to gpiod_line.

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

core: separate the chip and line logic

Lazily allocate memory for line objects in chip.c. This eliminates the
need for chip routines to know the size of a line object.

Line objects now contain the chip file descriptor as well, so that we
don't need to access the chip object in any way from line.c.

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

chip: release lines in bulk on close()

When closing the chip use a bulk operation to release all lines.

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

line: remove stray semicolons

These got introduced accidentally when adding chip_get_fd().

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

chip: rename is_unsigned_int()

Use a shorter name for this simple routine.

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

line: coding style fix

Correctly align a broken line.

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

core: tweak some comments

Minor changes to the file header comments in the core library.

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

core: move all line-related code to line.c and remove core.c

This is the final stage of splitting the core library code into
separate files.

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