1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. _GPIO_V2_GET_LINE_IOCTL:
  4
  5**********************
  6GPIO_V2_GET_LINE_IOCTL
  7**********************
  8
  9Name
 10====
 11
 12GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel.
 13
 14Synopsis
 15========
 16
 17.. c:macro:: GPIO_V2_GET_LINE_IOCTL
 18
 19``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)``
 20
 21Arguments
 22=========
 23
 24``chip_fd``
 25    The file descriptor of the GPIO character device returned by `open()`.
 26
 27``request``
 28    The :c:type:`line_request<gpio_v2_line_request>` specifying the lines
 29    to request and their configuration.
 30
 31Description
 32===========
 33
 34On success, the requesting process is granted exclusive access to the line
 35value, write access to the line configuration, and may receive events when
 36edges are detected on the line, all of which are described in more detail in
 37:ref:`gpio-v2-line-request`.
 38
 39A number of lines may be requested in the one line request, and request
 40operations are performed on the requested lines by the kernel as atomically
 41as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
 42requested lines at once.
 43
 44The state of a line, including the value of output lines, is guaranteed to
 45remain as requested until the returned file descriptor is closed. Once the
 46file descriptor is closed, the state of the line becomes uncontrolled from
 47the userspace perspective, and may revert to its default state.
 48
 49Requesting a line already in use is an error (**EBUSY**).
 50
 51Closing the ``chip_fd`` has no effect on existing line requests.
 52
 53.. _gpio-v2-get-line-config-rules:
 54
 55Configuration Rules
 56-------------------
 57
 58For any given requested line, the following configuration rules apply:
 59
 60The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and
 61``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then
 62the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW``
 63and the line is requested "as-is" to allow reading of the line value
 64without altering the electrical configuration.
 65
 66The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the
 67``GPIO_V2_LINE_FLAG_OUTPUT`` to be set.
 68Only one drive flag may be set.
 69If none are set then the line is assumed push-pull.
 70
 71Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it
 72requires a direction flag to also be set.
 73If no bias flags are set then the bias configuration is not changed.
 74
 75The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require
 76``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising
 77and falling edges.  Requesting edge detection from a line that does not support
 78it is an error (**ENXIO**).
 79
 80Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set.
 81If none are set then the event clock defaults to ``CLOCK_MONOTONIC``.
 82The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware
 83and a kernel with ``CONFIG_HTE`` set.  Requesting HTE from a device that
 84doesn't support it is an error (**EOPNOTSUPP**).
 85
 86The :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only
 87be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce
 88applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and
 89the edges returned by gpio-v2-line-event-read.rst.  If not
 90supported directly by hardware, debouncing is emulated in software by the
 91kernel.  Requesting debounce on a line that supports neither debounce in
 92hardware nor interrupts, as required for software emulation, is an error
 93(**ENXIO**).
 94
 95Requesting an invalid configuration is an error (**EINVAL**).
 96
 97.. _gpio-v2-get-line-config-support:
 98
 99Configuration Support
100---------------------
101
102Where the requested configuration is not directly supported by the underlying
103hardware and driver, the kernel applies one of these approaches:
104
105 - reject the request
106 - emulate the feature in software
107 - treat the feature as best effort
108
109The approach applied depends on whether the feature can reasonably be emulated
110in software, and the impact on the hardware and userspace if the feature is not
111supported.
112The approach applied for each feature is as follows:
113
114==============   ===========
115Feature          Approach
116==============   ===========
117Bias             best effort
118Debounce         emulate
119Direction        reject
120Drive            emulate
121Edge Detection   reject
122==============   ===========
123
124Bias is treated as best effort to allow userspace to apply the same
125configuration for platforms that support internal bias as those that require
126external bias.
127Worst case the line floats rather than being biased as expected.
128
129Debounce is emulated by applying a filter to hardware interrupts on the line.
130An edge event is generated after an edge is detected and the line remains
131stable for the debounce period.
132The event timestamp corresponds to the end of the debounce period.
133
134Drive is emulated by switching the line to an input when the line should not
135be actively driven.
136
137Edge detection requires interrupt support, and is rejected if that is not
138supported. Emulation by polling can still be performed from userspace.
139
140In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst
141is the requested configuration, not the resulting hardware configuration.
142Userspace cannot determine if a feature is supported in hardware, is
143emulated, or is best effort.
144
145Return Value
146============
147
148On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the
149file descriptor for the request.
150
151On error -1 and the ``errno`` variable is set appropriately.
152Common error codes are described in error-codes.rst.