Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
Extension
.rst
Size
3061 bytes
Lines
89
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. SPDX-License-Identifier: GPL-2.0

.. _GPIO_V2_LINE_EVENT_READ:

***********************
GPIO_V2_LINE_EVENT_READ
***********************

Name
====

GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request.

Synopsis
========

``int read(int req_fd, void *buf, size_t count)``

Arguments
=========

``req_fd``
    The file descriptor of the GPIO character device, as returned in the
    :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.

``buf``
    The buffer to contain the :c:type:`events<gpio_v2_line_event>`.

``count``
    The number of bytes available in ``buf``, which must be at
    least the size of a :c:type:`gpio_v2_line_event`.

Description
===========

Read edge detection events for lines from a request.

Edge detection must be enabled for the input line using either
``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or
both. Edge events are then generated whenever edge interrupts are detected on
the input line.

Edges are defined in terms of changes to the logical line value, so an inactive
to active transition is a rising edge.  If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is
set then logical polarity is the opposite of physical polarity, and
``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresponds to a falling physical edge.

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()`.

Events read from the buffer are always in the same order that they were
detected by the kernel, including when multiple lines are being monitored by
the one request.

The size of the kernel event buffer is fixed at the time of line request
creation, and can be influenced by the
:c:type:`request.event_buffer_size<gpio_v2_line_request>`.
The default size is 16 times the number of lines requested.

The buffer may overflow if bursts of events occur quicker than they are read
by userspace. If an overflow occurs then the oldest buffered event is
discarded. Overflow can be detected from userspace by monitoring the event
sequence numbers.

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``).

Annotation

Implementation Notes