Commit 42969726 authored by Kent Gibson's avatar Kent Gibson Committed by Bartosz Golaszewski
Browse files

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: default avatarKent Gibson <warthog618@gmail.com>
Signed-off-by: default avatarBartosz Golaszewski <bartosz.golaszewski@linaro.org>
parent 34737659

Documentation/userspace-api/gpio/error-codes.rst

+2 −1
Original line number Diff line number Diff line
@@ -65,7 +65,8 @@ GPIO Error Codes 


    -  - ``ENXIO``



       -  No device corresponding to this device special file exists.

       -  Typically returned when a feature requiring interrupt support was

          requested, but the line does not support interrupts.



.. note::

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

+6 −0
Original line number Diff line number Diff line
@@ -48,6 +48,12 @@ to its default state. 


Requesting a line already in use is an error (**EBUSY**).



Requesting edge detection on a line that does not support interrupts is an

error (**ENXIO**).



As with the :ref:`line handle<gpio-get-linehandle-config-support>`, the

bias configuration is best effort.



Closing the ``chip_fd`` has no effect on existing line events.



Configuration Rules

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

+39 −0
Original line number Diff line number Diff line
@@ -76,6 +76,45 @@ If no bias flags are set then the bias configuration is not changed. 


Requesting an invalid configuration is an error (**EINVAL**).





.. _gpio-get-linehandle-config-support:



Configuration Support

---------------------



Where the requested configuration is not directly supported by the underlying

hardware and driver, the kernel applies one of these approaches:



 - reject the request

 - emulate the feature in software

 - treat the feature as best effort



The approach applied depends on whether the feature can reasonably be emulated

in software, and the impact on the hardware and userspace if the feature is not

supported.

The approach applied for each feature is as follows:



==============   ===========

Feature          Approach

==============   ===========

Bias             best effort

Direction        reject

Drive            emulate

==============   ===========



Bias is treated as best effort to allow userspace to apply the same

configuration for platforms that support internal bias as those that require

external bias.

Worst case the line floats rather than being biased as expected.



Drive is emulated by switching the line to an input when the line should not

be driven.



In all cases, the configuration reported by gpio-get-lineinfo-ioctl.rst

is the requested configuration, not the resulting hardware configuration.

Userspace cannot determine if a feature is supported in hardware, is

emulated, or is best effort.



Return Value

============

Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst

+3 −2
Original line number Diff line number Diff line
@@ -41,12 +41,13 @@ line or introducing potential glitches. 


The configuration applies to all requested lines.



The same :ref:`gpio-get-linehandle-config-rules` that apply when requesting the

The same :ref:`gpio-get-linehandle-config-rules` and

:ref:`gpio-get-linehandle-config-support` that apply when requesting the

lines also apply when updating the line configuration.



The motivating use case for this command is changing direction of

bi-directional lines between input and output, but it may be used more

generally move lines seamlessly from one configuration state to another.

generally to move lines seamlessly from one configuration state to another.



To only change the value of output lines, use

gpio-handle-set-line-values-ioctl.rst.

Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst

+54 −3
Original line number Diff line number Diff line
@@ -74,7 +74,8 @@ If no bias flags are set then the bias configuration is not changed. 


The edge flags, ``GPIO_V2_LINE_FLAG_EDGE_xxx``, require

``GPIO_V2_LINE_FLAG_INPUT`` to be set and may be combined to detect both rising

and falling edges.

and falling edges.  Requesting edge detection from a line that does not support

it is an error (**ENXIO**).



Only one event clock flag, ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_xxx``, may be set.

If none are set then the event clock defaults to ``CLOCK_MONOTONIC``.
@@ -86,11 +87,61 @@ The :c:type:`debounce_period_us<gpio_v2_line_attribute>` attribute may only 
be applied to lines with ``GPIO_V2_LINE_FLAG_INPUT`` set. When set, debounce

applies to both the values returned by gpio-v2-line-get-values-ioctl.rst and

the edges returned by gpio-v2-line-event-read.rst.  If not

supported directly by hardware, the debouncing is performed in software by the

kernel.

supported directly by hardware, debouncing is emulated in software by the

kernel.  Requesting debounce on a line that supports neither debounce in

hardware nor interrupts, as required for software emulation, is an error

(**ENXIO**).



Requesting an invalid configuration is an error (**EINVAL**).



.. _gpio-v2-get-line-config-support:



Configuration Support

---------------------



Where the requested configuration is not directly supported by the underlying

hardware and driver, the kernel applies one of these approaches:



 - reject the request

 - emulate the feature in software

 - treat the feature as best effort



The approach applied depends on whether the feature can reasonably be emulated

in software, and the impact on the hardware and userspace if the feature is not

supported.

The approach applied for each feature is as follows:



==============   ===========

Feature          Approach

==============   ===========

Bias             best effort

Debounce         emulate

Direction        reject

Drive            emulate

Edge Detection   reject

==============   ===========



Bias is treated as best effort to allow userspace to apply the same

configuration for platforms that support internal bias as those that require

external bias.

Worst case the line floats rather than being biased as expected.



Debounce is emulated by applying a filter to hardware interrupts on the line.

An edge event is generated after an edge is detected and the line remains

stable for the debounce period.

The event timestamp corresponds to the end of the debounce period.



Drive is emulated by switching the line to an input when the line should not

be actively driven.



Edge detection requires interrupt support, and is rejected if that is not

supported. Emulation by polling can still be performed from userspace.



In all cases, the configuration reported by gpio-v2-get-lineinfo-ioctl.rst

is the requested configuration, not the resulting hardware configuration.

Userspace cannot determine if a feature is supported in hardware, is

emulated, or is best effort.



Return Value

============