89 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3.. _GPIO_V2_LINE_EVENT_READ:4 5***********************6GPIO_V2_LINE_EVENT_READ7***********************8 9Name10====11 12GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request.13 14Synopsis15========16 17``int read(int req_fd, void *buf, size_t count)``18 19Arguments20=========21 22``req_fd``23 The file descriptor of the GPIO character device, as returned in the24 :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 at31 least the size of a :c:type:`gpio_v2_line_event`.32 33Description34===========35 36Read edge detection events for lines from a request.37 38Edge detection must be enabled for the input line using either39``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or40both. Edge events are then generated whenever edge interrupts are detected on41the input line.42 43Edges are defined in terms of changes to the logical line value, so an inactive44to active transition is a rising edge. If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is45set then logical polarity is the opposite of physical polarity, and46``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 their49occurrence and stores them in a buffer from where they can be read by50userspace at its convenience using `read()`.51 52Events read from the buffer are always in the same order that they were53detected by the kernel, including when multiple lines are being monitored by54the one request.55 56The size of the kernel event buffer is fixed at the time of line request57creation, and can be influenced by the58: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 read62by userspace. If an overflow occurs then the oldest buffered event is63discarded. Overflow can be detected from userspace by monitoring the event64sequence numbers.65 66To minimize the number of calls required to copy events from the kernel to67userspace, `read()` supports copying multiple events. The number of events68copied is the lower of the number available in the kernel buffer and the69number that will fit in the userspace buffer (``buf``).70 71Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst72does not remove or modify the events already contained in the kernel event73buffer.74 75The `read()` will block if no event is available and the ``req_fd`` has not76been set **O_NONBLOCK**.77 78The presence of an event can be tested for by checking that the ``req_fd`` is79readable using `poll()` or an equivalent.80 81Return Value82============83 84On success the number of bytes read, which will be a multiple of the size of a85: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