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>
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>
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>
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>
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>
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>
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>
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>
