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