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
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.