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