117 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===================================4GPIO Character Device Userspace API5===================================6 7This is latest version (v2) of the character device API, as defined in8``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 kernel14 drivers. There may already be a driver for your use case, and an existing15 kernel driver is sure to provide a superior solution to bitbashing16 from userspace.17 18 Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing19 kernel wheels in userspace.20 21 Similarly, for multi-function lines there may be other subsystems, such as22 Documentation/spi/index.rst, Documentation/i2c/index.rst,23 Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that24 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 the29:ref:`gpio-v2-line-request`.30 31.. _gpio-v2-chip:32 33Chip34====35 36The Chip represents a single GPIO chip and is exposed to userspace using device37files 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 an41``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.rst44and the resulting line request is used to access the GPIO chip's lines or45monitor 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 50Operations51----------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 Request68============69 70Line requests are created by gpio-v2-get-line-ioctl.rst and provide71access to a set of requested lines. The line request is exposed to userspace72via the anonymous file descriptor returned in73: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 to76as ``req_fd``.77 78Operations79----------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 91Types92=====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.h98 :identifiers:99 gpio_v2_line_attr_id100 gpio_v2_line_attribute101 gpio_v2_line_changed_type102 gpio_v2_line_config103 gpio_v2_line_config_attribute104 gpio_v2_line_event105 gpio_v2_line_event_id106 gpio_v2_line_flag107 gpio_v2_line_info108 gpio_v2_line_info_changed109 gpio_v2_line_request110 gpio_v2_line_values111 gpiochip_info112 113.. toctree::114 :hidden:115 116 error-codes117