Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
From:   Ian Pilcher <arequipeno@gmail.com>
To:     linux-block@vger.kernel.org, linux-leds@vger.kernel.org
Cc:     axboe@kernel.dk, pavel@ucw.cz, linux-kernel@vger.kernel.org,
        kernelnewbies@kernelnewbies.org, Ian Pilcher <arequipeno@gmail.com>
Subject: [RFC PATCH 1/8] docs: Add block device LED trigger documentation
Date:   Wed, 28 Jul 2021 20:53:37 -0500
Message-Id: <20210729015344.3366750-2-arequipeno@gmail.com>
In-Reply-To: <20210729015344.3366750-1-arequipeno@gmail.com>
References: <20210729015344.3366750-1-arequipeno@gmail.com>
MIME-Version: 1.0
Content-Transfer-Encoding: 8bit
Precedence: bulk

* Document the sysfs attributes (/sys/class/block/led_trigger_*
  and /sys/class/block/${DEV}/led_trigger) that can be used to
  create, list, and delete block device LED triggers and to
  set and clear device/trigger associations.

* Pull API documentation from block/blk-ledtrig.c (once it
  exists).

Signed-off-by: Ian Pilcher <arequipeno@gmail.com>
---
 Documentation/block/index.rst        |   1 +
 Documentation/block/led-triggers.rst | 124 +++++++++++++++++++++++++++
 2 files changed, 125 insertions(+)
 create mode 100644 Documentation/block/led-triggers.rst

diff --git a/Documentation/block/index.rst b/Documentation/block/index.rst
index 86dcf7159f99..a125ecdb4c7b 100644
--- a/Documentation/block/index.rst
+++ b/Documentation/block/index.rst
@@ -25,3 +25,4 @@ Block
    stat
    switching-sched
    writeback_cache_control
+   led-triggers
diff --git a/Documentation/block/led-triggers.rst b/Documentation/block/led-triggers.rst
new file mode 100644
index 000000000000..a67e06c68073
--- /dev/null
+++ b/Documentation/block/led-triggers.rst
@@ -0,0 +1,124 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+============
+LED Triggers
+============
+
+Available when ``CONFIG_BLK_LED_TRIGGERS=y``.
+
+sysfs interface
+===============
+
+Create a new block device LED trigger::
+
+	# echo foo > /sys/class/block/led_trigger_new
+
+The name must be unique among all LED triggers (not just block device LED
+triggers).
+
+Create two more::
+
+	# echo bar baz > /sys/class/block/led_trigger_new
+
+List the triggers::
+
+	# cat /sys/class/block/led_trigger_list
+	baz: 0
+	bar: 0
+	foo: 0
+
+(The number after each trigger is its reference count.)
+
+Associate a trigger with a block device::
+
+	# cat /sys/class/block/sda/led_trigger
+	(none)
+
+	# echo foo > /sys/class/block/sda/led_trigger
+	# cat /sys/class/block/sda/led_trigger
+	foo
+
+Note that ``foo``'s reference count has increased, and it cannot be deleted::
+
+	# cat /sys/class/block/led_trigger_list
+	baz: 0
+	bar: 0
+	foo: 1
+
+	# echo foo > /sys/class/block/led_trigger_del
+	-bash: echo: write error: Device or resource busy
+
+	# dmesg | tail -n 1
+	[23176.475424] blockdev LED trigger foo still in use
+
+Associate the ``foo`` trigger with an LED::
+
+	# cat /sys/class/leds/input1::scrolllock/trigger
+	none usb-gadget usb-host rc-feedback [kbd-scrolllock] kbd-numlock
+	kbd-capslock kbd-kanalock kbd-shiftlock kbd-altgrlock kbd-ctrllock
+	kbd-altlock kbd-shiftllock kbd-shiftrlock kbd-ctrlllock kbd-ctrlrlock
+	disk-activity disk-read disk-write ide-disk mtd nand-disk panic
+	audio-mute audio-micmute rfkill-any rfkill-none foo bar baz
+
+	# echo foo > /sys/class/leds/input1::scrolllock/trigger
+
+	# cat /sys/class/leds/input1::scrolllock/trigger
+	none usb-gadget usb-host rc-feedback [kbd-scrolllock] kbd-numlock
+	kbd-capslock kbd-kanalock kbd-shiftlock kbd-altgrlock kbd-ctrllock
+	kbd-altlock kbd-shiftllock kbd-shiftrlock kbd-ctrlllock kbd-ctrlrlock
+	disk-activity disk-read disk-write ide-disk mtd nand-disk panic
+	audio-mute audio-micmute rfkill-any rfkill-none [foo] bar baz
+
+Reads and writes to ``sda`` should now cause the scroll lock LED on your
+keyboard to blink (assuming that it has one).
+
+Multiple devices can be associated with a trigger::
+
+	# echo foo > /sys/class/block/sdb/led_trigger
+
+	# cat /sys/class/block/led_trigger_list
+	baz: 0
+	bar: 0
+	foo: 2
+
+Activity on either ``sda`` or ``sdb`` should now be shown by your scroll lock
+LED.
+
+Clear ``sda``'s LED trigger::
+
+	# echo > /sys/class/block/sda/led_trigger
+
+	# cat /sys/class/block/sda/led_trigger
+	(none)
+
+	# cat /sys/class/block/led_trigger_list
+	baz: 0
+	bar: 0
+	foo: 1
+
+And ``sdb``'s trigger::
+
+	# echo > /sys/class/block/sdb/led_trigger
+
+Delete the triggers::
+
+	# echo foo bar baz > /sys/class/block/led_trigger_del
+
+	# cat /sys/class/block/led_trigger_list
+
+	# cat /sys/class/leds/input1::scrolllock/trigger
+	none usb-gadget usb-host rc-feedback [kbd-scrolllock] kbd-numlock
+	kbd-capslock kbd-kanalock kbd-shiftlock kbd-altgrlock kbd-ctrllock
+	kbd-altlock kbd-shiftllock kbd-shiftrlock kbd-ctrlllock kbd-ctrlrlock
+	disk-activity disk-read disk-write ide-disk mtd nand-disk panic
+	audio-mute audio-micmute rfkill-any rfkill-none
+
+Also see **Userspace LEDs** (``Documentation/leds/uleds.rst``).
+
+Kernel API
+==========
+
+``#include <linux/blk-ledtrig.h>``
+
+.. kernel-doc:: block/blk-ledtrig.c
+   :export:
-- 
2.31.1