Re: [PATCH v4 9/9] doc: convert README.LED to .rst documentation
On 6/20/24 06:37, Christian Marangi wrote: On Thu, Jun 20, 2024 at 08:13:34AM +0200, Heinrich Schuchardt wrote: On 6/20/24 01:03, Christian Marangi wrote: 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..000 --- 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 000..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, w...@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 Status LEDs can be used to signal the operational status of a + * bootloader, for example boot progress, file transfer fail, activity + * of some sort like tftp
Re: [PATCH v4 9/9] doc: convert README.LED to .rst documentation
On Thu, Jun 20, 2024 at 08:13:34AM +0200, Heinrich Schuchardt wrote: > On 6/20/24 01:03, Christian Marangi wrote: > > 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..000 > > --- 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 000..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: >
Re: [PATCH v4 9/9] doc: convert README.LED to .rst documentation
On 6/20/24 01:03, Christian Marangi wrote: 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..000 --- 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 000..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, w...@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 Status LEDs can be used to signal the operational status of a + * bootloader, for example boot progress, file transfer fail, activity + * of some sort like tftp transfer, mtd write/erase. for example boot progress, file transfer failure, or ongoing activity like tftp transfer or mtd
[PATCH v4 9/9] doc: convert README.LED to .rst documentation
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..000 --- 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 000..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, w...@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
