116b2bb7fSKent Gibson.. SPDX-License-Identifier: GPL-2.0 216b2bb7fSKent Gibson 316b2bb7fSKent Gibson.. _GPIO_GET_LINEHANDLE_IOCTL: 416b2bb7fSKent Gibson 516b2bb7fSKent Gibson************************* 616b2bb7fSKent GibsonGPIO_GET_LINEHANDLE_IOCTL 716b2bb7fSKent Gibson************************* 816b2bb7fSKent Gibson 916b2bb7fSKent Gibson.. warning:: 1016b2bb7fSKent Gibson This ioctl is part of chardev_v1.rst and is obsoleted by 1116b2bb7fSKent Gibson gpio-v2-get-line-ioctl.rst. 1216b2bb7fSKent Gibson 1316b2bb7fSKent GibsonName 1416b2bb7fSKent Gibson==== 1516b2bb7fSKent Gibson 1616b2bb7fSKent GibsonGPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel. 1716b2bb7fSKent Gibson 1816b2bb7fSKent GibsonSynopsis 1916b2bb7fSKent Gibson======== 2016b2bb7fSKent Gibson 2116b2bb7fSKent Gibson.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL 2216b2bb7fSKent Gibson 2316b2bb7fSKent Gibson``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)`` 2416b2bb7fSKent Gibson 2516b2bb7fSKent GibsonArguments 2616b2bb7fSKent Gibson========= 2716b2bb7fSKent Gibson 2816b2bb7fSKent Gibson``chip_fd`` 2916b2bb7fSKent Gibson The file descriptor of the GPIO character device returned by `open()`. 3016b2bb7fSKent Gibson 3116b2bb7fSKent Gibson``request`` 3216b2bb7fSKent Gibson The :c:type:`handle_request<gpiohandle_request>` specifying the lines to 3316b2bb7fSKent Gibson request and their configuration. 3416b2bb7fSKent Gibson 3516b2bb7fSKent GibsonDescription 3616b2bb7fSKent Gibson=========== 3716b2bb7fSKent Gibson 3816b2bb7fSKent GibsonRequest a line or lines from the kernel. 3916b2bb7fSKent Gibson 4016b2bb7fSKent GibsonWhile multiple lines may be requested, the same configuration applies to all 4116b2bb7fSKent Gibsonlines in the request. 4216b2bb7fSKent Gibson 4316b2bb7fSKent GibsonOn success, the requesting process is granted exclusive access to the line 4416b2bb7fSKent Gibsonvalue and write access to the line configuration. 4516b2bb7fSKent Gibson 4616b2bb7fSKent GibsonThe state of a line, including the value of output lines, is guaranteed to 4716b2bb7fSKent Gibsonremain as requested until the returned file descriptor is closed. Once the 4816b2bb7fSKent Gibsonfile descriptor is closed, the state of the line becomes uncontrolled from 4916b2bb7fSKent Gibsonthe userspace perspective, and may revert to its default state. 5016b2bb7fSKent Gibson 5116b2bb7fSKent GibsonRequesting a line already in use is an error (**EBUSY**). 5216b2bb7fSKent Gibson 5316b2bb7fSKent GibsonClosing the ``chip_fd`` has no effect on existing line handles. 5416b2bb7fSKent Gibson 5516b2bb7fSKent Gibson.. _gpio-get-linehandle-config-rules: 5616b2bb7fSKent Gibson 5716b2bb7fSKent GibsonConfiguration Rules 5816b2bb7fSKent Gibson------------------- 5916b2bb7fSKent Gibson 6016b2bb7fSKent GibsonThe following configuration rules apply: 6116b2bb7fSKent Gibson 6216b2bb7fSKent GibsonThe direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and 6316b2bb7fSKent Gibson``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the 6416b2bb7fSKent Gibsononly other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the 6516b2bb7fSKent Gibsonline is requested "as-is" to allow reading of the line value without altering 6616b2bb7fSKent Gibsonthe electrical configuration. 6716b2bb7fSKent Gibson 6816b2bb7fSKent GibsonThe drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the 6916b2bb7fSKent Gibson``GPIOHANDLE_REQUEST_OUTPUT`` to be set. 7016b2bb7fSKent GibsonOnly one drive flag may be set. 7116b2bb7fSKent GibsonIf none are set then the line is assumed push-pull. 7216b2bb7fSKent Gibson 7316b2bb7fSKent GibsonOnly one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and 7416b2bb7fSKent Gibsonit requires a direction flag to also be set. 7516b2bb7fSKent GibsonIf no bias flags are set then the bias configuration is not changed. 7616b2bb7fSKent Gibson 7716b2bb7fSKent GibsonRequesting an invalid configuration is an error (**EINVAL**). 7816b2bb7fSKent Gibson 79*42969726SKent Gibson 80*42969726SKent Gibson.. _gpio-get-linehandle-config-support: 81*42969726SKent Gibson 82*42969726SKent GibsonConfiguration Support 83*42969726SKent Gibson--------------------- 84*42969726SKent Gibson 85*42969726SKent GibsonWhere the requested configuration is not directly supported by the underlying 86*42969726SKent Gibsonhardware and driver, the kernel applies one of these approaches: 87*42969726SKent Gibson 88*42969726SKent Gibson - reject the request 89*42969726SKent Gibson - emulate the feature in software 90*42969726SKent Gibson - treat the feature as best effort 91*42969726SKent Gibson 92*42969726SKent GibsonThe approach applied depends on whether the feature can reasonably be emulated 93*42969726SKent Gibsonin software, and the impact on the hardware and userspace if the feature is not 94*42969726SKent Gibsonsupported. 95*42969726SKent GibsonThe approach applied for each feature is as follows: 96*42969726SKent Gibson 97*42969726SKent Gibson============== =========== 98*42969726SKent GibsonFeature Approach 99*42969726SKent Gibson============== =========== 100*42969726SKent GibsonBias best effort 101*42969726SKent GibsonDirection reject 102*42969726SKent GibsonDrive emulate 103*42969726SKent Gibson============== =========== 104*42969726SKent Gibson 105*42969726SKent GibsonBias is treated as best effort to allow userspace to apply the same 106*42969726SKent Gibsonconfiguration for platforms that support internal bias as those that require 107*42969726SKent Gibsonexternal bias. 108*42969726SKent GibsonWorst case the line floats rather than being biased as expected. 109*42969726SKent Gibson 110*42969726SKent GibsonDrive is emulated by switching the line to an input when the line should not 111*42969726SKent Gibsonbe driven. 112*42969726SKent Gibson 113*42969726SKent GibsonIn all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst 114*42969726SKent Gibsonis the requested configuration, not the resulting hardware configuration. 115*42969726SKent GibsonUserspace cannot determine if a feature is supported in hardware, is 116*42969726SKent Gibsonemulated, or is best effort. 117*42969726SKent Gibson 11816b2bb7fSKent GibsonReturn Value 11916b2bb7fSKent Gibson============ 12016b2bb7fSKent Gibson 12116b2bb7fSKent GibsonOn success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the 12216b2bb7fSKent Gibsonfile descriptor for the request. 12316b2bb7fSKent Gibson 12416b2bb7fSKent GibsonOn error -1 and the ``errno`` variable is set appropriately. 12516b2bb7fSKent GibsonCommon error codes are described in error-codes.rst. 126