35599f9a66
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>
3.5 KiB
3.5 KiB
IFD Layout
A coreboot image for an Intel SoC contains two separate definitions of the layout of the flash. The Intel Flash Descriptor (IFD) which defines offsets and sizes of various regions of flash and the coreboot FMAP.
The FMAP should define all of the of the regions defined by the IFD to ensure that those regions are accounted for by coreboot and will not be accidentally modified.
IFD mapping
The names of the IFD regions in the FMAP should follow the convention of
starting with the prefix SI_ which stands for silicon initialization as a
way to categorize anything required by the SoC but not provided by coreboot.
+------------+------------------+-----------+-------------------------------------------+
| IFD Region | IFD Region name | FMAP Name | Notes |
| index | | | |
+============+==================+===========+===========================================+
| 0 | Flash Descriptor | SI_DESC | Always the top 4 KiB of flash |
+------------+------------------+-----------+-------------------------------------------+
| 1 | BIOS | SI_BIOS | This is the region that contains coreboot |
+------------+------------------+-----------+-------------------------------------------+
| 2 | Intel ME | SI_ME | |
+------------+------------------+-----------+-------------------------------------------+
| 3 | Gigabit Ethernet | SI_GBE | |
+------------+------------------+-----------+-------------------------------------------+
| 4 | Platform Data | SI_PDR | |
+------------+------------------+-----------+-------------------------------------------+
| 8 | EC Firmware | SI_EC | Most ChromeOS devices do not use this |
| | | | region; EC firmware is stored in BIOS |
| | | | region of flash |
+------------+------------------+-----------+-------------------------------------------+
Validation
The ifdtool can be used to manipulate a firmware image with a IFD. This tool will not take into account the FMAP while modifying the image which can lead to unexpected and hard to debug issues with the firmware image. For example if the ME region is defined at 6 MiB in the IFD but the FMAP only allocates 4 MiB for the ME, then when the ME is added by the ifdtool 6 MiB will be written which could overwrite 2 MiB of the BIOS.
In order to validate that the FMAP and the IFD are compatible the ifdtool
provides --validate (-t) option. ifdtool -t will read both the IFD and the
FMAP in the image and for every non empty region in the IFD if that region is
defined in the FMAP but the offset or size is different then the tool will
return an error.
Example:
foo@bar:~$ ifdtool -t bad_image.bin
Region mismatch between bios and SI_BIOS
Descriptor region bios:
offset: 0x00400000
length: 0x01c00000
FMAP area SI_BIOS:
offset: 0x00800000
length: 0x01800000
Region mismatch between me and SI_ME
Descriptor region me:
offset: 0x00103000
length: 0x002f9000
FMAP area SI_ME:
offset: 0x00103000
length: 0x006f9000
Region mismatch between pd and SI_PDR
Descriptor region pd:
offset: 0x003fc000
length: 0x00004000
FMAP area SI_PDR:
offset: 0x007fc000
length: 0x00004000