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>
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>
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>
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>
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>
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>
These three constants define the possible line iterator states. Make
their names reflect that.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
Add functions for requesting events for line bulk objects. Both with
and without additional flags.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
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>
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>
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>
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>
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>
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>
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>
We can (and already do in gpiod_chip_close()) easily figure out if
a GPIO line was configured for events or values, so there's no need
to have a separate release function for events.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
The libgpiod-specific error codes are not really necessary and can be
easily replaced with regular libc error numbers defined in errno.h.
Remove all routines and definitions dealing with error numbers and
switch to using errnos in the library code.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
We don't know who might want to include gpiod.h, so let's try to avoid
any C99 extensions in the header.
Signed-off-by: Bartosz Golaszewski <bartekgola@gmail.com>
