132a0a0daSKent Gibson.. SPDX-License-Identifier: GPL-2.0 232a0a0daSKent Gibson 332a0a0daSKent Gibson.. _GPIO_V2_GET_LINE_IOCTL: 432a0a0daSKent Gibson 532a0a0daSKent Gibson********************** 632a0a0daSKent GibsonGPIO_V2_GET_LINE_IOCTL 732a0a0daSKent Gibson********************** 832a0a0daSKent Gibson 932a0a0daSKent GibsonName 1032a0a0daSKent Gibson==== 1132a0a0daSKent Gibson 1232a0a0daSKent GibsonGPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel. 1332a0a0daSKent Gibson 1432a0a0daSKent GibsonSynopsis 1532a0a0daSKent Gibson======== 1632a0a0daSKent Gibson 1732a0a0daSKent Gibson.. c:macro:: GPIO_V2_GET_LINE_IOCTL 1832a0a0daSKent Gibson 1932a0a0daSKent Gibson``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)`` 2032a0a0daSKent Gibson 2132a0a0daSKent GibsonArguments 2232a0a0daSKent Gibson========= 2332a0a0daSKent Gibson 2432a0a0daSKent Gibson``chip_fd`` 2532a0a0daSKent Gibson The file descriptor of the GPIO character device returned by `open()`. 2632a0a0daSKent Gibson 2732a0a0daSKent Gibson``request`` 2832a0a0daSKent Gibson The :c:type:`line_request<gpio_v2_line_request>` specifying the lines 2932a0a0daSKent Gibson to request and their configuration. 3032a0a0daSKent Gibson 3132a0a0daSKent GibsonDescription 3232a0a0daSKent Gibson=========== 3332a0a0daSKent Gibson 3432a0a0daSKent GibsonOn success, the requesting process is granted exclusive access to the line 3532a0a0daSKent Gibsonvalue, write access to the line configuration, and may receive events when 3632a0a0daSKent Gibsonedges are detected on the line, all of which are described in more detail in 3732a0a0daSKent Gibson:ref:`gpio-v2-line-request`. 3832a0a0daSKent Gibson 3932a0a0daSKent GibsonA number of lines may be requested in the one line request, and request 4032a0a0daSKent Gibsonoperations are performed on the requested lines by the kernel as atomically 4132a0a0daSKent Gibsonas possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the 4232a0a0daSKent Gibsonrequested lines at once. 4332a0a0daSKent Gibson 4432a0a0daSKent GibsonThe state of a line, including the value of output lines, is guaranteed to 4532a0a0daSKent Gibsonremain as requested until the returned file descriptor is closed. Once the 4632a0a0daSKent Gibsonfile descriptor is closed, the state of the line becomes uncontrolled from 4732a0a0daSKent Gibsonthe userspace perspective, and may revert to its default state. 4832a0a0daSKent Gibson 4932a0a0daSKent GibsonRequesting a line already in use is an error (**EBUSY**). 5032a0a0daSKent Gibson 5132a0a0daSKent GibsonClosing the ``chip_fd`` has no effect on existing line requests. 5232a0a0daSKent Gibson 5332a0a0daSKent Gibson.. _gpio-v2-get-line-config-rules: 5432a0a0daSKent Gibson 5532a0a0daSKent GibsonConfiguration Rules 5632a0a0daSKent Gibson------------------- 5732a0a0daSKent Gibson 5832a0a0daSKent GibsonFor any given requested line, the following configuration rules apply: 5932a0a0daSKent Gibson 6032a0a0daSKent GibsonThe direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and 6132a0a0daSKent Gibson``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then 6232a0a0daSKent Gibsonthe only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` 6332a0a0daSKent Gibsonand the line is requested "as-is" to allow reading of the line value 6432a0a0daSKent Gibsonwithout altering the electrical configuration. 6532a0a0daSKent Gibson 6632a0a0daSKent GibsonThe drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the 6732a0a0daSKent Gibson``GPIO_V2_LINE_FLAG_OUTPUT`` to be set. 6832a0a0daSKent GibsonOnly one drive flag may be set. 6932a0a0daSKent GibsonIf none are set then the line is assumed push-pull. 7032a0a0daSKent Gibson 7132a0a0daSKent GibsonOnly one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it 7232a0a0daSKent Gibsonrequires a direction flag to also be set. 7332a0a0daSKent GibsonIf no bias flags are set then the bias configuration is not changed. 7432a0a0daSKent Gibson 7532a0a0daSKent GibsonThe edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require 7632a0a0daSKent Gibson``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising 7742969726SKent Gibsonand falling edges. Requesting edge detection from a line that does not support 7842969726SKent Gibsonit is an error (**ENXIO**). 7932a0a0daSKent Gibson 8032a0a0daSKent GibsonOnly one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set. 8132a0a0daSKent GibsonIf none are set then the event clock defaults to ``CLOCK_MONOTONIC``. 8232a0a0daSKent GibsonThe ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware 8332a0a0daSKent Gibsonand a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that 84*a261e208SDavid Lechnerdoesn't support it is an error (**EOPNOTSUPP**). 8532a0a0daSKent Gibson 8632a0a0daSKent GibsonThe :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only 8732a0a0daSKent Gibsonbe applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce 8832a0a0daSKent Gibsonapplies to both the values returned by gpio-v2-line-get-values-ioctl.rst and 8932a0a0daSKent Gibsonthe edges returned by gpio-v2-line-event-read.rst. If not 9042969726SKent Gibsonsupported directly by hardware, debouncing is emulated in software by the 9142969726SKent Gibsonkernel. Requesting debounce on a line that supports neither debounce in 9242969726SKent Gibsonhardware nor interrupts, as required for software emulation, is an error 9342969726SKent Gibson(**ENXIO**). 9432a0a0daSKent Gibson 9532a0a0daSKent GibsonRequesting an invalid configuration is an error (**EINVAL**). 9632a0a0daSKent Gibson 9742969726SKent Gibson.. _gpio-v2-get-line-config-support: 9842969726SKent Gibson 9942969726SKent GibsonConfiguration Support 10042969726SKent Gibson--------------------- 10142969726SKent Gibson 10242969726SKent GibsonWhere the requested configuration is not directly supported by the underlying 10342969726SKent Gibsonhardware and driver, the kernel applies one of these approaches: 10442969726SKent Gibson 10542969726SKent Gibson - reject the request 10642969726SKent Gibson - emulate the feature in software 10742969726SKent Gibson - treat the feature as best effort 10842969726SKent Gibson 10942969726SKent GibsonThe approach applied depends on whether the feature can reasonably be emulated 11042969726SKent Gibsonin software, and the impact on the hardware and userspace if the feature is not 11142969726SKent Gibsonsupported. 11242969726SKent GibsonThe approach applied for each feature is as follows: 11342969726SKent Gibson 11442969726SKent Gibson============== =========== 11542969726SKent GibsonFeature Approach 11642969726SKent Gibson============== =========== 11742969726SKent GibsonBias best effort 11842969726SKent GibsonDebounce emulate 11942969726SKent GibsonDirection reject 12042969726SKent GibsonDrive emulate 12142969726SKent GibsonEdge Detection reject 12242969726SKent Gibson============== =========== 12342969726SKent Gibson 12442969726SKent GibsonBias is treated as best effort to allow userspace to apply the same 12542969726SKent Gibsonconfiguration for platforms that support internal bias as those that require 12642969726SKent Gibsonexternal bias. 12742969726SKent GibsonWorst case the line floats rather than being biased as expected. 12842969726SKent Gibson 12942969726SKent GibsonDebounce is emulated by applying a filter to hardware interrupts on the line. 13042969726SKent GibsonAn edge event is generated after an edge is detected and the line remains 13142969726SKent Gibsonstable for the debounce period. 13242969726SKent GibsonThe event timestamp corresponds to the end of the debounce period. 13342969726SKent Gibson 13442969726SKent GibsonDrive is emulated by switching the line to an input when the line should not 13542969726SKent Gibsonbe actively driven. 13642969726SKent Gibson 13742969726SKent GibsonEdge detection requires interrupt support, and is rejected if that is not 13842969726SKent Gibsonsupported. Emulation by polling can still be performed from userspace. 13942969726SKent Gibson 14042969726SKent GibsonIn all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst 14142969726SKent Gibsonis the requested configuration, not the resulting hardware configuration. 14242969726SKent GibsonUserspace cannot determine if a feature is supported in hardware, is 14342969726SKent Gibsonemulated, or is best effort. 14442969726SKent Gibson 14532a0a0daSKent GibsonReturn Value 14632a0a0daSKent Gibson============ 14732a0a0daSKent Gibson 14832a0a0daSKent GibsonOn success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the 14932a0a0daSKent Gibsonfile descriptor for the request. 15032a0a0daSKent Gibson 15132a0a0daSKent GibsonOn error -1 and the ``errno`` variable is set appropriately. 15232a0a0daSKent GibsonCommon error codes are described in error-codes.rst. 153