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

상태, 이행 지침, 핵심 객체

이 문서는 Linux 4.8에서 처음 추가된 GPIO character device ABI v1을 설명합니다. 이 API는 `chardev.rst`의 v2 API로 대체되었으며 향후 제거될 예정입니다. 새 개발은 v2를 사용해야 하고, 기존 v1 프로그램도 가능한 한 빨리 이전하는 것이 권장됩니다.

v2는 v1의 기능적 상위 집합이므로 모든 v1 호출을 대응하는 v2 호출로 직접 옮길 수 있습니다. 이전 기간에는 v1 인터페이스를 계속 유지하지만 새 기능은 v2에만 추가됩니다.

v1 ABI의 중심 객체는 `gpio-v1-chip`, `gpio-v1-line-handle`, `gpio-v1-line-event` 세 가지입니다. 이 문서에서 line event라는 말은 edge event 자체가 아니라 한 GPIO line의 edge event를 감시하도록 만든 요청 객체를 뜻합니다.

.. SPDX-License-Identifier: GPL-2.0

========================================
GPIO Character Device Userspace API (v1)
========================================

.. warning::
   This API is obsoleted by chardev.rst (v2).

   New developments should use the v2 API, and existing developments are
   encouraged to migrate as soon as possible, as this API will be removed
   in the future. The v2 API is a functional superset of the v1 API so any
   v1 call can be directly translated to a v2 equivalent.

   This interface will continue to be maintained for the migration period,
   but new features will only be added to the new API.

First added in 4.8.

The API is based around three major objects, the :ref:`gpio-v1-chip`, the
:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`.

Where "line event" is used in this document it refers to the request that can
monitor a line for edge events, not the edge events themselves.

Chip과 chip_fd

Chip은 하나의 GPIO chip을 나타내며 `/dev/gpiochipX` 형식의 장치 파일로 사용자 공간에 노출됩니다. 각 chip은 `gpiochip_info`의 `chip.lines`만큼 GPIO line을 제공하고, 각 line은 0부터 `chip.lines - 1`까지의 `offset`, 즉 반열린 구간 `[0, chip.lines)`로 식별됩니다.

`gpio-get-linehandle-ioctl.rst`로 line을 요청하면 GPIO line에 접근하는 line handle이 만들어집니다. `gpio-get-lineevent-ioctl.rst`로 요청하면 한 line의 edge event를 감시하는 line event가 만들어집니다. GPIO 장치 파일에 `open()`을 호출해 얻은 파일 디스크립터는 이 문서에서 `chip_fd`라고 부릅니다.

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

.. _gpio-v1-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 either gpio-get-linehandle-ioctl.rst
and the resulting line handle is used to access the GPIO chip's lines, or
gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor
a GPIO line 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 Handle <gpio-get-linehandle-ioctl>
   Get Line Event <gpio-get-lineevent-ioctl>
   Get Chip Info <gpio-get-chipinfo-ioctl>
   Get Line Info <gpio-get-lineinfo-ioctl>
   Watch Line Info <gpio-get-lineinfo-watch-ioctl>
   Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
   Read Line Info Changed Events <gpio-lineinfo-changed-read>

Line Handle과 handle_fd

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

Line handle에서는 요청한 line 값 읽기, line 값 쓰기, line 재구성 연산을 수행할 수 있습니다.

.. _gpio-v1-line-handle:

Line Handle
===========

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

Within this documentation, the line handle file descriptor is referred to
as ``handle_fd``.

Operations
----------

The following operations may be performed on the line handle:

.. toctree::
   :titlesonly:

   Get Line Values <gpio-handle-get-line-values-ioctl>
   Set Line Values <gpio-handle-set-line-values-ioctl>
   Reconfigure Lines <gpio-handle-set-config-ioctl>

Line Event와 event_fd

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

Line event에서는 현재 line 값을 가져오거나 line의 edge event를 읽을 수 있습니다.

.. _gpio-v1-line-event:

Line Event
==========

Line events are created by gpio-get-lineevent-ioctl.rst and provide
access to a requested line.  The line event is exposed to userspace
via the anonymous file descriptor returned  in
:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.

Within this documentation, the line event file descriptor is referred to
as ``event_fd``.

Operations
----------

The following operations may be performed on the line event:

.. toctree::
   :titlesonly:

   Get Line Value <gpio-handle-get-line-values-ioctl>
   Read Line Edge Events <gpio-lineevent-data-read>

ABI v1 자료형

이 절은 ABI v1이 참조하는 구조체를 `include/uapi/linux/gpio.h`의 kernel-doc에서 가져옵니다. `gpiochip_info` 구조체는 ABI v1과 v2가 함께 사용합니다.

v1 전용 식별자는 `gpioevent_data`, `gpioevent_request`, `gpiohandle_config`, `gpiohandle_data`, `gpiohandle_request`, `gpioline_info`, `gpioline_info_changed`입니다. 숨은 toctree 항목으로 공통 `error-codes` 문서를 연결합니다.

Types
=====

This section contains the structs that are referenced by the ABI v1.

The :c:type:`struct gpiochip_info<gpiochip_info>` is common to ABI v1 and v2.

.. kernel-doc:: include/uapi/linux/gpio.h
   :identifiers:
    gpioevent_data
    gpioevent_request
    gpiohandle_config
    gpiohandle_data
    gpiohandle_request
    gpioline_info
    gpioline_info_changed

.. toctree::
   :hidden:

   error-codes