85 lines
2.7 KiB
ReStructuredText
85 lines
2.7 KiB
ReStructuredText
.. SPDX-License-Identifier: GPL-2.0
|
|
|
|
.. _GPIO_LINEEVENT_DATA_READ:
|
|
|
|
************************
|
|
GPIO_LINEEVENT_DATA_READ
|
|
************************
|
|
|
|
.. warning::
|
|
This ioctl is part of chardev_v1.rst and is obsoleted by
|
|
gpio-v2-line-event-read.rst.
|
|
|
|
Name
|
|
====
|
|
|
|
GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event.
|
|
|
|
Synopsis
|
|
========
|
|
|
|
``int read(int event_fd, void *buf, size_t count)``
|
|
|
|
Arguments
|
|
=========
|
|
|
|
``event_fd``
|
|
The file descriptor of the GPIO character device, as returned in the
|
|
:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.
|
|
|
|
``buf``
|
|
The buffer to contain the :c:type:`events<gpioevent_data>`.
|
|
|
|
``count``
|
|
The number of bytes available in ``buf``, which must be at
|
|
least the size of a :c:type:`gpioevent_data`.
|
|
|
|
Description
|
|
===========
|
|
|
|
Read edge detection events for a line from a line event.
|
|
|
|
Edge detection must be enabled for the input line using either
|
|
``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or
|
|
both. Edge events are then generated whenever edge interrupts are detected on
|
|
the input line.
|
|
|
|
The kernel captures and timestamps edge events as close as possible to their
|
|
occurrence and stores them in a buffer from where they can be read by
|
|
userspace at its convenience using `read()`.
|
|
|
|
The source of the clock for :c:type:`event.timestamp<gpioevent_data>` is
|
|
``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was
|
|
``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data`
|
|
as to which clock source is used, it must be determined from either the kernel
|
|
version or sanity checks on the timestamp itself.
|
|
|
|
Events read from the buffer are always in the same order that they were
|
|
detected by the kernel.
|
|
|
|
The size of the kernel event buffer is fixed at 16 events.
|
|
|
|
The buffer may overflow if bursts of events occur quicker than they are read
|
|
by userspace. If an overflow occurs then the most recent event is discarded.
|
|
Overflow cannot be detected from userspace.
|
|
|
|
To minimize the number of calls required to copy events from the kernel to
|
|
userspace, `read()` supports copying multiple events. The number of events
|
|
copied is the lower of the number available in the kernel buffer and the
|
|
number that will fit in the userspace buffer (``buf``).
|
|
|
|
The `read()` will block if no event is available and the ``event_fd`` has not
|
|
been set **O_NONBLOCK**.
|
|
|
|
The presence of an event can be tested for by checking that the ``event_fd`` is
|
|
readable using `poll()` or an equivalent.
|
|
|
|
Return Value
|
|
============
|
|
|
|
On success the number of bytes read, which will be a multiple of the size of
|
|
a :c:type:`gpio_lineevent_data` event.
|
|
|
|
On error -1 and the ``errno`` variable is set appropriately.
|
|
Common error codes are described in error-codes.rst.
|