This fixes the following MyST Parser warnings:
- Non-consecutive header level increase
- Document headings start at H2, not H1
The header levels (the number of "#" characters before a heading) are
intended to form a logical hierarchy of each section and subsection in a
document. A subsection typically should have a header level one more
than its parent section. Most of these warnings are caused by extra "#"
characters, which were simply removed, or sections missing a "#"
character to make it fall under its parent section.
Notable changes:
getting_started/kconfig.md: Changed the header level of the "Keywords"
section from 2 to 3 to fall under "Kconfig Language" (level 2), and
increased the level of each keyword from 3 to 4 to remain under
"Keywords". This also fixes the warnings of "H3 to H5" increases, since
the Usage/Example/Notes/Restrictions sections for each keyword had a
level of 5.
soc/intel/cse_fw_update/cse_fw_update.md: Changed the first line to a
top level header acting as the title of the document. Without this
soc/intel/index.md displays all the level 2 headers in this document
instead of a single link to cse_fw_update.md.
Change-Id: Ia1f8b52e39b7b6524bef89a95365541235b5b1b9
Signed-off-by: Nicholas Chin <nic.c3.14@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/83382
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Elyes Haouas <ehaouas@noos.fr>
Remove m4 as it will be installed automatically by flex and bison.
Change-Id: Ifb748e5aaabb96825813ddb92cf28d2ea7bdcbf9
Signed-off-by: Elyes Haouas <ehaouas@noos.fr>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/83156
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Martin L Roth <gaumless@gmail.com>
One URL in this document did not show up as a link. Fix it.
Change-Id: I22bf2014e71e6a127a7981cc90a028e48c25da49
Signed-off-by: Angel Pons <th3fanbus@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/82160
Reviewed-by: Arthur Heymans <arthur@aheymans.xyz>
Reviewed-by: Felix Singer <service+coreboot-gerrit@felixsinger.de>
Reviewed-by: Nico Huber <nico.h@gmx.de>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
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>
* 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>
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>
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>
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>
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>
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>
