126 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3.. _GPIO_GET_LINEHANDLE_IOCTL:4 5*************************6GPIO_GET_LINEHANDLE_IOCTL7*************************8 9.. warning::10 This ioctl is part of chardev_v1.rst and is obsoleted by11 gpio-v2-get-line-ioctl.rst.12 13Name14====15 16GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.17 18Synopsis19========20 21.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL22 23``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``24 25Arguments26=========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 to33 request and their configuration.34 35Description36===========37 38Request a line or lines from the kernel.39 40While multiple lines may be requested, the same configuration applies to all41lines in the request.42 43On success, the requesting process is granted exclusive access to the line44value and write access to the line configuration.45 46The state of a line, including the value of output lines, is guaranteed to47remain as requested until the returned file descriptor is closed. Once the48file descriptor is closed, the state of the line becomes uncontrolled from49the 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 Rules58-------------------59 60The following configuration rules apply:61 62The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and63``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the64only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the65line is requested "as-is" to allow reading of the line value without altering66the electrical configuration.67 68The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the69``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, and74it 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 Support83---------------------84 85Where the requested configuration is not directly supported by the underlying86hardware and driver, the kernel applies one of these approaches:87 88 - reject the request89 - emulate the feature in software90 - treat the feature as best effort91 92The approach applied depends on whether the feature can reasonably be emulated93in software, and the impact on the hardware and userspace if the feature is not94supported.95The approach applied for each feature is as follows:96 97============== ===========98Feature Approach99============== ===========100Bias best effort101Direction reject102Drive emulate103============== ===========104 105Bias is treated as best effort to allow userspace to apply the same106configuration for platforms that support internal bias as those that require107external 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 not111be driven.112 113In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst114is the requested configuration, not the resulting hardware configuration.115Userspace cannot determine if a feature is supported in hardware, is116emulated, or is best effort.117 118Return Value119============120 121On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the122file 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