1.. SPDX-License-Identifier: GPL-2.0
2
3.. _GPIO_LINEEVENT_DATA_READ:
4
5************************
6GPIO_LINEEVENT_DATA_READ
7************************
8
9.. warning::
10    This ioctl is part of chardev_v1.rst and is obsoleted by
11    gpio-v2-line-event-read.rst.
12
13Name
14====
15
16GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event.
17
18Synopsis
19========
20
21``int read(int event_fd, void *buf, size_t count)``
22
23Arguments
24=========
25
26``event_fd``
27    The file descriptor of the GPIO character device, as returned in the
28    :c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.
29
30``buf``
31    The buffer to contain the :c:type:`events<gpioevent_data>`.
32
33``count``
34    The number of bytes available in ``buf``, which must be at
35    least the size of a :c:type:`gpioevent_data`.
36
37Description
38===========
39
40Read edge detection events for a line from a line event.
41
42Edge detection must be enabled for the input line using either
43``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or
44both. Edge events are then generated whenever edge interrupts are detected on
45the input line.
46
47Edges are defined in terms of changes to the logical line value, so an inactive
48to active transition is a rising edge.  If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is
49set then logical polarity is the opposite of physical polarity, and
50``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical edge.
51
52The kernel captures and timestamps edge events as close as possible to their
53occurrence and stores them in a buffer from where they can be read by
54userspace at its convenience using `read()`.
55
56The source of the clock for :c:type:`event.timestamp<gpioevent_data>` is
57``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was
58``CLOCK_REALTIME``.  There is no indication in the :c:type:`gpioevent_data`
59as to which clock source is used, it must be determined from either the kernel
60version or sanity checks on the timestamp itself.
61
62Events read from the buffer are always in the same order that they were
63detected by the kernel.
64
65The size of the kernel event buffer is fixed at 16 events.
66
67The buffer may overflow if bursts of events occur quicker than they are read
68by userspace. If an overflow occurs then the most recent event is discarded.
69Overflow cannot be detected from userspace.
70
71To minimize the number of calls required to copy events from the kernel to
72userspace, `read()` supports copying multiple events. The number of events
73copied is the lower of the number available in the kernel buffer and the
74number that will fit in the userspace buffer (``buf``).
75
76The `read()` will block if no event is available and the ``event_fd`` has not
77been set **O_NONBLOCK**.
78
79The presence of an event can be tested for by checking that the ``event_fd`` is
80readable using `poll()` or an equivalent.
81
82Return Value
83============
84
85On success the number of bytes read, which will be a multiple of the size of
86a :c:type:`gpio_lineevent_data` event.
87
88On error -1 and the ``errno`` variable is set appropriately.
89Common error codes are described in error-codes.rst.
90