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

[Tom Rini]

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.

-- 
Tom
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 228 bytes
Desc: not available
URL: <https://lists.denx.de/pipermail/u-boot/attachments/20251113/e3ecb570/attachment.sig>