Introduce simple led.rst documentation to document all the additional Kconfig and the current limitation of LED_BLINK and GPIO software blink.
Signed-off-by: Christian Marangi ansuelsmth@gmail.com --- doc/api/index.rst | 1 + doc/api/led.rst | 10 ++++++++++ include/led.h | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 49 insertions(+) create mode 100644 doc/api/led.rst
diff --git a/doc/api/index.rst b/doc/api/index.rst index 51b2013af36..6f11b94eac3 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -13,6 +13,7 @@ U-Boot API documentation event getopt interrupt + led linker_lists lmb logging diff --git a/doc/api/led.rst b/doc/api/led.rst new file mode 100644 index 00000000000..e52e350d1bb --- /dev/null +++ b/doc/api/led.rst @@ -0,0 +1,10 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +LED +=== + +.. kernel-doc:: include/led.h + :doc: Overview + +.. kernel-doc:: include/led.h + :internal: \ No newline at end of file diff --git a/include/led.h b/include/led.h index 409397e1df9..4dac54338e4 100644 --- a/include/led.h +++ b/include/led.h @@ -7,6 +7,44 @@ #ifndef __LED_H #define __LED_H
+/** + * DOC: Overview + * + * Generic LED API provided when a supported compatible is defined in DeviceTree. + * + * To enable support for LEDs, enable the `CONFIG_LED` Kconfig option. + * + * The most common implementation is for GPIO-connected LEDs. If using GPIO-connected LEDs, + * enable the `LED_GPIO` Kconfig option. + * + * `LED_BLINK` support requires LED driver support and is therefore optional. If LED blink + * functionality is needed, enable the `LED_BLINK` Kconfig option. + * + * GPIO-connected LEDs can simulate blinking via software using the Cyclic API. To utilize this, + * enable `CONFIG_LED_GPIO_SW_BLINK`. This will also select `CONFIG_LED_BLINK` and `CONFIG_CYCLIC`. + * + * Boot and Activity LEDs are also supported. These LEDs can signal various system operations + * during runtime, such as boot initialization, file transfers, and flash write/erase operations. + * + * To enable a Boot LED, enable `CONFIG_LED_BOOT_ENABLE` and define `CONFIG_LED_BOOT_LABEL`. This + * will enable the specified LED to blink and turn ON when the bootloader initializes correctly. + * + * To enable an Activity LED, enable `CONFIG_LED_ACTIVITY_ENABLE` and define + * `CONFIG_LED_ACTIVITY_LABEL`. + * This will enable the specified LED to blink and turn ON during file transfers or flash + * write/erase operations. + * + * Both Boot and Activity LEDs provide a simple API to turn the LED ON or OFF: + * `led_boot_on()`, `led_boot_off()`, `led_activity_on()`, and `led_activity_off()`. + * + * Both configurations can optionally define a `_PERIOD` option if `CONFIG_LED_BLINK` is enabled + * for LED blink operations, which is usually used by the Activity LED. + * + * When `CONFIG_LED_BLINK` is enabled, additional APIs are exposed: `led_boot_blink()` and + * `led_activity_blink()`. Note that if `CONFIG_LED_BLINK` is disabled, these APIs will behave + * like the `led_boot_on()` and `led_activity_on()` APIs, respectively. + */ + struct udevice;
enum led_state_t {