1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _GPIO_GET_LINEHANDLE_IOCTL: 3 .. _GPIO_GET_LINEHANDLE_IOCTL:
4 4
5 ************************* 5 *************************
6 GPIO_GET_LINEHANDLE_IOCTL 6 GPIO_GET_LINEHANDLE_IOCTL
7 ************************* 7 *************************
8 8
9 .. warning:: 9 .. warning::
10 This ioctl is part of chardev_v1.rst and i 10 This ioctl is part of chardev_v1.rst and is obsoleted by
11 gpio-v2-get-line-ioctl.rst. 11 gpio-v2-get-line-ioctl.rst.
12 12
13 Name 13 Name
14 ==== 14 ====
15 15
16 GPIO_GET_LINEHANDLE_IOCTL - Request a line or 16 GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.
17 17
18 Synopsis 18 Synopsis
19 ======== 19 ========
20 20
21 .. c:macro:: GPIO_GET_LINEHANDLE_IOCTL 21 .. c:macro:: GPIO_GET_LINEHANDLE_IOCTL
22 22
23 ``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_I 23 ``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``
24 24
25 Arguments 25 Arguments
26 ========= 26 =========
27 27
28 ``chip_fd`` 28 ``chip_fd``
29 The file descriptor of the GPIO character 29 The file descriptor of the GPIO character device returned by `open()`.
30 30
31 ``request`` 31 ``request``
32 The :c:type:`handle_request<gpiohandle_req 32 The :c:type:`handle_request<gpiohandle_request>` specifying the lines to
33 request and their configuration. 33 request and their configuration.
34 34
35 Description 35 Description
36 =========== 36 ===========
37 37
38 Request a line or lines from the kernel. 38 Request a line or lines from the kernel.
39 39
40 While multiple lines may be requested, the sam 40 While multiple lines may be requested, the same configuration applies to all
41 lines in the request. 41 lines in the request.
42 42
43 On success, the requesting process is granted 43 On success, the requesting process is granted exclusive access to the line
44 value and write access to the line configurati 44 value and write access to the line configuration.
45 45
46 The state of a line, including the value of ou 46 The state of a line, including the value of output lines, is guaranteed to
47 remain as requested until the returned file de 47 remain as requested until the returned file descriptor is closed. Once the
48 file descriptor is closed, the state of the li 48 file descriptor is closed, the state of the line becomes uncontrolled from
49 the userspace perspective, and may revert to i 49 the userspace perspective, and may revert to its default state.
50 50
51 Requesting a line already in use is an error ( 51 Requesting a line already in use is an error (**EBUSY**).
52 52
53 Closing the ``chip_fd`` has no effect on exist 53 Closing the ``chip_fd`` has no effect on existing line handles.
54 54
55 .. _gpio-get-linehandle-config-rules: 55 .. _gpio-get-linehandle-config-rules:
56 56
57 Configuration Rules 57 Configuration Rules
58 ------------------- 58 -------------------
59 59
60 The following configuration rules apply: 60 The following configuration rules apply:
61 61
62 The direction flags, ``GPIOHANDLE_REQUEST_INPU 62 The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and
63 ``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combi 63 ``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the
64 only other flag that may be set is ``GPIOHANDL 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 65 line is requested "as-is" to allow reading of the line value without altering
66 the electrical configuration. 66 the electrical configuration.
67 67
68 The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx 68 The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the
69 ``GPIOHANDLE_REQUEST_OUTPUT`` to be set. 69 ``GPIOHANDLE_REQUEST_OUTPUT`` to be set.
70 Only one drive flag may be set. 70 Only one drive flag may be set.
71 If none are set then the line is assumed push- 71 If none are set then the line is assumed push-pull.
72 72
73 Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_ 73 Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and
74 it requires a direction flag to also be set. 74 it requires a direction flag to also be set.
75 If no bias flags are set then the bias configu 75 If no bias flags are set then the bias configuration is not changed.
76 76
77 Requesting an invalid configuration is an erro 77 Requesting an invalid configuration is an error (**EINVAL**).
78 78
79 79
80 .. _gpio-get-linehandle-config-support: 80 .. _gpio-get-linehandle-config-support:
81 81
82 Configuration Support 82 Configuration Support
83 --------------------- 83 ---------------------
84 84
85 Where the requested configuration is not direc 85 Where the requested configuration is not directly supported by the underlying
86 hardware and driver, the kernel applies one of 86 hardware and driver, the kernel applies one of these approaches:
87 87
88 - reject the request 88 - reject the request
89 - emulate the feature in software 89 - emulate the feature in software
90 - treat the feature as best effort 90 - treat the feature as best effort
91 91
92 The approach applied depends on whether the fe 92 The approach applied depends on whether the feature can reasonably be emulated
93 in software, and the impact on the hardware an 93 in software, and the impact on the hardware and userspace if the feature is not
94 supported. 94 supported.
95 The approach applied for each feature is as fo 95 The approach applied for each feature is as follows:
96 96
97 ============== =========== 97 ============== ===========
98 Feature Approach 98 Feature Approach
99 ============== =========== 99 ============== ===========
100 Bias best effort 100 Bias best effort
101 Direction reject 101 Direction reject
102 Drive emulate 102 Drive emulate
103 ============== =========== 103 ============== ===========
104 104
105 Bias is treated as best effort to allow usersp 105 Bias is treated as best effort to allow userspace to apply the same
106 configuration for platforms that support inter 106 configuration for platforms that support internal bias as those that require
107 external bias. 107 external bias.
108 Worst case the line floats rather than being b 108 Worst case the line floats rather than being biased as expected.
109 109
110 Drive is emulated by switching the line to an 110 Drive is emulated by switching the line to an input when the line should not
111 be driven. 111 be driven.
112 112
113 In all cases, the configuration reported by gp 113 In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst
114 is the requested configuration, not the result 114 is the requested configuration, not the resulting hardware configuration.
115 Userspace cannot determine if a feature is sup 115 Userspace cannot determine if a feature is supported in hardware, is
116 emulated, or is best effort. 116 emulated, or is best effort.
117 117
118 Return Value 118 Return Value
119 ============ 119 ============
120 120
121 On success 0 and the :c:type:`request.fd<gpioh 121 On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the
122 file descriptor for the request. 122 file descriptor for the request.
123 123
124 On error -1 and the ``errno`` variable is set 124 On error -1 and the ``errno`` variable is set appropriately.
125 Common error codes are described in error-code 125 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.