요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. 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.
Edges are defined in terms of changes to the logical line value, so an inactive
to active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is
set then logical polarity is the opposite of physical polarity, and
``GPIOEVENT_REQUEST_RISING_EDGE`` 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()`.
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.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
상태, 이름, read 호출
1-35`GPIO_LINEEVENT_DATA_READ`은 line event에서 edge detection event를 읽습니다. ABI v1 인터페이스이며 `gpio-v2-line-event-read.rst`로 대체되었습니다.
호출 형식은 `int read(int event_fd, void *buf, size_t count)`입니다. `event_fd`는 `gpio-get-lineevent-ioctl.rst`가 `gpioevent_request`의 `request.fd`에 반환한 descriptor입니다. `buf`에는 `gpioevent_data` event가 저장되고, `count`는 buffer의 byte 수로 최소한 `gpioevent_data` 하나의 크기 이상이어야 합니다.
사용자 buffer에는 하나 이상의 고정 크기 event가 복사됩니다.
.. 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`.Edge 정의, timestamp, clock
36-60Input line에서 `GPIOEVENT_REQUEST_RISING_EDGE`, `GPIOEVENT_REQUEST_FALLING_EDGE` 또는 둘 다를 사용해 edge detection을 활성화해야 합니다. 이후 input line에서 edge interrupt가 감지될 때마다 event가 생성됩니다.
Edge는 logical line value의 변화로 정의됩니다. Inactive에서 active로 바뀌면 rising edge입니다. `GPIOHANDLE_REQUEST_ACTIVE_LOW`가 설정되면 logical polarity가 physical polarity와 반대이므로 logical rising edge 요청은 physical falling edge에 대응합니다.
Kernel은 edge 발생 시점과 가능한 한 가깝게 event를 포착해 timestamp를 찍고 buffer에 저장합니다. Userspace는 편한 시점에 `read()`로 이를 읽을 수 있습니다.
`gpioevent_data`의 `event.timestamp` clock source는 Linux 5.7 이상에서 `CLOCK_MONOTONIC`이고, 그 이전 kernel에서는 `CLOCK_REALTIME`입니다. 구조체 자체에는 clock source 표시가 없으므로 kernel version 또는 timestamp sanity check로 판단해야 합니다.
ABI v1은 logical edge와 kernel version에 따른 clock source를 사용합니다.
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.
Edges are defined in terms of changes to the logical line value, so an inactive
to active transition is a rising edge. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is
set then logical polarity is the opposite of physical polarity, and
``GPIOEVENT_REQUEST_RISING_EDGE`` 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()`.
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.순서, overflow, blocking
61-81Buffer에서 읽는 event 순서는 kernel이 감지한 순서와 항상 같습니다. Kernel event buffer의 크기는 16개 event로 고정되어 있습니다.
Userspace가 읽는 속도보다 event burst가 빠르면 buffer가 overflow할 수 있습니다. Overflow가 발생하면 가장 최근 event를 버리며 userspace에서는 overflow 발생 여부를 탐지할 수 없습니다.
Kernel에서 userspace로 복사하는 호출 횟수를 줄이기 위해 `read()`는 여러 event를 한 번에 복사할 수 있습니다. 복사 수는 kernel buffer에 있는 event 수와 userspace `buf`에 들어가는 event 수 가운데 작은 값입니다.
사용 가능한 event가 없고 `event_fd`에 `O_NONBLOCK`을 설정하지 않았다면 `read()`는 block합니다. `poll()` 또는 동등한 API에서 `event_fd`가 readable인지 확인하여 event 존재 여부를 검사할 수 있습니다.
고정 크기 buffer와 read 방식의 핵심 제약입니다.
Interrupt 감지부터 userspace batch read까지의 경로입니다.
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.
반환값
82-89성공하면 읽은 byte 수를 반환하며 이는 `gpio_lineevent_data` event 크기의 배수입니다. 실패하면 -1을 반환하고 `errno`를 설정합니다. 공통 오류 코드는 `error-codes.rst`를 따릅니다.
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.
요약·해설
gpio-lineevent-data-read.rst:1-89ABI v1 edge event의 logical polarity, timestamp clock, 16-event buffer, overflow와 blocking read 규칙을 설명합니다.
원문의 read/ioctl prototype, struct, flag, errno, clock, buffer 규칙과 줄 좌표를 보존해 전문 번역했습니다.