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