Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst

   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.