Documentation/userspace-api/gpio/chardev_v1.rst

Source file repositories/reference/linux-study-clean/Documentation/userspace-api/gpio/chardev_v1.rst

File Facts

System
Linux kernel
Corpus path
Documentation/userspace-api/gpio/chardev_v1.rst
Extension
.rst
Size
3851 bytes
Lines
132
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

.. 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.

.. _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>

.. _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.

Annotation

Implementation Notes