요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_V2_GET_LINE_IOCTL:
**********************
GPIO_V2_GET_LINE_IOCTL
**********************
Name
====
GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel.
Synopsis
========
.. c:macro:: GPIO_V2_GET_LINE_IOCTL
``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``request``
The :c:type:`line_request<gpio_v2_line_request>` specifying the lines
to request and their configuration.
Description
===========
On success, the requesting process is granted exclusive access to the line
value, write access to the line configuration, and may receive events when
edges are detected on the line, all of which are described in more detail in
:ref:`gpio-v2-line-request`.
A number of lines may be requested in the one line request, and request
operations are performed on the requested lines by the kernel as atomically
as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
requested lines at once.
The state of a line, including the value of output lines, is guaranteed to
remain as requested until the returned file descriptor is closed. Once the
file descriptor is closed, the state of the line becomes uncontrolled from
the userspace perspective, and may revert to its default state.
Requesting a line already in use is an error (**EBUSY**).
Closing the ``chip_fd`` has no effect on existing line requests.
.. _gpio-v2-get-line-config-rules:
Configuration Rules
-------------------
For any given requested line, the following configuration rules apply:
The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and
``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then
the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW``
and the line is requested "as-is" to allow reading of the line value
without altering the electrical configuration.
The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the
``GPIO_V2_LINE_FLAG_OUTPUT`` to be set.
Only one drive flag may be set.
If none are set then the line is assumed push-pull.
Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it
requires a direction flag to also be set.
If no bias flags are set then the bias configuration is not changed.
The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require
``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising
and falling edges. Requesting edge detection from a line that does not support
it is an error (**ENXIO**).
Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set.
If none are set then the event clock defaults to ``CLOCK_MONOTONIC``.
The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware
and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that
doesn't support it is an error (**EOPNOTSUPP**).
The :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only
be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce
applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and
the edges returned by gpio-v2-line-event-read.rst. If not
supported directly by hardware, debouncing is emulated in software by the
kernel. Requesting debounce on a line that supports neither debounce in
hardware nor interrupts, as required for software emulation, is an error
(**ENXIO**).
Requesting an invalid configuration is an error (**EINVAL**).
.. _gpio-v2-get-line-config-support:
Configuration Support
---------------------
Where the requested configuration is not directly supported by the underlying
hardware and driver, the kernel applies one of these approaches:
- reject the request
- emulate the feature in software
- treat the feature as best effort
The approach applied depends on whether the feature can reasonably be emulated
in software, and the impact on the hardware and userspace if the feature is not
supported.
The approach applied for each feature is as follows:
============== ===========
Feature Approach
============== ===========
Bias best effort
Debounce emulate
Direction reject
Drive emulate
Edge Detection reject
============== ===========
Bias is treated as best effort to allow userspace to apply the same
configuration for platforms that support internal bias as those that require
external bias.
Worst case the line floats rather than being biased as expected.
Debounce is emulated by applying a filter to hardware interrupts on the line.
An edge event is generated after an edge is detected and the line remains
stable for the debounce period.
The event timestamp corresponds to the end of the debounce period.
Drive is emulated by switching the line to an input when the line should not
be actively driven.
Edge detection requires interrupt support, and is rejected if that is not
supported. Emulation by polling can still be performed from userspace.
In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst
is the requested configuration, not the resulting hardware configuration.
Userspace cannot determine if a feature is supported in hardware, is
emulated, or is best effort.
Return Value
============
On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the
file descriptor for the request.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
3. 한국어 전문 번역
영어 원문의 문단 순서와 의미를 유지한 전체 번역입니다. 코드, 함수명, symbol과 URL은 원문 표기를 유지합니다.
이름과 호출 형식
1-30`GPIO_V2_GET_LINE_IOCTL`은 kernel에서 하나 이상의 GPIO line을 요청합니다. 호출 형식은 `int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)`입니다.
`chip_fd`는 GPIO character device를 `open()`해 얻고, `request`는 요청할 line 집합과 각 line의 configuration을 지정하는 `gpio_v2_line_request` 구조체입니다.
Request 구조체가 line 집합, 구성, 결과 descriptor를 전달합니다.
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_V2_GET_LINE_IOCTL:
**********************
GPIO_V2_GET_LINE_IOCTL
**********************
Name
====
GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel.
Synopsis
========
.. c:macro:: GPIO_V2_GET_LINE_IOCTL
``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``request``
The :c:type:`line_request<gpio_v2_line_request>` specifying the lines
to request and their configuration.
배타적 접근, atomicity, 수명
31-52성공하면 요청 process는 line 값에 대한 배타적 접근, line configuration에 대한 쓰기 권한, edge event 수신 권한을 얻습니다. 자세한 후속 연산은 `gpio-v2-line-request`에서 설명합니다.
하나의 line request로 여러 line을 요청할 수 있으며 kernel은 요청된 모든 line에 대한 연산을 가능한 한 atomic하게 수행합니다. 예를 들어 `gpio-v2-line-get-values-ioctl.rst`는 모든 요청 line을 한 번에 읽습니다.
Output 값까지 포함한 line 상태는 반환된 file descriptor가 닫힐 때까지 요청대로 유지됩니다. Descriptor를 닫으면 userspace 관점에서 상태가 제어되지 않고 기본 상태로 돌아갈 수 있습니다. 이미 사용 중인 line 요청은 `EBUSY`입니다. 기존 line request가 있는 상태에서 `chip_fd`를 닫아도 request에는 영향이 없습니다.
Chip descriptor는 요청 생성에 쓰이고 request descriptor가 소유권을 유지합니다.
Description
===========
On success, the requesting process is granted exclusive access to the line
value, write access to the line configuration, and may receive events when
edges are detected on the line, all of which are described in more detail in
:ref:`gpio-v2-line-request`.
A number of lines may be requested in the one line request, and request
operations are performed on the requested lines by the kernel as atomically
as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
requested lines at once.
The state of a line, including the value of output lines, is guaranteed to
remain as requested until the returned file descriptor is closed. Once the
file descriptor is closed, the state of the line becomes uncontrolled from
the userspace perspective, and may revert to its default state.
Requesting a line already in use is an error (**EBUSY**).
Closing the ``chip_fd`` has no effect on existing line requests.
방향, drive, bias, edge, clock, debounce 규칙
53-96한 requested line에서 `GPIO_V2_LINE_FLAG_INPUT`과 `GPIO_V2_LINE_FLAG_OUTPUT`은 함께 설정할 수 없습니다. 둘 다 없으면 `GPIO_V2_LINE_FLAG_ACTIVE_LOW`만 추가할 수 있고 전기적 구성을 바꾸지 않는 as-is 요청이 됩니다.
`GPIO_V2_LINE_FLAG_OPEN_xxx` drive flag는 `GPIO_V2_LINE_FLAG_OUTPUT`이 필요하며 하나만 선택할 수 있습니다. Drive flag가 없으면 push-pull입니다. `GPIO_V2_LINE_FLAG_BIAS_xxx`도 하나만 선택할 수 있고 방향 flag가 필요하며, bias flag가 없으면 기존 bias를 유지합니다.
`GPIO_V2_LINE_FLAG_EDGE_xxx`는 input flag가 필요하고 rising과 falling을 함께 선택할 수 있습니다. Edge detection을 지원하지 않는 line이면 `ENXIO`입니다.
`GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx`는 하나만 선택할 수 있고 없으면 `CLOCK_MONOTONIC`입니다. `GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`는 지원 hardware와 `CONFIG_HTE`가 설정된 kernel이 필요하며, device가 HTE를 지원하지 않으면 `EOPNOTSUPP`입니다.
`gpio_v2_line_attribute`의 `debounce_period_us`는 input line에만 적용할 수 있습니다. Debounce는 값 읽기와 edge event 모두에 적용되고 hardware가 직접 지원하지 않으면 kernel이 software로 모사합니다. Hardware debounce도 interrupt도 없는 line이면 software emulation이 불가능하므로 `ENXIO`입니다. 그 밖의 유효하지 않은 구성은 `EINVAL`입니다.
Flag와 attribute의 필수 조합 및 오류입니다.
.. _gpio-v2-get-line-config-rules:
Configuration Rules
-------------------
For any given requested line, the following configuration rules apply:
The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and
``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then
the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW``
and the line is requested "as-is" to allow reading of the line value
without altering the electrical configuration.
The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the
``GPIO_V2_LINE_FLAG_OUTPUT`` to be set.
Only one drive flag may be set.
If none are set then the line is assumed push-pull.
Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it
requires a direction flag to also be set.
If no bias flags are set then the bias configuration is not changed.
The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require
``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising
and falling edges. Requesting edge detection from a line that does not support
it is an error (**ENXIO**).
Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set.
If none are set then the event clock defaults to ``CLOCK_MONOTONIC``.
The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware
and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that
doesn't support it is an error (**EOPNOTSUPP**).
The :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only
be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce
applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and
the edges returned by gpio-v2-line-event-read.rst. If not
supported directly by hardware, debouncing is emulated in software by the
kernel. Requesting debounce on a line that supports neither debounce in
hardware nor interrupts, as required for software emulation, is an error
(**ENXIO**).
Requesting an invalid configuration is an error (**EINVAL**).
미지원 기능 fallback과 보고 한계
97-144하위 hardware와 driver가 요청 구성을 직접 지원하지 않으면 kernel은 요청 거부, software emulation, best effort 중 하나를 적용합니다. 선택은 합리적으로 모사할 수 있는지와 미지원 상태가 hardware 및 userspace에 미치는 영향에 따라 달라집니다.
Bias는 best effort, debounce는 emulate, direction은 reject, drive는 emulate, edge detection은 reject 방식입니다. Bias를 best effort로 다뤄 내부 bias platform과 외부 bias platform에서 같은 userspace 구성을 쓸 수 있게 하지만, 최악의 경우 line이 예상대로 bias되지 않고 floating일 수 있습니다.
Debounce는 line의 hardware interrupt를 filter하는 방식으로 모사합니다. Edge를 감지한 뒤 debounce period 동안 line이 안정적으로 유지되면 event를 생성하고, timestamp는 debounce period의 끝에 대응합니다.
Drive는 line을 능동적으로 구동하지 않아야 할 때 input으로 전환하여 모사합니다. Edge detection은 interrupt 지원이 필요하며 없으면 거부하지만 userspace가 polling으로 직접 모사할 수는 있습니다.
`gpio-v2-get-lineinfo-ioctl.rst`가 보고하는 configuration은 실제 hardware 결과가 아니라 요청한 구성입니다. 따라서 userspace는 기능이 hardware에서 지원되는지, emulation됐는지, best effort인지 판별할 수 없습니다.
기능별 kernel fallback 정책입니다.
직접 지원 여부와 기능별 정책에 따라 적용 경로를 선택합니다.
.. _gpio-v2-get-line-config-support:
Configuration Support
---------------------
Where the requested configuration is not directly supported by the underlying
hardware and driver, the kernel applies one of these approaches:
- reject the request
- emulate the feature in software
- treat the feature as best effort
The approach applied depends on whether the feature can reasonably be emulated
in software, and the impact on the hardware and userspace if the feature is not
supported.
The approach applied for each feature is as follows:
============== ===========
Feature Approach
============== ===========
Bias best effort
Debounce emulate
Direction reject
Drive emulate
Edge Detection reject
============== ===========
Bias is treated as best effort to allow userspace to apply the same
configuration for platforms that support internal bias as those that require
external bias.
Worst case the line floats rather than being biased as expected.
Debounce is emulated by applying a filter to hardware interrupts on the line.
An edge event is generated after an edge is detected and the line remains
stable for the debounce period.
The event timestamp corresponds to the end of the debounce period.
Drive is emulated by switching the line to an input when the line should not
be actively driven.
Edge detection requires interrupt support, and is rejected if that is not
supported. Emulation by polling can still be performed from userspace.
In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst
is the requested configuration, not the resulting hardware configuration.
Userspace cannot determine if a feature is supported in hardware, is
emulated, or is best effort.
반환값
145-152성공하면 0을 반환하고 `gpio_v2_line_request`의 `request.fd`에 요청 file descriptor를 저장합니다. 실패하면 -1을 반환하고 `errno`를 설정합니다. 공통 오류 코드는 `error-codes.rst`를 따릅니다.
Return Value
============
On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the
file descriptor for the request.
On error -1 and the ``errno`` variable is set appropriately.
Common error codes are described in error-codes.rst.
요약·해설
gpio-v2-get-line-ioctl.rst:1-152GPIO ABI v2 line request의 배타적 접근, atomicity, flag·clock·debounce 규칙과 hardware fallback을 설명합니다.
원문의 ioctl/read prototype, struct, flag, errno, clock, buffer 규칙과 줄 좌표를 보존해 전문 번역했습니다.