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 Subject: [RFC PATCH v2 01/10] docs: Add block device LED trigger documentation Date: Sun, 8 Aug 2021 22:32:08 -0500 [thread overview] Message-ID: <20210809033217.1113444-2-arequipeno@gmail.com> (raw) In-Reply-To: <20210809033217.1113444-1-arequipeno@gmail.com> 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@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@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@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@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@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
WARNING: multiple messages have this Message-ID (diff)
From: Ian Pilcher <arequipeno@gmail.com> To: linux-block@vger.kernel.org, linux-leds@vger.kernel.org Cc: axboe@kernel.dk, linux-kernel@vger.kernel.org, pavel@ucw.cz, kernelnewbies@kernelnewbies.org Subject: [RFC PATCH v2 01/10] docs: Add block device LED trigger documentation Date: Sun, 8 Aug 2021 22:32:08 -0500 [thread overview] Message-ID: <20210809033217.1113444-2-arequipeno@gmail.com> (raw) In-Reply-To: <20210809033217.1113444-1-arequipeno@gmail.com> 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@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@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@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@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@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 _______________________________________________ Kernelnewbies mailing list Kernelnewbies@kernelnewbies.org https://lists.kernelnewbies.org/mailman/listinfo/kernelnewbies
next prev parent reply other threads:[~2021-08-09 3:32 UTC|newest] Thread overview: 56+ messages / expand[flat|nested] mbox.gz Atom feed top 2021-08-09 3:32 [RFC PATCH v2 00/10] Add configurable block device LED triggers Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher [this message] 2021-08-09 3:32 ` [RFC PATCH v2 01/10] docs: Add block device LED trigger documentation Ian Pilcher 2021-08-10 13:49 ` Pavel Machek 2021-08-10 13:49 ` Pavel Machek 2021-08-09 3:32 ` [RFC PATCH v2 02/10] block: Add file (blk-ledtrig.c) for block device LED trigger implementation Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 03/10] block: Add block device LED trigger fields to gendisk structure Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 04/10] block: Add functions to set & clear block device LEDs Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 05/10] block: Add block device sysfs attribute to set/clear/show LED Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 4:21 ` Jackie Liu 2021-08-09 4:21 ` Jackie Liu 2021-08-09 15:44 ` Ian Pilcher 2021-08-09 15:44 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 06/10] block: Add activate and deactivate functions for block device LED trigger Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 07/10] block: Add sysfs attributes to LEDs associated with blkdev trigger Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 08/10] block: Add init function for block device LED trigger Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 09/10] block: Blink device LED (if any) when request is sent to its driver Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 3:32 ` [RFC PATCH v2 10/10] block: Add config option to enable block device LED triggers Ian Pilcher 2021-08-09 3:32 ` Ian Pilcher 2021-08-09 18:56 ` [RFC PATCH v2 00/10] Add configurable " Marek Behún 2021-08-09 18:56 ` Marek Behún 2021-08-09 19:07 ` Pali Rohár 2021-08-09 19:07 ` Pali Rohár 2021-08-09 19:54 ` Ian Pilcher 2021-08-09 19:54 ` Ian Pilcher 2021-08-09 22:43 ` Marek Behún 2021-08-09 22:43 ` Marek Behún 2021-08-09 23:50 ` Ian Pilcher 2021-08-09 23:50 ` Ian Pilcher 2021-08-10 6:35 ` Greg KH 2021-08-10 6:35 ` Greg KH 2021-08-10 13:38 ` Marek Behún 2021-08-10 13:38 ` Marek Behún 2021-08-10 14:48 ` Greg KH 2021-08-10 14:48 ` Greg KH 2021-08-10 15:55 ` Ian Pilcher 2021-08-10 15:55 ` Ian Pilcher 2021-08-10 16:24 ` Greg KH 2021-08-10 16:24 ` Greg KH 2021-08-10 16:39 ` Marek Behún 2021-08-10 16:39 ` Marek Behún 2021-08-10 16:43 ` Ian Pilcher 2021-08-10 16:43 ` Ian Pilcher 2021-08-11 6:26 ` Christoph Hellwig 2021-08-11 6:26 ` Christoph Hellwig 2021-08-11 10:50 ` Marek Behún 2021-08-11 10:50 ` Marek Behún
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=20210809033217.1113444-2-arequipeno@gmail.com \ --to=arequipeno@gmail.com \ --cc=axboe@kernel.dk \ --cc=kernelnewbies@kernelnewbies.org \ --cc=linux-block@vger.kernel.org \ --cc=linux-kernel@vger.kernel.org \ --cc=linux-leds@vger.kernel.org \ --cc=pavel@ucw.cz \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.