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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-Id: <20240610092157.9147-3-warthog618@gmail.com>
Date: Mon, 10 Jun 2024 17:21:57 +0800
From: Kent Gibson <warthog618@...il.com>
To: linux-kernel@...r.kernel.org,
	linux-gpio@...r.kernel.org,
	linux-doc@...r.kernel.org,
	brgl@...ev.pl,
	corbet@....net,
	drankinatty@...il.com
Cc: Kent Gibson <warthog618@...il.com>
Subject: [PATCH 2/2] Documentation: gpio: Clarify effect of active low flag on line edges

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@...il.com>
Signed-off-by: Kent Gibson <warthog618@...il.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