tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation: gpio: describe uAPI behaviour for unsupported config
The existing uAPI documentation does not adequately describe how the kernel
handles the case where the underlying hardware or driver does not support
the requested configuration.
Add a Configuration Support section describing that behaviour to both the
v1 and v2 documentation, and better document the errors returned where the
requested configuration cannot be supported.
Signed-off-by: Kent Gibson <warthog618@gmail.com>
Signed-off-by: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>
authored by
Kent Gibson
and committed by
Bartosz Golaszewski
42969726
34737659
+106
-7
+2
-1
Documentation/userspace-api/gpio/error-codes.rst
+2
-1
Documentation/userspace-api/gpio/error-codes.rst
+6
Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
+6
Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
···
48
48
49
49
Requesting a line already in use is an error (**EBUSY**).
50
50
51
+
Requesting edge detection on a line that does not support interrupts is an
52
+
error (**ENXIO**).
53
+
54
+
As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the
55
+
bias configuration is best effort.
56
+
51
57
Closing the ``chip_fd`` has no effect on existing line events.
52
58
53
59
Configuration Rules
+39
Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
+39
Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
···
76
76
77
77
Requesting an invalid configuration is an error (**EINVAL**).
78
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
+
79
118
Return Value
80
119
============
81
120
+3
-2
Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst
+3
-2
Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst
···
41
41
42
42
The configuration applies to all requested lines.
43
43
44
-
The same :ref:`gpio-get-linehandle-config-rules` that apply when requesting the
44
+
The same :ref:`gpio-get-linehandle-config-rules` and
45
+
:ref:`gpio-get-linehandle-config-support` that apply when requesting the
45
46
lines also apply when updating the line configuration.
46
47
47
48
The motivating use case for this command is changing direction of
48
49
bi-directional lines between input and output, but it may be used more
49
-
generally move lines seamlessly from one configuration state to another.
50
+
generally to move lines seamlessly from one configuration state to another.
50
51
51
52
To only change the value of output lines, use
52
53
gpio-handle-set-line-values-ioctl.rst.
+54
-3
Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
+54
-3
Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
···
74
74
75
75
The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require
76
76
``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising
77
-
and falling edges.
77
+
and falling edges. Requesting edge detection from a line that does not support
78
+
it is an error (**ENXIO**).
78
79
79
80
Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set.
80
81
If none are set then the event clock defaults to ``CLOCK_MONOTONIC``.
···
87
86
be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce
88
87
applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and
89
88
the edges returned by gpio-v2-line-event-read.rst. If not
90
-
supported directly by hardware, the debouncing is performed in software by the
91
-
kernel.
89
+
supported directly by hardware, debouncing is emulated in software by the
90
+
kernel. Requesting debounce on a line that supports neither debounce in
91
+
hardware nor interrupts, as required for software emulation, is an error
92
+
(**ENXIO**).
92
93
93
94
Requesting an invalid configuration is an error (**EINVAL**).
95
+
96
+
.. _gpio-v2-get-line-config-support:
97
+
98
+
Configuration Support
99
+
---------------------
100
+
101
+
Where the requested configuration is not directly supported by the underlying
102
+
hardware and driver, the kernel applies one of these approaches:
103
+
104
+
- reject the request
105
+
- emulate the feature in software
106
+
- treat the feature as best effort
107
+
108
+
The approach applied depends on whether the feature can reasonably be emulated
109
+
in software, and the impact on the hardware and userspace if the feature is not
110
+
supported.
111
+
The approach applied for each feature is as follows:
112
+
113
+
============== ===========
114
+
Feature Approach
115
+
============== ===========
116
+
Bias best effort
117
+
Debounce emulate
118
+
Direction reject
119
+
Drive emulate
120
+
Edge Detection reject
121
+
============== ===========
122
+
123
+
Bias is treated as best effort to allow userspace to apply the same
124
+
configuration for platforms that support internal bias as those that require
125
+
external bias.
126
+
Worst case the line floats rather than being biased as expected.
127
+
128
+
Debounce is emulated by applying a filter to hardware interrupts on the line.
129
+
An edge event is generated after an edge is detected and the line remains
130
+
stable for the debounce period.
131
+
The event timestamp corresponds to the end of the debounce period.
132
+
133
+
Drive is emulated by switching the line to an input when the line should not
134
+
be actively driven.
135
+
136
+
Edge detection requires interrupt support, and is rejected if that is not
137
+
supported. Emulation by polling can still be performed from userspace.
138
+
139
+
In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst
140
+
is the requested configuration, not the resulting hardware configuration.
141
+
Userspace cannot determine if a feature is supported in hardware, is
142
+
emulated, or is best effort.
94
143
95
144
Return Value
96
145
============
+2
-1
Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
+2
-1
Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
···
37
37
38
38
The new configuration must specify the configuration of all requested lines.
39
39
40
-
The same :ref:`gpio-v2-get-line-config-rules` that apply when requesting the lines
40
+
The same :ref:`gpio-v2-get-line-config-rules` and
41
+
:ref:`gpio-v2-get-line-config-support` that apply when requesting the lines
41
42
also apply when updating the line configuration.
42
43
43
44
The motivating use case for this command is changing direction of