diff mbox series

[9/9] doc: introduce led.rst documentation

Message ID 20240624214626.24336-10-ansuelsmth@gmail.com
State Deferred
Delegated to: Tom Rini
Headers show
Series led: introduce LED boot and activity function | expand

Commit Message

Christian Marangi June 24, 2024, 9:46 p.m. UTC 
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 mbox series

Patch

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 {