| 1 |
.. SPDX-License-Identifier: GPL-2.0 |
| 2 |
|
| 3 |
======================================== |
| 4 |
GPIO 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 |
|
| 18 |
First added in 4.8. |
| 19 |
|
| 20 |
The 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 |
|
| 23 |
Where "line event" is used in this document it refers to the request that can |
| 24 |
monitor a line for edge events, not the edge events themselves. |
| 25 |
|
| 26 |
.. _gpio-v1-chip: |
| 27 |
|
| 28 |
Chip |
| 29 |
==== |
| 30 |
|
| 31 |
The Chip represents a single GPIO chip and is exposed to userspace using device |
| 32 |
files of the form ``/dev/gpiochipX``. |
| 33 |
|
| 34 |
Each 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 |
|
| 38 |
Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst |
| 39 |
and the resulting line handle is used to access the GPIO chip's lines, or |
| 40 |
gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor |
| 41 |
a GPIO line for edge events. |
| 42 |
|
| 43 |
Within this documentation, the file descriptor returned by calling `open()` |
| 44 |
on the GPIO device file is referred to as ``chip_fd``. |
| 45 |
|
| 46 |
Operations |
| 47 |
---------- |
| 48 |
|
| 49 |
The 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 |
|
| 64 |
Line Handle |
| 65 |
=========== |
| 66 |
|
| 67 |
Line handles are created by gpio-get-linehandle-ioctl.rst and provide |
| 68 |
access to a set of requested lines. The line handle is exposed to userspace |
| 69 |
via the anonymous file descriptor returned in |
| 70 |
:c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst. |
| 71 |
|
| 72 |
Within this documentation, the line handle file descriptor is referred to |
| 73 |
as ``handle_fd``. |
| 74 |
|
| 75 |
Operations |
| 76 |
---------- |
| 77 |
|
| 78 |
The 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 |
|
| 89 |
Line Event |
| 90 |
========== |
| 91 |
|
| 92 |
Line events are created by gpio-get-lineevent-ioctl.rst and provide |
| 93 |
access to a requested line. The line event is exposed to userspace |
| 94 |
via the anonymous file descriptor returned in |
| 95 |
:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst. |
| 96 |
|
| 97 |
Within this documentation, the line event file descriptor is referred to |
| 98 |
as ``event_fd``. |
| 99 |
|
| 100 |
Operations |
| 101 |
---------- |
| 102 |
|
| 103 |
The 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 |
|
| 111 |
Types |
| 112 |
===== |
| 113 |
|
| 114 |
This section contains the structs that are referenced by the ABI v1. |
| 115 |
|
| 116 |
The :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 |