요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_V2_LINEINFO_CHANGED_READ:
*****************************
GPIO_V2_LINEINFO_CHANGED_READ
*****************************
Name
====
GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched
lines from the chip.
Synopsis
========
``int read(int chip_fd, void *buf, size_t count)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``buf``
The buffer to contain the :c:type:`events<gpio_v2_line_info_changed>`.
``count``
The number of bytes available in ``buf``, which must be at least the size
of a :c:type:`gpio_v2_line_info_changed` event.
Description
===========
Read line info changed events for watched lines from the chip.
.. note::
Monitoring line info changes is not generally required, and would typically
only be performed by a system monitoring component.
These events relate to changes in a line's request state or configuration,
not its value. Use gpio-v2-line-event-read.rst to receive events when a
line changes value.
A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate
info changed events. Subsequently, a request, release, or reconfiguration
of the line will generate an info changed event.
The kernel timestamps events when they occur and stores them in a buffer
from where they can be read by userspace at its convenience using `read()`.
The size of the kernel event buffer is fixed at 32 events per ``chip_fd``.
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.
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 ``chip_fd``.
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``).
A `read()` will block if no event is available and the ``chip_fd`` has not
been set **O_NONBLOCK**.
The presence of an event can be tested for by checking that the ``chip_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_v2_line_info_changed` event.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름, 호출 형식, 인자
1-31`GPIO_V2_LINEINFO_CHANGED_READ`는 GPIO chip에서 watch 중인 line들의 line-info 변경 event를 읽습니다. 호출 형식은 `int read(int chip_fd, void *buf, size_t count)`입니다.
`chip_fd`는 GPIO character device를 `open()`해 얻은 파일 디스크립터입니다. `buf`는 `gpio_v2_line_info_changed` event를 받을 버퍼이며 `count`는 그 바이트 수로, event 하나의 크기 이상이어야 합니다.
Chip 단위 event stream에서 고정 크기 정보를 읽습니다.
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_V2_LINEINFO_CHANGED_READ:
*****************************
GPIO_V2_LINEINFO_CHANGED_READ
*****************************
Name
====
GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched
lines from the chip.
Synopsis
========
``int read(int chip_fd, void *buf, size_t count)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``buf``
The buffer to contain the :c:type:`events<gpio_v2_line_info_changed>`.
``count``
The number of bytes available in ``buf``, which must be at least the size
of a :c:type:`gpio_v2_line_info_changed` event.Event 범위와 생성 조건
32-52이 event는 line의 request 상태나 configuration이 바뀐 사실을 나타냅니다. Line 값의 변화가 아니며, 값의 edge event는 `gpio-v2-line-event-read.rst`를 사용해야 합니다.
Line-info 변경 감시는 일반 응용프로그램에 대개 필요하지 않고 주로 시스템 감시 구성요소가 사용합니다. Event를 생성하려면 먼저 `GPIO_V2_GET_LINEINFO_WATCH_IOCTL`로 해당 line을 watch해야 합니다.
Watch 등록 뒤 line이 request, release 또는 reconfiguration되면 info-changed event가 생성됩니다. Kernel은 발생 시각에 timestamp를 기록해 chip event buffer에 저장하고 userspace가 편한 시점에 `read()`하도록 합니다.
Metadata 변화와 값 변화는 서로 다른 디스크립터와 레코드를 사용합니다.
Description
===========
Read line info changed events for watched lines from the chip.
.. note::
Monitoring line info changes is not generally required, and would typically
only be performed by a system monitoring component.
These events relate to changes in a line's request state or configuration,
not its value. Use gpio-v2-line-event-read.rst to receive events when a
line changes value.
A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate
info changed events. Subsequently, a request, release, or reconfiguration
of the line will generate an info changed event.
The kernel timestamps events when they occur and stores them in a buffer
from where they can be read by userspace at its convenience using `read()`.
32-event 버퍼, overflow, 순서, blocking
53-73Kernel event buffer는 `chip_fd`마다 32 events로 고정됩니다. Userspace보다 빠르게 event가 몰려 overflow가 발생하면 가장 최근 event를 버립니다. 이 overflow는 userspace에서 감지할 수 없습니다.
하나의 `chip_fd`에서 여러 line을 감시하더라도 읽은 event는 kernel이 감지한 순서를 유지합니다. `read()`는 여러 event를 한 번에 복사하며 실제 개수는 kernel buffer의 available event 수와 `buf` 용량 중 작은 값입니다.
Event가 없고 `chip_fd`가 `O_NONBLOCK`이 아니면 `read()`는 block합니다. `poll()` 또는 동등한 API로 descriptor가 readable인지 검사할 수 있습니다.
Edge event buffer와 달리 line-info buffer는 용량을 조정할 수 없고, overflow 시 가장 오래된 event가 아니라 가장 최근 event를 버리며, sequence number로 누락을 알아낼 수도 없습니다.
Edge event buffer와 혼동하기 쉬운 차이를 명시합니다.
Watch된 line의 metadata 변화가 chip descriptor로 전달됩니다.
The size of the kernel event buffer is fixed at 32 events per ``chip_fd``.
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.
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 ``chip_fd``.
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``).
A `read()` will block if no event is available and the ``chip_fd`` has not
been set **O_NONBLOCK**.
The presence of an event can be tested for by checking that the ``chip_fd`` is
readable using `poll()` or an equivalent.
반환값
74-81성공하면 읽은 바이트 수를 반환하며 `gpio_v2_line_info_changed` 크기의 배수입니다. 실패하면 -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_v2_line_info_changed` event.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
요약·해설
gpio-v2-lineinfo-changed-read.rst:1-81Watch된 GPIO line의 request·release·reconfiguration event, 고정 32-event buffer와 overflow 한계를 설명합니다.
원문의 호출 형식, 구조체, flag, buffer 정책, 오류 코드와 줄 좌표를 보존해 전문 번역했습니다.