My new year's resolution was to improve the documentation of the
character device API and gpio in general, so here we are.
Wrt the formatting and file breakdown, I've taken inspiration from
the userspace-api/media documentation.
Patch 1 adds documentation for the current chardev uAPI. I've added
it to the userspace-api book, as that is the most obvious place a
reader would look for it, but have also provided links from the
admin-guide book where the gpio docs currently reside.
I realise MAINTAINERS should be updated with
Documentation/userspace-api/gpio/, but the split out of GPIO UAPI
hasn't made it into gpio/for-next yet, so I was unsure of how to
handle that.
Patch 2 relocates the sysfs API doc to stress its deprecation by
moving it to a new deprecated section, again in userspace-api but
with a similar section in the admin-guide. The deprecated section
also provides a placeholder for subsequent changes.
Patch 3 updates the sysfs API doc to reference the chardev
documentation rather than gpio.h.
Patch 4 adds documentation for the deprecated v1 version of the
chardev uAPI. It is deprecated, but still useful to have, if
nothing else to help identify the differences between v1 and v2.
Patch 5 capitalizes the title of the admin-guide/gpio to match
the other subsystems and the userspace-api book.
Patch 6 adds a deprecation note to the gpio-mockup, as it is
obsoleted by the gpio-sim.
Patch 7 moves the gpio-mockup doc into the deprecated section.
I've got some minor updates for the kernel doc in gpio.h as well,
but they make sense on their own so I'll send those separately
keep the cross-posting to a minimum.
I realise the only thing less exciting than writing documentation
is reviewing it, so my apologies and thanks in advance if you
have the fortitude to attempt such a scintillating endeavour.
Cheers,
Kent.
Kent Gibson (7):
Documentation: gpio: add chardev userspace API documentation
Documentation: gpio: move sysfs into a deprecated section
Documentation: gpio: update sysfs documentation to reference new
chardev doc
Documentation: gpio: add chardev v1 userspace API documentation
Documentation: gpio: capitalize GPIO in index title
Documentation: gpio: document gpio-mockup as obsoleted by gpio-sim
Documentation: gpio: move gpio-mockup into deprecated section
Documentation/admin-guide/gpio/deprecated.rst | 13 ++
.../admin-guide/gpio/gpio-mockup.rst | 8 ++
Documentation/admin-guide/gpio/index.rst | 6 +-
Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++
.../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++
.../userspace-api/gpio/deprecated.rst | 11 ++
.../userspace-api/gpio/error-codes.rst | 78 +++++++++++
.../gpio/gpio-get-chipinfo-ioctl.rst | 41 ++++++
.../gpio/gpio-get-lineevent-ioctl.rst | 76 +++++++++++
.../gpio/gpio-get-linehandle-ioctl.rst | 84 ++++++++++++
.../gpio/gpio-get-lineinfo-ioctl.rst | 54 ++++++++
.../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 47 +++++++
.../gpio/gpio-get-lineinfo-watch-ioctl.rst | 72 ++++++++++
.../gpio-handle-get-line-values-ioctl.rst | 56 ++++++++
.../gpio/gpio-handle-set-config-ioctl.rst | 60 ++++++++
.../gpio-handle-set-line-values-ioctl.rst | 48 +++++++
.../gpio/gpio-lineevent-data-read.rst | 84 ++++++++++++
.../gpio/gpio-lineinfo-changed-read.rst | 85 ++++++++++++
.../gpio/gpio-v2-get-line-ioctl.rst | 99 ++++++++++++++
.../gpio/gpio-v2-get-lineinfo-ioctl.rst | 50 +++++++
.../gpio/gpio-v2-get-lineinfo-watch-ioctl.rst | 67 +++++++++
.../gpio/gpio-v2-line-event-read.rst | 83 +++++++++++
.../gpio/gpio-v2-line-get-values-ioctl.rst | 51 +++++++
.../gpio/gpio-v2-line-set-config-ioctl.rst | 57 ++++++++
.../gpio/gpio-v2-line-set-values-ioctl.rst | 47 +++++++
.../gpio/gpio-v2-lineinfo-changed-read.rst | 81 +++++++++++
Documentation/userspace-api/gpio/index.rst | 18 +++
.../gpio/sysfs.rst | 10 +-
Documentation/userspace-api/index.rst | 1 +
29 files changed, 1621 insertions(+), 9 deletions(-)
create mode 100644 Documentation/admin-guide/gpio/deprecated.rst
create mode 100644 Documentation/userspace-api/gpio/chardev.rst
create mode 100644 Documentation/userspace-api/gpio/chardev_v1.rst
create mode 100644 Documentation/userspace-api/gpio/deprecated.rst
create mode 100644 Documentation/userspace-api/gpio/error-codes.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
create mode 100644 Documentation/userspace-api/gpio/index.rst
rename Documentation/{admin-guide => userspace-api}/gpio/sysfs.rst (94%)
--
2.39.2
Add documentation for v1 of the GPIO character device userspace API
to the deprecated section of both the admin-guide and userspace-api
books.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/admin-guide/gpio/deprecated.rst | 1 +
.../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++
.../userspace-api/gpio/deprecated.rst | 1 +
.../gpio/gpio-get-lineevent-ioctl.rst | 76 +++++++++++
.../gpio/gpio-get-linehandle-ioctl.rst | 84 ++++++++++++
.../gpio/gpio-get-lineinfo-ioctl.rst | 54 ++++++++
.../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 2 +-
.../gpio/gpio-get-lineinfo-watch-ioctl.rst | 72 ++++++++++
.../gpio-handle-get-line-values-ioctl.rst | 56 ++++++++
.../gpio/gpio-handle-set-config-ioctl.rst | 60 ++++++++
.../gpio-handle-set-line-values-ioctl.rst | 48 +++++++
.../gpio/gpio-lineevent-data-read.rst | 84 ++++++++++++
.../gpio/gpio-lineinfo-changed-read.rst | 85 ++++++++++++
13 files changed, 751 insertions(+), 1 deletion(-)
create mode 100644 Documentation/userspace-api/gpio/chardev_v1.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst
diff --git a/Documentation/admin-guide/gpio/deprecated.rst b/Documentation/admin-guide/gpio/deprecated.rst
index 33f701294732..683d7d23e62a 100644
--- a/Documentation/admin-guide/gpio/deprecated.rst
+++ b/Documentation/admin-guide/gpio/deprecated.rst
@@ -7,5 +7,6 @@ Deprecated GPIO APIs
.. toctree::
:maxdepth: 1
+ Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1>
Sysfs Interface <../../userspace-api/gpio/sysfs>
diff --git a/Documentation/userspace-api/gpio/chardev_v1.rst b/Documentation/userspace-api/gpio/chardev_v1.rst
new file mode 100644
index 000000000000..d5b01d919383
--- /dev/null
+++ b/Documentation/userspace-api/gpio/chardev_v1.rst
@@ -0,0 +1,129 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+========================================
+GPIO Character Device Userspace API (v1)
+========================================
+
+.. warning::
+ This API is obsoleted by chardev.rst (v2).
+
+ New developments should use the v2 API and existing developments are
+ encouraged to migrate as soon as possible. The v2 API is a functional
+ superset of the v1 API so any v1 call can be directly translated to a
+ v2 equivalent.
+
+ This interface will continue to be maintained for the migration period,
+ but new features will only be added to the new API.
+
+The API is based around three major objects, the :ref:`gpio-v1-chip`, the
+:ref:`gpio-v1-line-handle`, and the :ref:`gpio-v1-line-event`.
+
+Where "line event" is used in this document it refers to the request that can
+monitor a line for edge events, not the edge events themselves.
+
+.. _gpio-v1-chip:
+
+Chip
+====
+
+The Chip represents a single GPIO chip and is exposed to userspace using device
+files of the form ``/dev/gpiochipX``.
+
+Each chip supports a number of GPIO lines,
+:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
+``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
+
+Lines are requested from the chip using either gpio-get-linehandle-ioctl.rst
+and the resulting line handle is used to access the GPIO chip's lines, or
+gpio-get-lineevent-ioctl.rst and the resulting line event is used to monitor
+a GPIO line for edge events.
+
+Within this documentation, the file descriptor returned by calling `open()`
+on the GPIO device file is referred to as ``chip_fd``.
+
+Operations
+----------
+
+The following operations may be performed on the chip:
+
+.. toctree::
+ :titlesonly:
+
+ Get Line Handle <gpio-get-linehandle-ioctl>
+ Get Line Event <gpio-get-lineevent-ioctl>
+ Get Chip Info <gpio-get-chipinfo-ioctl>
+ Get Line Info <gpio-get-lineinfo-ioctl>
+ Watch Line Info <gpio-get-lineinfo-watch-ioctl>
+ Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
+ Read Line Info Changed Events <gpio-lineinfo-changed-read>
+
+.. _gpio-v1-line-handle:
+
+Line Handle
+===========
+
+Line handles are created by gpio-get-linehandle-ioctl.rst and provide
+access to a set of requested lines. The line handle is exposed to userspace
+via the anonymous file descriptor returned in
+:c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.
+
+Within this documentation, the line handle file descriptor is referred to
+as ``handle_fd``.
+
+Operations
+----------
+
+The following operations may be performed on the line handle:
+
+.. toctree::
+ :titlesonly:
+
+ Get Line Values <gpio-handle-get-line-values-ioctl>
+ Set Line Values <gpio-handle-set-line-values-ioctl>
+ Reconfigure Lines <gpio-handle-set-config-ioctl>
+
+.. _gpio-v1-line-event:
+
+Line Event
+==========
+
+Line events are created by gpio-get-lineevent-ioctl.rst and provide
+access to a requested line. The line event is exposed to userspace
+via the anonymous file descriptor returned in
+:c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.
+
+Within this documentation, the line event file descriptor is referred to
+as ``event_fd``.
+
+Operations
+----------
+
+The following operations may be performed on the line event:
+
+.. toctree::
+ :titlesonly:
+
+ Get Line Value <gpio-handle-get-line-values-ioctl>
+ Read Line Edge Events <gpio-lineevent-data-read>
+
+Types
+=====
+
+This section contains the structs that are referenced by the ABI v1.
+
+The :c:type:`struct gpiochip_info<gpiochip_info>` is common to ABI v1 and v2.
+
+.. kernel-doc:: include/uapi/linux/gpio.h
+ :identifiers:
+ gpioevent_data
+ gpioevent_request
+ gpiohandle_config
+ gpiohandle_data
+ gpiohandle_request
+ gpioline_info
+ gpioline_info_changed
+
+.. toctree::
+ :hidden:
+
+ error-codes
diff --git a/Documentation/userspace-api/gpio/deprecated.rst b/Documentation/userspace-api/gpio/deprecated.rst
index 4cc7c79d7c23..09ed40e6c7fa 100644
--- a/Documentation/userspace-api/gpio/deprecated.rst
+++ b/Documentation/userspace-api/gpio/deprecated.rst
@@ -7,4 +7,5 @@ Deprecated GPIO Userspace APIs
.. toctree::
:maxdepth: 1
+ Character Device Userspace API (v1) <chardev_v1>
Sysfs Interface <sysfs>
diff --git a/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
new file mode 100644
index 000000000000..fe3bc37f1ab0
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-get-lineevent-ioctl.rst
@@ -0,0 +1,76 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_GET_LINEEVENT_IOCTL:
+
+************************
+GPIO_GET_LINEEVENT_IOCTL
+************************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-get-line-ioctl.rst.
+
+Name
+====
+
+GPIO_GET_LINEEVENT_IOCTL - Request a line with edge detection from the kernel.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_GET_LINEEVENT_IOCTL
+
+``int ioctl(int chip_fd, GPIO_GET_LINEEVENT_IOCTL, struct gpioevent_request *request)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``request``
+ The :c:type:`event_request<gpioevent_request>` specifying the line
+ to request and its configuration.
+
+Description
+===========
+
+Request a line with edge detection from the kernel.
+
+On success, the requesting process is granted exclusive access to the line
+value and may receive events when edges are detected on the line, as
+described in gpio-lineevent-data-read.rst.
+
+The state of a line is guaranteed to remain as requested until the returned
+file descriptor is closed. Once the file descriptor is closed, the state of
+the line becomes uncontrolled from the userspace perspective, and may revert
+to its default state.
+
+Closing the ``chip_fd`` has no effect on existing line events.
+
+Configuration Rules
+-------------------
+
+The following configuration rules apply:
+
+The line event is requested as an input, so no flags specific to output lines,
+``GPIOHANDLE_REQUEST_OUTPUT``, ``GPIOHANDLE_REQUEST_OPEN_DRAIN``, or
+``GPIOHANDLE_REQUEST_OPEN_SOURCE``, may be set.
+
+Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set.
+If no bias flags are set then the bias configuration is not changed.
+
+The edge flags, ``GPIOEVENT_REQUEST_RISING_EDGE`` and
+``GPIOEVENT_REQUEST_FALLING_EDGE``, may be combined to detect both rising
+and falling edges.
+
+Requesting an invalid configuration is an error (**EINVAL**).
+
+Return Value
+============
+
+On success 0 and the :c:type:`request.fd<gpioevent_request>` contains the file
+descriptor for the request.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
new file mode 100644
index 000000000000..71abea9f7e4b
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-get-linehandle-ioctl.rst
@@ -0,0 +1,84 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_GET_LINEHANDLE_IOCTL:
+
+*************************
+GPIO_GET_LINEHANDLE_IOCTL
+*************************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-get-line-ioctl.rst.
+
+Name
+====
+
+GPIO_GET_LINEHANDLE_IOCTL - Request a line or lines from the kernel.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_GET_LINEHANDLE_IOCTL
+
+``int ioctl(int chip_fd, GPIO_GET_LINEHANDLE_IOCTL, struct gpiohandle_request *request)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``request``
+ The :c:type:`handle_request<gpiohandle_request>` specifying the lines to
+ request and their configuration.
+
+Description
+===========
+
+Request a line or lines from the kernel.
+
+While multiple lines may be requested, the same configuration applies to all
+lines in the request.
+
+On success, the requesting process is granted exclusive access to the line
+value and write access to the line configuration.
+
+The state of a line, including the value of output lines, is guaranteed to
+remain as requested until the returned file descriptor is closed. Once the
+file descriptor is closed, the state of the line becomes uncontrolled from
+the userspace perspective, and may revert to its default state.
+
+Closing the ``chip_fd`` has no effect on existing line handles.
+
+.. _gpio-get-linehandle-config-rules:
+
+Configuration Rules
+-------------------
+
+The following configuration rules apply:
+
+The direction flags, ``GPIOHANDLE_REQUEST_INPUT`` and
+``GPIOHANDLE_REQUEST_OUTPUT``, cannot be combined. If neither are set then the
+only other flag that may be set is ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` and the
+line is requested "as-is" to allow reading of the line value without altering
+the electrical configuration.
+
+The drive flags, ``GPIOHANDLE_REQUEST_OPEN_xxx``, require the
+``GPIOHANDLE_REQUEST_OUTPUT`` to be set.
+Only one drive flag may be set.
+If none are set then the line is assumed push-pull.
+
+Only one bias flag, ``GPIOHANDLE_REQUEST_BIAS_xxx``, may be set, and
+it requires a direction flag to also be set.
+If no bias flags are set then the bias configuration is not changed.
+
+Requesting an invalid configuration is an error (**EINVAL**).
+
+Return Value
+============
+
+On success 0 and the :c:type:`request.fd<gpiohandle_request>` contains the
+file descriptor for the request.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst
new file mode 100644
index 000000000000..c895b8910b25
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-ioctl.rst
@@ -0,0 +1,54 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_GET_LINEINFO_IOCTL:
+
+***********************
+GPIO_GET_LINEINFO_IOCTL
+***********************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-get-lineinfo-ioctl.rst.
+
+Name
+====
+
+GPIO_GET_LINEINFO_IOCTL - Get the publicly available information for a line.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_GET_LINEINFO_IOCTL
+
+``int ioctl(int chip_fd, GPIO_GET_LINEINFO_IOCTL, struct gpioline_info *info)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``info``
+ The :c:type:`line_info<gpioline_info>` to be populated, with the
+ ``offset`` field set to indicate the line to be collected.
+
+Description
+===========
+
+Get the publicly available information for a line.
+
+This information is available independent of whether the line is in use.
+
+.. note::
+ The line info does not include the line value.
+
+ The line must be requested using gpio-get-linehandle-ioctl.rst or
+ gpio-get-lineevent-ioctl.rst to access its value.
+
+Return Value
+============
+
+On success 0 and ``info`` is populated with the chip info.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
index ba6f9d00a40b..13a833343ca4 100644
--- a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
+++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
@@ -33,7 +33,7 @@ Description
Remove the line from the list of lines being watched on this ``chip_fd``.
-This is the opposite of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and
+This is the reverse of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and
gpio-get-lineinfo-watch-ioctl.rst (v1).
Unwatching a line that is not watched is an error (**EBUSY**).
diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst
new file mode 100644
index 000000000000..1fda1d6900e3
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-watch-ioctl.rst
@@ -0,0 +1,72 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_GET_LINEINFO_WATCH_IOCTL:
+
+*****************************
+GPIO_GET_LINEINFO_WATCH_IOCTL
+*****************************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-get-lineinfo-watch-ioctl.rst.
+
+Name
+====
+
+GPIO_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its
+request state and configuration information.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_GET_LINEINFO_WATCH_IOCTL
+
+``int ioctl(int chip_fd, GPIO_GET_LINEINFO_WATCH_IOCTL, struct gpioline_info *info)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``info``
+ The :c:type:`line_info<gpioline_info>` struct to be populated, with
+ the ``offset`` set to indicate the line to watch
+
+Description
+===========
+
+Enable watching a line for changes to its request state and configuration
+information. Changes to line info include a line being requested, released
+or reconfigured.
+
+.. note::
+ Watching line info is not generally required, and would typically only be
+ used by a system monitoring component.
+
+ The line info does NOT include the line value.
+
+ The line must be requested using gpio-get-linehandle-ioctl.rst or
+ gpio-get-lineevent-ioctl.rst to access its value, and the line event can
+ monitor a line for events using gpio-lineevent-data-read.rst.
+
+By default all lines are unwatched when the GPIO chip is opened.
+
+Multiple lines may be watched simultaneously by adding a watch for each.
+
+Once a watch is set, any changes to line info will generate events which can be
+read from the ``chip_fd`` as described in
+gpio-lineinfo-changed-read.rst.
+
+Adding a watch to a line that is already watched is an error (**EBUSY**).
+
+Watches are specific to the ``chip_fd`` and are independent of watches
+on the same GPIO chip opened with a separate call to `open()`.
+
+Return Value
+============
+
+On success 0 and ``info`` is populated with the current line info.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst
new file mode 100644
index 000000000000..25263b8f0588
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst
@@ -0,0 +1,56 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIOHANDLE_GET_LINE_VALUES_IOCTL:
+
+********************************
+GPIOHANDLE_GET_LINE_VALUES_IOCTL
+********************************
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-line-get-values-ioctl.rst.
+
+Name
+====
+
+GPIOHANDLE_GET_LINE_VALUES_IOCTL - Get the values of all requested lines.
+
+Synopsis
+========
+
+.. c:macro:: GPIOHANDLE_GET_LINE_VALUES_IOCTL
+
+``int ioctl(int handle_fd, GPIOHANDLE_GET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)``
+
+Arguments
+=========
+
+``handle_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.
+
+``values``
+ The :c:type:`line_values<gpiohandle_data>` to be populated.
+
+Description
+===========
+
+Get the values of all requested lines.
+
+The values of both input and output lines may be read.
+
+For output lines, the value returned is driver and configuration dependent and
+may be either the output buffer (the last requested value set) or the input
+buffer (the actual level of the line), and depending on the hardware and
+configuration these may differ.
+
+This ioctl can also be used to read the line value for line events,
+substituting the ``event_fd`` for the ``handle_fd``. As there is only
+one line requested in that case, only the one value is returned in ``values``.
+
+Return Value
+============
+
+On success 0 and ``values`` populated with the values read.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst
new file mode 100644
index 000000000000..a9501b3c04f3
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-handle-set-config-ioctl.rst
@@ -0,0 +1,60 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIOHANDLE_SET_CONFIG_IOCTL:
+
+***************************
+GPIOHANDLE_SET_CONFIG_IOCTL
+***************************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-line-set-config-ioctl.rst.
+
+Name
+====
+
+GPIOHANDLE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines.
+
+Synopsis
+========
+
+.. c:macro:: GPIOHANDLE_SET_CONFIG_IOCTL
+
+``int ioctl(int handle_fd, GPIOHANDLE_SET_CONFIG_IOCTL, struct gpiohandle_config *config)``
+
+Arguments
+=========
+
+``handle_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.
+
+``config``
+ The new :c:type:`configuration<gpiohandle_config>` to apply to the
+ requested lines.
+
+Description
+===========
+
+Update the configuration of previously requested lines, without releasing the
+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
+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.
+
+To only change the value of output lines, use
+gpio-handle-set-line-values-ioctl.rst.
+
+Return Value
+============
+
+On success 0.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst
new file mode 100644
index 000000000000..0aa05e623a6c
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst
@@ -0,0 +1,48 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_HANDLE_SET_LINE_VALUES_IOCTL:
+
+*********************************
+GPIO_HANDLE_SET_LINE_VALUES_IOCTL
+*********************************
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-line-set-values-ioctl.rst.
+
+Name
+====
+
+GPIO_HANDLE_SET_LINE_VALUES_IOCTL - Set the values of all requested output lines.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_HANDLE_SET_LINE_VALUES_IOCTL
+
+``int ioctl(int handle_fd, GPIO_HANDLE_SET_LINE_VALUES_IOCTL, struct gpiohandle_data *values)``
+
+Arguments
+=========
+
+``handle_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpiohandle_request>` by gpio-get-linehandle-ioctl.rst.
+
+``values``
+ The :c:type:`line_values<gpiohandle_data>` to set.
+
+Description
+===========
+
+Set the values of all requested output lines.
+
+Only the values of output lines may be set.
+Attempting to set the value of input lines is an error (**EPERM**).
+
+Return Value
+============
+
+On success 0.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
new file mode 100644
index 000000000000..68b8d4f9f604
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
@@ -0,0 +1,84 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_LINEEVENT_DATA_READ:
+
+************************
+GPIO_LINEEVENT_DATA_READ
+************************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-line-event-read.rst.
+
+Name
+====
+
+GPIO_LINEEVENT_DATA_READ - Read edge detection events from a line event.
+
+Synopsis
+========
+
+``int read(int event_fd, void *buf, size_t count)``
+
+Arguments
+=========
+
+``event_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpioevent_request>` by gpio-get-lineevent-ioctl.rst.
+
+``buf``
+ The buffer to contain the :c:type:`events<gpioevent_data>`.
+
+``count``
+ The number of bytes available in ``buf``, which must be at
+ least the size of a :c:type:`gpioevent_data`.
+
+Description
+===========
+
+Read edge detection events for a line from a line event.
+
+Edge detection must be enabled for the input line using either
+``GPIOEVENT_REQUEST_RISING_EDGE`` or ``GPIOEVENT_REQUEST_FALLING_EDGE``, or
+both. Edge events are then generated whenever edge interrupts are detected on
+the input line.
+
+The kernel captures and timestamps edge events as close as possible to their
+occurrence and stores them in a buffer from where they can be read by
+userspace at its convenience using `read()`.
+
+The source of the clock for :c:type:`event.timestamp<gpioevent_data>` is
+``CLOCK_MONOTONIC``, except for kernels earlier than Linux 5.7 when it was
+``CLOCK_REALTIME``. There is no indication in the :c:type:`gpioevent_data`
+as to which clock source is used, it must be determined from either the kernel
+version or sanity checks on the timestamp itself.
+
+Events read from the buffer are always in the same order that they were
+detected by the kernel.
+
+The size of the kernel event buffer is fixed at 16 events.
+
+The buffer may overflow if bursts of events occur quicker than they are read
+by userspace. If an overflow occurs then the most recent event is discarded.
+Overflow cannot be detected from userspace.
+
+To minimize the number of calls required to copy events from the kernel to
+userspace, `read()` supports copying multiple events. The number of events
+copied is the lower of the number available in the kernel buffer and the
+number that will fit in the userspace buffer (``buf``).
+
+The `read()` will block if no event is available and the ``event_fd`` has not
+been set **O_NONBLOCK**.
+
+The presence of an event can be tested for by checking that the ``event_fd`` is
+readable using `poll()` or an equivalent.
+
+Return Value
+============
+
+On success the number of bytes read, which will be a multiple of the size of
+a :c:type:`gpio_lineevent_data` event.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst
new file mode 100644
index 000000000000..9bfd6f6aada8
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-lineinfo-changed-read.rst
@@ -0,0 +1,85 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_LINEINFO_CHANGED_READ:
+
+**************************
+GPIO_LINEINFO_CHANGED_READ
+**************************
+
+.. warning::
+ This ioctl is part of chardev_v1.rst and is obsoleted by
+ gpio-v2-lineinfo-changed-read.rst.
+
+Name
+====
+
+GPIO_LINEINFO_CHANGED_READ - Read line info change events for watched lines
+from the chip.
+
+Synopsis
+========
+
+``int read(int chip_fd, void *buf, size_t count)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``buf``
+ The buffer to contain the :c:type:`events<gpioline_info_changed>`.
+
+``count``
+ The number of bytes available in ``buf``, which must be at least the size
+ of a :c:type:`gpioline_info_changed` event.
+
+Description
+===========
+
+Read line info change events for watched lines from the chip.
+
+.. note::
+ Monitoring line info changes is not generally required, and would typically
+ only be performed by a system monitoring component.
+
+ These events relate to changes in a line's request state or configuration,
+ not its value. Use gpio-lineevent-data-read.rst to receive events when a
+ line changes value.
+
+A line must be watched using gpio-get-lineinfo-watch-ioctl.rst to generate
+info changed events. Subsequently, a request, release, or reconfiguration
+of the line will generate an info changed event.
+
+The kernel timestamps events when they occur and stores them in a buffer
+from where they can be read by userspace at its convenience using `read()`.
+
+The size of the kernel event buffer is fixed at 32 events per ``chip_fd``.
+
+The buffer may overflow if bursts of events occur quicker than they are read
+by userspace. If an overflow occurs then the most recent event is discarded.
+Overflow cannot be detected from userspace.
+
+Events read from the buffer are always in the same order that they were
+detected by the kernel, including when multiple lines are being monitored by
+the one ``chip_fd``.
+
+To minimize the number of calls required to copy events from the kernel to
+userspace, `read()` supports copying multiple events. The number of events
+copied is the lower of the number available in the kernel buffer and the
+number that will fit in the userspace buffer (``buf``).
+
+A `read()` will block if no event is available and the ``chip_fd`` has not
+been set **O_NONBLOCK**.
+
+The presence of an event can be tested for by checking that the ``chip_fd`` is
+readable using `poll()` or an equivalent.
+
+Return Value
+============
+
+On success the number of bytes read, which will be a multiple of the size of
+a :c:type:`gpioline_info_changed` event.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
--
2.39.2
The GPIO sysfs API is long deprecated, so highlight this even further
by moving it into a deprecated APIs section in both the admin-guide
and userspace-api books.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/admin-guide/gpio/deprecated.rst | 11 +++++++++++
Documentation/admin-guide/gpio/index.rst | 2 +-
Documentation/userspace-api/gpio/deprecated.rst | 10 ++++++++++
Documentation/userspace-api/gpio/index.rst | 1 +
.../{admin-guide => userspace-api}/gpio/sysfs.rst | 0
5 files changed, 23 insertions(+), 1 deletion(-)
create mode 100644 Documentation/admin-guide/gpio/deprecated.rst
create mode 100644 Documentation/userspace-api/gpio/deprecated.rst
rename Documentation/{admin-guide => userspace-api}/gpio/sysfs.rst (100%)
diff --git a/Documentation/admin-guide/gpio/deprecated.rst b/Documentation/admin-guide/gpio/deprecated.rst
new file mode 100644
index 000000000000..33f701294732
--- /dev/null
+++ b/Documentation/admin-guide/gpio/deprecated.rst
@@ -0,0 +1,11 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+Deprecated GPIO APIs
+====================
+
+.. toctree::
+ :maxdepth: 1
+
+ Sysfs Interface <../../userspace-api/gpio/sysfs>
+
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index b40f0a2a6822..9b0630f30d3e 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -9,9 +9,9 @@ gpio
Character Device Userspace API <../../userspace-api/gpio/chardev>
gpio-aggregator
- sysfs
gpio-mockup
gpio-sim
+ Deprecated APIs <deprecated>
.. only:: subproject and html
diff --git a/Documentation/userspace-api/gpio/deprecated.rst b/Documentation/userspace-api/gpio/deprecated.rst
new file mode 100644
index 000000000000..4cc7c79d7c23
--- /dev/null
+++ b/Documentation/userspace-api/gpio/deprecated.rst
@@ -0,0 +1,10 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============================
+Deprecated GPIO Userspace APIs
+==============================
+
+.. toctree::
+ :maxdepth: 1
+
+ Sysfs Interface <sysfs>
diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst
index 072b9fa18aea..17f0f92db384 100644
--- a/Documentation/userspace-api/gpio/index.rst
+++ b/Documentation/userspace-api/gpio/index.rst
@@ -8,6 +8,7 @@ GPIO
:maxdepth: 1
Character Device Userspace API <chardev>
+ Deprecated Userspace APIs <deprecated>
.. only:: subproject and html
diff --git a/Documentation/admin-guide/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst
similarity index 100%
rename from Documentation/admin-guide/gpio/sysfs.rst
rename to Documentation/userspace-api/gpio/sysfs.rst
--
2.39.2
Capitalise the title of the GPIO documentation page to match other
subsystems.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/admin-guide/gpio/index.rst | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index 9b0630f30d3e..8489b8a3991f 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -1,7 +1,7 @@
.. SPDX-License-Identifier: GPL-2.0
====
-gpio
+GPIO
====
.. toctree::
--
2.39.2
Update GPIO sysfs interface documentation to reference the new
chardev document rather than gpio.h.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/userspace-api/gpio/sysfs.rst | 10 ++++------
1 file changed, 4 insertions(+), 6 deletions(-)
diff --git a/Documentation/userspace-api/gpio/sysfs.rst b/Documentation/userspace-api/gpio/sysfs.rst
index 35171d15f78d..ef080d811451 100644
--- a/Documentation/userspace-api/gpio/sysfs.rst
+++ b/Documentation/userspace-api/gpio/sysfs.rst
@@ -5,12 +5,10 @@ GPIO Sysfs Interface for Userspace
THIS ABI IS DEPRECATED, THE ABI DOCUMENTATION HAS BEEN MOVED TO
Documentation/ABI/obsolete/sysfs-gpio AND NEW USERSPACE CONSUMERS
- ARE SUPPOSED TO USE THE CHARACTER DEVICE ABI. THIS OLD SYSFS ABI WILL
- NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE MAINTAINED.
+ SHOULD USE THE chardev.rst.
-Refer to the examples in tools/gpio/* for an introduction to the new
-character device ABI. Also see the userspace header in
-include/uapi/linux/gpio.h
+ THIS OLD SYSFS ABI WILL NOT BE DEVELOPED (NO NEW FEATURES), IT WILL JUST BE
+ MAINTAINED.
The deprecated sysfs ABI
------------------------
@@ -34,7 +32,7 @@ standard kernels won't know about. And for some tasks, simple userspace
GPIO drivers could be all that the system really needs.
DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
-PLEASE READ THE DOCUMENT AT Documentation/driver-api/gpio/drivers-on-gpio.rst
+PLEASE READ Documentation/driver-api/gpio/drivers-on-gpio.rst
TO AVOID REINVENTING KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
Paths in Sysfs
--
2.39.2
Update the gpio-mockup documentation to note that is has been
obsoleted by the gpio-sim.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/admin-guide/gpio/gpio-mockup.rst | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/Documentation/admin-guide/gpio/gpio-mockup.rst b/Documentation/admin-guide/gpio/gpio-mockup.rst
index 493071da1738..d6e7438a7550 100644
--- a/Documentation/admin-guide/gpio/gpio-mockup.rst
+++ b/Documentation/admin-guide/gpio/gpio-mockup.rst
@@ -3,6 +3,14 @@
GPIO Testing Driver
===================
+.. note::
+
+ This module has been obsoleted by the more flexible gpio-sim.rst.
+ New developments should use that API and existing developments are
+ encouraged to migrate as soon as possible.
+ This module will continue to be maintained but no new features will be
+ added.
+
The GPIO Testing Driver (gpio-mockup) provides a way to create simulated GPIO
chips for testing purposes. The lines exposed by these chips can be accessed
using the standard GPIO character device interface as well as manipulated
--
2.39.2
The gpio-mockup has been obsoleted by the gpio-sim, so relocate its
documentation into the deprecated section of the admin-guide book.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/admin-guide/gpio/deprecated.rst | 1 +
Documentation/admin-guide/gpio/index.rst | 1 -
2 files changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/admin-guide/gpio/deprecated.rst b/Documentation/admin-guide/gpio/deprecated.rst
index 683d7d23e62a..8503ea2f54d5 100644
--- a/Documentation/admin-guide/gpio/deprecated.rst
+++ b/Documentation/admin-guide/gpio/deprecated.rst
@@ -9,4 +9,5 @@ Deprecated GPIO APIs
Character Device Userspace API (v1) <../../userspace-api/gpio/chardev_v1>
Sysfs Interface <../../userspace-api/gpio/sysfs>
+ Mockup Testing Module <gpio-mockup>
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index 8489b8a3991f..573682212a56 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -9,7 +9,6 @@ GPIO
Character Device Userspace API <../../userspace-api/gpio/chardev>
gpio-aggregator
- gpio-mockup
gpio-sim
Deprecated APIs <deprecated>
--
2.39.2
Add documentation for the GPIO character device userspace API.
Added to the userspace-api book, but also provide a link from the
admin-guide book, as historically the GPIO documentation has been
there.
Signed-off-by: Kent Gibson <[email protected]>
---
Documentation/admin-guide/gpio/index.rst | 1 +
Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++++
.../userspace-api/gpio/error-codes.rst | 78 ++++++++++++
.../gpio/gpio-get-chipinfo-ioctl.rst | 41 +++++++
.../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 47 ++++++++
.../gpio/gpio-v2-get-line-ioctl.rst | 99 +++++++++++++++
.../gpio/gpio-v2-get-lineinfo-ioctl.rst | 50 ++++++++
.../gpio/gpio-v2-get-lineinfo-watch-ioctl.rst | 67 ++++++++++
.../gpio/gpio-v2-line-event-read.rst | 83 +++++++++++++
.../gpio/gpio-v2-line-get-values-ioctl.rst | 51 ++++++++
.../gpio/gpio-v2-line-set-config-ioctl.rst | 57 +++++++++
.../gpio/gpio-v2-line-set-values-ioctl.rst | 47 ++++++++
.../gpio/gpio-v2-lineinfo-changed-read.rst | 81 +++++++++++++
Documentation/userspace-api/gpio/index.rst | 17 +++
Documentation/userspace-api/index.rst | 1 +
15 files changed, 834 insertions(+)
create mode 100644 Documentation/userspace-api/gpio/chardev.rst
create mode 100644 Documentation/userspace-api/gpio/error-codes.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
create mode 100644 Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
create mode 100644 Documentation/userspace-api/gpio/index.rst
diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
index f6861ca16ffe..b40f0a2a6822 100644
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -7,6 +7,7 @@ gpio
.. toctree::
:maxdepth: 1
+ Character Device Userspace API <../../userspace-api/gpio/chardev>
gpio-aggregator
sysfs
gpio-mockup
diff --git a/Documentation/userspace-api/gpio/chardev.rst b/Documentation/userspace-api/gpio/chardev.rst
new file mode 100644
index 000000000000..af5f1753e565
--- /dev/null
+++ b/Documentation/userspace-api/gpio/chardev.rst
@@ -0,0 +1,114 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+===================================
+GPIO Character Device Userspace API
+===================================
+
+This is latest version (v2) of the character device API, as defined in
+``include/uapi/linux/gpio.h.``
+
+.. note::
+ Do NOT abuse userspace APIs to control hardware that has proper kernel
+ drivers. There may already be a driver for your use case, and an existing
+ kernel driver is sure to provide a superior solution to bitbashing
+ from userspace.
+
+ Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
+ kernel wheels in userspace.
+
+ Similarly, for multi-function lines there may be other subsystems, such as
+ Documentation/spi/index.rst, Documentation/i2c/index.rst,
+ Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that
+ provide suitable drivers and APIs for your hardware.
+
+Basic examples using the character device API can be found in ``tools/gpio/*``.
+
+The API is based around two major objects, the :ref:`gpio-v2-chip` and the
+:ref:`gpio-v2-line-request`.
+
+.. _gpio-v2-chip:
+
+Chip
+====
+
+The Chip represents a single GPIO chip and is exposed to userspace using device
+files of the form ``/dev/gpiochipX``.
+
+Each chip supports a number of GPIO lines,
+:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
+``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
+
+Lines are requested from the chip using gpio-v2-get-line-ioctl.rst
+and the resulting line request is used to access the GPIO chip's lines or
+monitor the lines for edge events.
+
+Within this documentation, the file descriptor returned by calling `open()`
+on the GPIO device file is referred to as ``chip_fd``.
+
+Operations
+----------
+
+The following operations may be performed on the chip:
+
+.. toctree::
+ :titlesonly:
+
+ Get Line <gpio-v2-get-line-ioctl>
+ Get Chip Info <gpio-get-chipinfo-ioctl>
+ Get Line Info <gpio-v2-get-lineinfo-ioctl>
+ Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl>
+ Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
+ Read Line Info Changed Events <gpio-v2-lineinfo-changed-read>
+
+.. _gpio-v2-line-request:
+
+Line Request
+============
+
+Line requests are created by gpio-v2-get-line-ioctl.rst and provide
+access to a set of requested lines. The line request is exposed to userspace
+via the anonymous file descriptor returned in
+:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
+
+Within this documentation, the line request file descriptor is referred to
+as ``req_fd``.
+
+Operations
+----------
+
+The following operations may be performed on the line request:
+
+.. toctree::
+ :titlesonly:
+
+ Get Line Values <gpio-v2-line-get-values-ioctl>
+ Set Line Values <gpio-v2-line-set-values-ioctl>
+ Read Line Edge Events <gpio-v2-line-event-read>
+ Reconfigure Lines <gpio-v2-line-set-config-ioctl>
+
+Types
+=====
+
+This section contains the structs and enums that are referenced by the API v2,
+as defined in ``include/uapi/linux/gpio.h``.
+
+.. kernel-doc:: include/uapi/linux/gpio.h
+ :identifiers:
+ gpio_v2_line_attr_id
+ gpio_v2_line_attribute
+ gpio_v2_line_changed_type
+ gpio_v2_line_config
+ gpio_v2_line_config_attribute
+ gpio_v2_line_event
+ gpio_v2_line_event_id
+ gpio_v2_line_flag
+ gpio_v2_line_info
+ gpio_v2_line_info_changed
+ gpio_v2_line_request
+ gpio_v2_line_values
+ gpiochip_info
+
+.. toctree::
+ :hidden:
+
+ error-codes
diff --git a/Documentation/userspace-api/gpio/error-codes.rst b/Documentation/userspace-api/gpio/error-codes.rst
new file mode 100644
index 000000000000..edf01f2cf9d2
--- /dev/null
+++ b/Documentation/userspace-api/gpio/error-codes.rst
@@ -0,0 +1,78 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _gpio_errors:
+
+*******************
+GPIO Error Codes
+*******************
+
+.. _gpio-errors:
+
+.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
+
+.. flat-table:: Common GPIO error codes
+ :header-rows: 0
+ :stub-columns: 0
+ :widths: 1 16
+
+ - - ``EAGAIN`` (aka ``EWOULDBLOCK``)
+
+ - The device was opened in non-blocking mode and a read can't
+ be performed as there is no data available.
+
+ - - ``EBADF``
+
+ - The file descriptor is not valid.
+
+ - - ``EBUSY``
+
+ - The ioctl can't be handled because the device is busy. Typically
+ returned when an ioctl attempts something that would require the
+ usage of a resource that was already allocated. The ioctl must not
+ be retried without performing another action to fix the problem
+ first.
+
+ - - ``EFAULT``
+
+ - There was a failure while copying data from/to userspace, probably
+ caused by an invalid pointer reference.
+
+ - - ``EINVAL``
+
+ - One or more of the ioctl parameters are invalid or out of the
+ allowed range. This is a widely used error code.
+
+ - - ``ENODEV``
+
+ - Device not found or was removed.
+
+ - - ``ENOMEM``
+
+ - There's not enough memory to handle the desired operation.
+
+ - - ``EPERM``
+
+ - Permission denied. Typically returned in response to an attempt
+ to perform an action incompatible with the current line
+ configuration.
+
+ - - ``EIO``
+
+ - I/O error. Typically returned when there are problems communicating
+ with a hardware device or requesting features that hardware does not
+ support. This could indicate broken or flaky hardware.
+ It's a 'Something is wrong, I give up!' type of error.
+
+ - - ``ENXIO``
+
+ - No device corresponding to this device special file exists.
+
+.. note::
+
+ #. This list is not exhaustive; ioctls may return other error codes.
+ Since errors may have side effects such as a driver reset,
+ applications should abort on unexpected errors, or otherwise
+ assume that the device is in a bad state.
+
+ #. Request-specific error codes are listed in the individual
+ requests descriptions.
diff --git a/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
new file mode 100644
index 000000000000..05f07fdefe2f
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
@@ -0,0 +1,41 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_GET_CHIPINFO_IOCTL:
+
+***********************
+GPIO_GET_CHIPINFO_IOCTL
+***********************
+
+Name
+====
+
+GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_GET_CHIPINFO_IOCTL
+
+``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``info``
+ The :c:type:`chip_info<gpiochip_info>` to be populated.
+
+Description
+===========
+
+Gets the publicly available information for a particular GPIO chip.
+
+Return Value
+============
+
+On success 0 and ``info`` is populated with the chip info.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
new file mode 100644
index 000000000000..ba6f9d00a40b
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_GET_LINEINFO_UNWATCH_IOCTL:
+
+*******************************
+GPIO_GET_LINEINFO_UNWATCH_IOCTL
+*******************************
+
+Name
+====
+
+GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to its
+requested state and configuration information.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL
+
+``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``offset``
+ The offset of the line to no longer watch.
+
+Description
+===========
+
+Remove the line from the list of lines being watched on this ``chip_fd``.
+
+This is the opposite of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and
+gpio-get-lineinfo-watch-ioctl.rst (v1).
+
+Unwatching a line that is not watched is an error (**EBUSY**).
+
+Return Value
+============
+
+On success 0.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
new file mode 100644
index 000000000000..4259c08779c1
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
@@ -0,0 +1,99 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_GET_LINE_IOCTL:
+
+**********************
+GPIO_V2_GET_LINE_IOCTL
+**********************
+
+Name
+====
+
+GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_V2_GET_LINE_IOCTL
+
+``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``request``
+ The :c:type:`line_request<gpio_v2_line_request>` specifying the lines
+ to request and their configuration.
+
+Description
+===========
+
+On success, the requesting process is granted exclusive access to the line
+value, write access to the line configuration, and may receive events when
+edges are detected on the line, all of which are described in more detail in
+:ref:`gpio-v2-line-request`.
+
+A number of lines may be requested in the one line request, and request
+operations are performed on the requested lines by the kernel as atomically
+as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
+requested lines at once.
+
+The state of a line, including the value of output lines, is guaranteed to
+remain as requested until the returned file descriptor is closed. Once the
+file descriptor is closed, the state of the line becomes uncontrolled from
+the userspace perspective, and may revert to its default state.
+
+Closing the ``chip_fd`` has no effect on existing line requests.
+
+.. _gpio-v2-get-line-config-rules:
+
+Configuration Rules
+-------------------
+
+For any given requested line, the following configuration rules apply:
+
+The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and
+``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then
+the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW``
+and the line is requested "as-is" to allow reading of the line value
+without altering the electrical configuration.
+
+The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the
+``GPIO_V2_LINE_FLAG_OUTPUT`` to be set.
+Only one drive flag may be set.
+If none are set then the line is assumed push-pull.
+
+Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it
+requires a direction flag to also be set.
+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.
+
+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``.
+The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware
+and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that
+doesn't support it is an error (**EOPNOTSUP**).
+
+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.
+
+Requesting an invalid configuration is an error (**EINVAL**).
+
+Return Value
+============
+
+On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the
+file descriptor for the request.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
new file mode 100644
index 000000000000..bc4d8df887d4
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
@@ -0,0 +1,50 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_GET_LINEINFO_IOCTL:
+
+**************************
+GPIO_V2_GET_LINEINFO_IOCTL
+**************************
+
+Name
+====
+
+GPIO_V2_GET_LINEINFO_IOCTL - Get the publicly available information for a line.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_V2_GET_LINEINFO_IOCTL
+
+``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_IOCTL, struct gpio_v2_line_info *info)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``info``
+ The :c:type:`line_info<gpio_v2_line_info>` to be populated, with the
+ ``offset`` field set to indicate the line to be collected.
+
+Description
+===========
+
+Get the publicly available information for a line.
+
+This information is available independent of whether the line is in use.
+
+.. note::
+ The line info does not include the line value.
+
+ The line must be requested using gpio-v2-get-line-ioctl.rst to access its
+ value.
+
+Return Value
+============
+
+On success 0 and ``info`` is populated with the chip info.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
new file mode 100644
index 000000000000..938ff85a9322
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
@@ -0,0 +1,67 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_GET_LINEINFO_WATCH_IOCTL:
+
+********************************
+GPIO_V2_GET_LINEINFO_WATCH_IOCTL
+********************************
+
+Name
+====
+
+GPIO_V2_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its
+request state and configuration information.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_V2_GET_LINEINFO_WATCH_IOCTL
+
+``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_WATCH_IOCTL, struct gpio_v2_line_info *info)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``info``
+ The :c:type:`line_info<gpio_v2_line_info>` struct to be populated, with
+ the ``offset`` set to indicate the line to watch
+
+Description
+===========
+
+Enable watching a line for changes to its request state and configuration
+information. Changes to line info include a line being requested, released
+or reconfigured.
+
+.. note::
+ Watching line info is not generally required, and would typically only be
+ used by a system monitoring component.
+
+ The line info does NOT include the line value.
+ The line must be requested using gpio-v2-get-line-ioctl.rst to access
+ its value, and the line request can monitor a line for events using
+ gpio-v2-line-event-read.rst.
+
+By default all lines are unwatched when the GPIO chip is opened.
+
+Multiple lines may be watched simultaneously by adding a watch for each.
+
+Once a watch is set, any changes to line info will generate events which can be
+read from the ``chip_fd`` as described in
+gpio-v2-lineinfo-changed-read.rst.
+
+Adding a watch to a line that is already watched is an error (**EBUSY**).
+
+Watches are specific to the ``chip_fd`` and are independent of watches
+on the same GPIO chip opened with a separate call to `open()`.
+
+Return Value
+============
+
+On success 0 and ``info`` is populated with the current line info.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
new file mode 100644
index 000000000000..6513c23fb7ca
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
@@ -0,0 +1,83 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_LINE_EVENT_READ:
+
+***********************
+GPIO_V2_LINE_EVENT_READ
+***********************
+
+Name
+====
+
+GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request.
+
+Synopsis
+========
+
+``int read(int req_fd, void *buf, size_t count)``
+
+Arguments
+=========
+
+``req_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
+
+``buf``
+ The buffer to contain the :c:type:`events<gpio_v2_line_event>`.
+
+``count``
+ The number of bytes available in ``buf``, which must be at
+ least the size of a :c:type:`gpio_v2_line_event`.
+
+Description
+===========
+
+Read edge detection events for lines from a request.
+
+Edge detection must be enabled for the input line using either
+``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or
+both. Edge events are then generated whenever edge interrupts are detected on
+the input line.
+
+The kernel captures and timestamps edge events as close as possible to their
+occurrence and stores them in a buffer from where they can be read by
+userspace at its convenience using `read()`.
+
+Events read from the buffer are always in the same order that they were
+detected by the kernel, including when multiple lines are being monitored by
+the one request.
+
+The size of the kernel event buffer is fixed at the time of line request
+creation, and can be influenced by the
+:c:type:`request.event_buffer_size<gpio_v2_line_request>`.
+The default size is 16 times the number of lines requested.
+
+The buffer may overflow if bursts of events occur quicker than they are read
+by userspace. If an overflow occurs then the oldest buffered event is
+discarded. Overflow can be detected from userspace by monitoring the event
+sequence numbers.
+
+To minimize the number of calls required to copy events from the kernel to
+userspace, `read()` supports copying multiple events. The number of events
+copied is the lower of the number available in the kernel buffer and the
+number that will fit in the userspace buffer (``buf``).
+
+Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst
+does not remove or modify the events already contained in the kernel event
+buffer.
+
+The `read()` will block if no event is available and the ``req_fd`` has not
+been set **O_NONBLOCK**.
+
+The presence of an event can be tested for by checking that the ``req_fd`` is
+readable using `poll()` or an equivalent.
+
+Return Value
+============
+
+On success the number of bytes read, which will be a multiple of the size of a
+:c:type:`gpio_v2_line_event` event.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
new file mode 100644
index 000000000000..e4e74a1926d8
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
@@ -0,0 +1,51 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_LINE_GET_VALUES_IOCTL:
+
+*****************************
+GPIO_V2_LINE_GET_VALUES_IOCTL
+*****************************
+
+Name
+====
+
+GPIO_V2_LINE_GET_VALUES_IOCTL - Get the values of requested lines.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_V2_LINE_GET_VALUES_IOCTL
+
+``int ioctl(int req_fd, GPIO_V2_LINE_GET_VALUES_IOCTL, struct gpio_v2_line_values *values)``
+
+Arguments
+=========
+
+``req_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
+
+``values``
+ The :c:type:`line_values<gpio_v2_line_values>` to get with the ``mask`` set
+ to indicate the subset of requested lines to get.
+
+Description
+===========
+
+Get the values of requested lines.
+
+The values of both input and output lines may be read.
+
+For output lines, the value returned is driver and configuration dependent and
+may be either the output buffer (the last requested value set) or the input
+buffer (the actual level of the line), and depending on the hardware and
+configuration these may differ.
+
+Return Value
+============
+
+On success 0 and the corresponding :c:type:`values.bits<gpio_v2_line_values>`
+contain the value read.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
new file mode 100644
index 000000000000..126c2626ba6b
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
@@ -0,0 +1,57 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_LINE_SET_CONFIG_IOCTL:
+
+*****************************
+GPIO_V2_LINE_SET_CONFIG_IOCTL
+*****************************
+
+Name
+====
+
+GPIO_V2_LINE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_V2_LINE_SET_CONFIG_IOCTL
+
+``int ioctl(int req_fd, GPIO_V2_LINE_SET_CONFIG_IOCTL, struct gpio_v2_line_config *config)``
+
+Arguments
+=========
+
+``req_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
+
+``config``
+ The new :c:type:`configuration<gpio_v2_line_config>` to apply to the
+ requested lines.
+
+Description
+===========
+
+Update the configuration of previously requested lines, without releasing the
+line or introducing potential glitches.
+
+The new configuration must specify the configuration of all requested lines.
+
+The same :ref:`gpio-v2-get-line-config-rules` 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 also be used to
+dynamically control edge detection, or more generally move lines seamlessly
+from one configuration state to another.
+
+To only change the value of output lines, use
+gpio-v2-line-set-values-ioctl.rst.
+
+Return Value
+============
+
+On success 0.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
new file mode 100644
index 000000000000..6d2d1886950b
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
@@ -0,0 +1,47 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_LINE_SET_VALUES_IOCTL:
+
+*****************************
+GPIO_V2_LINE_SET_VALUES_IOCTL
+*****************************
+
+Name
+====
+
+GPIO_V2_LINE_SET_VALUES_IOCTL - Set the values of requested output lines.
+
+Synopsis
+========
+
+.. c:macro:: GPIO_V2_LINE_SET_VALUES_IOCTL
+
+``int ioctl(int req_fd, GPIO_V2_LINE_SET_VALUES_IOCTL, struct gpio_v2_line_values *values)``
+
+Arguments
+=========
+
+``req_fd``
+ The file descriptor of the GPIO character device, as returned in the
+ :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
+
+``values``
+ The :c:type:`line_values<gpio_v2_line_values>` to set with the ``mask`` set
+ to indicate the subset of requested lines to set and ``bits`` set to
+ indicate the new value.
+
+Description
+===========
+
+Set the values of requested output lines.
+
+Only the values of output lines may be set.
+Attempting to set the value of an input line is an error (**EPERM**).
+
+Return Value
+============
+
+On success 0.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
new file mode 100644
index 000000000000..24ad325e7253
--- /dev/null
+++ b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
@@ -0,0 +1,81 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+.. _GPIO_V2_LINEINFO_CHANGED_READ:
+
+*****************************
+GPIO_V2_LINEINFO_CHANGED_READ
+*****************************
+
+Name
+====
+
+GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched
+lines from the chip.
+
+Synopsis
+========
+
+``int read(int chip_fd, void *buf, size_t count)``
+
+Arguments
+=========
+
+``chip_fd``
+ The file descriptor of the GPIO character device returned by `open()`.
+
+``buf``
+ The buffer to contain the :c:type:`events<gpio_v2_line_info_changed>`.
+
+``count``
+ The number of bytes available in ``buf``, which must be at least the size
+ of a :c:type:`gpio_v2_line_info_changed` event.
+
+Description
+===========
+
+Read line info changed events for watched lines from the chip.
+
+.. note::
+ Monitoring line info changes is not generally required, and would typically
+ only be performed by a system monitoring component.
+
+ These events relate to changes in a line's request state or configuration,
+ not its value. Use gpio-v2-line-event-read.rst to receive events when a
+ line changes value.
+
+A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate
+info changed events. Subsequently, a request, release, or reconfiguration
+of the line will generate an info changed event.
+
+The kernel timestamps events when they occur and stores them in a buffer
+from where they can be read by userspace at its convenience using `read()`.
+
+The size of the kernel event buffer is fixed at 32 events per ``chip_fd``.
+
+The buffer may overflow if bursts of events occur quicker than they are read
+by userspace. If an overflow occurs then the most recent event is discarded.
+Overflow cannot be detected from userspace.
+
+Events read from the buffer are always in the same order that they were
+detected by the kernel, including when multiple lines are being monitored by
+the one ``chip_fd``.
+
+To minimize the number of calls required to copy events from the kernel to
+userspace, `read()` supports copying multiple events. The number of events
+copied is the lower of the number available in the kernel buffer and the
+number that will fit in the userspace buffer (``buf``).
+
+A `read()` will block if no event is available and the ``chip_fd`` has not
+been set **O_NONBLOCK**.
+
+The presence of an event can be tested for by checking that the ``chip_fd`` is
+readable using `poll()` or an equivalent.
+
+Return Value
+============
+
+On success the number of bytes read, which will be a multiple of the size
+of a :c:type:`gpio_v2_line_info_changed` event.
+
+On error -1 and the ``errno`` variable is set appropriately.
+Common error codes are described in error-codes.rst.
diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst
new file mode 100644
index 000000000000..072b9fa18aea
--- /dev/null
+++ b/Documentation/userspace-api/gpio/index.rst
@@ -0,0 +1,17 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+GPIO
+====
+
+.. toctree::
+ :maxdepth: 1
+
+ Character Device Userspace API <chardev>
+
+.. only:: subproject and html
+
+ Indices
+ =======
+
+ * :ref:`genindex`
diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
index 031df47a7c19..8e174a605f69 100644
--- a/Documentation/userspace-api/index.rst
+++ b/Documentation/userspace-api/index.rst
@@ -25,6 +25,7 @@ place where this information is gathered.
dma-buf-alloc-exchange
ebpf/index
ELF
+ gpio/index
ioctl/index
iommu
iommufd
--
2.39.2
On Tue, Jan 9, 2024 at 4:00 PM Kent Gibson <[email protected]> wrote:
>
> My new year's resolution was to improve the documentation of the
> character device API and gpio in general, so here we are.
>
> Wrt the formatting and file breakdown, I've taken inspiration from
> the userspace-api/media documentation.
>
> Patch 1 adds documentation for the current chardev uAPI. I've added
> it to the userspace-api book, as that is the most obvious place a
> reader would look for it, but have also provided links from the
> admin-guide book where the gpio docs currently reside.
>
> I realise MAINTAINERS should be updated with
> Documentation/userspace-api/gpio/, but the split out of GPIO UAPI
> hasn't made it into gpio/for-next yet, so I was unsure of how to
> handle that.
>
> Patch 2 relocates the sysfs API doc to stress its deprecation by
> moving it to a new deprecated section, again in userspace-api but
> with a similar section in the admin-guide. The deprecated section
> also provides a placeholder for subsequent changes.
>
> Patch 3 updates the sysfs API doc to reference the chardev
> documentation rather than gpio.h.
>
> Patch 4 adds documentation for the deprecated v1 version of the
> chardev uAPI. It is deprecated, but still useful to have, if
> nothing else to help identify the differences between v1 and v2.
>
> Patch 5 capitalizes the title of the admin-guide/gpio to match
> the other subsystems and the userspace-api book.
>
> Patch 6 adds a deprecation note to the gpio-mockup, as it is
> obsoleted by the gpio-sim.
>
> Patch 7 moves the gpio-mockup doc into the deprecated section.
>
> I've got some minor updates for the kernel doc in gpio.h as well,
> but they make sense on their own so I'll send those separately
> keep the cross-posting to a minimum.
>
> I realise the only thing less exciting than writing documentation
> is reviewing it, so my apologies and thanks in advance if you
> have the fortitude to attempt such a scintillating endeavour.
Thanks a lot for doing this!
..
> Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++
> .../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++
Shouldn't it be better to have chardev_v2.rst along with chardev.rst
to be a link to it?
..
May we actually state in the documentation that sysfs is subject to
remove at some point?
--
With Best Regards,
Andy Shevchenko
On Tue, Jan 09, 2024 at 10:00:26PM +0200, Andy Shevchenko wrote:
> On Tue, Jan 9, 2024 at 4:00 PM Kent Gibson <[email protected]> wrote:
> >
>
> Thanks a lot for doing this!
>
I hope it makes sense - I've been polishing it for a while to
the point that I might be missing the forest for the trees.
> ...
>
> > Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++
> > .../userspace-api/gpio/chardev_v1.rst | 129 ++++++++++++++++++
>
> Shouldn't it be better to have chardev_v2.rst along with chardev.rst
> to be a link to it?
>
Didn't see any benefit to doing that. As I see it, chardev.rst will
always be the latest. If we do ever do a v3 then this doc will get the
renaming and link treatment then.
> ...
>
> May we actually state in the documentation that sysfs is subject to
> remove at some point?
>
So formally define what "deprecated" means?
Is that covered in the higher level documentation somewhere?
If so I'm more than happy to provide a reference.
Cheers,
Kent.
On 10/01/2024 00:45, Kent Gibson wrote:
> On Tue, Jan 09, 2024 at 10:00:26PM +0200, Andy Shevchenko wrote:
>> On Tue, Jan 9, 2024 at 4:00 PM Kent Gibson <[email protected]> wrote:
>>
>> May we actually state in the documentation that sysfs is subject to
>> remove at some point?
>>
>
> So formally define what "deprecated" means?
> Is that covered in the higher level documentation somewhere?
> If so I'm more than happy to provide a reference.
We have a few files that may be relevant here, that I'm aware of:
1) https://docs.kernel.org/admin-guide/sysfs-rules.html
documents some general assumptions that userspace can make about the
stability of sysfs and its files
2) https://docs.kernel.org/admin-guide/abi.html
This is the public-facing, somewhat machine-readable repository of what
is supposed to be the kernel's ABI/API, including "obsolete" and
"removed" interfaces.
3) Documentation/ABI/README
describes the process of deprecating an interface
Vegard
On Wed, Jan 10, 2024 at 10:16 AM Vegard Nossum <[email protected]> wrote:
> On 10/01/2024 00:45, Kent Gibson wrote:
> > On Tue, Jan 09, 2024 at 10:00:26PM +0200, Andy Shevchenko wrote:
> >> On Tue, Jan 9, 2024 at 4:00 PM Kent Gibson <[email protected]> wrote:
> >>
> >> May we actually state in the documentation that sysfs is subject to
> >> remove at some point?
> >
> > So formally define what "deprecated" means?
> > Is that covered in the higher level documentation somewhere?
> > If so I'm more than happy to provide a reference.
>
> We have a few files that may be relevant here, that I'm aware of:
>
> 1) https://docs.kernel.org/admin-guide/sysfs-rules.html
>
> documents some general assumptions that userspace can make about the
> stability of sysfs and its files
>
> 2) https://docs.kernel.org/admin-guide/abi.html
>
> This is the public-facing, somewhat machine-readable repository of what
> is supposed to be the kernel's ABI/API, including "obsolete" and
> "removed" interfaces.
>
> 3) Documentation/ABI/README
>
> describes the process of deprecating an interface
Yes and GPIO currently is under obsolete section with also this:
"This ABI is deprecated and will be removed after 2020. It is replaced
with the GPIO character device."
https://docs.kernel.org/admin-guide/abi-obsolete.html#symbols-under-sys-class
So, proposed cleanup series should probably rely on this documentation
among other existing descriptions of sysfs GPIO.
--
With Best Regards,
Andy Shevchenko
First up, thank you for this. I'm busy getting up to speed with libgpiod
having been spoiled by bit-bashing memory mapped GPIO and there
are many gotchas that the below helps clarify.
FWIW I've added a few "from the perspective of an advanced noob"
comments.
On Tue, 9 Jan 2024 at 14:00, Kent Gibson <[email protected]> wrote:
>
> Add documentation for the GPIO character device userspace API.
>
> Added to the userspace-api book, but also provide a link from the
> admin-guide book, as historically the GPIO documentation has been
> there.
>
> Signed-off-by: Kent Gibson <[email protected]>
> ---
> Documentation/admin-guide/gpio/index.rst | 1 +
> Documentation/userspace-api/gpio/chardev.rst | 114 ++++++++++++++++++
> .../userspace-api/gpio/error-codes.rst | 78 ++++++++++++
> .../gpio/gpio-get-chipinfo-ioctl.rst | 41 +++++++
> .../gpio/gpio-get-lineinfo-unwatch-ioctl.rst | 47 ++++++++
> .../gpio/gpio-v2-get-line-ioctl.rst | 99 +++++++++++++++
> .../gpio/gpio-v2-get-lineinfo-ioctl.rst | 50 ++++++++
> .../gpio/gpio-v2-get-lineinfo-watch-ioctl.rst | 67 ++++++++++
> .../gpio/gpio-v2-line-event-read.rst | 83 +++++++++++++
> .../gpio/gpio-v2-line-get-values-ioctl.rst | 51 ++++++++
> .../gpio/gpio-v2-line-set-config-ioctl.rst | 57 +++++++++
> .../gpio/gpio-v2-line-set-values-ioctl.rst | 47 ++++++++
> .../gpio/gpio-v2-lineinfo-changed-read.rst | 81 +++++++++++++
> Documentation/userspace-api/gpio/index.rst | 17 +++
> Documentation/userspace-api/index.rst | 1 +
> 15 files changed, 834 insertions(+)
> create mode 100644 Documentation/userspace-api/gpio/chardev.rst
> create mode 100644 Documentation/userspace-api/gpio/error-codes.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
> create mode 100644 Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
> create mode 100644 Documentation/userspace-api/gpio/index.rst
>
> diff --git a/Documentation/admin-guide/gpio/index.rst b/Documentation/admin-guide/gpio/index.rst
> index f6861ca16ffe..b40f0a2a6822 100644
> --- a/Documentation/admin-guide/gpio/index.rst
> +++ b/Documentation/admin-guide/gpio/index.rst
> @@ -7,6 +7,7 @@ gpio
> .. toctree::
> :maxdepth: 1
>
> + Character Device Userspace API <../../userspace-api/gpio/chardev>
> gpio-aggregator
> sysfs
> gpio-mockup
> diff --git a/Documentation/userspace-api/gpio/chardev.rst b/Documentation/userspace-api/gpio/chardev.rst
> new file mode 100644
> index 000000000000..af5f1753e565
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/chardev.rst
> @@ -0,0 +1,114 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +===================================
> +GPIO Character Device Userspace API
> +===================================
> +
> +This is latest version (v2) of the character device API, as defined in
> +``include/uapi/linux/gpio.h.``
> +
> +.. note::
> + Do NOT abuse userspace APIs to control hardware that has proper kernel
> + drivers. There may already be a driver for your use case, and an existing
> + kernel driver is sure to provide a superior solution to bitbashing
> + from userspace.
> +
> + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
> + kernel wheels in userspace.
I realise this is in part an emotional response, but very much
"citation needed" on
this one. While I believe Kernel drivers for things are a good idea, I
don't believe
userspace libraries are necessarily bad or wrong. They might be the first
experience a future kernel dev has with hardware. Either way there are multiple
ecosystems of userspace drivers both existing and thriving right now, and there
are good reasons to reinvent kernel wheels in userspace.
At least some of these reasons relate to the (incorrectly assumed)
insurmountable
nature of kernel development vs just throwing together some Python. Including
this loaded language just serves to reinforce that.
You catch more flies with honey than with vinegar, so I'd probably soften to:
Before abusing userspace APIs to bitbash drivers for your hardware you should
read Documentation/driver-api/gpio/drivers-on-gpio.rst to see if your device has
an existing kernel driver. If not, please consider contributing one.
> +
> + Similarly, for multi-function lines there may be other subsystems, such as
> + Documentation/spi/index.rst, Documentation/i2c/index.rst,
> + Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that
> + provide suitable drivers and APIs for your hardware.
This is good, people trying to do PWM via userspace bitbashing on arbitrary pins
(sometimes we really do just want to dim a bunch of LEDs without the cost of an
extra driver IC) is kind of silly in hindsight. If we steer people
toward the right
subsystems, perhaps those can be improved for the benefit of all.
> +
> +Basic examples using the character device API can be found in ``tools/gpio/*``.
> +
> +The API is based around two major objects, the :ref:`gpio-v2-chip` and the
> +:ref:`gpio-v2-line-request`.
> +
> +.. _gpio-v2-chip:
> +
> +Chip
> +====
> +
> +The Chip represents a single GPIO chip and is exposed to userspace using device
> +files of the form ``/dev/gpiochipX``.
Is it worth clarifying that - afaik - the numbering of these device
files is or can
be arbitrary? Or, in the opposite case, that the order is guaranteed
by the vendor's
device tree configuration?
> +
> +Each chip supports a number of GPIO lines,
> +:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
> +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
I don't recognise this syntax "`[0,chip.lines)`", typo, or me being clueless?
> +
> +Lines are requested from the chip using gpio-v2-get-line-ioctl.rst
> +and the resulting line request is used to access the GPIO chip's lines or
> +monitor the lines for edge events.
> +
> +Within this documentation, the file descriptor returned by calling `open()`
> +on the GPIO device file is referred to as ``chip_fd``.
> +
> +Operations
> +----------
> +
> +The following operations may be performed on the chip:
> +
> +.. toctree::
> + :titlesonly:
> +
> + Get Line <gpio-v2-get-line-ioctl>
> + Get Chip Info <gpio-get-chipinfo-ioctl>
> + Get Line Info <gpio-v2-get-lineinfo-ioctl>
> + Watch Line Info <gpio-v2-get-lineinfo-watch-ioctl>
> + Unwatch Line Info <gpio-get-lineinfo-unwatch-ioctl>
> + Read Line Info Changed Events <gpio-v2-lineinfo-changed-read>
> +
> +.. _gpio-v2-line-request:
> +
> +Line Request
> +============
> +
> +Line requests are created by gpio-v2-get-line-ioctl.rst and provide
> +access to a set of requested lines. The line request is exposed to userspace
> +via the anonymous file descriptor returned in
> +:c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
> +
> +Within this documentation, the line request file descriptor is referred to
> +as ``req_fd``.
> +
> +Operations
> +----------
> +
> +The following operations may be performed on the line request:
> +
> +.. toctree::
> + :titlesonly:
> +
> + Get Line Values <gpio-v2-line-get-values-ioctl>
> + Set Line Values <gpio-v2-line-set-values-ioctl>
> + Read Line Edge Events <gpio-v2-line-event-read>
> + Reconfigure Lines <gpio-v2-line-set-config-ioctl>
> +
> +Types
> +=====
> +
> +This section contains the structs and enums that are referenced by the API v2,
> +as defined in ``include/uapi/linux/gpio.h``.
> +
> +.. kernel-doc:: include/uapi/linux/gpio.h
> + :identifiers:
> + gpio_v2_line_attr_id
> + gpio_v2_line_attribute
> + gpio_v2_line_changed_type
> + gpio_v2_line_config
> + gpio_v2_line_config_attribute
> + gpio_v2_line_event
> + gpio_v2_line_event_id
> + gpio_v2_line_flag
> + gpio_v2_line_info
> + gpio_v2_line_info_changed
> + gpio_v2_line_request
> + gpio_v2_line_values
> + gpiochip_info
> +
> +.. toctree::
> + :hidden:
> +
> + error-codes
> diff --git a/Documentation/userspace-api/gpio/error-codes.rst b/Documentation/userspace-api/gpio/error-codes.rst
> new file mode 100644
> index 000000000000..edf01f2cf9d2
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/error-codes.rst
> @@ -0,0 +1,78 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _gpio_errors:
> +
> +*******************
> +GPIO Error Codes
> +*******************
> +
> +.. _gpio-errors:
> +
> +.. tabularcolumns:: |p{2.5cm}|p{15.0cm}|
> +
> +.. flat-table:: Common GPIO error codes
> + :header-rows: 0
> + :stub-columns: 0
> + :widths: 1 16
> +
> + - - ``EAGAIN`` (aka ``EWOULDBLOCK``)
> +
> + - The device was opened in non-blocking mode and a read can't
> + be performed as there is no data available.
> +
> + - - ``EBADF``
> +
> + - The file descriptor is not valid.
> +
> + - - ``EBUSY``
> +
> + - The ioctl can't be handled because the device is busy. Typically
> + returned when an ioctl attempts something that would require the
> + usage of a resource that was already allocated. The ioctl must not
> + be retried without performing another action to fix the problem
> + first.
eg: When a line is already claimed by another process?
> +
> + - - ``EFAULT``
> +
> + - There was a failure while copying data from/to userspace, probably
> + caused by an invalid pointer reference.
> +
> + - - ``EINVAL``
> +
> + - One or more of the ioctl parameters are invalid or out of the
> + allowed range. This is a widely used error code.
> +
> + - - ``ENODEV``
> +
> + - Device not found or was removed.
> +
> + - - ``ENOMEM``
> +
> + - There's not enough memory to handle the desired operation.
> +
> + - - ``EPERM``
> +
> + - Permission denied. Typically returned in response to an attempt
> + to perform an action incompatible with the current line
> + configuration.
> +
> + - - ``EIO``
> +
> + - I/O error. Typically returned when there are problems communicating
> + with a hardware device or requesting features that hardware does not
> + support. This could indicate broken or flaky hardware.
> + It's a 'Something is wrong, I give up!' type of error.
> +
> + - - ``ENXIO``
> +
> + - No device corresponding to this device special file exists.
> +
> +.. note::
> +
> + #. This list is not exhaustive; ioctls may return other error codes.
> + Since errors may have side effects such as a driver reset,
> + applications should abort on unexpected errors, or otherwise
> + assume that the device is in a bad state.
> +
> + #. Request-specific error codes are listed in the individual
> + requests descriptions.
> diff --git a/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
> new file mode 100644
> index 000000000000..05f07fdefe2f
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-get-chipinfo-ioctl.rst
> @@ -0,0 +1,41 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_GET_CHIPINFO_IOCTL:
> +
> +***********************
> +GPIO_GET_CHIPINFO_IOCTL
> +***********************
> +
> +Name
> +====
> +
> +GPIO_GET_CHIPINFO_IOCTL - Get the publicly available information for a chip.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_GET_CHIPINFO_IOCTL
> +
> +``int ioctl(int chip_fd, GPIO_GET_CHIPINFO_IOCTL, struct gpiochip_info *info)``
> +
> +Arguments
> +=========
> +
> +``chip_fd``
> + The file descriptor of the GPIO character device returned by `open()`.
> +
> +``info``
> + The :c:type:`chip_info<gpiochip_info>` to be populated.
> +
> +Description
> +===========
> +
> +Gets the publicly available information for a particular GPIO chip.
> +
> +Return Value
> +============
> +
> +On success 0 and ``info`` is populated with the chip info.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
> new file mode 100644
> index 000000000000..ba6f9d00a40b
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-get-lineinfo-unwatch-ioctl.rst
> @@ -0,0 +1,47 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_GET_LINEINFO_UNWATCH_IOCTL:
> +
> +*******************************
> +GPIO_GET_LINEINFO_UNWATCH_IOCTL
> +*******************************
> +
> +Name
> +====
> +
> +GPIO_GET_LINEINFO_UNWATCH_IOCTL - Disable watching a line for changes to its
> +requested state and configuration information.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_GET_LINEINFO_UNWATCH_IOCTL
> +
> +``int ioctl(int chip_fd, GPIO_GET_LINEINFO_UNWATCH_IOCTL, u32 *offset)``
> +
> +Arguments
> +=========
> +
> +``chip_fd``
> + The file descriptor of the GPIO character device returned by `open()`.
> +
> +``offset``
> + The offset of the line to no longer watch.
> +
> +Description
> +===========
> +
> +Remove the line from the list of lines being watched on this ``chip_fd``.
> +
> +This is the opposite of gpio-v2-get-lineinfo-watch-ioctl.rst (v2) and
> +gpio-get-lineinfo-watch-ioctl.rst (v1).
> +
> +Unwatching a line that is not watched is an error (**EBUSY**).
> +
> +Return Value
> +============
> +
> +On success 0.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
> new file mode 100644
> index 000000000000..4259c08779c1
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-get-line-ioctl.rst
> @@ -0,0 +1,99 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_GET_LINE_IOCTL:
> +
> +**********************
> +GPIO_V2_GET_LINE_IOCTL
> +**********************
> +
> +Name
> +====
> +
> +GPIO_V2_GET_LINE_IOCTL - Request a line or lines from the kernel.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_V2_GET_LINE_IOCTL
> +
> +``int ioctl(int chip_fd, GPIO_V2_GET_LINE_IOCTL, struct gpio_v2_line_request *request)``
> +
> +Arguments
> +=========
> +
> +``chip_fd``
> + The file descriptor of the GPIO character device returned by `open()`.
> +
> +``request``
> + The :c:type:`line_request<gpio_v2_line_request>` specifying the lines
> + to request and their configuration.
> +
> +Description
> +===========
> +
> +On success, the requesting process is granted exclusive access to the line
> +value, write access to the line configuration, and may receive events when
> +edges are detected on the line, all of which are described in more detail in
> +:ref:`gpio-v2-line-request`.
> +
> +A number of lines may be requested in the one line request, and request
> +operations are performed on the requested lines by the kernel as atomically
> +as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
> +requested lines at once.
> +
> +The state of a line, including the value of output lines, is guaranteed to
> +remain as requested until the returned file descriptor is closed. Once the
> +file descriptor is closed, the state of the line becomes uncontrolled from
> +the userspace perspective, and may revert to its default state.
At the behest of the line driver? (an example of a line driver that
has good reason
for reverting might be useful here, to indicate that in the general
case the user
cannot assume the state of unclaimed lines)
> +
> +Closing the ``chip_fd`` has no effect on existing line requests.
> +
> +.. _gpio-v2-get-line-config-rules:
> +
> +Configuration Rules
> +-------------------
> +
> +For any given requested line, the following configuration rules apply:
> +
> +The direction flags, ``GPIO_V2_LINE_FLAG_INPUT`` and
> +``GPIO_V2_LINE_FLAG_OUTPUT``, cannot be combined. If neither are set then
> +the only other flag that may be set is ``GPIO_V2_LINE_FLAG_ACTIVE_LOW``
> +and the line is requested "as-is" to allow reading of the line value
> +without altering the electrical configuration.
> +
> +The drive flags, ``GPIO_V2_LINE_FLAG_OPEN_xxx``, require the
> +``GPIO_V2_LINE_FLAG_OUTPUT`` to be set.
> +Only one drive flag may be set.
> +If none are set then the line is assumed push-pull.
> +
> +Only one bias flag, ``GPIO_V2_LINE_FLAG_BIAS_xxx``, may be set, and it
> +requires a direction flag to also be set.
> +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.
> +
> +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``.
> +The ``GPIO_V2_LINE_FLAG_EVENT_CLOCK_HTE`` flag requires supporting hardware
> +and a kernel with ``CONFIG_HTE`` set. Requesting HTE from a device that
> +doesn't support it is an error (**EOPNOTSUP**).
> +
> +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.
> +
> +Requesting an invalid configuration is an error (**EINVAL**).
> +
> +Return Value
> +============
> +
> +On success 0 and the :c:type:`request.fd<gpio_v2_line_request>` contains the
> +file descriptor for the request.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
> new file mode 100644
> index 000000000000..bc4d8df887d4
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-ioctl.rst
> @@ -0,0 +1,50 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_GET_LINEINFO_IOCTL:
> +
> +**************************
> +GPIO_V2_GET_LINEINFO_IOCTL
> +**************************
> +
> +Name
> +====
> +
> +GPIO_V2_GET_LINEINFO_IOCTL - Get the publicly available information for a line.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_V2_GET_LINEINFO_IOCTL
> +
> +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_IOCTL, struct gpio_v2_line_info *info)``
> +
> +Arguments
> +=========
> +
> +``chip_fd``
> + The file descriptor of the GPIO character device returned by `open()`.
> +
> +``info``
> + The :c:type:`line_info<gpio_v2_line_info>` to be populated, with the
> + ``offset`` field set to indicate the line to be collected.
> +
> +Description
> +===========
> +
> +Get the publicly available information for a line.
> +
> +This information is available independent of whether the line is in use.
> +
> +.. note::
> + The line info does not include the line value.
> +
> + The line must be requested using gpio-v2-get-line-ioctl.rst to access its
> + value.
> +
> +Return Value
> +============
> +
> +On success 0 and ``info`` is populated with the chip info.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
> new file mode 100644
> index 000000000000..938ff85a9322
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-get-lineinfo-watch-ioctl.rst
> @@ -0,0 +1,67 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_GET_LINEINFO_WATCH_IOCTL:
> +
> +********************************
> +GPIO_V2_GET_LINEINFO_WATCH_IOCTL
> +********************************
> +
> +Name
> +====
> +
> +GPIO_V2_GET_LINEINFO_WATCH_IOCTL - Enable watching a line for changes to its
> +request state and configuration information.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_V2_GET_LINEINFO_WATCH_IOCTL
> +
> +``int ioctl(int chip_fd, GPIO_V2_GET_LINEINFO_WATCH_IOCTL, struct gpio_v2_line_info *info)``
> +
> +Arguments
> +=========
> +
> +``chip_fd``
> + The file descriptor of the GPIO character device returned by `open()`.
> +
> +``info``
> + The :c:type:`line_info<gpio_v2_line_info>` struct to be populated, with
> + the ``offset`` set to indicate the line to watch
> +
> +Description
> +===========
> +
> +Enable watching a line for changes to its request state and configuration
> +information. Changes to line info include a line being requested, released
> +or reconfigured.
> +
> +.. note::
> + Watching line info is not generally required, and would typically only be
> + used by a system monitoring component.
> +
> + The line info does NOT include the line value.
> + The line must be requested using gpio-v2-get-line-ioctl.rst to access
> + its value, and the line request can monitor a line for events using
> + gpio-v2-line-event-read.rst.
> +
> +By default all lines are unwatched when the GPIO chip is opened.
> +
> +Multiple lines may be watched simultaneously by adding a watch for each.
> +
> +Once a watch is set, any changes to line info will generate events which can be
> +read from the ``chip_fd`` as described in
> +gpio-v2-lineinfo-changed-read.rst.
> +
> +Adding a watch to a line that is already watched is an error (**EBUSY**).
> +
> +Watches are specific to the ``chip_fd`` and are independent of watches
> +on the same GPIO chip opened with a separate call to `open()`.
> +
> +Return Value
> +============
> +
> +On success 0 and ``info`` is populated with the current line info.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
> new file mode 100644
> index 000000000000..6513c23fb7ca
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
> @@ -0,0 +1,83 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_LINE_EVENT_READ:
> +
> +***********************
> +GPIO_V2_LINE_EVENT_READ
> +***********************
> +
> +Name
> +====
> +
> +GPIO_V2_LINE_EVENT_READ - Read edge detection events for lines from a request.
> +
> +Synopsis
> +========
> +
> +``int read(int req_fd, void *buf, size_t count)``
> +
> +Arguments
> +=========
> +
> +``req_fd``
> + The file descriptor of the GPIO character device, as returned in the
> + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
> +
> +``buf``
> + The buffer to contain the :c:type:`events<gpio_v2_line_event>`.
> +
> +``count``
> + The number of bytes available in ``buf``, which must be at
> + least the size of a :c:type:`gpio_v2_line_event`.
> +
> +Description
> +===========
> +
> +Read edge detection events for lines from a request.
> +
> +Edge detection must be enabled for the input line using either
> +``GPIO_V2_LINE_FLAG_EDGE_RISING`` or ``GPIO_V2_LINE_FLAG_EDGE_FALLING``, or
> +both. Edge events are then generated whenever edge interrupts are detected on
> +the input line.
> +
> +The kernel captures and timestamps edge events as close as possible to their
> +occurrence and stores them in a buffer from where they can be read by
> +userspace at its convenience using `read()`.
> +
> +Events read from the buffer are always in the same order that they were
> +detected by the kernel, including when multiple lines are being monitored by
> +the one request.
> +
> +The size of the kernel event buffer is fixed at the time of line request
> +creation, and can be influenced by the
> +:c:type:`request.event_buffer_size<gpio_v2_line_request>`.
> +The default size is 16 times the number of lines requested.
This might explain why I could never quite get high-speed pulse counting to feel
right. Thank you!
> +
> +The buffer may overflow if bursts of events occur quicker than they are read
> +by userspace. If an overflow occurs then the oldest buffered event is
> +discarded. Overflow can be detected from userspace by monitoring the event
> +sequence numbers.
> +
> +To minimize the number of calls required to copy events from the kernel to
> +userspace, `read()` supports copying multiple events. The number of events
> +copied is the lower of the number available in the kernel buffer and the
> +number that will fit in the userspace buffer (``buf``).
> +
> +Changing the edge detection flags using gpio-v2-line-set-config-ioctl.rst
> +does not remove or modify the events already contained in the kernel event
> +buffer.
> +
> +The `read()` will block if no event is available and the ``req_fd`` has not
> +been set **O_NONBLOCK**.
> +
> +The presence of an event can be tested for by checking that the ``req_fd`` is
> +readable using `poll()` or an equivalent.
> +
> +Return Value
> +============
> +
> +On success the number of bytes read, which will be a multiple of the size of a
> +:c:type:`gpio_v2_line_event` event.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
> new file mode 100644
> index 000000000000..e4e74a1926d8
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
> @@ -0,0 +1,51 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_LINE_GET_VALUES_IOCTL:
> +
> +*****************************
> +GPIO_V2_LINE_GET_VALUES_IOCTL
> +*****************************
> +
> +Name
> +====
> +
> +GPIO_V2_LINE_GET_VALUES_IOCTL - Get the values of requested lines.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_V2_LINE_GET_VALUES_IOCTL
> +
> +``int ioctl(int req_fd, GPIO_V2_LINE_GET_VALUES_IOCTL, struct gpio_v2_line_values *values)``
> +
> +Arguments
> +=========
> +
> +``req_fd``
> + The file descriptor of the GPIO character device, as returned in the
> + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
> +
> +``values``
> + The :c:type:`line_values<gpio_v2_line_values>` to get with the ``mask`` set
> + to indicate the subset of requested lines to get.
> +
> +Description
> +===========
> +
> +Get the values of requested lines.
> +
> +The values of both input and output lines may be read.
> +
> +For output lines, the value returned is driver and configuration dependent and
> +may be either the output buffer (the last requested value set) or the input
> +buffer (the actual level of the line), and depending on the hardware and
> +configuration these may differ.
> +
> +Return Value
> +============
> +
> +On success 0 and the corresponding :c:type:`values.bits<gpio_v2_line_values>`
> +contain the value read.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
> new file mode 100644
> index 000000000000..126c2626ba6b
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-config-ioctl.rst
> @@ -0,0 +1,57 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_LINE_SET_CONFIG_IOCTL:
> +
> +*****************************
> +GPIO_V2_LINE_SET_CONFIG_IOCTL
> +*****************************
> +
> +Name
> +====
> +
> +GPIO_V2_LINE_SET_CONFIG_IOCTL - Update the configuration of previously requested lines.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_V2_LINE_SET_CONFIG_IOCTL
> +
> +``int ioctl(int req_fd, GPIO_V2_LINE_SET_CONFIG_IOCTL, struct gpio_v2_line_config *config)``
> +
> +Arguments
> +=========
> +
> +``req_fd``
> + The file descriptor of the GPIO character device, as returned in the
> + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
> +
> +``config``
> + The new :c:type:`configuration<gpio_v2_line_config>` to apply to the
> + requested lines.
> +
> +Description
> +===========
> +
> +Update the configuration of previously requested lines, without releasing the
> +line or introducing potential glitches.
Is this guaranteed by all line drivers?
> +
> +The new configuration must specify the configuration of all requested lines.
> +
> +The same :ref:`gpio-v2-get-line-config-rules` 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 also be used to
> +dynamically control edge detection, or more generally move lines seamlessly
> +from one configuration state to another.
> +
> +To only change the value of output lines, use
> +gpio-v2-line-set-values-ioctl.rst.
> +
> +Return Value
> +============
> +
> +On success 0.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
> new file mode 100644
> index 000000000000..6d2d1886950b
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
> @@ -0,0 +1,47 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_LINE_SET_VALUES_IOCTL:
> +
> +*****************************
> +GPIO_V2_LINE_SET_VALUES_IOCTL
> +*****************************
> +
> +Name
> +====
> +
> +GPIO_V2_LINE_SET_VALUES_IOCTL - Set the values of requested output lines.
> +
> +Synopsis
> +========
> +
> +.. c:macro:: GPIO_V2_LINE_SET_VALUES_IOCTL
> +
> +``int ioctl(int req_fd, GPIO_V2_LINE_SET_VALUES_IOCTL, struct gpio_v2_line_values *values)``
> +
> +Arguments
> +=========
> +
> +``req_fd``
> + The file descriptor of the GPIO character device, as returned in the
> + :c:type:`request.fd<gpio_v2_line_request>` by gpio-v2-get-line-ioctl.rst.
> +
> +``values``
> + The :c:type:`line_values<gpio_v2_line_values>` to set with the ``mask`` set
> + to indicate the subset of requested lines to set and ``bits`` set to
> + indicate the new value.
> +
> +Description
> +===========
> +
> +Set the values of requested output lines.
> +
> +Only the values of output lines may be set.
> +Attempting to set the value of an input line is an error (**EPERM**).
User beware if they come from some cursed ecosystem where writing a value
to an input line sets or enables/disables the bias,
eg: https://www.arduino.cc/reference/en/language/functions/digital-io/digitalwrite/
> +
> +Return Value
> +============
> +
> +On success 0.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
> new file mode 100644
> index 000000000000..24ad325e7253
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/gpio-v2-lineinfo-changed-read.rst
> @@ -0,0 +1,81 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +.. _GPIO_V2_LINEINFO_CHANGED_READ:
> +
> +*****************************
> +GPIO_V2_LINEINFO_CHANGED_READ
> +*****************************
> +
> +Name
> +====
> +
> +GPIO_V2_LINEINFO_CHANGED_READ - Read line info changed events for watched
> +lines from the chip.
> +
> +Synopsis
> +========
> +
> +``int read(int chip_fd, void *buf, size_t count)``
> +
> +Arguments
> +=========
> +
> +``chip_fd``
> + The file descriptor of the GPIO character device returned by `open()`.
> +
> +``buf``
> + The buffer to contain the :c:type:`events<gpio_v2_line_info_changed>`.
> +
> +``count``
> + The number of bytes available in ``buf``, which must be at least the size
> + of a :c:type:`gpio_v2_line_info_changed` event.
> +
> +Description
> +===========
> +
> +Read line info changed events for watched lines from the chip.
> +
> +.. note::
> + Monitoring line info changes is not generally required, and would typically
> + only be performed by a system monitoring component.
> +
> + These events relate to changes in a line's request state or configuration,
> + not its value. Use gpio-v2-line-event-read.rst to receive events when a
> + line changes value.
> +
> +A line must be watched using gpio-v2-get-lineinfo-watch-ioctl.rst to generate
> +info changed events. Subsequently, a request, release, or reconfiguration
> +of the line will generate an info changed event.
> +
> +The kernel timestamps events when they occur and stores them in a buffer
> +from where they can be read by userspace at its convenience using `read()`.
> +
> +The size of the kernel event buffer is fixed at 32 events per ``chip_fd``.
> +
> +The buffer may overflow if bursts of events occur quicker than they are read
> +by userspace. If an overflow occurs then the most recent event is discarded.
> +Overflow cannot be detected from userspace.
> +
> +Events read from the buffer are always in the same order that they were
> +detected by the kernel, including when multiple lines are being monitored by
> +the one ``chip_fd``.
> +
> +To minimize the number of calls required to copy events from the kernel to
> +userspace, `read()` supports copying multiple events. The number of events
> +copied is the lower of the number available in the kernel buffer and the
> +number that will fit in the userspace buffer (``buf``).
> +
> +A `read()` will block if no event is available and the ``chip_fd`` has not
> +been set **O_NONBLOCK**.
> +
> +The presence of an event can be tested for by checking that the ``chip_fd`` is
> +readable using `poll()` or an equivalent.
> +
> +Return Value
> +============
> +
> +On success the number of bytes read, which will be a multiple of the size
> +of a :c:type:`gpio_v2_line_info_changed` event.
> +
> +On error -1 and the ``errno`` variable is set appropriately.
> +Common error codes are described in error-codes.rst.
> diff --git a/Documentation/userspace-api/gpio/index.rst b/Documentation/userspace-api/gpio/index.rst
> new file mode 100644
> index 000000000000..072b9fa18aea
> --- /dev/null
> +++ b/Documentation/userspace-api/gpio/index.rst
> @@ -0,0 +1,17 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +====
> +GPIO
> +====
> +
> +.. toctree::
> + :maxdepth: 1
> +
> + Character Device Userspace API <chardev>
> +
> +.. only:: subproject and html
> +
> + Indices
> + =======
> +
> + * :ref:`genindex`
> diff --git a/Documentation/userspace-api/index.rst b/Documentation/userspace-api/index.rst
> index 031df47a7c19..8e174a605f69 100644
> --- a/Documentation/userspace-api/index.rst
> +++ b/Documentation/userspace-api/index.rst
> @@ -25,6 +25,7 @@ place where this information is gathered.
> dma-buf-alloc-exchange
> ebpf/index
> ELF
> + gpio/index
> ioctl/index
> iommu
> iommufd
> --
> 2.39.2
>
>
--
Philip Howard
On Wed, Jan 10, 2024 at 1:40 PM Phil Howard <[email protected]> wrote:
> On Tue, 9 Jan 2024 at 14:00, Kent Gibson <[email protected]> wrote:
..
> > + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
> > + kernel wheels in userspace.
>
> I realise this is in part an emotional response, but very much
> "citation needed" on
> this one. While I believe Kernel drivers for things are a good idea, I
> don't believe
> userspace libraries are necessarily bad or wrong. They might be the first
> experience a future kernel dev has with hardware. Either way there are multiple
> ecosystems of userspace drivers both existing and thriving right now, and there
> are good reasons to reinvent kernel wheels in userspace.
>
> At least some of these reasons relate to the (incorrectly assumed)
> insurmountable
> nature of kernel development vs just throwing together some Python. Including
> this loaded language just serves to reinforce that.
>
> You catch more flies with honey than with vinegar, so I'd probably soften to:
>
> Before abusing userspace APIs to bitbash drivers for your hardware you should
> read Documentation/driver-api/gpio/drivers-on-gpio.rst to see if your device has
> an existing kernel driver. If not, please consider contributing one.
I believe this note was motivated by the quite popular pyGPIO for RPi
and MRAA for some platforms, which are the examples of how _not_ do
things.
..
> > +Each chip supports a number of GPIO lines,
> > +:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
> > +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
>
> I don't recognise this syntax "`[0,chip.lines)`", typo, or me being clueless?
It's called "open interval", a mathematical term.
..
> > + - - ``EFAULT``
Wondering if these constants can be referenced via % and if it makes sense.
..
> > +The size of the kernel event buffer is fixed at the time of line request
> > +creation, and can be influenced by the
> > +:c:type:`request.event_buffer_size<gpio_v2_line_request>`.
> > +The default size is 16 times the number of lines requested.
>
> This might explain why I could never quite get high-speed pulse counting to feel
> right. Thank you!
GPIO is just not a good tool for this kind of measurement.
--
With Best Regards,
Andy Shevchenko
On Wed, Jan 10, 2024 at 11:40:34AM +0000, Phil Howard wrote:
[snip]
> > +
> > +===================================
> > +GPIO Character Device Userspace API
> > +===================================
> > +
> > +This is latest version (v2) of the character device API, as defined in
> > +``include/uapi/linux/gpio.h.``
> > +
> > +.. note::
> > + Do NOT abuse userspace APIs to control hardware that has proper kernel
> > + drivers. There may already be a driver for your use case, and an existing
> > + kernel driver is sure to provide a superior solution to bitbashing
> > + from userspace.
> > +
> > + Read Documentation/driver-api/gpio/drivers-on-gpio.rst to avoid reinventing
> > + kernel wheels in userspace.
>
> I realise this is in part an emotional response, but very much
> "citation needed" on
> this one.
> While I believe Kernel drivers for things are a good idea, I
> don't believe
> userspace libraries are necessarily bad or wrong. They might be the first
> experience a future kernel dev has with hardware. Either way there are multiple
> ecosystems of userspace drivers both existing and thriving right now, and there
> are good reasons to reinvent kernel wheels in userspace.
>
What I stated is kernel policy as I understand it.
What you describe is what I would consider to be prototyping.
If you want play with bitbashing SPI, or whatever, go knock yourself out.
If you want to release that in a product then you really should
be using the kernel driver if one is available.
Bitbashing should be the last resort.
> At least some of these reasons relate to the (incorrectly assumed)
> insurmountable
> nature of kernel development vs just throwing together some Python. Including
> this loaded language just serves to reinforce that.
>
> You catch more flies with honey than with vinegar, so I'd probably soften to:
>
> Before abusing userspace APIs to bitbash drivers for your hardware you should
> read Documentation/driver-api/gpio/drivers-on-gpio.rst to see if your device has
> an existing kernel driver. If not, please consider contributing one.
>
The note is is a rewording of a section of the existing sysfs documentation:
DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
PLEASE READ THE DOCUMENT AT Subsystem drivers using GPIO TO AVOID REINVENTING
KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
So I've already toned down the vineger.
And your suggestion seems at odds with your earlier argument - we should suggest
that such a user write a kernel driver??
> > +
> > + Similarly, for multi-function lines there may be other subsystems, such as
> > + Documentation/spi/index.rst, Documentation/i2c/index.rst,
> > + Documentation/driver-api/pwm.rst, Documentation/w1/index.rst etc, that
> > + provide suitable drivers and APIs for your hardware.
>
> This is good, people trying to do PWM via userspace bitbashing on arbitrary pins
> (sometimes we really do just want to dim a bunch of LEDs without the cost of an
> extra driver IC) is kind of silly in hindsight. If we steer people
> toward the right
> subsystems, perhaps those can be improved for the benefit of all.
>
Indeed, this paragraph is in response to community discussions, one of
which was looking for a something official that says this.
Now there is one.
> > +
> > +Basic examples using the character device API can be found in ``tools/gpio/*``.
> > +
> > +The API is based around two major objects, the :ref:`gpio-v2-chip` and the
> > +:ref:`gpio-v2-line-request`.
> > +
> > +.. _gpio-v2-chip:
> > +
> > +Chip
> > +====
> > +
> > +The Chip represents a single GPIO chip and is exposed to userspace using device
> > +files of the form ``/dev/gpiochipX``.
>
> Is it worth clarifying that - afaik - the numbering of these device
> files is or can
> be arbitrary? Or, in the opposite case, that the order is guaranteed
> by the vendor's
> device tree configuration?
>
I consider that outside the scope of the API.
> > +
> > +Each chip supports a number of GPIO lines,
> > +:c:type:`chip.lines<gpiochip_info>`. Lines on the chip are identified by an
> > +``offset`` in the range from 0 to ``chip.lines - 1``, i.e. `[0,chip.lines)`.
>
> I don't recognise this syntax "`[0,chip.lines)`", typo, or me being clueless?
>
Sadly the latter.
To exand on Andy's response, within the notation '[' and ']' are inclusive,
'(' and ')' are exclusive.
Too esoteric?
[snip]
> > + - - ``EBUSY``
> > +
> > + - The ioctl can't be handled because the device is busy. Typically
> > + returned when an ioctl attempts something that would require the
> > + usage of a resource that was already allocated. The ioctl must not
> > + be retried without performing another action to fix the problem
> > + first.
>
> eg: When a line is already claimed by another process?
>
My preference would be to put a note in the appropriate ioctl than provide
specific examples in the error codes.
The descriptions here should remain general.
That one probably should be explicitly stated in GPIO_V2_GET_LINE_IOCTL.
[snip]
> > +Description
> > +===========
> > +
> > +On success, the requesting process is granted exclusive access to the line
> > +value, write access to the line configuration, and may receive events when
> > +edges are detected on the line, all of which are described in more detail in
> > +:ref:`gpio-v2-line-request`.
> > +
> > +A number of lines may be requested in the one line request, and request
> > +operations are performed on the requested lines by the kernel as atomically
> > +as possible. e.g. gpio-v2-line-get-values-ioctl.rst will read all the
> > +requested lines at once.
> > +
> > +The state of a line, including the value of output lines, is guaranteed to
> > +remain as requested until the returned file descriptor is closed. Once the
> > +file descriptor is closed, the state of the line becomes uncontrolled from
> > +the userspace perspective, and may revert to its default state.
>
> At the behest of the line driver? (an example of a line driver that
> has good reason
> for reverting might be useful here, to indicate that in the general
> case the user
> cannot assume the state of unclaimed lines)
>
I've tried to keep the kernel a black box from the userspace perspective.
And the sentence explicitly includes "from the userspace perspective"
for that reason.
Where I do provide details of the internal workings it remains high
level - "the kernel does this".
I do not want to go into the detais of kernel internal components here
- out of scope.
[snip]
> > +
> > +Description
> > +===========
> > +
> > +Update the configuration of previously requested lines, without releasing the
> > +line or introducing potential glitches.
>
> Is this guaranteed by all line drivers?
>
I'm not sure anything is guaranteed by all the line drivers ;-).
But, AIUI, we should be all good. AFAIAA, and I stand to be corrected if I'm
wrong, none of the actions we perform on the driver would trigger a glitch
unless the driver is buggy.
It certainly wont glitch output line values like releasing and requesting
the line with the new config could - and that is independent of driver.
[snip]
> > +Description
> > +===========
> > +
> > +Set the values of requested output lines.
> > +
> > +Only the values of output lines may be set.
> > +Attempting to set the value of an input line is an error (**EPERM**).
>
> User beware if they come from some cursed ecosystem where writing a value
> to an input line sets or enables/disables the bias,
>
> eg: https://www.arduino.cc/reference/en/language/functions/digital-io/digitalwrite/
>
Everything there boggles the mind.
How does this API do anything that such a user needs to "beware" of?
Here if they use their janky overloading behaviour they get an error and
have to switch to the correct knob. Is that scary ;-).
Cheers,
Kent.
On Wed, Jan 10, 2024 at 2:02 PM Kent Gibson <[email protected]> wrote:
> On Wed, Jan 10, 2024 at 11:40:34AM +0000, Phil Howard wrote:
> > You catch more flies with honey than with vinegar, so I'd probably soften to:
> >
> > Before abusing userspace APIs to bitbash drivers for your hardware you should
> > read Documentation/driver-api/gpio/drivers-on-gpio.rst to see if your device has
> > an existing kernel driver. If not, please consider contributing one.
> >
>
> The note is is a rewording of a section of the existing sysfs documentation:
>
> DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
> PLEASE READ THE DOCUMENT AT Subsystem drivers using GPIO TO AVOID REINVENTING
> KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
>
> So I've already toned down the vineger.
I wrote that and I recognized the strong wording.
I have come with great regret to the conclusion that it is better to
shout like this,
note that the sentence is not directed to any specific person and that means
it is more OK to be harsh. It is not feedback to anyone, it is black-and-yellow
warning tape to not go into this dangerous area.
I like the current wording.
Yours,
Linus Walleij
On Wed, Jan 10, 2024 at 03:27:50PM +0100, Linus Walleij wrote:
> On Wed, Jan 10, 2024 at 2:02 PM Kent Gibson <[email protected]> wrote:
> > On Wed, Jan 10, 2024 at 11:40:34AM +0000, Phil Howard wrote:
>
> > > You catch more flies with honey than with vinegar, so I'd probably soften to:
> > >
> > > Before abusing userspace APIs to bitbash drivers for your hardware you should
> > > read Documentation/driver-api/gpio/drivers-on-gpio.rst to see if your device has
> > > an existing kernel driver. If not, please consider contributing one.
> > >
> >
> > The note is is a rewording of a section of the existing sysfs documentation:
> >
> > DO NOT ABUSE SYSFS TO CONTROL HARDWARE THAT HAS PROPER KERNEL DRIVERS.
> > PLEASE READ THE DOCUMENT AT Subsystem drivers using GPIO TO AVOID REINVENTING
> > KERNEL WHEELS IN USERSPACE. I MEAN IT. REALLY.
> >
> > So I've already toned down the vineger.
>
> I wrote that and I recognized the strong wording.
>
> I have come with great regret to the conclusion that it is better to
> shout like this,
> note that the sentence is not directed to any specific person and that means
> it is more OK to be harsh. It is not feedback to anyone, it is black-and-yellow
> warning tape to not go into this dangerous area.
>
> I like the current wording.
>
Can you clarify which current wording?
Are you ok with the proposed chardev wording, or should I be more
closely following the sysfs?
Cheers,
Kent.
On Wed, Jan 10, 2024 at 3:34 PM Kent Gibson <[email protected]> wrote:
> On Wed, Jan 10, 2024 at 03:27:50PM +0100, Linus Walleij wrote:
> > I like the current wording.
>
> Can you clarify which current wording?
> Are you ok with the proposed chardev wording, or should I be more
> closely following the sysfs?
I think what you have in the current patch looks great.
Reviewed-by: Linus Walleij <[email protected]>
Yours,
Linus Walleij
On Wed, Jan 10, 2024 at 03:50:36PM +0100, Linus Walleij wrote:
> On Wed, Jan 10, 2024 at 3:34 PM Kent Gibson <[email protected]> wrote:
> > On Wed, Jan 10, 2024 at 03:27:50PM +0100, Linus Walleij wrote:
>
> > > I like the current wording.
> >
> > Can you clarify which current wording?
> > Are you ok with the proposed chardev wording, or should I be more
> > closely following the sysfs?
>
> I think what you have in the current patch looks great.
> Reviewed-by: Linus Walleij <[email protected]>
>
Thanks - that is what I was hoping you meant but wanted to be 100% sure.
Cheers,
Kent.
On Wed, Jan 10, 2024 at 01:10:51PM +0200, Andy Shevchenko wrote:
> On Wed, Jan 10, 2024 at 10:16 AM Vegard Nossum <[email protected]> wrote:
> > On 10/01/2024 00:45, Kent Gibson wrote:
> > > On Tue, Jan 09, 2024 at 10:00:26PM +0200, Andy Shevchenko wrote:
> > >> On Tue, Jan 9, 2024 at 4:00 PM Kent Gibson <[email protected]> wrote:
> > >>
> > >> May we actually state in the documentation that sysfs is subject to
> > >> remove at some point?
> > >
> > > So formally define what "deprecated" means?
> > > Is that covered in the higher level documentation somewhere?
> > > If so I'm more than happy to provide a reference.
> >
> > We have a few files that may be relevant here, that I'm aware of:
> >
> > 1) https://docs.kernel.org/admin-guide/sysfs-rules.html
> >
> > documents some general assumptions that userspace can make about the
> > stability of sysfs and its files
> >
> > 2) https://docs.kernel.org/admin-guide/abi.html
> >
> > This is the public-facing, somewhat machine-readable repository of what
> > is supposed to be the kernel's ABI/API, including "obsolete" and
> > "removed" interfaces.
> >
> > 3) Documentation/ABI/README
> >
> > describes the process of deprecating an interface
>
> Yes and GPIO currently is under obsolete section with also this:
>
> "This ABI is deprecated and will be removed after 2020. It is replaced
> with the GPIO character device."
>
> https://docs.kernel.org/admin-guide/abi-obsolete.html#symbols-under-sys-class
>
> So, proposed cleanup series should probably rely on this documentation
> among other existing descriptions of sysfs GPIO.
>
The sysfs doc already references the doc (sysfs-gpio) that generates the
HTML that link points to, so not sure what to change.
I can't include a direct reference to the HTML, AFAICT, as that HTML is
generated using kernel-abi makefile magic so the usual doc path
cross-references don't work - you just get the path as plain text.
If there is some way to provide a cross-reference that generates to that
link then I'll change it, but I don't know how.
>>> + - - ``EFAULT``
> Wondering if these constants can be referenced via % and if it makes sense.
That would be great and I do want to do that, particularly for the
uAPI v1 docs that use a lot of consts rather than enums, but, AFAICT, you
can't create cross-references for consts, you can only add formatting[1].
And the % formatting only works in kernel-doc, in rst you have to add it
explicitly yourself, hence the ``EFAULT`` .
Cheers,
Kent.
[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#highlights-and-cross-references
On Tue, Jan 09, 2024 at 09:59:45PM +0800, Kent Gibson wrote:
> My new year's resolution was to improve the documentation of the
> character device API and gpio in general, so here we are.
>
>
> Patch 2 relocates the sysfs API doc to stress its deprecation by
> moving it to a new deprecated section, again in userspace-api but
> with a similar section in the admin-guide. The deprecated section
> also provides a placeholder for subsequent changes.
>
While preparing the v2 version of this series, I'm now wondering
if this should be changed to "obsolete" rather than "deprecated", to
better fit with the interface lifecycle, to indicate there is an
alternative, and to emphasise that it is scheduled for removal.
i.e. from a userspace perspective "obsolete" is the clearer term.
Is that a change worth making?
Cheers,
Kent.
On Sun, Jan 14, 2024 at 4:47 AM Kent Gibson <[email protected]> wrote:
> On Tue, Jan 09, 2024 at 09:59:45PM +0800, Kent Gibson wrote:
> > My new year's resolution was to improve the documentation of the
> > character device API and gpio in general, so here we are.
..
> While preparing the v2 version of this series, I'm now wondering
> if this should be changed to "obsolete" rather than "deprecated", to
> better fit with the interface lifecycle, to indicate there is an
> alternative, and to emphasise that it is scheduled for removal.
> i.e. from a userspace perspective "obsolete" is the clearer term.
>
> Is that a change worth making?
From my p.o.v. yes, as it makes it consistent with what we already
have in the sysfs/obsolete.
--
With Best Regards,
Andy Shevchenko
On Sun, Jan 14, 2024 at 02:01:29PM +0200, Andy Shevchenko wrote:
> On Sun, Jan 14, 2024 at 4:47 AM Kent Gibson <[email protected]> wrote:
> > On Tue, Jan 09, 2024 at 09:59:45PM +0800, Kent Gibson wrote:
> > > My new year's resolution was to improve the documentation of the
> > > character device API and gpio in general, so here we are.
>
> ...
>
> > While preparing the v2 version of this series, I'm now wondering
> > if this should be changed to "obsolete" rather than "deprecated", to
> > better fit with the interface lifecycle, to indicate there is an
> > alternative, and to emphasise that it is scheduled for removal.
> > i.e. from a userspace perspective "obsolete" is the clearer term.
> >
> > Is that a change worth making?
>
> From my p.o.v. yes, as it makes it consistent with what we already
> have in the sysfs/obsolete.
>
Ok then, I'll incorporate it into v2.
Cheers,
Kent.