1.. SPDX-License-Identifier: GPL-2.0 2 3=================================== 4GPIO Character Device Userspace API 5=================================== 6 7This is latest version (v2) of the character device API, as defined in 8``include/uapi/linux/gpio.h.`` 9 10First 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 26Basic examples using the character device API can be found in ``tools/gpio/*``. 27 28The 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 33Chip 34==== 35 36The Chip represents a single GPIO chip and is exposed to userspace using device 37files of the form ``/dev/gpiochipX``. 38 39Each 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 43Lines are requested from the chip using gpio-v2-get-line-ioctl.rst 44and the resulting line request is used to access the GPIO chip's lines or 45monitor the lines for edge events. 46 47Within this documentation, the file descriptor returned by calling `open()` 48on the GPIO device file is referred to as ``chip_fd``. 49 50Operations 51---------- 52 53The 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 67Line Request 68============ 69 70Line requests are created by gpio-v2-get-line-ioctl.rst and provide 71access to a set of requested lines. The line request is exposed to userspace 72via the anonymous file descriptor returned in 73:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst. 74 75Within this documentation, the line request file descriptor is referred to 76as ``req_fd``. 77 78Operations 79---------- 80 81The 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 91Types 92===== 93 94This section contains the structs and enums that are referenced by the API v2, 95as 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 117