1.. SPDX-License-Identifier: GPL-2.0
  2
  3.. _GPIO_GET_LINEHANDLE_IOCTL:
  4
  5*************************
  6GPIO_GET_LINEHANDLE_IOCTL
  7*************************
  8
  9.. warning::
 10    This ioctl is part of chardev_v1.rst and is obsoleted by
 11    gpio-v2-get-line-ioctl.rst.
 12
 13Name
 14====
 15
 16GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.
 17
 18Synopsis
 19========
 20
 21.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL
 22
 23``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``
 24
 25Arguments
 26=========
 27
 28``chip_fd``
 29    The file descriptor of the GPIO character device returned by `open()`.
 30
 31``request``
 32    The :c:type:`handle_request<gpiohandle_request>` specifying the lines to
 33    request and their configuration.
 34
 35Description
 36===========
 37
 38Request a line or lines from the kernel.
 39
 40While multiple lines may be requested, the same configuration applies to all
 41lines in the request.
 42
 43On success, the requesting process is granted exclusive access to the line
 44value and write access to the line configuration.
 45
 46The state of a line, including the value of output lines, is guaranteed to
 47remain as requested until the returned file descriptor is closed. Once the
 48file descriptor is closed, the state of the line becomes uncontrolled from
 49the userspace perspective, and may revert to its default state.
 50
 51Requesting a line already in use is an error (**EBUSY**).
 52
 53Closing the ``chip_fd`` has no effect on existing line handles.
 54
 55.. _gpio-get-linehandle-config-rules:
 56
 57Configuration Rules
 58-------------------
 59
 60The following configuration rules apply:
 61
 62The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and
 63``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the
 64only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the
 65line is requested "as-is" to allow reading of the line value without altering
 66the electrical configuration.
 67
 68The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the
 69``GPIOHANDLE_REQUEST_OUTPUT`` to be set.
 70Only one drive flag may be set.
 71If none are set then the line is assumed push-pull.
 72
 73Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and
 74it requires a direction flag to also be set.
 75If no bias flags are set then the bias configuration is not changed.
 76
 77Requesting an invalid configuration is an error (**EINVAL**).
 78
 79
 80.. _gpio-get-linehandle-config-support:
 81
 82Configuration Support
 83---------------------
 84
 85Where the requested configuration is not directly supported by the underlying
 86hardware and driver, the kernel applies one of these approaches:
 87
 88 - reject the request
 89 - emulate the feature in software
 90 - treat the feature as best effort
 91
 92The approach applied depends on whether the feature can reasonably be emulated
 93in software, and the impact on the hardware and userspace if the feature is not
 94supported.
 95The approach applied for each feature is as follows:
 96
 97==============   ===========
 98Feature          Approach
 99==============   ===========
100Bias             best effort
101Direction        reject
102Drive            emulate
103==============   ===========
104
105Bias is treated as best effort to allow userspace to apply the same
106configuration for platforms that support internal bias as those that require
107external bias.
108Worst case the line floats rather than being biased as expected.
109
110Drive is emulated by switching the line to an input when the line should not
111be driven.
112
113In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst
114is the requested configuration, not the resulting hardware configuration.
115Userspace cannot determine if a feature is supported in hardware, is
116emulated, or is best effort.
117
118Return Value
119============
120
121On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the
122file descriptor for the request.
123
124On error -1 and the ``errno`` variable is set appropriately.
125Common error codes are described in error-codes.rst.