Skip to contentSkip to conversation

Documentation: gpio: clarify that line values are logical

PATCH Applied Kent Gibson 2 participants 4 messages Jun 10, 2024 – Jun 12, 2024

Subsystems (3)
lore
Share & tools
lore

Kent Gibson

author reviewer
#0 lore raw

cover Documentation: gpio: clarify that line values are logical

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

author reviewer
#1 lore raw

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

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.

---
 .../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(+)
Documentation/userspace-api/gpio/gpio-handle-get-line-values-ioctl.rst +7 -0
index 25263b8f0588..2e3a52c113d5 100644
@@ -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
Documentation/userspace-api/gpio/gpio-handle-set-line-values-ioctl.rst +7 -0
index 0aa05e623a6c..12862132b420 100644
@@ -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**).
 
Documentation/userspace-api/gpio/gpio-v2-line-get-values-ioctl.rst +7 -0
index e4e74a1926d8..d7defd4ca397 100644
@@ -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
Documentation/userspace-api/gpio/gpio-v2-line-set-values-ioctl.rst +7 -0
index 6d2d1886950b..16dd50fc60ca 100644
@@ -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**).
 
Signature · 1 line
2.39.2
author reviewer
#2 lore raw

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

In reply to 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.

---
 .../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(+)
Documentation/userspace-api/gpio/gpio-lineevent-data-read.rst +5 -0
index 68b8d4f9f604..d1e7e2383b0d 100644
@@ -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()`.
Documentation/userspace-api/gpio/gpio-v2-line-event-read.rst +5 -0
index 6513c23fb7ca..1312668e0f6a 100644
@@ -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()`.
Signature · 1 line
2.39.2
#3 lore raw
In reply to Kent Gibson

From: Bartosz Golaszewski <[email protected]>

Quoted 8 lines · 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.

[...]

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,

Signature · 1 line
Bartosz Golaszewski <[email protected]>