1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 =================================== 3 ===================================
4 GPIO Character Device Userspace API 4 GPIO Character Device Userspace API
5 =================================== 5 ===================================
6 6
7 This is latest version (v2) of the character d 7 This is latest version (v2) of the character device API, as defined in
8 ``include/uapi/linux/gpio.h.`` 8 ``include/uapi/linux/gpio.h.``
9 9
10 First added in 5.10. 10 First added in 5.10.
11 11
12 .. note:: 12 .. note::
13 Do NOT abuse userspace APIs to control hard 13 Do NOT abuse userspace APIs to control hardware that has proper kernel
14 drivers. There may already be a driver for 14 drivers. There may already be a driver for your use case, and an existing
15 kernel driver is sure to provide a superior 15 kernel driver is sure to provide a superior solution to bitbashing
16 from userspace. 16 from userspace.
17 17
18 Read Documentation/driver-api/gpio/drivers- 18 Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
19 kernel wheels in userspace. 19 kernel wheels in userspace.
20 20
21 Similarly, for multi-function lines there m 21 Similarly, for multi-function lines there may be other subsystems, such as
22 Documentation/spi/index.rst, Documentation/ 22 Documentation/spi/index.rst, Documentation/i2c/index.rst,
23 Documentation/driver-api/pwm.rst, Documenta 23 Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that
24 provide suitable drivers and APIs for your 24 provide suitable drivers and APIs for your hardware.
25 25
26 Basic examples using the character device API 26 Basic examples using the character device API can be found in ``tools/gpio/*``.
27 27
28 The API is based around two major objects, the 28 The API is based around two major objects, the :ref:`gpio-v2-chip` and the
29 :ref:`gpio-v2-line-request`. 29 :ref:`gpio-v2-line-request`.
30 30
31 .. _gpio-v2-chip: 31 .. _gpio-v2-chip:
32 32
33 Chip 33 Chip
34 ==== 34 ====
35 35
36 The Chip represents a single GPIO chip and is 36 The Chip represents a single GPIO chip and is exposed to userspace using device
37 files of the form ``/dev/gpiochipX``. 37 files of the form ``/dev/gpiochipX``.
38 38
39 Each chip supports a number of GPIO lines, 39 Each chip supports a number of GPIO lines,
40 :c:type:`chip.lines<gpiochip_info>`. Lines on 40 :c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
41 ``offset`` in the range from 0 to ``chip.lines 41 ``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
42 42
43 Lines are requested from the chip using gpio-v 43 Lines are requested from the chip using gpio-v2-get-line-ioctl.rst
44 and the resulting line request is used to acce 44 and the resulting line request is used to access the GPIO chip's lines or
45 monitor the lines for edge events. 45 monitor the lines for edge events.
46 46
47 Within this documentation, the file descriptor 47 Within this documentation, the file descriptor returned by calling `open()`
48 on the GPIO device file is referred to as ``ch 48 on the GPIO device file is referred to as ``chip_fd``.
49 49
50 Operations 50 Operations
51 ---------- 51 ----------
52 52
53 The following operations may be performed on t 53 The following operations may be performed on the chip:
54 54
55 .. toctree:: 55 .. toctree::
56 :titlesonly: 56 :titlesonly:
57 57
58 Get Line <gpio-v2-get-line-ioctl> 58 Get Line <gpio-v2-get-line-ioctl>
59 Get Chip Info <gpio-get-chipinfo-ioctl> 59 Get Chip Info <gpio-get-chipinfo-ioctl>
60 Get Line Info <gpio-v2-get-lineinfo-ioctl> 60 Get Line Info <gpio-v2-get-lineinfo-ioctl>
61 Watch Line Info <gpio-v2-get-lineinfo-watch 61 Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl>
62 Unwatch Line Info <gpio-get-lineinfo-unwatc 62 Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
63 Read Line Info Changed Events <gpio-v2-line 63 Read Line Info Changed Events <gpio-v2-lineinfo-changed-read>
64 64
65 .. _gpio-v2-line-request: 65 .. _gpio-v2-line-request:
66 66
67 Line Request 67 Line Request
68 ============ 68 ============
69 69
70 Line requests are created by gpio-v2-get-line- 70 Line requests are created by gpio-v2-get-line-ioctl.rst and provide
71 access to a set of requested lines. The line 71 access to a set of requested lines. The line request is exposed to userspace
72 via the anonymous file descriptor returned in 72 via the anonymous file descriptor returned in
73 :c:type:`request.fd<gpio_v2_line_request>` by 73 :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
74 74
75 Within this documentation, the line request fi 75 Within this documentation, the line request file descriptor is referred to
76 as ``req_fd``. 76 as ``req_fd``.
77 77
78 Operations 78 Operations
79 ---------- 79 ----------
80 80
81 The following operations may be performed on t 81 The following operations may be performed on the line request:
82 82
83 .. toctree:: 83 .. toctree::
84 :titlesonly: 84 :titlesonly:
85 85
86 Get Line Values <gpio-v2-line-get-values-io 86 Get Line Values <gpio-v2-line-get-values-ioctl>
87 Set Line Values <gpio-v2-line-set-values-io 87 Set Line Values <gpio-v2-line-set-values-ioctl>
88 Read Line Edge Events <gpio-v2-line-event-r 88 Read Line Edge Events <gpio-v2-line-event-read>
89 Reconfigure Lines <gpio-v2-line-set-config- 89 Reconfigure Lines <gpio-v2-line-set-config-ioctl>
90 90
91 Types 91 Types
92 ===== 92 =====
93 93
94 This section contains the structs and enums th 94 This section contains the structs and enums that are referenced by the API v2,
95 as defined in ``include/uapi/linux/gpio.h``. 95 as defined in ``include/uapi/linux/gpio.h``.
96 96
97 .. kernel-doc:: include/uapi/linux/gpio.h 97 .. kernel-doc:: include/uapi/linux/gpio.h
98 :identifiers: 98 :identifiers:
99 gpio_v2_line_attr_id 99 gpio_v2_line_attr_id
100 gpio_v2_line_attribute 100 gpio_v2_line_attribute
101 gpio_v2_line_changed_type 101 gpio_v2_line_changed_type
102 gpio_v2_line_config 102 gpio_v2_line_config
103 gpio_v2_line_config_attribute 103 gpio_v2_line_config_attribute
104 gpio_v2_line_event 104 gpio_v2_line_event
105 gpio_v2_line_event_id 105 gpio_v2_line_event_id
106 gpio_v2_line_flag 106 gpio_v2_line_flag
107 gpio_v2_line_info 107 gpio_v2_line_info
108 gpio_v2_line_info_changed 108 gpio_v2_line_info_changed
109 gpio_v2_line_request 109 gpio_v2_line_request
110 gpio_v2_line_values 110 gpio_v2_line_values
111 gpiochip_info 111 gpiochip_info
112 112
113 .. toctree:: 113 .. toctree::
114 :hidden: 114 :hidden:
115 115
116 error-codes 116 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.