[RFC PATCH v2 01/10] docs: Add block device LED trigger documentation

[Ian Pilcher]

Add Documentation/ABI/testing/sysfs-class-led-trigger-blkdev to
document:

  * /sys/class/leds/<led>/blink_on
  * /sys/class/leds/<led>/blink_off
  * /sys/class/leds/<led>/block_devices

Add /sys/block/<disk>/led to Documentation/ABI/testing/sysfs-block

Add usage overview in Documentation/block/blk-ledtrig.rst

Signed-off-by: Ian Pilcher <arequipeno at gmail.com>
---
 Documentation/ABI/testing/sysfs-block         | 16 ++++
 .../testing/sysfs-class-led-trigger-blkdev    | 28 +++++++
 Documentation/block/blk-ledtrig.rst           | 79 +++++++++++++++++++
 Documentation/block/index.rst                 |  1 +
 4 files changed, 124 insertions(+)
 create mode 100644 Documentation/ABI/testing/sysfs-class-led-trigger-blkdev
 create mode 100644 Documentation/block/blk-ledtrig.rst

diff --git a/Documentation/ABI/testing/sysfs-block b/Documentation/ABI/testing/sysfs-block
index e34cdeeeb9d4..36253fff25b2 100644
--- a/Documentation/ABI/testing/sysfs-block
+++ b/Documentation/ABI/testing/sysfs-block
@@ -316,3 +316,19 @@ Description:
 		does not complete in this time then the block driver timeout
 		handler is invoked. That timeout handler can decide to retry
 		the request, to fail it or to start a device recovery strategy.
+
+What:		/sys/block/<disk>/led
+Date:		August 2021
+Contact:	Ian Pilcher <arequipeno at gmail.com>
+Description:
+		Set the LED associated with this block device (or show available
+		LEDs and the currently selected LED, if any).
+
+		Reading the attribute will display the available LEDs (LEDs that
+		are associated with the blkdev LED trigger).  The currently
+		selected LED is enclosed in square brackets.  To clear the
+		device's LED association write 'none' (without the quotes) or
+		an empty string/line to the attribute.
+
+		See Documentation/ABI/testing/sysfs-class-led-trigger-blkdev and
+		Documentation/block/blk-ledtrig.rst.)
diff --git a/Documentation/ABI/testing/sysfs-class-led-trigger-blkdev b/Documentation/ABI/testing/sysfs-class-led-trigger-blkdev
new file mode 100644
index 000000000000..1139a099a3cc
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-class-led-trigger-blkdev
@@ -0,0 +1,28 @@
+What:		/sys/class/leds/<led>/blink_on
+Date:		August 2021
+Contact:	Ian Pilcher <arequipeno at gmail.com>
+Description:
+		Time (in milliseconds) that the LED will be on during a single
+		"blink".
+
+What:		/sys/class/leds/<led>/blink_off
+Date:		August 2021
+Contact:	Ian Pilcher <arequipeno at gmail.com>
+Description:
+		Time (in milliseconds) that the LED will be off during a single
+		"blink".  Effectively the amount of time that the LED will be
+		off before the next blink, when the associated block device(s)
+		are continuously active.
+
+What:		/sys/class/leds/<led>/block_devices
+Date:		August 2021
+Contact:	Ian Pilcher <arequipeno at gmail.com>
+Description:
+		Directory containing links to all block devices that are
+		associated with this LED.
+
+		Once an LED has been associated with the blkdev trigger, a block
+		device can be associated with that LED by writing the LED name
+		to the device's /sys/[class/]block/<disk>/led attribute.  (See
+		Documentation/ABI/testing/sysfs-block and
+		Documentation/block/blk-ledtrig.rst.)
diff --git a/Documentation/block/blk-ledtrig.rst b/Documentation/block/blk-ledtrig.rst
new file mode 100644
index 000000000000..194fc6a51019
--- /dev/null
+++ b/Documentation/block/blk-ledtrig.rst
@@ -0,0 +1,79 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Block Device (blkdev) LED Trigger
+=================================
+
+Available when ``CONFIG_BLK_LED_TRIGGERS=y``.
+
+See also:
+
+* ``Documentation/ABI/testing/sysfs-class-led-trigger-blkdev``
+* ``Documentation/ABI/testing/sysfs-block`` (``/sys/block/<disk>/led``)
+
+.. note::
+	The examples below use ``<LED>`` to refer to the name of a
+	system-specific LED.  If no suitable LED is available on a test
+	system (in a virtual machine, for example), it is possible to
+	use a userspace LED (``Documentation/leds/uleds.rst``).
+
+Associate the LED with the ``blkdev`` LED trigger::
+
+	# echo blkdev > /sys/class/leds/<LED>/trigger
+
+	# cat /sys/class/leds/<LED>/trigger
+	... kbd-ctrlrlock [blkdev] disk-activity ...
+
+Note that the ``blink_on`` and ``blink_off`` attributes have been added to the
+LED, along with the ``block_devices`` subdirectory.
+
+The LED is now available for association with block devices::
+
+	# cat /sys/block/sda/led
+	[none] <LED>
+
+Associate the LED with the block device::
+
+	# echo <LED> > /sys/block/sda/led
+
+	# cat /sys/block/sda/led
+	none [<LED>]
+
+Reads and write activity on the device should cause the LED to blink.  The
+duration of each blink (in milliseconds) can be adjusted by setting
+``/sys/class/leds/<LED>/blink_on``, and the minimum delay between blinks can
+be set via ``/sys/class/leds/<LED>/blink_off``.
+
+Associate a second device with the LED::
+
+	# echo <LED> > /sys/block/sdb/led
+
+	# cat /sys/block/sdb/led
+	none [<LED>]
+
+Note that both block devices are linked from the LED's ``block_devices``
+subdirectory::
+
+	# ls /sys/class/leds/<LED>/block_devices
+	sda sdb
+
+Other notes:
+
+* Many types of block devices work with this trigger, including:
+
+  * SCSI (including SATA and USB) hard disk drives and SSDs
+  * SCSI (including SATA and USB) optical drives
+  * SD cards
+  * loopback block devices (``/dev/loop*``)
+
+* NVMe SSDs and most virtual block devices can be associated with LEDs, but
+  they will produce little or no LED activity.
+
+* Multiple LEDs can be associated with the ``blkdev`` trigger; different block
+  devices can be associated with different LEDs.
+
+* This trigger causes associated LED(s) to blink (per the LED's ``blink_on``
+  and ``blink_off`` attributes) when a request is sent to an associated
+  block device's low-level driver.  It does not track the duration (or
+  result) of requests further.  Thus, it provides an approximate visual
+  indication of device activity, not an exact measurement.
diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
index 86dcf7159f99..cbb11a42f825 100644
--- a/Documentation/block/index.rst
+++ b/Documentation/block/index.rst
@@ -25,3 +25,4 @@ Block
    stat
    switching-sched
    writeback_cache_control
+   blk-ledtrig
-- 
2.31.1