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 43The kernel captures and timestamps edge events as close as possible to their 44occurrence and stores them in a buffer from where they can be read by 45userspace at its convenience using `read()`. 46 47Events read from the buffer are always in the same order that they were 48detected by the kernel, including when multiple lines are being monitored by 49the one request. 50 51The size of the kernel event buffer is fixed at the time of line request 52creation, and can be influenced by the 53:c:type:`request.event_buffer_size<gpio_v2_line_request>`. 54The default size is 16 times the number of lines requested. 55 56The buffer may overflow if bursts of events occur quicker than they are read 57by userspace. If an overflow occurs then the oldest buffered event is 58discarded. Overflow can be detected from userspace by monitoring the event 59sequence numbers. 60 61To minimize the number of calls required to copy events from the kernel to 62userspace, `read()` supports copying multiple events. The number of events 63copied is the lower of the number available in the kernel buffer and the 64number that will fit in the userspace buffer (``buf``). 65 66Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst 67does not remove or modify the events already contained in the kernel event 68buffer. 69 70The `read()` will block if no event is available and the ``req_fd`` has not 71been set **O_NONBLOCK**. 72 73The presence of an event can be tested for by checking that the ``req_fd`` is 74readable using `poll()` or an equivalent. 75 76Return Value 77============ 78 79On success the number of bytes read, which will be a multiple of the size of a 80:c:type:`gpio_v2_line_event` event. 81 82On error -1 and the ``errno`` variable is set appropriately. 83Common error codes are described in error-codes.rst. 84