요약·해설과 원문, 전문 번역을 서로 분리했습니다. API 이름, symbol, source path는 원문 표기를 사용합니다.
1. 요약·해설
원문의 핵심 논리와 kernel programming 관점의 보충 설명입니다. 아래의 전문 번역과는 별도로 작성했습니다.
2. 영어 원문 전체
번역 기준이 된 Linux v6.18.37 원문입니다. 줄 번호는 이 버전의 파일 좌표입니다.
원문 전체 펼치기
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_GET_LINEHANDLE_IOCTL:
*************************
GPIO_GET_LINEHANDLE_IOCTL
*************************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-get-line-ioctl.rst.
Name
====
GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.
Synopsis
========
.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL
``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``request``
The :c:type:`handle_request<gpiohandle_request>` specifying the lines to
request and their configuration.
Description
===========
Request a line or lines from the kernel.
While multiple lines may be requested, the same configuration applies to all
lines in the request.
On success, the requesting process is granted exclusive access to the line
value and write access to the line configuration.
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 handles.
.. _gpio-get-linehandle-config-rules:
Configuration Rules
-------------------
The following configuration rules apply:
The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and
``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the
only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the
line is requested "as-is" to allow reading of the line value without altering
the electrical configuration.
The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the
``GPIOHANDLE_REQUEST_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, ``GPIOHANDLE_REQUEST_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.
Requesting an invalid configuration is an error (**EINVAL**).
.. _gpio-get-linehandle-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
Direction reject
Drive emulate
============== ===========
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.
Drive is emulated by switching the line to an input when the line should not
be driven.
In all cases, the configuration reported by gpio-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<gpiohandle_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-34`GPIO_GET_LINEHANDLE_IOCTL`은 kernel에서 하나 이상의 GPIO line을 요청합니다. 이 ioctl은 `chardev_v1.rst`의 ABI v1에 속하며 `gpio-v2-get-line-ioctl.rst`로 대체되었습니다.
호출 형식은 `int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)`입니다. `chip_fd`는 GPIO character device를 `open()`해 얻고, `request`는 요청할 line 집합과 공통 구성을 지정하는 `gpiohandle_request` 구조체입니다.
한 요청 안의 모든 line에는 같은 구성이 적용됩니다.
.. SPDX-License-Identifier: GPL-2.0
.. _GPIO_GET_LINEHANDLE_IOCTL:
*************************
GPIO_GET_LINEHANDLE_IOCTL
*************************
.. warning::
This ioctl is part of chardev_v1.rst and is obsoleted by
gpio-v2-get-line-ioctl.rst.
Name
====
GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.
Synopsis
========
.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL
``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``
Arguments
=========
``chip_fd``
The file descriptor of the GPIO character device returned by `open()`.
``request``
The :c:type:`handle_request<gpiohandle_request>` specifying the lines to
request and their configuration.
배타적 접근과 수명
35-54한 번에 여러 line을 요청할 수 있지만 요청에 포함된 모든 line에는 동일한 구성이 적용됩니다. 성공하면 요청 process는 line 값에 대한 배타적 접근 권한과 line configuration에 대한 쓰기 권한을 얻습니다.
Output line의 값을 포함한 line 상태는 반환된 file descriptor가 닫힐 때까지 요청대로 유지됩니다. Descriptor를 닫으면 사용자 공간 관점에서 상태가 더 이상 제어되지 않고 기본 상태로 돌아갈 수 있습니다.
이미 사용 중인 line을 요청하면 `EBUSY`입니다. 기존 line handle이 있는 상태에서 `chip_fd`를 닫아도 해당 handle에는 영향이 없습니다.
Chip descriptor는 요청 생성에 쓰이고 handle descriptor가 line 소유권을 유지합니다.
Description
===========
Request a line or lines from the kernel.
While multiple lines may be requested, the same configuration applies to all
lines in the request.
On success, the requesting process is granted exclusive access to the line
value and write access to the line configuration.
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 handles.
방향, drive, bias 구성 규칙
55-78방향 flag `GPIOHANDLE_REQUEST_INPUT`과 `GPIOHANDLE_REQUEST_OUTPUT`은 함께 설정할 수 없습니다. 둘 다 설정하지 않았다면 허용되는 다른 flag는 `GPIOHANDLE_REQUEST_ACTIVE_LOW`뿐입니다. 이 경우 전기적 구성을 바꾸지 않고 값을 읽도록 line을 현재 상태 그대로, 즉 as-is로 요청합니다.
`GPIOHANDLE_REQUEST_OPEN_xxx` drive flag를 쓰려면 `GPIOHANDLE_REQUEST_OUTPUT`도 설정해야 하며 drive flag는 하나만 선택할 수 있습니다. Drive flag가 없으면 push-pull로 간주합니다.
`GPIOHANDLE_REQUEST_BIAS_xxx` bias flag도 하나만 선택할 수 있고 방향 flag가 함께 있어야 합니다. Bias flag가 없으면 bias 구성을 변경하지 않습니다. 유효하지 않은 구성을 요청하면 `EINVAL`입니다.
Flag 그룹별 조합 제약입니다.
.. _gpio-get-linehandle-config-rules:
Configuration Rules
-------------------
The following configuration rules apply:
The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and
``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the
only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the
line is requested "as-is" to allow reading of the line value without altering
the electrical configuration.
The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the
``GPIOHANDLE_REQUEST_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, ``GPIOHANDLE_REQUEST_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.
Requesting an invalid configuration is an error (**EINVAL**).
하드웨어 미지원 기능의 처리
79-117요청 구성을 하위 hardware와 driver가 직접 지원하지 않으면 kernel은 요청 거부, software emulation, best effort 중 하나를 적용합니다. 어떤 방식을 쓸지는 기능을 software로 합리적으로 모사할 수 있는지와 미지원 상태가 hardware 및 userspace에 미치는 영향에 따라 결정됩니다.
Bias는 best effort, direction은 reject, drive는 emulate 방식입니다. 내부 bias가 있는 platform과 외부 bias가 필요한 platform에서 userspace가 같은 구성을 적용할 수 있도록 bias를 best effort로 취급합니다. 최악의 경우 예상한 bias가 걸리지 않고 line이 floating 상태가 됩니다.
Drive는 line을 구동하지 않아야 할 때 input으로 전환하는 방식으로 모사합니다. 모든 경우 `gpio-get-lineinfo-ioctl.rst`가 보고하는 구성은 실제 hardware 구성이 아니라 요청한 구성입니다. 따라서 userspace는 기능이 hardware에서 직접 지원되는지, emulation되는지, best effort인지 판별할 수 없습니다.
ABI가 기능별로 정한 fallback입니다.
Driver와 hardware의 지원 수준에 따라 kernel이 정해진 정책을 적용합니다.
.. _gpio-get-linehandle-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
Direction reject
Drive emulate
============== ===========
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.
Drive is emulated by switching the line to an input when the line should not
be driven.
In all cases, the configuration reported by gpio-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.
반환값
118-125성공하면 0을 반환하고 `gpiohandle_request`의 `request.fd`에 요청 file descriptor를 저장합니다. 실패하면 -1을 반환하고 `errno`를 설정합니다. 공통 오류 코드는 `error-codes.rst`에 설명되어 있습니다.
Return Value
============
On success 0 and the :c:type:`request.fd<gpiohandle_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-get-linehandle-ioctl.rst:1-125ABI v1 line 집합 요청의 배타적 접근, 구성 flag 조합, hardware 미지원 기능 처리와 반환값을 설명합니다.
원문의 ioctl prototype, struct, flag, errno, source path와 줄 좌표를 보존해 전문 번역했습니다.