1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _GPIO_V2_LINE_EVENT_READ: 3 .. _GPIO_V2_LINE_EVENT_READ:
4 4
5 *********************** 5 ***********************
6 GPIO_V2_LINE_EVENT_READ 6 GPIO_V2_LINE_EVENT_READ
7 *********************** 7 ***********************
8 8
9 Name 9 Name
10 ==== 10 ====
11 11
12 GPIO_V2_LINE_EVENT_READ - Read edge detection 12 GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request.
13 13
14 Synopsis 14 Synopsis
15 ======== 15 ========
16 16
17 ``int read(int req_fd, void *buf, size_t count 17 ``int read(int req_fd, void *buf, size_t count)``
18 18
19 Arguments 19 Arguments
20 ========= 20 =========
21 21
22 ``req_fd`` 22 ``req_fd``
23 The file descriptor of the GPIO character 23 The file descriptor of the GPIO character device, as returned in the
24 :c:type:`request.fd<gpio_v2_line_request>` 24 :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
25 25
26 ``buf`` 26 ``buf``
27 The buffer to contain the :c:type:`events< 27 The buffer to contain the :c:type:`events<gpio_v2_line_event>`.
28 28
29 ``count`` 29 ``count``
30 The number of bytes available in ``buf``, 30 The number of bytes available in ``buf``, which must be at
31 least the size of a :c:type:`gpio_v2_line_ 31 least the size of a :c:type:`gpio_v2_line_event`.
32 32
33 Description 33 Description
34 =========== 34 ===========
35 35
36 Read edge detection events for lines from a re 36 Read edge detection events for lines from a request.
37 37
38 Edge detection must be enabled for the input l 38 Edge detection must be enabled for the input line using either
39 ``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2 39 ``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or
40 both. Edge events are then generated whenever 40 both. Edge events are then generated whenever edge interrupts are detected on
41 the input line. 41 the input line.
42 42
43 Edges are defined in terms of changes to the l 43 Edges are defined in terms of changes to the logical line value, so an inactive
44 to active transition is a rising edge. If ``G 44 to active transition is a rising edge. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is
45 set then logical polarity is the opposite of p 45 set then logical polarity is the opposite of physical polarity, and
46 ``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresp 46 ``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresponds to a falling physical edge.
47 47
48 The kernel captures and timestamps edge events 48 The kernel captures and timestamps edge events as close as possible to their
49 occurrence and stores them in a buffer from wh 49 occurrence and stores them in a buffer from where they can be read by
50 userspace at its convenience using `read()`. 50 userspace at its convenience using `read()`.
51 51
52 Events read from the buffer are always in the 52 Events read from the buffer are always in the same order that they were
53 detected by the kernel, including when multipl 53 detected by the kernel, including when multiple lines are being monitored by
54 the one request. 54 the one request.
55 55
56 The size of the kernel event buffer is fixed a 56 The size of the kernel event buffer is fixed at the time of line request
57 creation, and can be influenced by the 57 creation, and can be influenced by the
58 :c:type:`request.event_buffer_size<gpio_v2_lin 58 :c:type:`request.event_buffer_size<gpio_v2_line_request>`.
59 The default size is 16 times the number of lin 59 The default size is 16 times the number of lines requested.
60 60
61 The buffer may overflow if bursts of events oc 61 The buffer may overflow if bursts of events occur quicker than they are read
62 by userspace. If an overflow occurs then the o 62 by userspace. If an overflow occurs then the oldest buffered event is
63 discarded. Overflow can be detected from users 63 discarded. Overflow can be detected from userspace by monitoring the event
64 sequence numbers. 64 sequence numbers.
65 65
66 To minimize the number of calls required to co 66 To minimize the number of calls required to copy events from the kernel to
67 userspace, `read()` supports copying multiple 67 userspace, `read()` supports copying multiple events. The number of events
68 copied is the lower of the number available in 68 copied is the lower of the number available in the kernel buffer and the
69 number that will fit in the userspace buffer ( 69 number that will fit in the userspace buffer (``buf``).
70 70
71 Changing the edge detection flags using gpio-v 71 Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst
72 does not remove or modify the events already c 72 does not remove or modify the events already contained in the kernel event
73 buffer. 73 buffer.
74 74
75 The `read()` will block if no event is availab 75 The `read()` will block if no event is available and the ``req_fd`` has not
76 been set **O_NONBLOCK**. 76 been set **O_NONBLOCK**.
77 77
78 The presence of an event can be tested for by 78 The presence of an event can be tested for by checking that the ``req_fd`` is
79 readable using `poll()` or an equivalent. 79 readable using `poll()` or an equivalent.
80 80
81 Return Value 81 Return Value
82 ============ 82 ============
83 83
84 On success the number of bytes read, which wil 84 On success the number of bytes read, which will be a multiple of the size of a
85 :c:type:`gpio_v2_line_event` event. 85 :c:type:`gpio_v2_line_event` event.
86 86
87 On error -1 and the ``errno`` variable is set 87 On error -1 and the ``errno`` variable is set appropriately.
88 Common error codes are described in error-code 88 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.