116b2bb7fSKent Gibson.. SPDX-License-Identifier: GPL-2.0 216b2bb7fSKent Gibson 316b2bb7fSKent Gibson.. _GPIO_LINEEVENT_DATA_READ: 416b2bb7fSKent Gibson 516b2bb7fSKent Gibson************************ 616b2bb7fSKent GibsonGPIO_LINEEVENT_DATA_READ 716b2bb7fSKent Gibson************************ 816b2bb7fSKent Gibson 916b2bb7fSKent Gibson.. warning:: 1016b2bb7fSKent Gibson This ioctl is part of chardev_v1.rst and is obsoleted by 1116b2bb7fSKent Gibson gpio-v2-line-event-read.rst. 1216b2bb7fSKent Gibson 1316b2bb7fSKent GibsonName 1416b2bb7fSKent Gibson==== 1516b2bb7fSKent Gibson 1616b2bb7fSKent GibsonGPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event. 1716b2bb7fSKent Gibson 1816b2bb7fSKent GibsonSynopsis 1916b2bb7fSKent Gibson======== 2016b2bb7fSKent Gibson 2116b2bb7fSKent Gibson``int read(int event_fd, void *buf, size_t count)`` 2216b2bb7fSKent Gibson 2316b2bb7fSKent GibsonArguments 2416b2bb7fSKent Gibson========= 2516b2bb7fSKent Gibson 2616b2bb7fSKent Gibson``event_fd`` 2716b2bb7fSKent Gibson The file descriptor of the GPIO character device, as returned in the 2816b2bb7fSKent Gibson :c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst. 2916b2bb7fSKent Gibson 3016b2bb7fSKent Gibson``buf`` 3116b2bb7fSKent Gibson The buffer to contain the :c:type:`events<gpioevent_data>`. 3216b2bb7fSKent Gibson 3316b2bb7fSKent Gibson``count`` 3416b2bb7fSKent Gibson The number of bytes available in ``buf``, which must be at 3516b2bb7fSKent Gibson least the size of a :c:type:`gpioevent_data`. 3616b2bb7fSKent Gibson 3716b2bb7fSKent GibsonDescription 3816b2bb7fSKent Gibson=========== 3916b2bb7fSKent Gibson 4016b2bb7fSKent GibsonRead edge detection events for a line from a line event. 4116b2bb7fSKent Gibson 4216b2bb7fSKent GibsonEdge detection must be enabled for the input line using either 4316b2bb7fSKent Gibson``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or 4416b2bb7fSKent Gibsonboth. Edge events are then generated whenever edge interrupts are detected on 4516b2bb7fSKent Gibsonthe input line. 4616b2bb7fSKent Gibson 47*08d94c74SKent GibsonEdges are defined in terms of changes to the logical line value, so an inactive 48*08d94c74SKent Gibsonto active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is 49*08d94c74SKent Gibsonset then logical polarity is the opposite of physical polarity, and 50*08d94c74SKent Gibson``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical edge. 51*08d94c74SKent Gibson 5216b2bb7fSKent GibsonThe kernel captures and timestamps edge events as close as possible to their 5316b2bb7fSKent Gibsonoccurrence and stores them in a buffer from where they can be read by 5416b2bb7fSKent Gibsonuserspace at its convenience using `read()`. 5516b2bb7fSKent Gibson 5616b2bb7fSKent GibsonThe source of the clock for :c:type:`event.timestamp<gpioevent_data>` is 5716b2bb7fSKent Gibson``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was 5816b2bb7fSKent Gibson``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data` 5916b2bb7fSKent Gibsonas to which clock source is used, it must be determined from either the kernel 6016b2bb7fSKent Gibsonversion or sanity checks on the timestamp itself. 6116b2bb7fSKent Gibson 6216b2bb7fSKent GibsonEvents read from the buffer are always in the same order that they were 6316b2bb7fSKent Gibsondetected by the kernel. 6416b2bb7fSKent Gibson 6516b2bb7fSKent GibsonThe size of the kernel event buffer is fixed at 16 events. 6616b2bb7fSKent Gibson 6716b2bb7fSKent GibsonThe buffer may overflow if bursts of events occur quicker than they are read 6816b2bb7fSKent Gibsonby userspace. If an overflow occurs then the most recent event is discarded. 6916b2bb7fSKent GibsonOverflow cannot be detected from userspace. 7016b2bb7fSKent Gibson 7116b2bb7fSKent GibsonTo minimize the number of calls required to copy events from the kernel to 7216b2bb7fSKent Gibsonuserspace, `read()` supports copying multiple events. The number of events 7316b2bb7fSKent Gibsoncopied is the lower of the number available in the kernel buffer and the 7416b2bb7fSKent Gibsonnumber that will fit in the userspace buffer (``buf``). 7516b2bb7fSKent Gibson 7616b2bb7fSKent GibsonThe `read()` will block if no event is available and the ``event_fd`` has not 7716b2bb7fSKent Gibsonbeen set **O_NONBLOCK**. 7816b2bb7fSKent Gibson 7916b2bb7fSKent GibsonThe presence of an event can be tested for by checking that the ``event_fd`` is 8016b2bb7fSKent Gibsonreadable using `poll()` or an equivalent. 8116b2bb7fSKent Gibson 8216b2bb7fSKent GibsonReturn Value 8316b2bb7fSKent Gibson============ 8416b2bb7fSKent Gibson 8516b2bb7fSKent GibsonOn success the number of bytes read, which will be a multiple of the size of 8616b2bb7fSKent Gibsona :c:type:`gpio_lineevent_data` event. 8716b2bb7fSKent Gibson 8816b2bb7fSKent GibsonOn error -1 and the ``errno`` variable is set appropriately. 8916b2bb7fSKent GibsonCommon error codes are described in error-codes.rst. 90