요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. 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``).
Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst
does not remove or modify the events already contained in the kernel event
buffer.
The `read()` will block if no event is available and the ``req_fd`` has not
been set **O_NONBLOCK**.
The presence of an event can be tested for by checking that the ``req_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_event` 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_LINE_EVENT_READ`는 하나의 GPIO v2 line 요청에서 edge detection event를 읽는 연산입니다. 호출 형식은 `int read(int req_fd, void *buf, size_t count)`입니다.
`req_fd`는 `GPIO_V2_GET_LINE_IOCTL` 성공 시 `gpio_v2_line_request.request.fd`로 받은 요청 파일 디스크립터입니다. `buf`는 하나 이상의 `gpio_v2_line_event`를 받을 버퍼이고, `count`는 그 버퍼의 바이트 수이며 최소한 event 하나의 크기 이상이어야 합니다.
요청 디스크립터에서 고정 크기 event 레코드를 읽습니다.
.. 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`.Edge 활성화, 논리 극성, 순서
32-54이 연산을 사용하려면 입력 line에 `GPIO_V2_LINE_FLAG_EDGE_RISING`, `GPIO_V2_LINE_FLAG_EDGE_FALLING` 또는 두 flag를 모두 설정해 edge detection을 활성화해야 합니다. Kernel은 입력 line에서 edge interrupt를 감지할 때 event를 생성합니다.
Rising과 falling은 물리 전압이 아니라 논리 line 값의 변화로 정의됩니다. inactive에서 active로 바뀌면 rising edge입니다. `GPIO_V2_LINE_FLAG_ACTIVE_LOW`가 설정되면 논리 극성이 물리 극성과 반대이므로 논리 rising edge는 물리 falling edge에 해당합니다.
Kernel은 발생 시점에 최대한 가깝게 event를 포착하고 timestamp를 기록한 뒤 요청 버퍼에 저장합니다. 여러 line을 같은 요청으로 감시해도 `read()` 결과는 kernel이 감지한 순서를 항상 유지합니다.
ACTIVE_LOW가 edge 이름과 실제 전압 변화의 대응을 바꿉니다.
입력 변화가 요청 버퍼를 거쳐 userspace로 전달됩니다.
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.버퍼 크기, overflow, 여러 event 읽기
55-73Kernel event buffer 크기는 line 요청을 만들 때 고정됩니다. `gpio_v2_line_request.request.event_buffer_size`로 크기에 영향을 줄 수 있으며, 기본값은 요청한 line 수의 16배입니다.
Userspace가 읽는 속도보다 event burst가 빠르면 buffer가 넘칠 수 있습니다. 이때 가장 오래된 buffered event가 버려집니다. 각 event의 sequence number를 감시하면 userspace에서 누락을 감지할 수 있습니다.
`read()`는 한 번에 여러 event를 복사할 수 있습니다. 실제 복사 개수는 kernel buffer에서 사용 가능한 event 수와 userspace `buf`에 들어갈 수 있는 event 수 중 작은 값입니다.
`GPIO_V2_LINE_SET_CONFIG_IOCTL`로 edge detection flag를 바꾸더라도 이미 kernel event buffer에 들어 있는 event는 삭제되거나 수정되지 않습니다.
요청 생성 시점의 크기와 sequence number가 overflow 처리의 핵심입니다.
Sequence number를 추적해 폐기된 event를 식별합니다.
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``).
Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst
does not remove or modify the events already contained in the kernel event
buffer.Blocking, readiness, 반환값
74-88읽을 event가 없고 `req_fd`에 `O_NONBLOCK`이 설정되지 않았다면 `read()`는 block합니다. `poll()` 또는 동등한 API로 `req_fd`가 readable인지 확인하면 event 존재 여부를 검사할 수 있습니다.
성공하면 읽은 바이트 수를 반환하며 이 값은 `gpio_v2_line_event` 크기의 배수입니다. 실패하면 -1을 반환하고 `errno`를 설정합니다. 공통 오류 코드는 `error-codes.rst`를 따릅니다.
Blocking 모드와 반환값을 함께 확인해야 합니다.
The `read()` will block if no event is available and the ``req_fd`` has not
been set **O_NONBLOCK**.
The presence of an event can be tested for by checking that the ``req_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_event` event.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
요약·해설
gpio-v2-line-event-read.rst:1-88GPIO v2 edge event의 논리 극성, 요청별 buffer, sequence 기반 overflow 감지와 blocking read를 설명합니다.
원문의 호출 형식, 구조체, flag, buffer 정책, 오류 코드와 줄 좌표를 보존해 전문 번역했습니다.