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

[Simon Glass]

Hi Tom,

On Thu, 13 Nov 2025 at 10:46, Tom Rini <trini at konsulko.com> wrote:
>
> On Thu, Nov 13, 2025 at 11:58:23AM +0100, Quentin Schulz wrote:
> > 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.
>
> Yes, when discussions around the legacy LED stuff have come up, it's
> come down to now that we finally have nominal parity in APIs, can we
> migrate the older users? For the two m68k platforms, I'm OK with just
> removing the code and letting someone that has interest and can test
> re-introducing the functionality. Of the other three, I think pinephone
> is the hardest / most important case. I forget if previous migration
> attempts ran in to non-obvious problems.

The last I remember someone was going to get one out of a drawer and
try it. But that was probably last year sometime.

Regards,
SImon