| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
.. _GPIO_GET_LINEEVENT_IOCTL: |
| 4 |
|
| 5 |
************************ |
| 6 |
GPIO_GET_LINEEVENT_IOCTL |
| 7 |
************************ |
| 8 |
|
| 9 |
.. warning:: |
| 10 |
This ioctl is part of chardev_v1.rst and is obsoleted by |
| 11 |
gpio-v2-get-line-ioctl.rst. |
| 12 |
|
| 13 |
Name |
| 14 |
==== |
| 15 |
|
| 16 |
GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel. |
| 17 |
|
| 18 |
Synopsis |
| 19 |
======== |
| 20 |
|
| 21 |
.. c:macro:: GPIO_GET_LINEEVENT_IOCTL |
| 22 |
|
| 23 |
``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)`` |
| 24 |
|
| 25 |
Arguments |
| 26 |
========= |
| 27 |
|
| 28 |
``chip_fd`` |
| 29 |
The file descriptor of the GPIO character device returned by `open()`. |
| 30 |
|
| 31 |
``request`` |
| 32 |
The :c:type:`event_request<gpioevent_request>` specifying the line |
| 33 |
to request and its configuration. |
| 34 |
|
| 35 |
Description |
| 36 |
=========== |
| 37 |
|
| 38 |
Request a line with edge detection from the kernel. |
| 39 |
|
| 40 |
On success, the requesting process is granted exclusive access to the line |
| 41 |
value and may receive events when edges are detected on the line, as |
| 42 |
described in gpio-lineevent-data-read.rst. |
| 43 |
|
| 44 |
The state of a line is guaranteed to remain as requested until the returned |
| 45 |
file descriptor is closed. Once the file descriptor is closed, the state of |
| 46 |
the line becomes uncontrolled from the userspace perspective, and may revert |
| 47 |
to its default state. |
| 48 |
|
| 49 |
Requesting a line already in use is an error (**EBUSY**). |
| 50 |
|
| 51 |
Requesting edge detection on a line that does not support interrupts is an |
| 52 |
error (**ENXIO**). |
| 53 |
|
| 54 |
As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the |
| 55 |
bias configuration is best effort. |
| 56 |
|
| 57 |
Closing the ``chip_fd`` has no effect on existing line events. |
| 58 |
|
| 59 |
Configuration Rules |
| 60 |
------------------- |
| 61 |
|
| 62 |
The following configuration rules apply: |
| 63 |
|
| 64 |
The line event is requested as an input, so no flags specific to output lines, |
| 65 |
``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or |
| 66 |
``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set. |
| 67 |
|
| 68 |
Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set. |
| 69 |
If no bias flags are set then the bias configuration is not changed. |
| 70 |
|
| 71 |
The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and |
| 72 |
``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising |
| 73 |
and falling edges. |
| 74 |
|
| 75 |
Requesting an invalid configuration is an error (**EINVAL**). |
| 76 |
|
| 77 |
Return Value |
| 78 |
============ |
| 79 |
|
| 80 |
On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file |
| 81 |
descriptor for the request. |
| 82 |
|
| 83 |
On error -1 and the ``errno`` variable is set appropriately. |
| 84 |
Common error codes are described in error-codes.rst. |