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