1 .. SPDX-License-Identifier: GPL-2.0 1 .. SPDX-License-Identifier: GPL-2.0
2 2
3 .. _GPIO_V2_GET_LINE_IOCTL: 3 .. _GPIO_V2_GET_LINE_IOCTL:
4 4
5 ********************** 5 **********************
6 GPIO_V2_GET_LINE_IOCTL 6 GPIO_V2_GET_LINE_IOCTL
7 ********************** 7 **********************
8 8
9 Name 9 Name
10 ==== 10 ====
11 11
12 GPIO_V2_GET_LINE_IOCTL - Request a line or lin 12 GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel.
13 13
14 Synopsis 14 Synopsis
15 ======== 15 ========
16 16
17 .. c:macro:: GPIO_V2_GET_LINE_IOCTL 17 .. c:macro:: GPIO_V2_GET_LINE_IOCTL
18 18
19 ``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCT 19 ``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)``
20 20
21 Arguments 21 Arguments
22 ========= 22 =========
23 23
24 ``chip_fd`` 24 ``chip_fd``
25 The file descriptor of the GPIO character 25 The file descriptor of the GPIO character device returned by `open()`.
26 26
27 ``request`` 27 ``request``
28 The :c:type:`line_request<gpio_v2_line_req 28 The :c:type:`line_request<gpio_v2_line_request>` specifying the lines
29 to request and their configuration. 29 to request and their configuration.
30 30
31 Description 31 Description
32 =========== 32 ===========
33 33
34 On success, the requesting process is granted 34 On success, the requesting process is granted exclusive access to the line
35 value, write access to the line configuration, 35 value, write access to the line configuration, and may receive events when
36 edges are detected on the line, all of which a 36 edges are detected on the line, all of which are described in more detail in
37 :ref:`gpio-v2-line-request`. 37 :ref:`gpio-v2-line-request`.
38 38
39 A number of lines may be requested in the one 39 A number of lines may be requested in the one line request, and request
40 operations are performed on the requested line 40 operations are performed on the requested lines by the kernel as atomically
41 as possible. e.g. gpio-v2-line-get-values-ioct 41 as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
42 requested lines at once. 42 requested lines at once.
43 43
44 The state of a line, including the value of ou 44 The state of a line, including the value of output lines, is guaranteed to
45 remain as requested until the returned file de 45 remain as requested until the returned file descriptor is closed. Once the
46 file descriptor is closed, the state of the li 46 file descriptor is closed, the state of the line becomes uncontrolled from
47 the userspace perspective, and may revert to i 47 the userspace perspective, and may revert to its default state.
48 48
49 Requesting a line already in use is an error ( 49 Requesting a line already in use is an error (**EBUSY**).
50 50
51 Closing the ``chip_fd`` has no effect on exist 51 Closing the ``chip_fd`` has no effect on existing line requests.
52 52
53 .. _gpio-v2-get-line-config-rules: 53 .. _gpio-v2-get-line-config-rules:
54 54
55 Configuration Rules 55 Configuration Rules
56 ------------------- 56 -------------------
57 57
58 For any given requested line, the following co 58 For any given requested line, the following configuration rules apply:
59 59
60 The direction flags, ``GPIO_V2_LINE_FLAG_INPUT 60 The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and
61 ``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combin 61 ``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then
62 the only other flag that may be set is ``GPIO_ 62 the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW``
63 and the line is requested "as-is" to allow rea 63 and the line is requested "as-is" to allow reading of the line value
64 without altering the electrical configuration. 64 without altering the electrical configuration.
65 65
66 The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx` 66 The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the
67 ``GPIO_V2_LINE_FLAG_OUTPUT`` to be set. 67 ``GPIO_V2_LINE_FLAG_OUTPUT`` to be set.
68 Only one drive flag may be set. 68 Only one drive flag may be set.
69 If none are set then the line is assumed push- 69 If none are set then the line is assumed push-pull.
70 70
71 Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_x 71 Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it
72 requires a direction flag to also be set. 72 requires a direction flag to also be set.
73 If no bias flags are set then the bias configu 73 If no bias flags are set then the bias configuration is not changed.
74 74
75 The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx`` 75 The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require
76 ``GPIO_V2_LINE_FLAG_INPUT`` to be set and may 76 ``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising
77 and falling edges. Requesting edge detection 77 and falling edges. Requesting edge detection from a line that does not support
78 it is an error (**ENXIO**). 78 it is an error (**ENXIO**).
79 79
80 Only one event clock flag, ``GPIO_V2_LINE_FLAG 80 Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set.
81 If none are set then the event clock defaults 81 If none are set then the event clock defaults to ``CLOCK_MONOTONIC``.
82 The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag 82 The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware
83 and a kernel with ``CONFIG_HTE`` set. Request 83 and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that
84 doesn't support it is an error (**EOPNOTSUPP** !! 84 doesn't support it is an error (**EOPNOTSUP**).
85 85
86 The :c:type:`debounce_period_us<gpio_v2_line_a 86 The :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only
87 be applied to lines with ``GPIO_V2_LINE_FLAG_I 87 be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce
88 applies to both the values returned by gpio-v2 88 applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and
89 the edges returned by gpio-v2-line-event-read. 89 the edges returned by gpio-v2-line-event-read.rst. If not
90 supported directly by hardware, debouncing is 90 supported directly by hardware, debouncing is emulated in software by the
91 kernel. Requesting debounce on a line that su 91 kernel. Requesting debounce on a line that supports neither debounce in
92 hardware nor interrupts, as required for softw 92 hardware nor interrupts, as required for software emulation, is an error
93 (**ENXIO**). 93 (**ENXIO**).
94 94
95 Requesting an invalid configuration is an erro 95 Requesting an invalid configuration is an error (**EINVAL**).
96 96
97 .. _gpio-v2-get-line-config-support: 97 .. _gpio-v2-get-line-config-support:
98 98
99 Configuration Support 99 Configuration Support
100 --------------------- 100 ---------------------
101 101
102 Where the requested configuration is not direc 102 Where the requested configuration is not directly supported by the underlying
103 hardware and driver, the kernel applies one of 103 hardware and driver, the kernel applies one of these approaches:
104 104
105 - reject the request 105 - reject the request
106 - emulate the feature in software 106 - emulate the feature in software
107 - treat the feature as best effort 107 - treat the feature as best effort
108 108
109 The approach applied depends on whether the fe 109 The approach applied depends on whether the feature can reasonably be emulated
110 in software, and the impact on the hardware an 110 in software, and the impact on the hardware and userspace if the feature is not
111 supported. 111 supported.
112 The approach applied for each feature is as fo 112 The approach applied for each feature is as follows:
113 113
114 ============== =========== 114 ============== ===========
115 Feature Approach 115 Feature Approach
116 ============== =========== 116 ============== ===========
117 Bias best effort 117 Bias best effort
118 Debounce emulate 118 Debounce emulate
119 Direction reject 119 Direction reject
120 Drive emulate 120 Drive emulate
121 Edge Detection reject 121 Edge Detection reject
122 ============== =========== 122 ============== ===========
123 123
124 Bias is treated as best effort to allow usersp 124 Bias is treated as best effort to allow userspace to apply the same
125 configuration for platforms that support inter 125 configuration for platforms that support internal bias as those that require
126 external bias. 126 external bias.
127 Worst case the line floats rather than being b 127 Worst case the line floats rather than being biased as expected.
128 128
129 Debounce is emulated by applying a filter to h 129 Debounce is emulated by applying a filter to hardware interrupts on the line.
130 An edge event is generated after an edge is de 130 An edge event is generated after an edge is detected and the line remains
131 stable for the debounce period. 131 stable for the debounce period.
132 The event timestamp corresponds to the end of 132 The event timestamp corresponds to the end of the debounce period.
133 133
134 Drive is emulated by switching the line to an 134 Drive is emulated by switching the line to an input when the line should not
135 be actively driven. 135 be actively driven.
136 136
137 Edge detection requires interrupt support, and 137 Edge detection requires interrupt support, and is rejected if that is not
138 supported. Emulation by polling can still be p 138 supported. Emulation by polling can still be performed from userspace.
139 139
140 In all cases, the configuration reported by gp 140 In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst
141 is the requested configuration, not the result 141 is the requested configuration, not the resulting hardware configuration.
142 Userspace cannot determine if a feature is sup 142 Userspace cannot determine if a feature is supported in hardware, is
143 emulated, or is best effort. 143 emulated, or is best effort.
144 144
145 Return Value 145 Return Value
146 ============ 146 ============
147 147
148 On success 0 and the :c:type:`request.fd<gpio_ 148 On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the
149 file descriptor for the request. 149 file descriptor for the request.
150 150
151 On error -1 and the ``errno`` variable is set 151 On error -1 and the ``errno`` variable is set appropriately.
152 Common error codes are described in error-code 152 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.