summaryrefslogtreecommitdiff
path: root/Documentation/lib
AgeCommit message (Collapse)Author
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>
2023-10-28doc/lib/flashmap: Fix incorrect path to FMD implementationNicholas Sudsgaard
Change-Id: I6864cd041d7173cd284f47d09f4388341a7ee756 Signed-off-by: Nicholas Sudsgaard <devel+coreboot@nsudsgaard.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/78690 Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2023-09-15Documentation: Adjust master -> main branchStefan Reinauer
Some of our documentation still points to the wrong branches Change-Id: Idb72e4f44f294f64eb01c588027d300a53d6fb41 Signed-off-by: Stefan Reinauer <stefan.reinauer@coreboot.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/77875 Reviewed-by: Patrick Georgi <patrick@coreboot.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2022-12-30fw_config: Fix typo in documentBora Guvendik
There is no fw_config_probe_one api, change it to fw_config_probe. BUG=none TEST=none Signed-off-by: Bora Guvendik <bora.guvendik@intel.com> Change-Id: I916713c038f72a1718be8c9d4e8e21420effbf76 Reviewed-on: https://review.coreboot.org/c/coreboot/+/71276 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Eric Lai <eric_lai@quanta.corp-partner.google.com> Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
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>
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-06-11docs/flashmap: state the endianness of FMAPKrystian Hebel
Signed-off-by: Krystian Hebel <krystian.hebel@3mdeb.com> Change-Id: Idf6d46ed262b18c176d69352e333c56f4fdff66a Reviewed-on: https://review.coreboot.org/c/coreboot/+/55041 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2021-05-28option: Allow mainboards to implement the APIAngel Pons
Some mainboards need a mainboard-specific mechanism to access option values. Allow mainboards to implement the option API. Also, add some documentation about the current option API, and describe when should one reimplement the option API in mainboard code: only when the code is mainboard-specific to comply with externally-imposed constraints. Change-Id: Idccdb9a008b1ebb89821961659f27b1c0b17d29c Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com> Signed-off-by: Angel Pons <th3fanbus@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/54729 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
2021-05-03util/sconfig: Add support for discontiguous FW_CONFIG fieldsTim Wawrzynczak
Sooner or later, some board was going to need extra FW_CONFIG bits for a field that was already in production, so this patch adds support for adding extra (unused) bits to a field. The extra are appended via a syntax like: `field FIELD_NAME START0 END0 | START1 END1 | START2 END2 ...` and the suffixed bits are all treated as if they are contiguous when defining option values. BUG=b:185190978 TEST=Modified volteer fw_config to the following: field AUDIO 8 10 | 29 29 | 31 31 option NONE 0 option MAX98357_ALC5682I_I2S 1 option MAX98373_ALC5682I_I2S 2 option MAX98373_ALC5682_SNDW 3 option MAX98373_ALC5682I_I2S_UP4 4 option MAX98360_ALC5682I_I2S 5 option RT1011_ALC5682I_I2S 6 option AUDIO_FOO 7 option AUDIO_BAR 8 option AUDIO_QUUX 9 option AUDIO_BLAH1 10 option AUDIO_BLAH2 15 option AUDIO_BLAH3 16 option AUDIO_BLAH4 31 end which yielded (in static_fw_config.h): FW_CONFIG_FIELD_AUDIO_MASK 0xa0000700 FW_CONFIG_FIELD_AUDIO_OPTION_NONE_VALUE 0x0 FW_CONFIG_FIELD_AUDIO_OPTION_MAX98357_ALC5682I_I2S_VALUE 0x100 FW_CONFIG_FIELD_AUDIO_OPTION_MAX98373_ALC5682I_I2S_VALUE 0x200 FW_CONFIG_FIELD_AUDIO_OPTION_MAX98373_ALC5682_SNDW_VALUE 0x300 FW_CONFIG_FIELD_AUDIO_OPTION_MAX98373_ALC5682I_I2S_UP4_VALUE 0x400 FW_CONFIG_FIELD_AUDIO_OPTION_MAX98360_ALC5682I_I2S_VALUE 0x500 FW_CONFIG_FIELD_AUDIO_OPTION_RT1011_ALC5682I_I2S_VALUE 0x600 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_FOO_VALUE 0x700 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BAR_VALUE 0x20000000 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_QUUX_VALUE 0x20000100 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH1_VALUE 0x20000200 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH2_VALUE 0x20000700 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH3_VALUE 0x80000000 FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH4_VALUE 0xa0000700 Change-Id: I5ed76706347ee9642198efc77139abdc3af1b8a6 Signed-off-by: Tim Wawrzynczak <twawrzynczak@chromium.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/52747 Reviewed-by: Duncan Laurie <duncan@iceblink.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2020-10-30fw_config: Convert fw_config to a 64-bit fieldTim Wawrzynczak
We all knew this was coming, 32 bits is never enough. Doing this early so that it doesn't affect too much code yet. Take care of every usage of fw_config throughout the codebase so the conversion is all done at once. BUG=b:169668368 TEST=Hacked up this code to OR 0x1_000_0000 with CBI-sourced FW_CONFIG and verify the console print contained that bit. Signed-off-by: Tim Wawrzynczak <twawrzynczak@chromium.org> Change-Id: I6f2065d347eafa0ef7b346caeabdc3b626402092 Reviewed-on: https://review.coreboot.org/c/coreboot/+/45939 Reviewed-by: Furquan Shaikh <furquan@google.com> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2020-08-19arch/arm: Enable FIT payloadsSam Lewis
Implements fit_payload_arch for the arm (aarch32) architecture, so that FIT images can be used. The implementation is very similar to the existing implementations for arm64 and riscv, and has mostly been lifted from these other ports. TEST: Booted Beaglebone Black (in progress port, to be submitted soon!) with a FIT image containing a 5.4 kernel, dtb and initramfs. Change-Id: I6b50c6f06b83c00a5b3622b5bbafe67130b6d233 Signed-off-by: Sam Lewis <sam.vr.lewis@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/44377 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Julius Werner <jwerner@chromium.org>
2020-06-02fw_config: Add firmware configuration interfaceDuncan Laurie
This change introduces a new top-level interface for interacting with a bitmask providing firmware configuration information. This is motivated by Chromebook mainboards that need to support multiple different configurations at runtime with the same BIOS. In these devices the Embedded Controller provides a bitmask that can be broken down into different fields and each field can then be broken down into different options. The firmware configuration value could also be stored in CBFS and this interface will look in CBFS first to allow the Embedded Controller value to be overridden. The firmware configuration interface is intended to easily integrate into devicetree.cb and lead to less code duplication for new mainboards that make use of this feature. BUG=b:147462631 TEST=this provides a new interface that is tested in subsequent commits Change-Id: I1e889c235a81545e2ec0e3a34dfa750ac828a330 Signed-off-by: Duncan Laurie <dlaurie@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/41209 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Furquan Shaikh <furquan@google.com>
2020-01-10{Documentation,soc/intel}: Fix typoElyes HAOUAS
Change-Id: I708ab503ece37f44cc38511aad2383ab2cec3368 Signed-off-by: Elyes HAOUAS <ehaouas@noos.fr> Reviewed-on: https://review.coreboot.org/c/coreboot/+/37468 Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2019-10-24Documentation: trivial typo fix strcut/structMarty E. Plummer
Change-Id: I5e7d8e8a95e5bef23307eb50456a89e0e23c445a Signed-off-by: Marty E. Plummer <hanetzer@startmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/36299 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Held <felix-coreboot@felixheld.de>
2019-08-08arch/riscv: Enable FIT supportJonathan Neuschäfer
Tested on qemu-riscv. Depends on OpenSBI integration and proper memory detection in qemu. Boots into Linux until initrd should be loaded. Tested on SiFive/unleashed: Boots into Linux until earlycon terminates. Change-Id: I5ebc6cc2cc9e328f36d70fba13555386bb8c29d6 Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/30292 Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2019-04-19Documentation: Add small fixesPatrick Rudolph
* Remove empty security.md * Remove second H1 header from lib/index.md * Move two documents in appropriate subfolders * Fix file path * Drop document overview Change-Id: I0e9df6203e82003c01b84967ea6bd779d7583fef Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/32340 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Hung-Te Lin <hungte@chromium.org> Reviewed-by: Martin Roth <martinroth@google.com>
2019-04-11Documentation: Explain FMAP and FMDHung-Te Lin
The Flashmap (FMAP) was not clearly documented. The new flashmap.md explains where to find more details about that and how / why it was used in coreboot. Also explained what is FMD and how to use it (based on original README.fmaptool). BUG=None TEST=None (only documentation) Change-Id: Ia389e56c632096d7c905ed221fd4f140dec382e6 Signed-off-by: Hung-Te Lin <hungte@chromium.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/31766 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Patrick Rudolph <siro@das-labor.org>
2018-12-19Documentation/*/fit.md: Fix reference to arm64 FIT implementation fileJonathan Neuschäfer
Change-Id: I5844642e25f4c9fe114f621446b4df1075500441 Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Reviewed-on: https://review.coreboot.org/c/30174 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Tristan Corrick <tristan@corrick.kiwi>
2018-10-29Documentation: Improve payload fitPatrick Rudolph
* Convert '' to ` * Add example how to use mkimage Change-Id: Id83db3db51582cb0d6ded7f3152b5549fba1f2e7 Signed-off-by: Patrick Rudolph <siro@das-labor.org> Reviewed-on: https://review.coreboot.org/29319 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
2018-09-28Documentation/lib/payloads/fit.md: Consistently indent with tabsJonathan Neuschäfer
Sphinx displays a tab as four spaces, which makes code indented with eight spaces per level stand out. Format the example configuration file in fit.md consistently with tabs to make it look consistent everywhere. Change-Id: Ia1d4c44e68e5267bac1f0f558421c6a0c7a9329c Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net> Reviewed-on: https://review.coreboot.org/28734 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Ronald G. Minnich <rminnich@gmail.com> Reviewed-by: Patrick Rudolph <siro@das-labor.org>
2018-08-08Documentation: Add FIT payload documentationPatrick Rudolph
Describe the new uImage.FIT loader. Change-Id: I8b2060f2a63406669196bcbc190cc1511ae9fe94 Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com> Reviewed-on: https://review.coreboot.org/27253 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Philipp Deppenwiese <zaolin.daisuki@gmail.com>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-11 12:56:47 +0000