From b6f3ee3f8f79fc4f07515f275442128dad9d8ce9 Mon Sep 17 00:00:00 2001 From: Nicholas Chin Date: Sun, 27 Oct 2024 16:23:45 -0600 Subject: [PATCH] util/util_readme: Use HTML comments in generated output Util_readme adds comments to the top of the generated Doc/util.md file to indicate that it is generated and should not be edited directly. These comments are not intended to show up in the rendered HTML output. Since Markdown does not have a native way of adding comments, the `[comment text]: #` syntax is often used to mark the line as a comment. This takes advantage of the fact that references (often used throughout the docs to list long URLs at the end of the document and reference them in inline links) aren't rendered. However, MyST parser detects these as a duplicate reference and issues a warning, since both lines use "//" as the comment text. Address this by using HTML comments, since Markdown also allows raw HTML to be used. This seems like a cleaner option compared to repurposing references and appears to have better compatibility with various Markdown readers, which may be useful if someone wants to read the documentation outside of doc.coreboot.org. While we are here, regenerate Documentation/util.md and util/README.md Change-Id: Ibd4f61009c01c7b64594d88c5d86e472f0ccaa6c Signed-off-by: Nicholas Chin Reviewed-on: https://review.coreboot.org/c/coreboot/+/84885 Tested-by: build bot (Jenkins) Reviewed-by: Felix Singer --- Documentation/util.md | 36 ++++++++++++++++++--------------- util/README.md | 30 ++++++++++++++++----------- util/util_readme/util_readme.sh | 6 ++---- 3 files changed, 40 insertions(+), 32 deletions(-) diff --git a/Documentation/util.md b/Documentation/util.md index 887d6966b0..f902ba4fdd 100644 --- a/Documentation/util.md +++ b/Documentation/util.md @@ -1,7 +1,5 @@ - -[//]: # ( DO NOT EDIT - AUTOGENERATED FILE ) - -[//]: # ( RUN 'util/util_readme/util_readme.sh' to regenerate ) + + # Utilities @@ -32,8 +30,8 @@ binary with specific SPDs and GPIO selection pins. `Python3` * _apcb_v3_edit.py_ - This tool allows patching an existing APCB v3 binary with up to 16 specific SPDs. `Python3` * __archive__ - Concatenate files and create an archive `C` -* __autoport__ - Automated porting coreboot to Sandy Bridge/Ivy Bridge -platforms `Go` +* __autoport__ - Automated porting coreboot to Sandy Bridge/Ivy +Bridge/Haswell platforms `Go` * __bincfg__ - Compiler/Decompiler for data blobs with specs `Lex` `Yacc` * __board_status__ - Tools to collect logs and upload them to the board @@ -66,6 +64,8 @@ Controller (EC). `C` * __genbuild_h__ - Generate build system definitions `Shell` * __gitconfig__ - Initialize git repository submodules install git hooks `Bash` +* __hda-decoder__ - Dumps decoded HDA default configuration registers +into a format which can be used in coreboot's verb table `Go` * __ifdtool__ - Extract and dump Intel Firmware Descriptor information `C` * __intelmetool__ - Dump interesting things about Management Engine @@ -75,14 +75,6 @@ an inteltool dump to coreboot macros. `go` * __inteltool__ - Provides information about the Intel CPU/chipset hardware configuration (register contents, MSRs, etc). `C` * __intelvbttool__ - Parse VBT from VGA BIOS `C` -* __ipqheader__ - * _createxbl.py_ - Concatenates XBL segments into one ELF image -`Python` - * _ipqheader.py_ - Returns a packed MBN header image with the -specified base and size `Python` - * _mbncat.py_ - Generate ipq8064 uber SBL `Python` - * *mbn_tools.py* - Contains all MBN Utilities for image -generation `Python` * __kbc1126__ - Tools used to dump the two blobs from the factory firmware of many HP laptops with 8051-based SMSC KBC1098/KBC1126 embedded controller and insert them to the firmware image. `C` @@ -107,8 +99,16 @@ devices on the board such as dGPU. `C` * __post__ - Userspace utility that can be used to test POST cards. `C` * __qemu__ - Makefile & comprehensive default config for QEMU Q35 emulation `Make` -* __qualcomm__ - CMM script to debug Qualcomm coreboot environments. -`CMM` +* __qualcomm__ - __cmm__ + * CMM script to debug Qualcomm coreboot environments. `CMM` +__ipqheader__ + * _createxbl.py_ - Concatenates XBL segments into one ELF image +`Python` + * _ipqheader.py_ - Returns a packed MBN header image with the +specified base and size `Python` + * _mbncat.py_ - Generate ipq8064 uber SBL `Python` + * *mbn_tools.py* - Contains all MBN Utilities for image +generation `Python` * __release__ - Generate coreboot release `Bash` * __riscv__ * _make-spike-elf.sh_ - Converts a flat file into an ELF, that @@ -118,6 +118,8 @@ SiFive's bootrom. `Python3` * __rockchip__ - Generate Rockchip idblock bootloader. `Python3` * __sconfig__ - coreboot device tree compiler `Lex` `Yacc` * __scripts__ + * capture_commands.sh - Write all commands from the build to a +file. `Shell` * _config_ - Manipulate options in a .config file from the command line `Bash` * _cross-repo-cherrypick_ - Pull in patches from another tree @@ -126,6 +128,8 @@ from a gerrit repository. `Shell` into various human readable formats. `Bash` * _dts-to-fmd.sh_ -Converts a depthcharge fmap.dts into an fmaptool compatible .fmd format `Bash` + * _find_new_user_commits.sh_ - Finds new gerrit committers +`Bash` * _find-unused-kconfig-symbols.sh_ - Points out Kconfig variables that may be unused. There are some false positives, but it serves as a starting point `Shell` diff --git a/util/README.md b/util/README.md index ec1c6bf7ce..7a98bb6061 100644 --- a/util/README.md +++ b/util/README.md @@ -21,8 +21,8 @@ binary with specific SPDs and GPIO selection pins. `Python3` * _apcb_v3_edit.py_ - This tool allows patching an existing APCB v3 binary with up to 16 specific SPDs. `Python3` * __archive__ - Concatenate files and create an archive `C` -* __autoport__ - Automated porting coreboot to Sandy Bridge/Ivy Bridge -platforms `Go` +* __autoport__ - Automated porting coreboot to Sandy Bridge/Ivy +Bridge/Haswell platforms `Go` * __bincfg__ - Compiler/Decompiler for data blobs with specs `Lex` `Yacc` * __board_status__ - Tools to collect logs and upload them to the board @@ -55,6 +55,8 @@ Controller (EC). `C` * __genbuild_h__ - Generate build system definitions `Shell` * __gitconfig__ - Initialize git repository submodules install git hooks `Bash` +* __hda-decoder__ - Dumps decoded HDA default configuration registers +into a format which can be used in coreboot's verb table `Go` * __ifdtool__ - Extract and dump Intel Firmware Descriptor information `C` * __intelmetool__ - Dump interesting things about Management Engine @@ -64,14 +66,6 @@ an inteltool dump to coreboot macros. `go` * __inteltool__ - Provides information about the Intel CPU/chipset hardware configuration (register contents, MSRs, etc). `C` * __intelvbttool__ - Parse VBT from VGA BIOS `C` -* __ipqheader__ - * _createxbl.py_ - Concatenates XBL segments into one ELF image -`Python` - * _ipqheader.py_ - Returns a packed MBN header image with the -specified base and size `Python` - * _mbncat.py_ - Generate ipq8064 uber SBL `Python` - * *mbn_tools.py* - Contains all MBN Utilities for image -generation `Python` * __kbc1126__ - Tools used to dump the two blobs from the factory firmware of many HP laptops with 8051-based SMSC KBC1098/KBC1126 embedded controller and insert them to the firmware image. `C` @@ -96,8 +90,16 @@ devices on the board such as dGPU. `C` * __post__ - Userspace utility that can be used to test POST cards. `C` * __qemu__ - Makefile & comprehensive default config for QEMU Q35 emulation `Make` -* __qualcomm__ - CMM script to debug Qualcomm coreboot environments. -`CMM` +* __qualcomm__ - __cmm__ + * CMM script to debug Qualcomm coreboot environments. `CMM` +__ipqheader__ + * _createxbl.py_ - Concatenates XBL segments into one ELF image +`Python` + * _ipqheader.py_ - Returns a packed MBN header image with the +specified base and size `Python` + * _mbncat.py_ - Generate ipq8064 uber SBL `Python` + * *mbn_tools.py* - Contains all MBN Utilities for image +generation `Python` * __release__ - Generate coreboot release `Bash` * __riscv__ * _make-spike-elf.sh_ - Converts a flat file into an ELF, that @@ -107,6 +109,8 @@ SiFive's bootrom. `Python3` * __rockchip__ - Generate Rockchip idblock bootloader. `Python3` * __sconfig__ - coreboot device tree compiler `Lex` `Yacc` * __scripts__ + * capture_commands.sh - Write all commands from the build to a +file. `Shell` * _config_ - Manipulate options in a .config file from the command line `Bash` * _cross-repo-cherrypick_ - Pull in patches from another tree @@ -115,6 +119,8 @@ from a gerrit repository. `Shell` into various human readable formats. `Bash` * _dts-to-fmd.sh_ -Converts a depthcharge fmap.dts into an fmaptool compatible .fmd format `Bash` + * _find_new_user_commits.sh_ - Finds new gerrit committers +`Bash` * _find-unused-kconfig-symbols.sh_ - Points out Kconfig variables that may be unused. There are some false positives, but it serves as a starting point `Shell` diff --git a/util/util_readme/util_readme.sh b/util/util_readme/util_readme.sh index 986c393ca8..41ee4087fe 100755 --- a/util/util_readme/util_readme.sh +++ b/util/util_readme/util_readme.sh @@ -21,10 +21,8 @@ DESCRIPTION_FILES=$(find "$UTIL_DIR" -name "description.md" | sort) echo -n "" > "$UTIL_DIR/README.md" { - echo - echo "[//]: # ( DO NOT EDIT - AUTOGENERATED FILE )"; - echo - echo "[//]: # ( RUN 'util/util_readme/util_readme.sh' to regenerate )"; + echo ""; + echo ""; echo; echo "# Utilities"; echo "${SUMMARY}"