chardev_v1.rst

  1.. SPDX-License-Identifier: GPL-2.0
  2
  3========================================
  4GPIO Character Device Userspace API (v1)
  5========================================
  6
  7.. warning::
  8   This API is obsoleted by chardev.rst (v2).
  9
 10   New developments should use the v2 API, and existing developments are
 11   encouraged to migrate as soon as possible, as this API will be removed
 12   in the future. The v2 API is a functional superset of the v1 API so any
 13   v1 call can be directly translated to a v2 equivalent.
 14
 15   This interface will continue to be maintained for the migration period,
 16   but new features will only be added to the new API.
 17
 18First added in 4.8.
 19
 20The API is based around three major objects, the :ref:`gpio-v1-chip`, the
 21:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`.
 22
 23Where "line event" is used in this document it refers to the request that can
 24monitor a line for edge events, not the edge events themselves.
 25
 26.. _gpio-v1-chip:
 27
 28Chip
 29====
 30
 31The Chip represents a single GPIO chip and is exposed to userspace using device
 32files of the form ``/dev/gpiochipX``.
 33
 34Each chip supports a number of GPIO lines,
 35:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
 36``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
 37
 38Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst
 39and the resulting line handle is used to access the GPIO chip's lines, or
 40gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor
 41a GPIO line for edge events.
 42
 43Within this documentation, the file descriptor returned by calling `open()`
 44on the GPIO device file is referred to as ``chip_fd``.
 45
 46Operations
 47----------
 48
 49The following operations may be performed on the chip:
 50
 51.. toctree::
 52   :titlesonly:
 53
 54   Get Line Handle <gpio-get-linehandle-ioctl>
 55   Get Line Event <gpio-get-lineevent-ioctl>
 56   Get Chip Info <gpio-get-chipinfo-ioctl>
 57   Get Line Info <gpio-get-lineinfo-ioctl>
 58   Watch Line Info <gpio-get-lineinfo-watch-ioctl>
 59   Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
 60   Read Line Info Changed Events <gpio-lineinfo-changed-read>
 61
 62.. _gpio-v1-line-handle:
 63
 64Line Handle
 65===========
 66
 67Line handles are created by gpio-get-linehandle-ioctl.rst and provide
 68access to a set of requested lines.  The line handle is exposed to userspace
 69via the anonymous file descriptor returned  in
 70:c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.
 71
 72Within this documentation, the line handle file descriptor is referred to
 73as ``handle_fd``.
 74
 75Operations
 76----------
 77
 78The following operations may be performed on the line handle:
 79
 80.. toctree::
 81   :titlesonly:
 82
 83   Get Line Values <gpio-handle-get-line-values-ioctl>
 84   Set Line Values <gpio-handle-set-line-values-ioctl>
 85   Reconfigure Lines <gpio-handle-set-config-ioctl>
 86
 87.. _gpio-v1-line-event:
 88
 89Line Event
 90==========
 91
 92Line events are created by gpio-get-lineevent-ioctl.rst and provide
 93access to a requested line.  The line event is exposed to userspace
 94via the anonymous file descriptor returned  in
 95:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.
 96
 97Within this documentation, the line event file descriptor is referred to
 98as ``event_fd``.
 99
100Operations
101----------
102
103The following operations may be performed on the line event:
104
105.. toctree::
106   :titlesonly:
107
108   Get Line Value <gpio-handle-get-line-values-ioctl>
109   Read Line Edge Events <gpio-lineevent-data-read>
110
111Types
112=====
113
114This section contains the structs that are referenced by the ABI v1.
115
116The :c:type:`struct gpiochip_info<gpiochip_info>` is common to ABI v1 and v2.
117
118.. kernel-doc:: include/uapi/linux/gpio.h
119   :identifiers:
120    gpioevent_data
121    gpioevent_request
122    gpiohandle_config
123    gpiohandle_data
124    gpiohandle_request
125    gpioline_info
126    gpioline_info_changed
127
128.. toctree::
129   :hidden:
130
131   error-codes