[PATCH 03/11] doc: cmd: document the led shell command

[Quentin Schulz]

Hi all,

On 11/12/25 6:48 PM, Quentin Schulz wrote:
> From: Quentin Schulz <quentin.schulz at cherry.de>
> 
> This adds documentation on how to use the led shell command.
> 
> Signed-off-by: Quentin Schulz <quentin.schulz at cherry.de>
> ---
>   doc/usage/cmd/led.rst | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++
>   1 file changed, 95 insertions(+)
> 
> diff --git a/doc/usage/cmd/led.rst b/doc/usage/cmd/led.rst
> new file mode 100644
> index 00000000000..b5623895c7e
> --- /dev/null
> +++ b/doc/usage/cmd/led.rst
> @@ -0,0 +1,95 @@
> +.. SPDX-License-Identifier: GPL-2.0-or-later
> +
> +.. index::
> +   single: led (command)
> +
> +led command
> +===========
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    led <led_label> <on|off|toggle>
> +    led <led_label> blink <blink-freq in ms>
> +    led <led_label>
> +    led list
> +
> +led <led_label>
> +---------------
> +
> +Get state of the LED whose label is the one passed as ``<led_label>`` argument.
> +
> +Provided ``<led_label>`` is *module_led*, the possible outputs for this command
> +are::
> +
> +    LED 'module_led': off
> +    LED 'module_led': on
> +    LED 'module_led': blink
> +
> +led <led_label> on|off|toggle
> +-----------------------------
> +
> +Turn on, off or toggle state of the LED whose label is the one passed as
> +``<led_label>`` argument.
> +
> +led <led_label> blink <blink-freq in ms>
> +----------------------------------------
> +
> +Make the LED whose label is the one passed as ``<led_label>`` argument blink at
> +a frequency specified by the argument ``<blink-freq in ms>``.
> +
> +The frequency is parsed as a decimal number and its unit is milliseconds. The
> +duty cycle is 50%. Example::
> +
> +    led blue blink 1000
> +
> +will make the *blue*-labeled LED blink with a state (on or off) kept for 500ms
> +before switching to the other state (respectively off or on) for 500ms,
> +looping endlessly.
> +
> +led list
> +--------
> +
> +List all available LEDs by their label and provide their known state, which can
> +be either *off*, *on* or *blink*.
> +
> +If a LED has not been probed yet, its state will be shown as *<inactive>* in the
> +list.
> +
> +Examples
> +--------
> +
> +::
> +
> +    => led list
> +    module_led      on
> +    sd_card_led     <inactive>
> +    => led module_led
> +    LED 'module_led': on
> +    => led module_led off
> +    => led module_led
> +    LED 'module_led': off
> +    => led module_led toggle
> +    => led module_led
> +    LED 'module_led': on
> +    => led module_led toggle
> +    => led module_led
> +    LED 'module_led': off
> +    => led module_led blink 1000
> +    => led module_led
> +    LED 'module_led': blink
> +    => led sd_card_led
> +    LED 'sd_card_led': off
> +    => led list
> +    module_led      blink
> +    sd_card_led     off
> +
> +Configuration
> +-------------
> +
> +The *led* commands are only available if ``CONFIG_CMD_LED=y``.
> +
> +The *led <led_label> blink* command is only available if ``CONFIG_CMD_LED=y``
> +and either ``CONFIG_LED_BLINK=y`` or ``CONFIG_LED_SW_BLINK=y``.
> 

It seems like there's another led shell command that you can build with 
CONFIG_LED_STATUS_CMD=y that uses the legacy LED API... Should it be 
mentioned/have its own documentation page?

Maybe we should spend time porting the 5 defconfigs that make use of 
this legacy API to the new one and entirely retire the legacy LED API. 
However, there seems to be some discrepancies between the LED_BOOT 
behavior and that of CONFIG_LED_STATUS_BOOT. The former blinks for a 
brief period of time and then is solid on once reaching U-Boot's main 
loop. The latter is blinking sometime after relocation and then turned 
off on first BOOTP packet.

Out of the 5 defconfigs, 3 are using GPIO LEDs with 
CONFIG_LED_STATUS_GPIO=y so it shouldn't be too difficult to migrate to 
the new API just to get the LEDs working (I am not talking about keeping 
the same behavior). The other two are configs/eb_cpu5282_defconfig and 
configs/eb_cpu5282_internal_defconfig which I assume are for the same 
product, but it has not seen actual updates (aside from tree-wide 
migrations) in the last 13 years. From what I could tell, this is also 
GPIO leds, but controlled by writing directly to the GPIO registers 
instead of using a driver. Maybe we can issue a deprecation notice and 
tell the maintainers/users of that board they have X releases to migrate 
else it gets support for the LEDs removed.
For the other boards, we probably need to check how to use the DT for 
the LEDs that are currently configured via the legacy API.

This is at the end of my todo list though.

Cheers,
Quentin