Debian Codegraph @

Documentation/userspace-api/gpio/chardev.rst

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