42969726a1
The existing uAPI documentation does not adequately describe how the kernel handles the case where the underlying hardware or driver does not support the requested configuration. Add a Configuration Support section describing that behaviour to both the v1 and v2 documentation, and better document the errors returned where the requested configuration cannot be supported. Signed-off-by: Kent Gibson <warthog618@gmail.com> Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
85 lines
2.4 KiB
ReStructuredText
85 lines
2.4 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
.. _GPIO_GET_LINEEVENT_IOCTL:
|
|
|
|
************************
|
|
GPIO_GET_LINEEVENT_IOCTL
|
|
************************
|
|
|
|
.. warning::
|
|
This ioctl is part of chardev_v1.rst and is obsoleted by
|
|
gpio-v2-get-line-ioctl.rst.
|
|
|
|
Name
|
|
====
|
|
|
|
GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel.
|
|
|
|
Synopsis
|
|
========
|
|
|
|
.. c:macro:: GPIO_GET_LINEEVENT_IOCTL
|
|
|
|
``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)``
|
|
|
|
Arguments
|
|
=========
|
|
|
|
``chip_fd``
|
|
The file descriptor of the GPIO character device returned by `open()`.
|
|
|
|
``request``
|
|
The :c:type:`event_request<gpioevent_request>` specifying the line
|
|
to request and its configuration.
|
|
|
|
Description
|
|
===========
|
|
|
|
Request a line with edge detection from the kernel.
|
|
|
|
On success, the requesting process is granted exclusive access to the line
|
|
value and may receive events when edges are detected on the line, as
|
|
described in gpio-lineevent-data-read.rst.
|
|
|
|
The state of a line is guaranteed to remain as requested until the returned
|
|
file descriptor is closed. Once the file descriptor is closed, the state of
|
|
the line becomes uncontrolled from the userspace perspective, and may revert
|
|
to its default state.
|
|
|
|
Requesting a line already in use is an error (**EBUSY**).
|
|
|
|
Requesting edge detection on a line that does not support interrupts is an
|
|
error (**ENXIO**).
|
|
|
|
As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the
|
|
bias configuration is best effort.
|
|
|
|
Closing the ``chip_fd`` has no effect on existing line events.
|
|
|
|
Configuration Rules
|
|
-------------------
|
|
|
|
The following configuration rules apply:
|
|
|
|
The line event is requested as an input, so no flags specific to output lines,
|
|
``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or
|
|
``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set.
|
|
|
|
Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set.
|
|
If no bias flags are set then the bias configuration is not changed.
|
|
|
|
The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and
|
|
``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising
|
|
and falling edges.
|
|
|
|
Requesting an invalid configuration is an error (**EINVAL**).
|
|
|
|
Return Value
|
|
============
|
|
|
|
On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file
|
|
descriptor for the request.
|
|
|
|
On error -1 and the ``errno`` variable is set appropriately.
|
|
Common error codes are described in error-codes.rst.
|