summaryrefslogtreecommitdiff
path: root/Documentation/util.md
AgeCommit message (Collapse)Author
2024-10-27util/util_readme: Use HTML comments in generated outputNicholas Chin
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 <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/84885 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
2024-03-21Docs: Replace Recommonmark with MyST ParserNicholas Chin
Recommonmark has been deprecated since 2021 [1] and the last release was over 3 years ago [2]. As per their announcement, Markedly Structured Text (MyST) Parser [3] is the recommended replacement. For the most part, the existing documentation is compatible with MyST, as both parsers are built around the CommonMark flavor of Markdown. The main difference that affects coreboot is how the Sphinx toctree is generated. Recommonmark has a feature called auto_toc_tree, which converts single level lists of references into a toctree: * [Part 1: Starting from scratch](part1.md) * [Part 2: Submitting a patch to coreboot.org](part2.md) * [Part 3: Writing unit tests](part3.md) * [Managing local additions](managing_local_additions.md) * [Flashing firmware](flashing_firmware/index.md) MyST Parser does not provide a replacement for this feature, meaning the toctree must be defined manually. This is done using MyST's syntax for Sphinx directives: ```{toctree} :maxdepth: 1 Part 1: Starting from scratch <part1.md> Part 2: Submitting a patch to coreboot.org <part2.md> Part 3: Writing unit tests <part3.md> Managing local additions <managing_local_additions.md> Flashing firmware <flashing_firmware/index.md> ``` Internally, auto_toc_tree essentially converts lists of references into the Sphinx toctree structure that the MyST syntax above more directly represents. The toctrees were converted to the MyST syntax using the following command and Python script: `find ./ -iname "*.md" | xargs -n 1 python conv_toctree.py` ``` import re import sys in_list = False f = open(sys.argv[1]) lines = f.readlines() f.close() with open(sys.argv[1], "w") as f: for line in lines: match = re.match(r"^[-*+] \[(.*)\]\((.*)\)$", line) if match is not None: if not in_list: in_list = True f.write("```{toctree}\n") f.write(":maxdepth: 1\n\n") f.write(match.group(1) + " <" + match.group(2) + ">\n") else: if in_list: f.write("```\n") f.write(line) in_list = False if in_list: f.write("```\n") ``` While this does add a little more work for creating the toctree, this does give more control over exactly what goes into the toctree. For instance, lists of links to external resources currently end up in the toctree, but we may want to limit it to pages within coreboot. This change does break rendering and navigation of the documentation in applications that can render Markdown, such as Okular, Gitiles, or the GitHub mirror. Assuming the docs are mainly intended to be viewed after being rendered to doc.coreboot.org, this is probably not an issue in practice. Another difference is that MyST natively supports Markdown tables, whereas with Recommonmark, tables had to be written in embedded rST [4]. However, MyST also supports embedded rST, so the existing tables can be easily converted as the syntax is nearly identical. These were converted using `find ./ -iname "*.md" | xargs -n 1 sed -i "s/eval_rst/{eval-rst}/"` Makefile.sphinx and conf.py were regenerated from scratch by running `sphinx-quickstart` using the updated version of Sphinx, which removes a lot of old commented out boilerplate. Any relevant changes coreboot had made on top of the previous autogenerated versions of these files were ported over to the newly generated file. From some initial testing the generated webpages appear and function identically to the existing documentation built with Recommonmark. TEST: `make -C util/docker docker-build-docs` builds the documentation successfully and the generated output renders properly when viewed in a web browser. [1] https://github.com/readthedocs/recommonmark/issues/221 [2] https://pypi.org/project/recommonmark/ [3] https://myst-parser.readthedocs.io/en/latest/ [4] https://doc.coreboot.org/getting_started/writing_documentation.html Change-Id: I0837c1722fa56d25c9441ea218e943d8f3d9b804 Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/73158 Reviewed-by: Matt DeVillier <matt.devillier@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2024-03-09util: add smmstoretool for editing SMMSTORESergii Dmytruk
Offline SMMSTORE variable modification tool. Can be used to pre-configure ROM image or debug EFI state stored in a dump. Change-Id: I6c1c06f1d0c39c13b5be76a3070f09b715aca6e0 Signed-off-by: Sergii Dmytruk <sergii.dmytruk@3mdeb.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/79080 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Michał Żygowski <michal.zygowski@3mdeb.com> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
2024-02-14util/showdevicetree: drop unmaintained toolFelix Held
This tool doesn't have a makefile, when trying to compile it manually with the given instructions it even fails to compile after fixing the paths in the given command, and it references the non-existing PCI_BUS_SEGN_BITS Kconfig symbol, so just drop this. Signed-off-by: Felix Held <felix-coreboot@felixheld.de> Change-Id: I8ca75db281a215bf3f194ab72a107f666dc0694e Reviewed-on: https://review.coreboot.org/c/coreboot/+/79934 Reviewed-by: Martin Roth <martin.roth@amd.corp-partner.google.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2023-08-27doc,util: Regenerate documentation filesFelix Singer
Add new documentation generated by util/util_readme/util_readme.sh. This also fixes the following Sphinx warning: util/abuild/index.md: WARNING: document isn't included in any toctree Change-Id: I26c33af3c5a5853f6bcce23e982a6b192b01f1d7 Signed-off-by: Felix Singer <felixsinger@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/77441 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Nicholas Chin <nic.c3.14@gmail.com>
2022-07-04treewide: Unify Google brandingJon Murphy
Branding changes to unify and update Chrome OS to ChromeOS (removing the space). This CL also includes changing Chromium OS to ChromiumOS as well. BUG=None TEST=N/A Change-Id: I39af9f1069b62747dbfeebdd62d85fabfa655dcd Signed-off-by: Jon Murphy <jpmurphy@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/65479 Reviewed-by: Jack Rosenthal <jrosenth@chromium.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <felixsinger@posteo.net>
2022-06-07util, Documentation: Run util_readme.sh to regen util.mdMartin Roth
Change-Id: Ie14204d0637bb5081e2fae4a9a0e2590bf7abeeb Signed-off-by: Martin Roth <gaumless@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/64582 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Raul Rangel <rrangel@chromium.org>
2022-05-30Documentation: Move intelp2m from description.md to DocumentionMartin Roth
The description.md file for the intelp2m utility wasn't the description that was needed - just a subject, and what language it was written in. It was instead a set of more full documentation, so move it into the Documentation directory and create a new description file. Change-Id: Ia180ae41f91f8b8eb408351a9e44e899edc031d3 Signed-off-by: Martin Roth <gaumless@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/64578 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <felixsinger@posteo.net>
2022-05-28Documentation: Move cbfstool & ifdtool dirs under util\Martin Roth
Change-Id: If1b263345baf321cde75058f310c96d89a95d62d Signed-off-by: Martin Roth <gaumless@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/64577 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <felixsinger@posteo.net>
2022-01-10util/apcb: Add apcb_v3_edit toolRob Barnes
apcb_v3_edit.py tool edits APCB V3 binaries. Specifically it will inject up to 16 SPDs into an existing APCB. The APCB must have a magic number at the top of each SPD slot. BUG=b:209486191 BRANCH=None TEST=Inject 4 SPDs into magic APCB, boot guybrush with modified APCB Change-Id: I9148977c415df41210a3a13a1cd9b3bc1504a480 Signed-off-by: Rob Barnes <robbarnes@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/60281 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Raul Rangel <rrangel@chromium.org>
2021-10-05Documentation: Fix spelling errorsMartin Roth
These issues were found and fixed by codespell, a useful tool for finding spelling errors. Signed-off-by: Martin Roth <martin@coreboot.org> Change-Id: If2a8e97911420c19e9365d5c28810b998f2c2ac8 Reviewed-on: https://review.coreboot.org/c/coreboot/+/58078 Reviewed-by: Felix Held <felix-coreboot@felixheld.de> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2021-01-28Update util.md documentationMartin Roth
This is the new output of the util_readme.sh script. Signed-off-by: Martin Roth <martin@coreboot.org> Change-Id: Ia46924474f75692192ef4b52aab714f5071f9534 Reviewed-on: https://review.coreboot.org/c/coreboot/+/48966 Reviewed-by: Patrick Georgi <pgeorgi@google.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2020-12-11Docs/cbfstool: Add details about memory mapped window handlingFurquan Shaikh
This change adds details memory mapped window handling in cbfstool required for x86 platforms. It also captures the details about the newly added support for multiple decode windows. BUG=b:171534504 Change-Id: Icf970f951e56d717e6a4f8845fc73f10d5a21dd0 Signed-off-by: Furquan Shaikh <furquan@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/48477 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org> Reviewed-by: Duncan Laurie <dlaurie@chromium.org>
2020-04-20Doc,util: Update list of utilitiesJacob Garber
Remove entries for old utilities and add entries for new ones. Generated using util/util_readme, with some tweaks to preserve the markdown. Change-Id: I3a4d8a6bf15a677aa07aa72b8809328110fb72da Signed-off-by: Jacob Garber <jgarber1@ualberta.ca> Reviewed-on: https://review.coreboot.org/c/coreboot/+/40504 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2020-03-04util: Remove viatoolAngel Pons
It somehow creeps into `make clean`, but is not used at all. Since no VIA platform remains in coreboot, drop the utility as well. Change-Id: Ia7e11379a6db650b5190a056226a9101c2be7dec Signed-off-by: Angel Pons <th3fanbus@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/38853 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2019-11-20Remove imgtec/pistachio SoCJulius Werner
After removing urara no board still uses this SoC, and there are no plans to add any in the future (I'm not sure if the chip really exists tbh...). Change-Id: Ic4628fdfacc9fb19b6210394d96431fdb5f8e8f1 Signed-off-by: Julius Werner <jwerner@chromium.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/36491 Reviewed-by: Arthur Heymans <arthur@aheymans.xyz> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2019-10-21Documentation: Make sure ifdtool/index gets added to toctreeArthur Heymans
Change-Id: I57b37ebd3383e73a101511e303ad3beeb9d4ea31 Signed-off-by: Arthur Heymans <arthur@aheymans.xyz> Reviewed-on: https://review.coreboot.org/c/coreboot/+/36109 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Rudolph <siro@das-labor.org>
2019-10-03ifdtool: Add validate option to ifdtoolMathew King
Add an option to ifdtool which validates that the flash regions defined in the descriptor match the coresponding areas in the FMAP. BUG=chromium:992215 TEST=Ran 'ifdtool -t' with a good bios image and verify no issues run 'ifdtool -t' with a bad bios image and verify expected issues Signed-off-by: Mathew King <mathewk@chromium.org> Change-Id: Idebf105dee1b8f829d54bd65c82867af7aa4aded Reviewed-on: https://review.coreboot.org/c/coreboot/+/34802 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
2018-12-19utils: introduce find_usbdebug.sh to help find USB debug portsStefan Tauner
Carl-Daniel made this script a long time ago but it never was picked up in the tree. Now that USB debugging is way more common it makes sense to include it. I have made a number of changes to the original version: * -h help text * check for running as root * enhanced readability (test -> if) * new execution flow and refined output that better shows the device(s) attached to the debug port(s) * handling of Intel rate-matching hubs * hiding of (bogus) error messages from lspci and lsusb Signed-off-by: Stefan Tauner <stefan.tauner@gmx.at> Change-Id: Iadf775e990f5c5f91a28d57e3331d1f59acee305 Reviewed-on: https://review.coreboot.org/c/9305 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2018-12-18util/bucts: Add a description.md fileJonathan Neuschäfer
Change-Id: I367703ffcd8d10dec0c67b61c9ebbefd497424fd Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Reviewed-on: https://review.coreboot.org/c/30161 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2018-11-30broadcom: Remove SoC and board supportPhilipp Deppenwiese
The reason for this code cleanup is the legacy Google Purin board which isn't available anymore and AFAIK never made it into the stores. * Remove broadcom cygnus SoC support * Remove /util/broadcom tool * Remove Google Purin mainboard * Remove MAINTAINERS entries Change-Id: I148dd7eb0192d396cb69bc26c4062f88a764771a Signed-off-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com> Reviewed-on: https://review.coreboot.org/c/29905 Reviewed-by: Julius Werner <jwerner@chromium.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2018-09-30Documentation: add description for util/pmh7toolEvgeny Zinoviev
Change-Id: Iab5daf101a9ff27aa49b7849bf6bf39362b8db09 Signed-off-by: Evgeny Zinoviev <me@ch1p.com> Reviewed-on: https://review.coreboot.org/28368 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Tom Hiller <thrilleratplay@gmail.com> Reviewed-by: Felix Held <felix-coreboot@felixheld.de>
2018-08-23util/ifdfake: Remove deprecated utilityAngel Pons
Since ifdfake has been deprecated in favor of better alternatives, there is no need to support it any further. Remove it from "util/", as well as any leftover references in other files. Change-Id: I45fe3d9fd606a61d5c3b9d0e6489a1df6d6510f0 Signed-off-by: Angel Pons <th3fanbus@gmail.com> Reviewed-on: https://review.coreboot.org/28234 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Nico Huber <nico.h@gmx.de> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
2018-07-31Documentation: Add util.md summaryTom Hiller
Add short explanation of Utility list Change-Id: I5fc45ebe29cd42c1aa18c59dabc3ac3db3107bd7 Signed-off-by: Tom Hiller <thrilleratplay@gmail.com> Reviewed-on: https://review.coreboot.org/27656 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Patrick Rudolph <siro@das-labor.org> Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
2018-07-26util: Add util_readme scriptTom Hiller
Bash script to concatenate description.md files into ./util/README.md and Documention/Util.md Change-Id: I015ae6816ea74cacb7f0332fda2c3ebef205c1e2 Signed-off-by: Tom Hiller <thrilleratplay@gmail.com> Reviewed-on: https://review.coreboot.org/27564 Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-16 21:42:45 +0000