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. 126