[PATCH 0/2] Documentation: gpio: clarify that line values are logical

[PATCH 0/2] Documentation: gpio: clarify that line values are logical

[Kent Gibson]

The line values passed by the GPIO uAPI are logical values, and the edges
returned are based on changes to logical line values.  While the
documentation consistently uses active/inactive terminology to identify
the values as logical, this is never explicitly spelt out.
This series clarifies those points, with paricular emphasis on the
effect the active low flag has on values and edge polarity.

Patch 1 provides clarification for ioctls passing line values.

Patch 2 provides clarification for functions returning edge events.

Cheers,
Kent.

Kent Gibson (2):
  Documentation: gpio: Clarify effect of active low flag on line values
  Documentation: gpio: Clarify effect of active low flag on line edges

 .../gpio/gpio-handle-get-line-values-ioctl.rst             | 7 +++++++
 .../gpio/gpio-handle-set-line-values-ioctl.rst             | 7 +++++++
 .../userspace-api/gpio/gpio-lineevent-data-read.rst        | 5 +++++
 .../userspace-api/gpio/gpio-v2-line-event-read.rst         | 5 +++++
 .../userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst   | 7 +++++++
 .../userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst   | 7 +++++++
 6 files changed, 38 insertions(+)

--
2.39.2

[PATCH 1/2] Documentation: gpio: Clarify effect of active low flag on line values

[Kent Gibson]

The documentation does not make sufficiently clear that the uAPI deals with
logical line values, nor does it describe the influence of the active low
flag on the mapping between physical and logical line values.

Clarify the relationship between physical and logical line values and the
effect of the active low flag for ioctls passing line values.

Suggested-by: David C. Rankin <drankinatty@gmail.com>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 .../gpio/gpio-handle-get-line-values-ioctl.rst             | 7 +++++++
 .../gpio/gpio-handle-set-line-values-ioctl.rst             | 7 +++++++
 .../userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst   | 7 +++++++
 .../userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst   | 7 +++++++
 4 files changed, 28 insertions(+)

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
index 25263b8f0588..2e3a52c113d5 100644
--- a/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst
+++ b/Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst
@@ -36,6 +36,13 @@ Description
 
 Get the values of all requested lines.
 
+The values returned are logical, indicating if the line is active or inactive.
+The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between physical
+values (high/low) and logical values (active/inactive).
+If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then high is active and
+low is inactive. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then low is active
+and high is inactive.
+
 The values of both input and output lines may be read.
 
 For output lines, the value returned is driver and configuration dependent and
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
index 0aa05e623a6c..12862132b420 100644
--- a/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst
+++ b/Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst
@@ -36,6 +36,13 @@ Description
 
 Set the values of all requested output lines.
 
+The values set are logical, indicating if the line is to be active or inactive.
+The ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` flag controls the mapping between logical
+values (active/inactive) and physical values (high/low).
+If  ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is not set then active is high and
+inactive is low. If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is set then active is low
+and inactive is high.
+
 Only the values of output lines may be set.
 Attempting to set the value of input lines is an error (**EPERM**).
 
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
index e4e74a1926d8..d7defd4ca397 100644
--- a/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst
@@ -34,6 +34,13 @@ Description
 
 Get the values of requested lines.
 
+The values returned are logical, indicating if the line is active or inactive.
+The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between physical
+values (high/low) and logical values (active/inactive).
+If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then high is active and low is
+inactive.  If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then low is active and
+high is inactive.
+
 The values of both input and output lines may be read.
 
 For output lines, the value returned is driver and configuration dependent and
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
index 6d2d1886950b..16dd50fc60ca 100644
--- a/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst
@@ -35,6 +35,13 @@ Description
 
 Set the values of requested output lines.
 
+The values set are logical, indicating if the line is to be active or inactive.
+The ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` flag controls the mapping between logical
+values (active/inactive) and physical values (high/low).
+If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is not set then active is high and inactive
+is low.  If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is set then active is low and
+inactive is high.
+
 Only the values of output lines may be set.
 Attempting to set the value of an input line is an error (**EPERM**).
 
-- 
2.39.2

[PATCH 2/2] Documentation: gpio: Clarify effect of active low flag on line edges

[Kent Gibson]

The documentation does not make sufficiently clear that edge polarity is
based on changes to the logical line values, and that the physical
polarity of edges is dependent on the active low flag.

Clarify the relationship between the active low flag and edge polarity
for the functions that read edge events.

Suggested-by: David C. Rankin <drankinatty@gmail.com>
Signed-off-by: Kent Gibson <warthog618@gmail.com>
---
 .../userspace-api/gpio/gpio-lineevent-data-read.rst          | 5 +++++
 Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst | 5 +++++
 2 files changed, 10 insertions(+)

diff --git a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
index 68b8d4f9f604..d1e7e2383b0d 100644
--- a/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
+++ b/Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst
@@ -44,6 +44,11 @@ Edge detection must be enabled for the input line using either
 both. Edge events are then generated whenever edge interrupts are detected on
 the input line.
 
+Edges are defined in terms of changes to the logical line value, so an inactive
+to active transition is a rising edge.  If ``GPIOHANDLE_REQUEST_ACTIVE_LOW`` is
+set then logical polarity is the opposite of physical polarity, and
+``GPIOEVENT_REQUEST_RISING_EDGE`` then corresponds to a falling physical edge.
+
 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()`.
diff --git a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
index 6513c23fb7ca..1312668e0f6a 100644
--- a/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
+++ b/Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst
@@ -40,6 +40,11 @@ Edge detection must be enabled for the input line using either
 both. Edge events are then generated whenever edge interrupts are detected on
 the input line.
 
+Edges are defined in terms of changes to the logical line value, so an inactive
+to active transition is a rising edge.  If ``GPIO_V2_LINE_FLAG_ACTIVE_LOW`` is
+set then logical polarity is the opposite of physical polarity, and
+``GPIO_V2_LINE_FLAG_EDGE_RISING`` then corresponds to a falling physical edge.
+
 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()`.
-- 
2.39.2

Re: [PATCH 0/2] Documentation: gpio: clarify that line values are logical

[Bartosz Golaszewski]

From: Bartosz Golaszewski <bartosz.golaszewski@linaro.org>


On Mon, 10 Jun 2024 17:21:55 +0800, Kent Gibson wrote:
> The line values passed by the GPIO uAPI are logical values, and the edges
> returned are based on changes to logical line values.  While the
> documentation consistently uses active/inactive terminology to identify
> the values as logical, this is never explicitly spelt out.
> This series clarifies those points, with paricular emphasis on the
> effect the active low flag has on values and edge polarity.
> 
> [...]

Applied, thanks!

[1/2] Documentation: gpio: Clarify effect of active low flag on line values
      commit: 5ca84d416e1ca82ca068906fc1386f61a57b17f2
[2/2] Documentation: gpio: Clarify effect of active low flag on line edges
      commit: 08d94c7428680715527757585a6c4575fcf571b9

Best regards,
-- 
Bartosz Golaszewski <bartosz.golaszewski@linaro.org>