1.. SPDX-License-Identifier: GPL-2.0 2 3.. _GPIO_LINEEVENT_DATA_READ: 4 5************************ 6GPIO_LINEEVENT_DATA_READ 7************************ 8 9.. warning:: 10 This ioctl is part of chardev_v1.rst and is obsoleted by 11 gpio-v2-line-event-read.rst. 12 13Name 14==== 15 16GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event. 17 18Synopsis 19======== 20 21``int read(int event_fd, void *buf, size_t count)`` 22 23Arguments 24========= 25 26``event_fd`` 27 The file descriptor of the GPIO character device, as returned in the 28 :c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst. 29 30``buf`` 31 The buffer to contain the :c:type:`events<gpioevent_data>`. 32 33``count`` 34 The number of bytes available in ``buf``, which must be at 35 least the size of a :c:type:`gpioevent_data`. 36 37Description 38=========== 39 40Read edge detection events for a line from a line event. 41 42Edge detection must be enabled for the input line using either 43``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or 44both. Edge events are then generated whenever edge interrupts are detected on 45the input line. 46 47The kernel captures and timestamps edge events as close as possible to their 48occurrence and stores them in a buffer from where they can be read by 49userspace at its convenience using `read()`. 50 51The source of the clock for :c:type:`event.timestamp<gpioevent_data>` is 52``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was 53``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data` 54as to which clock source is used, it must be determined from either the kernel 55version or sanity checks on the timestamp itself. 56 57Events read from the buffer are always in the same order that they were 58detected by the kernel. 59 60The size of the kernel event buffer is fixed at 16 events. 61 62The buffer may overflow if bursts of events occur quicker than they are read 63by userspace. If an overflow occurs then the most recent event is discarded. 64Overflow cannot be detected from userspace. 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 71The `read()` will block if no event is available and the ``event_fd`` has not 72been set **O_NONBLOCK**. 73 74The presence of an event can be tested for by checking that the ``event_fd`` is 75readable using `poll()` or an equivalent. 76 77Return Value 78============ 79 80On success the number of bytes read, which will be a multiple of the size of 81a :c:type:`gpio_lineevent_data` event. 82 83On error -1 and the ``errno`` variable is set appropriately. 84Common error codes are described in error-codes.rst. 85