| Age | Commit message (Collapse) | Author |
|---|
|
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 patch fixes the table issue in markdown file identified with commit
96481066 (Documentation: gpio: Update table as per coreboot guidelines).
BUG=b:211573253, b:211950520
Signed-off-by: Subrata Banik <subratabanik@google.com>
Change-Id: Ifd8265b92b5ef0dcabb754371591477ca19c39be
Reviewed-on: https://review.coreboot.org/c/coreboot/+/63177
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Michael Niewöhner <foss@mniewoehner.de>
Reviewed-by: Eric Lai <eric_lai@quanta.corp-partner.google.com>
|
|
This patch fixes the table issue in markdown file introduced with commit
5338a16b (Documentation: gpio: Fix table).
BUG=b:211573253, b:211950520
Signed-off-by: Subrata Banik <subratabanik@google.com>
Change-Id: Ic4f27f46a9d219098612d8b7747ae26116506fce
Reviewed-on: https://review.coreboot.org/c/coreboot/+/63126
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Michael Niewöhner <foss@mniewoehner.de>
|
|
This patch fixes the indentation issue introduced with commit 0c1c2dec
(Documentation: Capture anomalies between pad and lock reset type).
BUG=b:211573253, b:211950520
Signed-off-by: Subrata Banik <subratabanik@google.com>
Change-Id: Ib6974cda26e6f7968688a2a7c30c7351d212a780
Reviewed-on: https://review.coreboot.org/c/coreboot/+/61107
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: EricR Lai <ericr_lai@compal.corp-partner.google.com>
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
|
|
This patch documents the recommendation as per Intel GPIO BWG on
GPIO PAD lock configuration.
As per GPIO BWG, it's recommended to change the Pad Reset Config
for lock GPP as `Power Good` so that pad configuration and lock
bit can be reset at the same time.
Refer to Intel doc:630603 for details.
Signed-off-by: Subrata Banik <subratabanik@google.com>
Change-Id: I3faf5dfc28c8c2dbc322db80a59f44a29002673c
Reviewed-on: https://review.coreboot.org/c/coreboot/+/61000
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: EricR Lai <ericr_lai@compal.corp-partner.google.com>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Reviewed-by: Michael Niewöhner <foss@mniewoehner.de>
|
|
Soft straps, that can be configured by the vendor in the Intel Flash
Image Tool (FIT), can influence some pads' default state. It is possible
to select either a native function or GPIO mode for some pads on
non-server SoCs, while on server SoCs most pads can be controlled.
Thus, add a recommendation to always configure all pads for a board to
guarantee integrity between different board or vendor firmware revisions
where the soft straps might have been changed.
Change-Id: I33063a3f6a1c9cd5267d85f7da84deb554489a26
Signed-off-by: Michael Niewöhner <foss@mniewoehner.de>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/52297
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
|
|
Intel PDGs starting from Skylake / Sunrise Point state that, different
from the general recommendation in digital electronics, unconnected
GPIOs defaulting to GPIO mode do explicitly not require termination.
The reason for this is, that these GPIOs have the `GPIORXDIS` bit set,
which effectively disconnects the pad from the internal logic by
disabling the input buffer.
This bit - besides `GPIOTXDIS` - can also be set explicitly by using
the gpio macro `PAD_NC(pad, NONE)`.
In some cases, a pull resistor may be required due to bad board design
or when a vendor sets the RX/TX disable bits together with a pull
resistor and schematics are not available to check if the pad is really
unconnected or just unused. In this case the pull resistor should be
kept.
Pads defaulting to native functions usually don't need special handling.
However, when pads requiring external pull-ups are missing these due to
bad board design, they should be configured with `PAD_NC` to disconnect
them internally.
Rewrite the documentation to reflect these new findings.
Also clarify the comment in soc/intel gpio code accordingly.
Change-Id: Id01b197ebe8f2b8bb4ecf3d119ec2298b26d9be0
Signed-off-by: Michael Niewöhner <foss@mniewoehner.de>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/52139
Reviewed-by: Tim Crawford <tcrawford@system76.com>
Reviewed-by: Felix Singer <felixsinger@posteo.net>
Reviewed-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
Drop LPC pad configuration code since all boards now do pad
configuration on their own. The comment about LPC_CLKRUNB when using
eSPI is moved to `Documentation/getting_started/gpio.md`.
Change-Id: I710d6aee8c3b2c8282cd321cd0688b9b26abea07
Signed-off-by: Michael Niewöhner <foss@mniewoehner.de>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/49410
Reviewed-by: Angel Pons <th3fanbus@gmail.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
This macro is not correct because the RX Level/Edge Configuration
(trig) and the GPIO Tx/Rx Buffer Disable (bufdis) fields in DW0
register do not affect on the pad in the native function mode.
This is part of the patch set
"src/mb/*, src/soc/intel/common/gpio: Remove PAD_CFG_NF_BUF_TRIG ":
CB:43455 - cedarisland: undo set trig and bufdis for NF pads
CB:43454 - tiogapass: undo set trig and bufdis for NF pads
CB:43561 - h110m: undo set trig and bufdis for NF pads
CB:43569 - soc/intel/common/gpio_defs: Remove PAD_CFG_NF_BUF_TRIG
Change-Id: Ic0416e3f67016c648f0886df73f585e8a08d4e92
Signed-off-by: Maxim Polyakov <max.senia.poliak@gmail.com>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/43569
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Lance Zhao
Reviewed-by: Michael Niewöhner
|
|
Change-Id: I2c61770d60a4f290fd8d516850f16bc3808ad48d
Signed-off-by: Ivan Labáth <iger@labo.rs>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/39082
Reviewed-by: Paul Menzel <paulepanter@users.sourceforge.net>
Reviewed-by: Patrick Georgi <pgeorgi@google.com>
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
|
|
The new documentation describes typical ways that mainboards will
set up their GPIOs, as well as the distinction between "early"
and "normal" GPIOs. It also describes the typical properties
that GPIO configuration will cover.
Change-Id: I279eec4ed2bb0248a2bdb363fb73b40b8272267f
Signed-off-by: Tim Wawrzynczak <twawrzynczak@chromium.org>
Reviewed-on: https://review.coreboot.org/c/coreboot/+/37802
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Justin TerAvest <teravest@chromium.org>
|
