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