summaryrefslogtreecommitdiff
path: root/Documentation/tutorial
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>
2024-02-26Documentation/tutorial/part1.md: Reformat Redhat package descriptionJuan José García-Castro Crespo
Convert multiline Redhat package list to one-line code markup. Change-Id: I1ba38bf2fc767a3f1694c55cf50e137ce10bfd75 Signed-off-by: Juan José García-Castro Crespo <jjgcc@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/80749 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
2024-02-26Documentation/tutorial/part1.md: Install libssl-dev and pkg-config on DebianJuan José García-Castro Crespo
Missing pkg-config and libcrypto when building coreboot (Step 6) on Debian 12 (bookworm). Add required packages to Step 1, libssl-dev and pkg-config. Change-Id: I5df06611a934d1ef85c8335764f4f6e0f241c9a9 Signed-off-by: Juan José García-Castro Crespo <jjgcc@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/80722 Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2024-01-26Documentation: Update Makefile .inc references to .mkMartin Roth
Signed-off-by: Martin Roth <gaumless@gmail.com> Change-Id: I464170e60a22f39225044c6794d091455d931e9c Reviewed-on: https://review.coreboot.org/c/coreboot/+/80128 Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Held <felix-coreboot@felixheld.de>
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>
2023-08-26docs: Tidy up the English in the testing tutorialSimon Glass
Tweak a few sentences noticed when reading this. BUG=none BRANCH=none TEST=none Change-Id: I0a072c83402bc551a6bbdb7cd7c55fc3505784b2 Signed-off-by: Simon Glass <sjg@chromium.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/77096 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/77464 Reviewed-by: Martin L Roth <gaumless@gmail.com> Reviewed-by: Patrick Georgi <patrick@coreboot.org> Tested-by: Patrick Georgi <patrick@coreboot.org>
2023-05-11Documentation/tutorial: Improve clarity of Part 1Nicholas Chin
Based on feedback and experiences from new coreboot users, it isn't clear that Tutorial 1 is mainly intended to set up the toolchain and will not produce a bootable ROM for their board. Thus, add a note explicitly mentioning this with a short explanation. The process of manually building and adding the payload is also unusual, since payloads are usually handled automatically by the build system. This adds a note in the summary to provide an explanation of this. The savedefconfig output is also outdated, as Kconfig now outputs additional lines (even though many of those are the same as the defaults). This has caused confusion, leading users to think that they may have configured coreboot incorrectly. Update this to the current defconfig contents and add a note that this may change depending on the coreboot version. Change-Id: I13206aa05a425ddfe33ee35feff0db490585a59f Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/73816 Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2023-05-02doc/tutorial/part1.md: Fix package name to install qemu on DebianDaniel R. Franzini
Fix package name to install qemu on Debian. It used to be 'qemu' only but it is now called 'qemu-system'. Signed-off-by: Daniel R. Franzini <danielt3@usp.br> Change-Id: Ibae9031a3e397925db95b7283fa8c6573f6d5858 Reviewed-on: https://review.coreboot.org/c/coreboot/+/74894 Reviewed-by: Nico Huber <nico.h@gmx.de> Reviewed-by: Sean Rhodes <sean@starlabs.systems> Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
2023-03-02Documentation/tutorial/part1: fix payload instructionsDaniel Maslowski
The instructions and actual menu got a bit out of sync, or were just inaccurate. This fixes the notes on the payload. Change-Id: I22d6588ef3708e98a8fd9b0652b3f827ff9ff698 Signed-off-by: Daniel Maslowski <info@orangecms.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/73355 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Felix Held <felix-coreboot@felixheld.de> Reviewed-by: Lance Zhao <lance.zhao@gmail.com> Reviewed-by: Felix Singer <felixsinger@posteo.net>
2022-10-10Documentation/flashing_firmware: Add info about SPI flash headerNicholas Chin
Some mainboards have a header connected to the SPI bus, which can be used to connect a second flash chip and override the onboard flash. This allows one to boot coreboot on the system without ever having to flash the onboard flash. HP boards with this header all seem to use the same 2x8 or 2x10 header layout, so document the pinout. Change-Id: Ic2bf1244adfb78872340f212519c6ab33e26646a Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/67818 Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2022-08-29Documentation/tutorial: Fix markdown heading in Part 3Nicholas Chin
Part of the content was on the same line as the heading. Change-Id: Ia19487d80e9f004d59f96ff09e1f3de4f37c2f77 Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/67000 Reviewed-by: Felix Singer <felixsinger@posteo.net> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2022-06-24Docs/tutorial: Wrap the text in part?.md to 72 charactersMartin Roth
Signed-off-by: Martin Roth <gaumless@gmail.com> Change-Id: I4f0a07b4ab729aafdb4a1149a7617cd34392cf12 Reviewed-on: https://review.coreboot.org/c/coreboot/+/64967 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
2022-06-24Docs/tutorial: Update markdown for part1Martin Roth
The tutorial documents were updated from the wiki very early in the transition to markdown, and the style has changed over time. This updates the markdown style to match documents that are being created now. Signed-off-by: Martin Roth <gaumless@gmail.com> Change-Id: I619c04f420042f530335482c30070436f9190865 Reviewed-on: https://review.coreboot.org/c/coreboot/+/64966 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <felixsinger@posteo.net> Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
2022-03-15Documentation/tutorial/part1.md: Add Fedora package `patch`Eloy Degen
It is necessary to build crossgcc. Change-Id: I32f6507b4d8346bf94aaccd3eef4f22697c33965 Signed-off-by: Eloy Degen <degeneloy@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/62765 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Singer <felixsinger@posteo.net> Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2022-03-11Documentation: Move firmware flashing tutorial to tutorial sectionFelix Singer
There is no need that the tutorial for flashing firmware has its own point in the main menu. Thus, move it to the tutorial section. Change-Id: Ife6d97254af4c006fe01480a78c76303f9cb34bb Signed-off-by: Felix Singer <felixsinger@posteo.net> Reviewed-on: https://review.coreboot.org/c/coreboot/+/62424 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Thomas Heijligen <src@posteo.de>
2021-12-06Documentation: Update SSH key procedurePatrick Georgi
Use ed25519 keys because recent changes to RSA keys in OpenSSH are making a mess. Also update references to the Gerrit UI to match the current version. Change-Id: Ib13836feb6968307d2c8b3022cb0c859dac89bb8 Signed-off-by: Patrick Georgi <patrick@coreboot.org> Reviewed-on: https://review.coreboot.org/c/coreboot/+/59806 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@mailbox.org> Reviewed-by: Felix Singer <felixsinger@posteo.net>
2021-11-22Documentation: Add warning about "private" changes on GerritPatrick Georgi
Private changes on Gerrit are a tricky beast in that they're well hidden in the UI and a few other places but still reachable under certain circumstances. Change-Id: I1c8c6cccfd023bc1d839dc5d9544204c88f89c7e Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/59229 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-09-01tests: Improve test output readabilityJakub Czapiga
When running multiple tests, e.g. by using unit-tests target, it is hard to differentiate, which output comes from which file and/or configuration. This patch makes the output easier to analyze and understand by using new wrapper macro cb_run_group_tests(). This macro uses __TEST_NAME__ value (containing test path and Makefile test name) as a group name when calling cmocka group runner. Example: Test path: tests/lib/ Makefile test name: cbmem_stage_cache-test Test group array name: tests Result: tests/lib/cbmem_stage_cache-test(tests) Signed-off-by: Jakub Czapiga <jacz@semihalf.com> Change-Id: I4fd936d00d77cbe2637b857ba03b4a208428ea0d Reviewed-on: https://review.coreboot.org/c/coreboot/+/57144 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Fagerburg <pfagerburg@chromium.org> Reviewed-by: Julius Werner <jwerner@chromium.org>
2021-06-10tests: Rework mocking facilityPatrick Georgi
Using the linker's --wrap feature has the downside that it only covers references across object files: If foo.c defines a() and b(), with b calling a, --wrap=a does nothing to that call. Instead, use objcopy to mark a weak and global so it can be overridden by another implementation, but only for files originating in src/. That way mocks - implemented in tests/ - become the source of truth. TEST=Had such an issue with get_log_level() in a follow-up commit, and the mock now takes over. Also, all existing unit tests still pass. Change-Id: I99c6d6e44ecfc73366bf464d9c51c7da3f8db388 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/55360 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jakub Czapiga <jacz@semihalf.com>
2021-05-19tests: improve code coverage supportPaul Fagerburg
Fix the exclusion path for lcov; it should exclude the directory with source code, not object files. Use the COV environment variable to * control whether we build for coverage or not * select the output directory Add a separate target for generating the report, so we can get a report for all of the tests together or just a single test. Add documentation. Signed-off-by: Paul Fagerburg <pfagerburg@google.com> Change-Id: I2bd2bfdedfab291aabeaa968c10b17e9b61c9c0a Reviewed-on: https://review.coreboot.org/c/coreboot/+/54072 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jakub Czapiga <jacz@semihalf.com>
2021-03-17Documentation: Describe the site-local hook in our config/build systemPatrick Georgi
Change-Id: Ia682b784540fa82e1f216f76d87d59a4f0b94486 Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/51546 Reviewed-by: Furquan Shaikh <furquan@google.com> Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2020-07-22Doc/tutorial/part1.md: Show how to list toolchain targetsDavid Hendricks
Change-Id: I276ea0a6b52b55b8772c76f48f7a0fb149af6e78 Signed-off-by: David Hendricks <david.hendricks@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/43518 Reviewed-by: Angel Pons <th3fanbus@gmail.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
2020-07-16Documentation: Remove mention of manual checkpatch.pl invocationPatrick Georgi
We typically call checkpatch.pl through make lint which properly adds the option to tell checkpatch that our lines may be 96 columns long. However there's one mention of calling checkpatch directly and that confuses people with complaints about overly long lines that exceed 80 columns. The lint test that runs checkpatch (and with the right options) can also be used on a per-directory basis, so offer that instead. Change-Id: If21e925d2d2394c876724a44b0e23c9b2744c56b Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/43450 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Angel Pons <th3fanbus@gmail.com> Reviewed-by: Nico Huber <nico.h@gmx.de>
2020-05-30Documentation/tutorial: Add tutorial for writing unit testsJan Dabros
Signed-off-by: Jan Dabros <jsd@semihalf.com> Change-Id: I1ebd2786a49ec8bc25e209d67ecc4c94b475442d Reviewed-on: https://review.coreboot.org/c/coreboot/+/41727 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Fagerburg <pfagerburg@chromium.org> Reviewed-by: Patrick Georgi <pgeorgi@google.com>
2020-02-17treewide: capitalize 'BIOS'Elyes HAOUAS
Also replace 'BIOS' by coreboot when the image is 'coreboot.rom'. Change-Id: I8303b7baa9671f19a036a59775026ffd63c85273 Signed-off-by: Elyes HAOUAS <ehaouas@noos.fr> Reviewed-on: https://review.coreboot.org/c/coreboot/+/38932 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2020-02-12doc/tutorial/part1.md: Add commands for yum- & pacman-based distroPatrik Tesarik
* Add additional information on non-debian cli tools * Improve spellings and descriptions to the best of my knowledge Adding info about needed tools in other distribution's package managers was requested at the coreboot beginner's workshop at 36C3. Change-Id: Ifff3c8354b4bec9f195f075eb6b2f377195fc237 Signed-off-by: Patrik Tesarik <mail@patrik-tesarik.de> Reviewed-on: https://review.coreboot.org/c/coreboot/+/38225 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Felix Held <felix-coreboot@felixheld.de>
2019-12-26Doc/tutorial/part2.md: Align headings with part1.mdAngel Pons
Substitute `Part` with `Step` on this file's headings and use present tense instead of gerund. Change-Id: Ic130ed9865be43716e7de3121534761d9fc2ae8d Signed-off-by: Angel Pons <th3fanbus@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/37933 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jacob Garber <jgarber1@ualberta.ca>
2019-12-26Doc/tutorial/part1.md: Fix minor formatting issuesAngel Pons
Make sure all titles are capitalized, and add a missing period. Change-Id: I48b8d6c85b915cc422bdfa3a89804f92f46800ba Signed-off-by: Angel Pons <th3fanbus@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/37932 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Jacob Garber <jgarber1@ualberta.ca>
2019-12-10Documentation: Describe how to deal with snooping https proxiesPatrick Georgi
Disabling SSL verification is far from optimal, but depending on the circumstances may be the most practical way, so describe how to do that instead of leaving users confused. It's also not _that_ bad because git's hashing scheme should uncover most attempts to tamper with code, either when checking signed tags or when people push (and see lots of modified commits). State the command in a way that isn't conductive to careless copy & paste. Change-Id: Idbd52ba5d6e8b0f0e891fca16e4159ccef10771a Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/37599 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
2019-11-28Documentation: Rework staging and commit informationDavid Hendricks
This patch does two things: - The CLI and Git Cola sections contained some duplicated information about pushing patches, which is now factored out into its own section. - The draft workflow is now disabled, so that part has been reworded to describe how to submit a private patch. Signed-off-by: David Hendricks <david.hendricks@gmail.com> Change-Id: I562c101ab2ee78d901be7e99165daba7473dc3c1 Reviewed-on: https://review.coreboot.org/c/coreboot/+/37256 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Stefan Reinauer <stefan.reinauer@coreboot.org>
2019-09-16Documentation: rename "Rookie guide" to "tutorial"Patrick Georgi
We generally try to stay away from ascribing attributes to (future) devs. "Rookie guide" refers to the reader, while "tutorial" refers to the material. In the same spirit, move from "lessons" to "parts". It's not school :-) Change-Id: I11a69a2a05ba9a0bc48f8bf62463d9585da043ec Signed-off-by: Patrick Georgi <pgeorgi@google.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/35425 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Lance Zhao <lance.zhao@gmail.com> Reviewed-by: Jacob Garber <jgarber1@ualberta.ca> Reviewed-by: Angel Pons <th3fanbus@gmail.com>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-12 13:42:46 +0000