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