From patchwork Thu Jun 6 14:29:29 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Christian Marangi X-Patchwork-Id: 1944740 X-Patchwork-Delegate: trini@ti.com Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.a=rsa-sha256 header.s=20230601 header.b=VkfhJftV; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=lists.denx.de (client-ip=2a01:238:438b:c500:173d:9f52:ddab:ee01; helo=phobos.denx.de; envelope-from=u-boot-bounces@lists.denx.de; receiver=patchwork.ozlabs.org) Received: from phobos.denx.de (phobos.denx.de [IPv6:2a01:238:438b:c500:173d:9f52:ddab:ee01]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature ECDSA (secp384r1)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4Vw92C2YF7z20PW for ; Fri, 7 Jun 2024 02:36:19 +1000 (AEST) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id BB183884EA; Thu, 6 Jun 2024 18:33:48 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=gmail.com header.i=@gmail.com header.b="VkfhJftV"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id DA61F87E1D; Thu, 6 Jun 2024 16:30:51 +0200 (CEST) X-Spam-Checker-Version: SpamAssassin 3.4.2 (2018-09-13) on phobos.denx.de X-Spam-Level: X-Spam-Status: No, score=-2.1 required=5.0 tests=BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,FREEMAIL_FROM,SPF_HELO_NONE, SPF_PASS,T_SCC_BODY_TEXT_LINE autolearn=ham autolearn_force=no version=3.4.2 Received: from mail-wr1-x429.google.com (mail-wr1-x429.google.com [IPv6:2a00:1450:4864:20::429]) (using TLSv1.3 with cipher TLS_AES_128_GCM_SHA256 (128/128 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 9AE6A88428 for ; Thu, 6 Jun 2024 16:30:49 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=ansuelsmth@gmail.com Received: by mail-wr1-x429.google.com with SMTP id ffacd0b85a97d-35dd0c06577so1064623f8f.2 for ; Thu, 06 Jun 2024 07:30:49 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1717684249; x=1718289049; darn=lists.denx.de; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:from:to:cc:subject:date:message-id :reply-to; bh=1SnK722UF5gQtV5gKPMHvDpazj/jDZqxf6MafxYMW7M=; b=VkfhJftV/Y/IgEqmozQOyB4bfIvcUa6oj2M/f/lvPkc8wM/bLyiF6GP4o+6R2VrT6m 3mkJs3whrf6SEN/I0vl9wCB9jJYC822d5HoY5jDltbV9H5PBYoYl4MxTdvvDGiTKdsRg 5XB9qWseA7fK7UoDnPIj/SswGSRYWSZ9ZTeJwmEvh5yUwGhf8i0XiEh13WFGOqXNsrih KRQ3ZNJY3I7ed8z2MTowjvHrOZGNF0QaWNfwCZ+ZlasvKTzE0FR9rmUoOwbYBHSMgb71 tknFH3Q4l6GBiwh0PFB+/DD3cPkecd5K4qyYwpbIpK/M2sd03fCf9e476RgLjSgujlnr nNHA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1717684249; x=1718289049; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=1SnK722UF5gQtV5gKPMHvDpazj/jDZqxf6MafxYMW7M=; b=raGvyyMjrej0dsw89DuCb6f8bo9Kg5G1jYnHTYTazGLJ1nrmxc1Ccv6n4fmE1zO4A+ yggiKcNLp2f8d/E3sTX9Y/MILd5ScV6YjeBN0GvHcMsaufyMqF88QHkQA/oD+EwPBhla E1Eet0Z+NVA8IqLufDUXjwleX/h891VCLg3fQFUiz/Gc57dj0wxpJNQTEyQig+PwhehQ Kh7CE/axtTHq+zlPkqfVo4gRxVGlysFJd7ALR1crsgMA77l5ylXlzQGGmJeENz4BAeBd EXV+BkbJ55J98XmGQweeWWUImGeW+mTd6zbW9JhC5hghESe3pnDtmPQ6TaQi+Ej+TojU y7oA== X-Forwarded-Encrypted: i=1; AJvYcCVH1WaizNJjedqIa50KzAIhjfU17ZhyNaXGq+5KPAn6EsTXxdjWQp0D6Uomt7GSoksot48ZKLyVA9PFSYdTKPIpDSZnWA== X-Gm-Message-State: AOJu0YxfYzxepCZixq8WKKprZX11Mtl2WPc1I3NZbtlV+zw+L0ZJqrbZ OitgrZKEn0SxThvtkmZVASffDajjEtLExV446+sLU2dipxO8XHa2 X-Google-Smtp-Source: AGHT+IHdQVRcEnnaWi7drWG1rxMggzQKW2ohz3XJnImAkpIiPNxDRv40FmPbtIyJJFheOFPDmbIgxA== X-Received: by 2002:a5d:658d:0:b0:358:380:f44c with SMTP id ffacd0b85a97d-35e840582femr4390753f8f.5.1717684248884; Thu, 06 Jun 2024 07:30:48 -0700 (PDT) Received: from localhost.localdomain (93-34-90-105.ip49.fastwebnet.it. [93.34.90.105]) by smtp.googlemail.com with ESMTPSA id ffacd0b85a97d-35ef5e989b3sm1718060f8f.71.2024.06.06.07.30.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Thu, 06 Jun 2024 07:30:48 -0700 (PDT) From: Christian Marangi To: Tom Rini , Joe Hershberger , Ramon Fried , Christian Marangi , Dario Binacchi , Arseniy Krasnov , Miquel Raynal , Simon Glass , Heinrich Schuchardt , Dmitry Dunaev , Devarsh Thakkar , Bin Meng , Stefan Bosch , Eugene Uriev , Nikhil M Jain , Shiji Yang , Raymond Mao , Leo Yu-Chi Liang , Rasmus Villemoes , Doug Zobel , AKASHI Takahiro , u-boot@lists.denx.de, John Crispin Subject: [PATCH v2 8/8] doc: convert README.LED to .rst documentation Date: Thu, 6 Jun 2024 16:29:29 +0200 Message-ID: <20240606143024.20024-9-ansuelsmth@gmail.com> X-Mailer: git-send-email 2.43.0 In-Reply-To: <20240606143024.20024-1-ansuelsmth@gmail.com> References: <20240606143024.20024-1-ansuelsmth@gmail.com> MIME-Version: 1.0 X-Mailman-Approved-At: Thu, 06 Jun 2024 18:33:44 +0200 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.8 at phobos.denx.de X-Virus-Status: Clean Convert README.LED to .rst documentation and include all the relevant documentation in the status_led.h. Signed-off-by: Christian Marangi --- doc/README.LED | 77 -------------- doc/api/index.rst | 1 + doc/api/status_led.rst | 35 +++++++ include/status_led.h | 224 ++++++++++++++++++++++++++++++++++++++++- 4 files changed, 256 insertions(+), 81 deletions(-) delete mode 100644 doc/README.LED create mode 100644 doc/api/status_led.rst diff --git a/doc/README.LED b/doc/README.LED deleted file mode 100644 index c21c9d53ec3..00000000000 --- a/doc/README.LED +++ /dev/null @@ -1,77 +0,0 @@ -Status LED -======================================== - -This README describes the status LED API. - -The API is defined by the include file include/status_led.h - -The first step is to enable CONFIG_LED_STATUS in menuconfig: -> Device Drivers > LED Support. - -If the LED support is only for specific board, enable -CONFIG_LED_STATUS_BOARD_SPECIFIC in the menuconfig. - -Status LEDS 0 to 5 are enabled by the following configurations at menuconfig: -CONFIG_STATUS_LED0, CONFIG_STATUS_LED1, ... CONFIG_STATUS_LED5 - -The following should be configured for each of the enabled LEDs: -CONFIG_STATUS_LED_BIT -CONFIG_STATUS_LED_STATE -CONFIG_STATUS_LED_FREQ -Where is an integer 1 through 5 (empty for 0). - -CONFIG_STATUS_LED_BIT is passed into the __led_* functions to identify which LED -is being acted on. As such, the value choose must be unique with with respect to -the other CONFIG_STATUS_LED_BIT's. Mapping the value to a physical LED is the -reponsiblity of the __led_* function. - -CONFIG_STATUS_LED_STATE is the initial state of the LED. It should be set to one -of these values: CONFIG_LED_STATUS_OFF or CONFIG_LED_STATUS_ON. - -CONFIG_STATUS_LED_FREQ determines the LED blink frequency. -Values range from 2 to 10. - -Some other LED macros ---------------------- - -CONFIG_STATUS_LED_BOOT is the LED to light when the board is booting. -This must be a valid LED number (0-5). - -CONFIG_STATUS_LED_RED is the red LED. It is used to signal errors. This must be -a valid LED number (0-5). Other similar color LED's macros are -CONFIG_STATUS_LED_GREEN, CONFIG_STATUS_LED_YELLOW and CONFIG_STATUS_LED_BLUE. - -General LED functions ---------------------- -The following functions should be defined: - -__led_init is called once to initialize the LED to CONFIG_STATUS_LED_STATE. -One time start up code should be placed here. - -__led_set is called to change the state of the LED. - -__led_toggle is called to toggle the current state of the LED. - -Colour LED -======================================== - -Colour LED's are at present only used by ARM. - -The functions names explain their purpose. - -coloured_LED_init -red_LED_on -red_LED_off -green_LED_on -green_LED_off -yellow_LED_on -yellow_LED_off -blue_LED_on -blue_LED_off - -These are weakly defined in arch/arm/lib/board.c to noops. Where applicable, define -these functions in the board specific source. - -TBD : Describe older board dependent macros similar to what is done for - -TBD : Describe general support via asm/status_led.h diff --git a/doc/api/index.rst b/doc/api/index.rst index 51b2013af36..d40e90801d1 100644 --- a/doc/api/index.rst +++ b/doc/api/index.rst @@ -22,6 +22,7 @@ U-Boot API documentation rng sandbox serial + status_led sysreset timer unicode diff --git a/doc/api/status_led.rst b/doc/api/status_led.rst new file mode 100644 index 00000000000..44bbea47157 --- /dev/null +++ b/doc/api/status_led.rst @@ -0,0 +1,35 @@ +.. SPDX-License-Identifier: GPL-2.0+ + +Status LED +========== + +.. kernel-doc:: include/status_led.h + :doc: Overview + +CONFIG_STATUS_LED Description +----------------------------- + +.. kernel-doc:: include/status_led.h + :doc: CONFIG Description + +Special Status LED Configs +-------------------------- +.. kernel-doc:: include/status_led.h + :doc: LED Status Config + +Colour Status LED Configs +------------------------- +.. kernel-doc:: include/status_led.h + :doc: LED Colour Config + +Required API +------------ + +.. kernel-doc:: include/status_led.h + :doc: Required API + +Status LED API +-------------- + +.. kernel-doc:: include/status_led.h + :internal: diff --git a/include/status_led.h b/include/status_led.h index 7de40551621..6893d1d68e0 100644 --- a/include/status_led.h +++ b/include/status_led.h @@ -4,18 +4,102 @@ * Wolfgang Denk, DENX Software Engineering, wd@denx.de. */ -/* - * The purpose of this code is to signal the operational status of a +/** + * DOC: Overview + * + * Status LED is a Low-Level way to handle LEDs to signal state of the + * bootloader, for example boot progress, file transfer fail, activity + * of some sort like tftp transfer, mtd write/erase. + * + * The original usage these API were to signal the operational status of a * target which usually boots over the network; while running in * PCBoot, a status LED is blinking. As soon as a valid BOOTP reply * message has been received, the LED is turned off. The Linux * kernel, once it is running, will start blinking the LED again, * with another frequency. + * + * Status LED require support Low Level and the board to implement + * the specific functions to correctly works. */ #ifndef _STATUS_LED_H_ #define _STATUS_LED_H_ +/** + * DOC: CONFIG Description + * + * Enable `CONFIG_LED_STATUS` to support the Status LED under + * > Device Drivers > LED Support. + * + * The Status LED can be defined in various ways, but most of the time, + * specific functions will need to be defined in the board file. + * If this is the case, enable `CONFIG_LED_STATUS_BOARD_SPECIFIC`. + * + * If the LEDs are GPIO-driven, you can use the GPIO wrapper driver + * instead of defining specific board functions. + * If this is the case, enable `CONFIG_LED_STATUS_GPIO`. + * (Note that `CONFIG_LED_STATUS_BOARD_SPECIFIC` is also required.) + * + * The Status LED allows defining up to six different LEDs, from 0 to 5, + * with the following configurations: + * `CONFIG_STATUS_LED`, `CONFIG_STATUS_LED1`, ..., `CONFIG_STATUS_LED5`. + * + * For each LED, the following options are required: + * * `CONFIG_STATUS_LED_BIT` + * * `CONFIG_STATUS_LED_STATE` + * * `CONFIG_STATUS_LED_FREQ` + * + * Where `` is an integer from 1 through 5. (Note that LED 0 doesn't have the + * integer suffix.) + * + * `CONFIG_STATUS_LED_BIT` is passed into the `__led_*` functions to identify + * which LED is being acted on. The value is opaque, meaning it depends on how + * the low-level API handles this value. It can be an ID to reference the LED + * internally, or in the case of the GPIO wrapper, it's the GPIO number of the LED. + * Mapping the value to a physical LED is the responsibility of the `__led_*` function. + * + * `CONFIG_STATUS_LED_STATE` sets the initial state of the LED. It should be set + * to one of these values: `CONFIG_LED_STATUS_OFF` or `CONFIG_LED_STATUS_ON`. + * + * `CONFIG_STATUS_LED_FREQ` determines the LED blink frequency. + * Values range from 2 to 10. + */ +/** + * DOC: LED Status Config + * + * The Status LED uses two special configurations for common operations: + * + * * CONFIG_STATUS_LED_BOOT is the LED that lights up when the board is booting. + * * CONFIG_STATUS_LED_ACTIVITY is the LED that lights and blinks during activity + * (e.g., file transfer, flash write). + * + * The values set in these configurations refer to the LED ID previously set. + * + * - ``CONFIG_STATUS_LED_RED=0`` will refer to the option ``CONFIG_STATUS_LED_BIT``. + * - ``CONFIG_STATUS_LED_RED=1`` will refer to the option ``CONFIG_STATUS_LED_BIT1``. + * - ``CONFIG_STATUS_LED_RED=2`` will refer to the option ``CONFIG_STATUS_LED_BIT2``. + * - ... + */ +/** + * DOC: LED Colour Config + * + * The Status LED exposes specific configurations for LEDs of different colors. + * + * The values set in these configurations refer to the LED ID previously set. + * + * - ``CONFIG_STATUS_LED_RED=0`` will refer to the option ``CONFIG_STATUS_LED_BIT``. + * - ``CONFIG_STATUS_LED_RED=1`` will refer to the option ``CONFIG_STATUS_LED_BIT1``. + * - ``CONFIG_STATUS_LED_RED=2`` will refer to the option ``CONFIG_STATUS_LED_BIT2``. + * - ... + * + * Supported colors are: + * * red + * * green + * * yellow + * * blue + * * white + */ + #ifdef CONFIG_LED_STATUS #define LED_STATUS_PERIOD (CONFIG_SYS_HZ / CONFIG_LED_STATUS_FREQ) @@ -35,11 +119,49 @@ #define LED_STATUS_PERIOD5 (CONFIG_SYS_HZ / CONFIG_LED_STATUS_FREQ5) #endif /* CONFIG_LED_STATUS5 */ +/** + * void status_led_init - Init the Status LED with all the required structs. + */ void status_led_init(void); +/** + * void status_led_tick - Blink each LED that is currently set in blinking + * mode + * @timestamp: currently unused + */ void status_led_tick(unsigned long timestamp); +/** + * void status_led_set - Set the LED ID passed as first arg to the mode set + * @led: reference to the Status LED ID + * @state: state to set the LED to + * + * Modes for state arE: + * * CONFIG_LED_STATUS_OFF (LED off) + * * CONFIG_LED_STATUS_ON (LED on) + * * CONFIG_LED_STATUS_BLINK (LED initially on, expected to blink) + */ void status_led_set(int led, int state); +/** + * void status_led_toggle - toggle the LED ID + * @led: reference to the Status LED ID + * + * Toggle the LED ID passed as first arg. If it's ON became OFF, if it's + * OFF became ON. + */ void status_led_toggle(int led); +/** + * void status_led_activity_start - start a LED activity + * @led: reference to the Status LED ID + * + * Set the Status LED ON and start the Cyclic to make the LED blink at + * the configured freq. + */ void status_led_activity_start(int led); +/** + * void status_led_activity_stop - stop a LED activity + * @led: reference to the Status LED ID + * + * Stop and free the Cyclic and turn the LED OFF. + */ void status_led_activity_stop(int led); /***** MVS v1 **********************************************************/ @@ -62,9 +184,61 @@ void status_led_activity_stop(int led); /* led_id_t is unsigned long mask */ typedef unsigned long led_id_t; +/** + * DOC: Required API + * + * The Status LED requires the following API functions to operate correctly + * and compile: + * + * - ``__led_toggle``: Low-level function to toggle the LED at the specified + * mask. + * - ``__led_init``: Initializes the Status LED, sets up required tables, and + * configures registers. + * - ``__led_set``: Low-level function to set the state of the LED at the + * specified mask. + * - ``__led_blink``: Low-level function to set the LED to blink at the + * specified frequency. + * + * The Status LED also provides optional functions to control colored LEDs. + * Each supported LED color has corresponding ``_on`` and ``_off`` functions. + * + * There is also support for ``coloured_LED_init`` for LEDs that provide + * multiple colors. (Currently, this is only used by ARM.) + * + * Each function is weakly defined and should be implemented in the + * board-specific source file. (This does not apply to the GPIO LED wrapper.) + */ +/** + * void __led_toggle - toggle LED at @mask + * @mask: opaque value to reference the LED + * + * Low-Level function to toggle the LED at mask. + */ extern void __led_toggle (led_id_t mask); +/** + * void __led_init - Init the LED at @mask + * @mask: opaque value to reference the LED + * @state: starting state of the LED + * + * Init the Status LED, init required tables, setup regs... + */ extern void __led_init (led_id_t mask, int state); +/** + * void __led_set - Set the LED at @mask + * @mask: opaque value to reference the LED + * @state: state to set the LED to + * + * Init the Status LED, init required tables, setup regs... + */ extern void __led_set (led_id_t mask, int state); +/** + * void __led_blink - Set the LED at @mask to HW blink + * @mask: opaque value to reference the LED + * @freq: freq to make the LED blink at + * + * Low-Level function to set the LED at HW blink by the + * passed freq. + */ void __led_blink(led_id_t mask, int freq); #else # error Status LED configuration missing @@ -77,20 +251,62 @@ void __led_blink(led_id_t mask, int freq); #endif /* CONFIG_LED_STATUS */ -/* - * Coloured LEDs API +/** + * DOC: Coloured LED API + * + * Status LED expose optional functions to control coloured LED. + * Each LED color supported expose _on and _off function. + * + * There is also support for coloured_LED_init for LED that provide + * multiple colours. (currently only used by ARM) + * + * Each function is weakly defined and should be defined in the board + * specific source. (doesn't apply for GPIO LED wrapper) */ #ifndef __ASSEMBLY__ +/** + * void coloured_LED_init - Init multi colour LED + */ void coloured_LED_init(void); +/** + * void red_led_on - Turn LED Red on + */ void red_led_on(void); +/** + * void red_led_off - Turn LED Red off + */ void red_led_off(void); +/** + * void green_led_on - Turn LED Green on + */ void green_led_on(void); +/** + * void green_led_off - Turn LED Green off + */ void green_led_off(void); +/** + * void yellow_led_on - Turn LED Yellow on + */ void yellow_led_on(void); +/** + * void yellow_led_off - Turn LED Yellow off + */ void yellow_led_off(void); +/** + * void blue_led_on - Turn LED Blue on + */ void blue_led_on(void); +/** + * void blue_led_off - Turn LED Blue off + */ void blue_led_off(void); +/** + * void white_led_on - Turn LED White on + */ void white_led_on(void); +/** + * void white_led_off - Turn LED White off + */ void white_led_off(void); #else .extern LED_init