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@xxxxxxxxx>
---
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@xxxxxxxxx>
+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@xxxxxxxxx>
+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@xxxxxxxxx>
+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@xxxxxxxxx>
+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
