요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_LINEINFO_CHANGED_READ:
**************************
GPIO_LINEINFO_CHANGED_READ
**************************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-lineinfo-changed-read.rst.
Name
====
GPIO_LINEINFO_CHANGED_READ - Read line info change 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<gpioline_info_changed>`.
``count``
The number of bytes available in ``buf``, which must be at least the size
of a :c:type:`gpioline_info_changed` event.
Description
===========
Read line info change 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-lineevent-data-read.rst to receive events when a
line changes value.
A line must be watched using gpio-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.
First added in 5.7.
Return Value
============
On success the number of bytes read, which will be a multiple of the size of
a :c:type:`gpioline_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은 원문 표기를 유지합니다.
상태, 이름, read 호출
1-35`GPIO_LINEINFO_CHANGED_READ`은 chip에서 감시 중인 line의 정보 변경 event를 읽습니다. ABI v1 인터페이스이며 `gpio-v2-lineinfo-changed-read.rst`로 대체되었습니다.
호출 형식은 `int read(int chip_fd, void *buf, size_t count)`입니다. `chip_fd`는 GPIO character device를 `open()`해 얻고, `buf`는 `gpioline_info_changed` event를 받을 buffer입니다. `count`는 buffer의 byte 수이며 event 하나의 크기 이상이어야 합니다.
한 chip_fd의 감시 event를 하나 이상 읽습니다.
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_LINEINFO_CHANGED_READ:
**************************
GPIO_LINEINFO_CHANGED_READ
**************************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-lineinfo-changed-read.rst.
Name
====
GPIO_LINEINFO_CHANGED_READ - Read line info change 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<gpioline_info_changed>`.
``count``
The number of bytes available in ``buf``, which must be at least the size
of a :c:type:`gpioline_info_changed` event.Event 대상과 생성
36-56이 read는 감시 중인 line의 정보 변경 event를 chip에서 가져옵니다. Line info 변경 감시는 일반적인 프로그램보다 system monitoring component가 주로 사용합니다.
Event는 line의 요청 상태 또는 configuration 변경을 나타내며 line 값 변경을 나타내지 않습니다. 값 변경 event가 필요하면 `gpio-lineevent-data-read.rst`를 사용합니다.
Info changed event가 생성되려면 먼저 `gpio-get-lineinfo-watch-ioctl.rst`로 line을 감시해야 합니다. 이후 line request, release 또는 reconfiguration이 일어나면 event가 생성됩니다. Kernel은 발생 시각을 기록하고 userspace가 `read()`할 때까지 buffer에 저장합니다.
Watch 등록 이후 상태나 구성 변경이 chip event stream으로 전달됩니다.
Description
===========
Read line info change 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-lineevent-data-read.rst to receive events when a
line changes value.
A line must be watched using gpio-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 buffer, overflow, blocking
57-79Kernel event buffer의 크기는 `chip_fd`마다 32개 event로 고정됩니다. Userspace가 읽는 속도보다 event burst가 빠르면 overflow할 수 있고, 이 경우 가장 최근 event가 버려집니다. Userspace에서는 overflow를 탐지할 수 없습니다.
여러 line을 하나의 `chip_fd`로 감시하더라도 read 결과는 kernel이 event를 감지한 순서를 항상 유지합니다.
`read()`는 여러 event를 한 번에 복사할 수 있습니다. 복사 개수는 kernel buffer의 available event 수와 userspace `buf`에 들어가는 event 수 중 작은 값입니다.
Event가 없고 `chip_fd`에 `O_NONBLOCK`이 설정되지 않았다면 `read()`는 block합니다. `poll()` 또는 동등한 API에서 descriptor가 readable인지 확인해 event 존재를 검사할 수 있습니다. 이 인터페이스는 Linux 5.7에서 처음 추가되었습니다.
Chip descriptor별 고정 buffer의 동작입니다.
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.
First added in 5.7.
반환값
80-87성공하면 읽은 byte 수를 반환하며 이는 `gpioline_info_changed` 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:`gpioline_info_changed` event.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
요약·해설
gpio-lineinfo-changed-read.rst:1-87ABI v1 line-info changed event의 생성 조건, chip_fd별 32-event buffer, overflow와 blocking read를 설명합니다.
원문의 ioctl/read prototype, struct, flag, errno, clock, buffer 규칙과 줄 좌표를 보존해 전문 번역했습니다.