GPIO 문자 장치 사용자 공간 API(v2)

최신 ABI와 사용 원칙

이 문서는 `include/uapi/linux/gpio.h`에 정의된 최신 GPIO character device API인 v2를 설명합니다. v2는 Linux 5.10에서 처음 추가되었습니다.

적절한 kernel driver가 있는 하드웨어를 제어하기 위해 userspace API를 남용해서는 안 됩니다. 이미 해당 용도의 driver가 있을 수 있으며, 기존 kernel driver는 사용자 공간에서 bitbanging하는 방식보다 확실히 우수한 해법을 제공합니다. `Documentation/driver-api/gpio/drivers-on-gpio.rst`를 읽어 사용자 공간에서 kernel 기능을 다시 구현하지 않도록 해야 합니다.

다기능 line은 SPI, I2C, PWM, W1 같은 다른 subsystem이 적합한 driver와 API를 제공할 수 있습니다. 관련 문서는 `Documentation/spi/index.rst`, `Documentation/i2c/index.rst`, `Documentation/driver-api/pwm.rst`, `Documentation/w1/index.rst`입니다. Character device API의 기본 예제는 `tools/gpio/*`에 있습니다.

v2 API의 핵심 객체는 `gpio-v2-chip`과 `gpio-v2-line-request` 두 가지입니다.

.. SPDX-License-Identifier: GPL-2.0

===================================
GPIO Character Device Userspace API
===================================

This is latest version (v2) of the character device API, as defined in
``include/uapi/linux/gpio.h.``

First added in 5.10.

.. note::
   Do NOT abuse userspace APIs to control hardware that has proper kernel
   drivers. There may already be a driver for your use case, and an existing
   kernel driver is sure to provide a superior solution to bitbashing
   from userspace.

   Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
   kernel wheels in userspace.

   Similarly, for multi-function lines there may be other subsystems, such as
   Documentation/spi/index.rst, Documentation/i2c/index.rst,
   Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that
   provide suitable drivers and APIs for your hardware.

Basic examples using the character device API can be found in ``tools/gpio/*``.

The API is based around two major objects, the :ref:`gpio-v2-chip` and the
:ref:`gpio-v2-line-request`.

Chip과 line 요청

Chip은 하나의 GPIO chip을 나타내며 `/dev/gpiochipX` 형식의 장치 파일로 사용자 공간에 노출됩니다. Chip이 제공하는 line 수는 `gpiochip_info`의 `chip.lines`이고, 각 line은 `[0, chip.lines)` 범위의 `offset`으로 식별됩니다.

`gpio-v2-get-line-ioctl.rst`로 chip의 line을 요청하면 line request가 만들어집니다. 이 요청 객체로 GPIO line에 접근하거나 여러 line의 edge event를 감시합니다. GPIO 장치 파일을 `open()`해 얻은 파일 디스크립터는 `chip_fd`라고 부릅니다.

Chip에서는 line 요청, chip 정보 조회, v2 line 정보 조회, line 정보 변경 감시 시작과 해제, line 정보 변경 이벤트 읽기 연산을 수행할 수 있습니다.

.. _gpio-v2-chip:

Chip
====

The Chip represents a single GPIO chip and is exposed to userspace using device
files of the form ``/dev/gpiochipX``.

Each chip supports a number of GPIO lines,
:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.

Lines are requested from the chip using gpio-v2-get-line-ioctl.rst
and the resulting line request is used to access the GPIO chip's lines or
monitor the lines for edge events.

Within this documentation, the file descriptor returned by calling `open()`
on the GPIO device file is referred to as ``chip_fd``.

Operations
----------

The following operations may be performed on the chip:

.. toctree::
   :titlesonly:

   Get Line <gpio-v2-get-line-ioctl>
   Get Chip Info <gpio-get-chipinfo-ioctl>
   Get Line Info <gpio-v2-get-lineinfo-ioctl>
   Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl>
   Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
   Read Line Info Changed Events <gpio-v2-lineinfo-changed-read>

Line Request와 req_fd

Line request는 `gpio-v2-get-line-ioctl.rst`로 만들며 요청한 line 집합에 접근합니다. ioctl이 `gpio_v2_line_request`의 `request.fd`에 반환하는 익명 파일 디스크립터로 사용자 공간에 노출되고, 이 문서에서는 이를 `req_fd`라고 부릅니다.

Line request에서는 line 값 읽기, line 값 쓰기, line edge event 읽기, line 재구성 연산을 수행할 수 있습니다.

.. _gpio-v2-line-request:

Line Request
============

Line requests are created by gpio-v2-get-line-ioctl.rst and provide
access to a set of requested lines.  The line request is exposed to userspace
via the anonymous file descriptor returned in
:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.

Within this documentation, the line request file descriptor is referred to
as ``req_fd``.

Operations
----------

The following operations may be performed on the line request:

.. toctree::
   :titlesonly:

   Get Line Values <gpio-v2-line-get-values-ioctl>
   Set Line Values <gpio-v2-line-set-values-ioctl>
   Read Line Edge Events <gpio-v2-line-event-read>
   Reconfigure Lines <gpio-v2-line-set-config-ioctl>

ABI v2 자료형

이 절은 `include/uapi/linux/gpio.h`에 정의되고 API v2가 참조하는 구조체와 열거형을 kernel-doc에서 가져옵니다. 공통 오류 코드는 숨은 toctree의 `error-codes` 문서에서 설명합니다.

Types
=====

This section contains the structs and enums that are referenced by the API v2,
as defined in ``include/uapi/linux/gpio.h``.

.. kernel-doc:: include/uapi/linux/gpio.h
   :identifiers:
    gpio_v2_line_attr_id
    gpio_v2_line_attribute
    gpio_v2_line_changed_type
    gpio_v2_line_config
    gpio_v2_line_config_attribute
    gpio_v2_line_event
    gpio_v2_line_event_id
    gpio_v2_line_flag
    gpio_v2_line_info
    gpio_v2_line_info_changed
    gpio_v2_line_request
    gpio_v2_line_values
    gpiochip_info

.. toctree::
   :hidden:

   error-codes