dasharo/coreboot
0
0
Fork 0
mirror of https://github.com/Dasharo/coreboot.git synced 2026-03-06 14:43:26 -08:00
Code Issues Packages Projects Releases Wiki Activity

Docs: Replace Recommonmark with MyST Parser

Browse Source 
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>
This commit is contained in:
Nicholas Chin
2023-02-21 19:41:06 -07:00
committed by Martin L Roth
parent 9203e25a35
commit 35599f9a66
178 changed files with 1261 additions and 1021 deletions
Download Patch File Download Diff File Expand all files Collapse all files

235
Documentation/Makefile.sphinx
View File

@@ -1,60 +1,20 @@
## SPDX-License-Identifier: GPL-2.0-only
# Makefile for Sphinx documentation
# Minimal makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS ?=
SPHINXBUILD = sphinx-build
SPHINXAUTOBUILD = sphinx-autobuild
PAPER =
BUILDDIR = _build
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SPHINXAUTOBUILD = sphinx-autobuild
SOURCEDIR = .
BUILDDIR = _build
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help
# Put it first so that "make" without argument is like "make help".
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " applehelp to make an Apple Help Book"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " epub3 to make an epub3"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
@echo " coverage to run coverage check of the documentation (if enabled)"
@echo " dummy to check syntax errors of document sources"
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
.PHONY: clean
clean:
rm -rf $(BUILDDIR)
.PHONY: html
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
.PHONY: help Makefile.sphinx
.PHONY: livehtml
livehtml:
@@ -63,172 +23,7 @@ livehtml:
@echo
$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
.PHONY: dirhtml
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
.PHONY: singlehtml
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
.PHONY: pickle
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
.PHONY: json
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
.PHONY: htmlhelp
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
.PHONY: qthelp
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/coreboot.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/coreboot.qhc"
.PHONY: applehelp
applehelp:
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
@echo
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
@echo "N.B. You won't be able to view it unless you put it in" \
"~/Library/Documentation/Help or install it in your application" \
"bundle."
.PHONY: devhelp
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/coreboot"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/coreboot"
@echo "# devhelp"
.PHONY: epub
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
.PHONY: epub3
epub3:
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
@echo
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
.PHONY: latex
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
.PHONY: latexpdf
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: latexpdfja
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
.PHONY: text
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
.PHONY: man
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
.PHONY: texinfo
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
.PHONY: info
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
.PHONY: gettext
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
.PHONY: changes
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
.PHONY: linkcheck
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
.PHONY: doctest
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
.PHONY: coverage
coverage:
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
@echo "Testing of coverage in the sources finished, look at the " \
"results in $(BUILDDIR)/coverage/python.txt."
.PHONY: xml
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
.PHONY: pseudoxml
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
.PHONY: dummy
dummy:
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
@echo
@echo "Build finished. Dummy builder generates no files."
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile.sphinx
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

28
Documentation/acpi/index.md
View File

@@ -5,18 +5,34 @@ backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
upwards.
- [SSDT UID generation](uid.md)
```{toctree}
:maxdepth: 1
SSDT UID generation <uid.md>
```
## GPIO
- [GPIO toggling in ACPI AML](gpio.md)
```{toctree}
:maxdepth: 1
GPIO toggling in ACPI AML <gpio.md>
```
## Windows-specific ACPI documentation
- [Windows-specific documentation](windows.md)
```{toctree}
:maxdepth: 1
Windows-specific documentation <windows.md>
```
## ACPI specification - Useful links
- [ACPI Specification 6.5](https://uefi.org/specs/ACPI/6.5/index.html)
- [ASL 2.0 Syntax](https://uefi.org/specs/ACPI/6.5/19_ASL_Reference.html#asl-2-0-symbolic-operators-and-expressions)
- [Predefined ACPI Names](https://uefi.org/specs/ACPI/6.5/05_ACPI_Software_Programming_Model.html#predefined-acpi-names)
```{toctree}
:maxdepth: 1
ACPI Specification 6.5 <https://uefi.org/specs/ACPI/6.5/index.html>
ASL 2.0 Syntax <https://uefi.org/specs/ACPI/6.5/19_ASL_Reference.html#asl-2-0-symbolic-operators-and-expressions>
Predefined ACPI Names <https://uefi.org/specs/ACPI/6.5/05_ACPI_Software_Programming_Model.html#predefined-acpi-names>
```

6
Documentation/acronyms.md
View File

@@ -1141,4 +1141,8 @@ Spec](https://uefi.org/specifications) for details, or run the tool
## References:
* [AMD Glossary of terms](https://www.amd.com/system/files/documents/glossary-of-terms-20220505-for-web.pdf)
```{toctree}
:maxdepth: 1
AMD Glossary of terms <https://www.amd.com/system/files/documents/glossary-of-terms-20220505-for-web.pdf>
```

12
Documentation/arch/index.md
View File

@@ -5,7 +5,15 @@ architectures.
## RISC-V
- [RISC-V documentation](riscv/index.md)
```{toctree}
:maxdepth: 1
RISC-V documentation <riscv/index.md>
```
## x86
- [x86 documentation](x86/index.md)
```{toctree}
:maxdepth: 1
x86 documentation <x86/index.md>
```

14
Documentation/arch/x86/index.md
View File

@@ -2,7 +2,11 @@
This section contains documentation about coreboot on x86 architecture.
* [x86 PAE support](pae.md)
```{toctree}
:maxdepth: 1
x86 PAE support <pae.md>
```
## State of x86_64 support
At the moment there's only experimental x86_64 support.
@@ -43,8 +47,12 @@ Basic support for x86_64 has been implemented for QEMU mainboard target.
## Reference implementation
The reference implementation is
* [QEMU i440fx](../../mainboard/emulation/qemu-i440fx.md)
* [QEMU Q35](../../mainboard/emulation/qemu-q35.md)
```{toctree}
:maxdepth: 1
QEMU i440fx <../../mainboard/emulation/qemu-i440fx.md>
QEMU Q35 <../../mainboard/emulation/qemu-q35.md>
```
## TODO
* Identity map memory above 4GiB in ramstage

12
Documentation/community/index.md
View File

@@ -1,6 +1,10 @@
# Community
* [Code of Conduct](code_of_conduct.md)
* [Language style](language_style.md)
* [Community forums](forums.md)
* [coreboot at conferences](conferences.md)
```{toctree}
:maxdepth: 1
Code of Conduct <code_of_conduct.md>
Language style <language_style.md>
Community forums <forums.md>
coreboot at conferences <conferences.md>
```

119
Documentation/conf.py
View File

@@ -1,46 +1,34 @@
# -*- coding: utf-8 -*-
import subprocess
from recommonmark.parser import CommonMarkParser
import sphinx
# Get Sphinx version
major = 0
minor = 0
patchlevel = 0
version = sphinx.__version__.split(".")
if len(version) > 1:
major = int(version[0])
minor = int(version[1])
if len(version) > 2:
patchlevel = int(version[2])
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix(es) of source filenames.
source_suffix = ['.md']
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'coreboot'
copyright = u'CC-by 4.0 the coreboot project'
author = u'the coreboot project'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
# Configuration file for the Sphinx documentation builder.
#
# The full version, including alpha/beta/rc tags.
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
import subprocess
project = 'coreboot'
copyright = 'CC-by 4.0 the coreboot project'
author = 'the coreboot project'
release = subprocess.check_output(('git', 'describe')).decode("utf-8")
# The short X.Y version.
version = release.split("-")[0]
extensions = []
# Load recommonmark, supported since 1.8+
if major >= 2 or (major == 1 and minor >= 8):
extensions += ['recommonmark']
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = ["myst_parser"]
myst_heading_anchors = 5
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# Try to load DITAA
try:
@@ -57,62 +45,11 @@ else:
# Usually you set "language" from the command line for these cases.
language = 'en'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This patterns also effect to html_static_path and html_extra_path
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'sphinx_rtd_theme'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
html_css_files = [
'theme_overrides.css', # override wide tables in RTD theme
]
# Output file base name for HTML help builder.
htmlhelp_basename = 'corebootdoc'
enable_auto_toc_tree = True
class MyCommonMarkParser(CommonMarkParser):
# remove this hack once upstream RecommonMark supports inline code
def visit_code(self, mdnode):
from docutils import nodes
n = nodes.literal(mdnode.literal, mdnode.literal)
self.current_node.append(n)
def setup(app):
from recommonmark.transform import AutoStructify
# Load recommonmark on old Sphinx
if major == 1 and minor < 8:
app.add_source_parser('.md', MyCommonMarkParser)
app.add_config_value('recommonmark_config', {
'enable_auto_toc_tree': True,
'enable_auto_doc_ref': False, # broken in Sphinx 1.6+
'enable_eval_rst': True,
'url_resolver': lambda url: '/' + url
}, True)
app.add_transform(AutoStructify)

14
Documentation/contributing/index.md
View File

@@ -1,7 +1,11 @@
# Contributing
* [Coding Style](coding_style.md)
* [Gerrit Guidelines](gerrit_guidelines.md)
* [Project Ideas](project_ideas.md)
* [Documentation Ideas](documentation_ideas.md)
* [Google Summer of Code](gsoc.md)
```{toctree}
:maxdepth: 1
Coding Style <coding_style.md>
Gerrit Guidelines <gerrit_guidelines.md>
Project Ideas <project_ideas.md>
Documentation Ideas <documentation_ideas.md>
Google Summer of Code <gsoc.md>
```

18
Documentation/drivers/index.md
View File

@@ -8,10 +8,14 @@ For details on how to connect device drivers to a mainboard, see [Driver Devicet
Some of the drivers currently available include:
* [Intel DPTF](dptf.md)
* [IPMI KCS](ipmi_kcs.md)
* [SMMSTORE](smmstore.md)
* [SMMSTOREv2](smmstorev2.md)
* [SoundWire](soundwire.md)
* [USB4 Retimer](retimer.md)
* [CBFS SMBIOS hooks](cbfs_smbios.md)
```{toctree}
:maxdepth: 1
Intel DPTF <dptf.md>
IPMI KCS <ipmi_kcs.md>
SMMSTORE <smmstore.md>
SMMSTOREv2 <smmstorev2.md>
SoundWire <soundwire.md>
USB4 Retimer <retimer.md>
CBFS SMBIOS hooks <cbfs_smbios.md>
```

6
Documentation/drivers/smmstore.md
View File

@@ -128,7 +128,11 @@ data or modify the currently running kernel.*
## External links
* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
```{toctree}
:maxdepth: 1
A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI <https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf>
```
Note, this differs significantly from coreboot's implementation.
[SMM]: ../security/smm.md

6
Documentation/drivers/smmstorev2.md
View File

@@ -215,7 +215,11 @@ running kernel.
## External links
* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
```{toctree}
:maxdepth: 1
A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI <https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf>
```
Note that this differs significantly from coreboot's implementation.
[SMM]: ../security/smm.md

100
Documentation/external_docs.md
View File

@@ -17,13 +17,21 @@ Please add any helpful or informational links and sections as you see fit.
* [Part 1: PCI-based systems](https://resources.infosecinstitute.com/topic/system-address-map-initialization-in-x86x64-architecture-part-1-pci-based-systems/)
* [Part 2: PCI express-based systems](https://resources.infosecinstitute.com/topic/system-address-map-initialization-x86x64-architecture-part-2-pci-express-based-systems/)
* [PCIe elastic buffer](https://www.mindshare.com/files/resources/mindshare_pcie_elastic_buffer.pdf)
* [Boot Guard and PSB have user-hostile defaults](https://mjg59.dreamwidth.org/58424.html)
```{toctree}
:maxdepth: 1
Boot Guard and PSB have user-hostile defaults <https://mjg59.dreamwidth.org/58424.html>
```
## General Information
* [OS Dev](https://wiki.osdev.org/Categorized_Main_Page)
* [Interface BUS](http://www.interfacebus.com/)
```{toctree}
:maxdepth: 1
OS Dev <https://wiki.osdev.org/Categorized_Main_Page>
Interface BUS <http://www.interfacebus.com/>
```
## OpenSecurityTraining2
@@ -43,10 +51,14 @@ modified works back to the community.
Below is a list of currently available courses that can help understand the
inner workings of coreboot and other firmware-related topics:
* [coreboot design principles and boot process](https://ost2.fyi/Arch4031)
* [x86-64 Assembly](https://ost2.fyi/Arch1001)
* [x86-64 OS Internals](https://ost2.fyi/Arch2001)
* [x86-64 Intel Firmware Attack & Defense](https://ost2.fyi/Arch4001)
```{toctree}
:maxdepth: 1
coreboot design principles and boot process <https://ost2.fyi/Arch4031>
x86-64 Assembly <https://ost2.fyi/Arch1001>
x86-64 OS Internals <https://ost2.fyi/Arch2001>
x86-64 Intel Firmware Attack & Defense <https://ost2.fyi/Arch4001>
```
There are [additional security courses](https://p.ost2.fyi/courses) at the site
as well (such as
@@ -54,47 +66,79 @@ as well (such as
## Firmware Specifications & Information
* [System Management BIOS - SMBIOS](https://www.dmtf.org/standards/smbios)
* [Desktop and Mobile Architecture for System Hardware - DASH](https://www.dmtf.org/standards/dash)
* [PNP BIOS](https://www.intel.com/content/dam/support/us/en/documents/motherboards/desktop/sb/pnpbiosspecificationv10a.pdf)
```{toctree}
:maxdepth: 1
System Management BIOS - SMBIOS <https://www.dmtf.org/standards/smbios>
Desktop and Mobile Architecture for System Hardware - DASH <https://www.dmtf.org/standards/dash>
PNP BIOS <https://www.intel.com/content/dam/support/us/en/documents/motherboards/desktop/sb/pnpbiosspecificationv10a.pdf>
```
### ACPI
* [ACPI Specs](https://uefi.org/acpi/specs)
* [ACPI in Linux](https://www.kernel.org/doc/ols/2005/ols2005v1-pages-59-76.pdf)
* [ACPI 5 Linux](https://blog.linuxplumbersconf.org/2012/wp-content/uploads/2012/09/LPC2012-ACPI5.pdf)
* [ACPI 6 Linux](https://events.static.linuxfound.org/sites/events/files/slides/ACPI_6_and_Linux_0.pdf)
```{toctree}
:maxdepth: 1
ACPI Specs <https://uefi.org/acpi/specs>
ACPI in Linux <https://www.kernel.org/doc/ols/2005/ols2005v1-pages-59-76.pdf>
ACPI 5 Linux <https://blog.linuxplumbersconf.org/2012/wp-content/uploads/2012/09/LPC2012-ACPI5.pdf>
ACPI 6 Linux <https://events.static.linuxfound.org/sites/events/files/slides/ACPI_6_and_Linux_0.pdf>
```
### Security
* [Intel Boot Guard](https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/intel_boot_guard)
```{toctree}
:maxdepth: 1
Intel Boot Guard <https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/intel_boot_guard>
```
## Hardware information
* [WikiChip](https://en.wikichip.org/wiki/WikiChip)
* [Sandpile](https://www.sandpile.org/)
* [CPU-World](https://www.cpu-world.com/index.html)
* [CPU-Upgrade](https://www.cpu-upgrade.com/index.html)
```{toctree}
:maxdepth: 1
WikiChip <https://en.wikichip.org/wiki/WikiChip>
Sandpile <https://www.sandpile.org/>
CPU-World <https://www.cpu-world.com/index.html>
CPU-Upgrade <https://www.cpu-upgrade.com/index.html>
```
### Hardware Specifications & Standards
* [Bluetooth](https://www.bluetooth.com/specifications/specs/) - Bluetooth SIG
* [eMMC](https://www.jedec.org/) - JEDEC - (LOGIN REQUIRED)
```{toctree}
:maxdepth: 1
eMMC <https://www.jedec.org/) - JEDEC - (LOGIN REQUIRED>
```
* [eSPI](https://cdrdv2.intel.com/v1/dl/getContent/645987) - Intel
* [I2c Spec](https://web.archive.org/web/20170704151406/https://www.nxp.com/docs/en/user-guide/UM10204.pdf),
[Appnote](https://www.nxp.com/docs/en/application-note/AN10216.pdf) - NXP
* [I2S](https://www.nxp.com/docs/en/user-manual/UM11732.pdf) - NXP
* [I3C](https://www.mipi.org/specifications/i3c-sensor-specification) - MIPI Alliance (LOGIN REQUIRED)
* [Memory](https://www.jedec.org/) - JEDEC - (LOGIN REQUIRED)
```{toctree}
:maxdepth: 1
I3C <https://www.mipi.org/specifications/i3c-sensor-specification) - MIPI Alliance (LOGIN REQUIRED>
Memory <https://www.jedec.org/) - JEDEC - (LOGIN REQUIRED>
```
* [NVMe](https://nvmexpress.org/developers/) - NVMe Specifications
* [LPC](https://www.intel.com/content/dam/www/program/design/us/en/documents/low-pin-count-interface-specification.pdf) - Intel
* [PCI / PCIe / M.2](https://pcisig.com/specifications) - PCI-SIG - (LOGIN REQUIRED)
```{toctree}
:maxdepth: 1
PCI / PCIe / M.2 <https://pcisig.com/specifications) - PCI-SIG - (LOGIN REQUIRED>
```
* [Power Delivery](https://www.usb.org/documents) - USB Implementers Forum
* [SATA](https://sata-io.org/developers/purchase-specification) - SATA-IO (LOGIN REQUIRED)
```{toctree}
:maxdepth: 1
SATA <https://sata-io.org/developers/purchase-specification) - SATA-IO (LOGIN REQUIRED>
```
* [SMBus](http://www.smbus.org/specs/) - System Management Interface Forum
* [Smart Battery](http://smartbattery.org/specs/) - Smart Battery System Implementers Forum
* [USB](https://www.usb.org/documents) - USB Implementers Forum
@@ -133,5 +177,9 @@ as well (such as
## Infrastructure software
* [Kconfig](https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html)
* [GNU Make](https://www.gnu.org/software/make/manual/)
```{toctree}
:maxdepth: 1
Kconfig <https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html>
GNU Make <https://www.gnu.org/software/make/manual/>
```

2
Documentation/getting_started/build_system.md
View File

@@ -75,7 +75,7 @@ $(call add_intermediate, add_mrc_data)
Note that the second line must start with a tab, not spaces.
```eval_rst
```{eval-rst}
See also :doc:`../tutorial/managing_local_additions`.
```

2
Documentation/getting_started/gpio.md
View File

@@ -167,7 +167,7 @@ could cause catastrophic failures, up to and including your mainboard!
As per Intel Platform Controller Hub (PCH) EDS since Skylake, a GPIO PAD register
supports four different types of GPIO reset as:
```eval_rst
```{eval-rst}
+------------------------+----------------+-------------+-------------+
| | | PAD Reset ? |
+ PAD Reset Config + Platform Reset +-------------+-------------+

20
Documentation/getting_started/index.md
View File

@@ -1,10 +1,14 @@
# Getting Started
* [coreboot architecture](architecture.md)
* [Build System](build_system.md)
* [Submodules](submodules.md)
* [Kconfig](kconfig.md)
* [Writing Documentation](writing_documentation.md)
* [Setting up GPIOs](gpio.md)
* [Adding devices to a device tree](devicetree.md)
* [Frequently Asked Questions](faq.md)
```{toctree}
:maxdepth: 1
coreboot architecture <architecture.md>
Build System <build_system.md>
Submodules <submodules.md>
Kconfig <kconfig.md>
Writing Documentation <writing_documentation.md>
Setting up GPIOs <gpio.md>
Adding devices to a device tree <devicetree.md>
Frequently Asked Questions <faq.md>
```

8
Documentation/getting_started/kconfig.md
View File

@@ -11,8 +11,12 @@ configuration front end in coreboot today.
The official Kconfig source and documentation is kept at kernel.org:
- [Kconfig source](https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig)
- [Kconfig Language Documentation](https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt)
```{toctree}
:maxdepth: 1
Kconfig source <https://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/tree/scripts/kconfig>
Kconfig Language Documentation <https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt>
```
The advantage to using Kconfig is that it allows users to easily select the
high level features of the project to be enabled or disabled at build time.

2
Documentation/gfx/display-panel.md
View File

@@ -22,7 +22,7 @@ the power sequence timing parameters, which are usually named T[N] and also
referenced in Intel's respective registers listing. You need the values for
`PP_ON_DELAYS`, `PP_OFF_DELAYS` and `PP_DIVISOR` for your `devicetree.cb`:
```eval_rst
```{eval-rst}
+-----------------------------+---------------------------------------+-----+
| Intel docs | devicetree.cb | eDP |
+-----------------------------+---------------------------------------+-----+

62
Documentation/index.md
View File

@@ -170,34 +170,38 @@ for example OpenBSD, is probably the closest cousin of our approach.
Contents:
* [Getting Started](getting_started/index.md)
* [Tutorial](tutorial/index.md)
* [Contributing](contributing/index.md)
* [Community](community/index.md)
* [Payloads](payloads.md)
* [Distributions](distributions.md)
* [Technotes](technotes/index.md)
* [ACPI](acpi/index.md)
* [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)
* [Display panel](gfx/display-panel.md)
* [CPU Architecture](arch/index.md)
* [Platform independent drivers](drivers/index.md)
* [Northbridge](northbridge/index.md)
* [System on Chip](soc/index.md)
* [Mainboard](mainboard/index.md)
* [Payloads](lib/payloads/index.md)
* [Libraries](lib/index.md)
* [Options](lib/option.md)
* [Security](security/index.md)
* [SuperIO](superio/index.md)
* [Vendorcode](vendorcode/index.md)
* [Utilities](util.md)
* [Software Bill of Materials](sbom/sbom.md)
* [Project infrastructure & services](infrastructure/index.md)
* [Boards supported in each release directory](releases/boards_supported_on_branches.md)
* [Release notes](releases/index.md)
* [Acronyms & Definitions](acronyms.md)
* [External Resources](external_docs.md)
* [Documentation License](documentation_license.md)
```{toctree}
:maxdepth: 1
Getting Started <getting_started/index.md>
Tutorial <tutorial/index.md>
Contributing <contributing/index.md>
Community <community/index.md>
Payloads <payloads.md>
Distributions <distributions.md>
Technotes <technotes/index.md>
ACPI <acpi/index.md>
Native Graphics Initialization with libgfxinit <gfx/libgfxinit.md>
Display panel <gfx/display-panel.md>
CPU Architecture <arch/index.md>
Platform independent drivers <drivers/index.md>
Northbridge <northbridge/index.md>
System on Chip <soc/index.md>
Mainboard <mainboard/index.md>
Payloads <lib/payloads/index.md>
Libraries <lib/index.md>
Options <lib/option.md>
Security <security/index.md>
SuperIO <superio/index.md>
Vendorcode <vendorcode/index.md>
Utilities <util.md>
Software Bill of Materials <sbom/sbom.md>
Project infrastructure & services <infrastructure/index.md>
Boards supported in each release directory <releases/boards_supported_on_branches.md>
Release notes <releases/index.md>
Acronyms & Definitions <acronyms.md>
External Resources <external_docs.md>
Documentation License <documentation_license.md>
```
[Documentation]: https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/main/Documentation/

12
Documentation/infrastructure/builders.md
View File

@@ -93,11 +93,19 @@ You can see all the builds in the main jenkins interface:
Most of the time on the builders is taken up by the coreboot main and
coreboot gerrit builds.
* [coreboot gerrit build](https://qa.coreboot.org/job/coreboot-gerrit/)
```{toctree}
:maxdepth: 1
coreboot gerrit build <https://qa.coreboot.org/job/coreboot-gerrit/>
```
([Time trend](https://qa.coreboot.org/job/coreboot-gerrit/buildTimeTrend))
* [coreboot main build](https://qa.coreboot.org/job/coreboot/)
```{toctree}
:maxdepth: 1
coreboot main build <https://qa.coreboot.org/job/coreboot/>
```
([Time trend](https://qa.coreboot.org/job/coreboot/buildTimeTrend))

16
Documentation/infrastructure/index.md
View File

@@ -4,9 +4,17 @@ This section contains documentation about our infrastructure
## Services
* [Project services](services.md)
* [Administrator's handbook](admin.md)
```{toctree}
:maxdepth: 1
Project services <services.md>
Administrator's handbook <admin.md>
```
## Jenkins builders and builds
* [Setting up Jenkins build machines](builders.md)
* [Coverity Scan integration](coverity.md)
```{toctree}
:maxdepth: 1
Setting up Jenkins build machines <builders.md>
Coverity Scan integration <coverity.md>
```

Some files were not shown because too many files have changed in this diff Show More