[PATCH v2 0/2] Documentation: ABI: leds: Document shared trigger attributes

[PATCH v2 0/2] Documentation: ABI: leds: Document shared trigger attributes

[Wayne Ho]

The delay_on, delay_off and invert attributes are created by several
LED triggers, but only the oneshot variants are documented. Adding a
separate ABI file per trigger would make get_abi.py report the same
sysfs path as defined more than once, so patch 2 moves these entries
to sysfs-class-led and describes each trigger's behaviour there.

Patch 1 is a small preparatory fix: the existing inverted entry still
mentions the gpio trigger, which no longer creates that attribute.

Checked with tools/docs/get_abi.py validate (no new warnings) and
scripts/checkpatch.pl (clean).

Signed-off-by: Wayne Ho <wayneho219@gmail.com>
---
Changes in v2:
- Capitalize the description after the subject prefix, and reword
  patch 1's subject to start with a verb (Sashiko)
- Add Fixes tag to patch 1 and reference the commit that removed the
  attribute (Griffin)
- Link to v1: https://patch.msgid.link/20261001-docs-leds-abi-trigger-attrs-v1-0-54f0529bf0f6@gmail.com

---
Wayne Ho (2):
      Documentation: ABI: leds: Drop stale gpio trigger reference for inverted
      Documentation: ABI: leds: Document timer, heartbeat and activity attributes

 Documentation/ABI/testing/sysfs-class-led          | 73 +++++++++++++++++++++-
 .../ABI/testing/sysfs-class-led-trigger-oneshot    | 29 ---------
 2 files changed, 70 insertions(+), 32 deletions(-)
---
base-commit: 5dd1818b15d98d4a20806cd00b1b40320b06004f
change-id: 20261001-docs-leds-abi-trigger-attrs-a20ed96981dd

Best regards,
--  
Wayne Ho <wayneho219@gmail.com>

[PATCH v2 1/2] Documentation: ABI: leds: Drop stale gpio trigger reference for inverted

[Wayne Ho]

The description of the inverted attribute says it is specific to the
gpio and backlight triggers, but commit 4a11dbf04f31 ("leds: triggers:
gpio: Rewrite to use trigger-sources") removed it from the gpio trigger,
which now only provides desired_brightness. Only the backlight trigger
creates the inverted attribute today.

Drop the reference to the gpio trigger.

Fixes: 4a11dbf04f31 ("leds: triggers: gpio: Rewrite to use trigger-sources")
Signed-off-by: Wayne Ho <wayneho219@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-led | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index d4c918cc..c72cb1e0 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -84,6 +84,5 @@ KernelVersion:	2.6.38
 Contact:	Richard Purdie <rpurdie@rpsys.net>
 Description:
 		Invert the LED on/off state. This parameter is specific to
-		gpio and backlight triggers. In case of the backlight trigger,
-		it is useful when driving a LED which is intended to indicate
-		a device in a standby like state.
+		the backlight trigger. It is useful when driving a LED which
+		is intended to indicate a device in a standby like state.

-- 
Git-155)

[PATCH v2 2/2] Documentation: ABI: leds: Document timer, heartbeat and activity attributes

[Wayne Ho]

The delay_on and delay_off attributes created by the timer trigger and
the invert attribute created by the heartbeat and activity triggers
are not documented. They share their sysfs paths with the oneshot
trigger attributes, so adding a separate entry per trigger would make
get_abi.py warn about the same path being defined more than once.

Move the delay_on, delay_off and invert entries from
sysfs-class-led-trigger-oneshot to sysfs-class-led and describe the
behaviour of each trigger that creates them.

Signed-off-by: Wayne Ho <wayneho219@gmail.com>
---
 Documentation/ABI/testing/sysfs-class-led          | 68 ++++++++++++++++++++++
 .../ABI/testing/sysfs-class-led-trigger-oneshot    | 29 ---------
 2 files changed, 68 insertions(+), 29 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-class-led b/Documentation/ABI/testing/sysfs-class-led
index c72cb1e0..f438fb83 100644
--- a/Documentation/ABI/testing/sysfs-class-led
+++ b/Documentation/ABI/testing/sysfs-class-led
@@ -86,3 +86,71 @@ Description:
 		Invert the LED on/off state. This parameter is specific to
 		the backlight trigger. It is useful when driving a LED which
 		is intended to indicate a device in a standby like state.
+
+What:		/sys/class/leds/<led>/delay_on
+Date:		March 2006
+KernelVersion:	2.6.17
+Contact:	linux-leds@vger.kernel.org
+Description:
+		This attribute is only present when the LED's trigger is
+		set to "timer" or "oneshot".
+
+		For the "timer" trigger, specifies for how many milliseconds
+		the LED has to stay on in each cycle of a repeating on/off
+		blink. Writing a new value restarts the blink immediately.
+		Defaults to 500 ms.
+
+		For the "oneshot" trigger, specifies for how many
+		milliseconds the LED has to stay at LED_FULL brightness
+		after it has been armed. Defaults to 100 ms.
+
+What:		/sys/class/leds/<led>/delay_off
+Date:		March 2006
+KernelVersion:	2.6.17
+Contact:	linux-leds@vger.kernel.org
+Description:
+		This attribute is only present when the LED's trigger is
+		set to "timer" or "oneshot".
+
+		For the "timer" trigger, specifies for how many milliseconds
+		the LED has to stay off in each cycle of a repeating on/off
+		blink. Writing a new value restarts the blink immediately.
+		Defaults to 500 ms; together with the default delay_on this
+		gives a 1 Hz blink.
+
+		For the "oneshot" trigger, specifies for how many
+		milliseconds the LED has to stay at LED_OFF brightness
+		after it has been armed. Defaults to 100 ms.
+
+What:		/sys/class/leds/<led>/invert
+Date:		Jun 2012
+KernelVersion:	3.6
+Contact:	linux-leds@vger.kernel.org
+Description:
+		This attribute is only present when the LED's trigger is
+		set to "oneshot", "heartbeat" or "activity". Any non-zero
+		value written is stored as 1, so reading it back returns
+		0 or 1.
+
+		For the "oneshot" trigger, reverses the blink logic. If set
+		to 0 (default) blink on for delay_on ms, then blink off for
+		delay_off ms, leaving the LED normally off. If set to 1,
+		blink off for delay_off ms, then blink on for delay_on ms,
+		leaving the LED normally on. Setting this value also
+		immediately changes the LED state.
+
+		For the "heartbeat" trigger, inverts the heartbeat pattern.
+		If set to 0 (default) the LED stays off most of the time and
+		blinks briefly on. If set to 1 the LED stays on most of the
+		time and blinks briefly off. Unlike "oneshot", the new value
+		only takes effect at the next phase of the pattern.
+
+		For the "activity" trigger, inverts the on/off states of the
+		CPU activity blink. If set to 0 (default) the LED is mostly
+		off when the system is idle and stays on longer as CPU usage
+		grows. If set to 1 the LED is mostly on when idle and stays
+		off longer as CPU usage grows. The new value only takes
+		effect at the next on/off transition.
+
+		This is unrelated to the /sys/class/leds/<led>/inverted
+		attribute, which is specific to the backlight trigger.
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
index 378a3a4d..3532f13d 100644
--- a/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-oneshot
@@ -1,32 +1,3 @@
-What:		/sys/class/leds/<led>/delay_on
-Date:		Jun 2012
-KernelVersion:	3.6
-Contact:	linux-leds@vger.kernel.org
-Description:
-		Specifies for how many milliseconds the LED has to stay at
-		LED_FULL brightness after it has been armed.
-		Defaults to 100 ms.
-
-What:		/sys/class/leds/<led>/delay_off
-Date:		Jun 2012
-KernelVersion:	3.6
-Contact:	linux-leds@vger.kernel.org
-Description:
-		Specifies for how many milliseconds the LED has to stay at
-		LED_OFF brightness after it has been armed.
-		Defaults to 100 ms.
-
-What:		/sys/class/leds/<led>/invert
-Date:		Jun 2012
-KernelVersion:	3.6
-Contact:	linux-leds@vger.kernel.org
-Description:
-		Reverse the blink logic. If set to 0 (default) blink on for
-		delay_on ms, then blink off for delay_off ms, leaving the LED
-		normally off. If set to 1, blink off for delay_off ms, then
-		blink on for delay_on ms, leaving the LED normally on.
-		Setting this value also immediately changes the LED state.
-
 What:		/sys/class/leds/<led>/shot
 Date:		Jun 2012
 KernelVersion:	3.6

-- 
Git-155)