Files

Nicholas Chin 35599f9a66 Docs: Replace Recommonmark with MyST Parser

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>

2024-03-21 16:11:56 +00:00

6.1 KiB

Raw Blame History

Beaglebone Black

This page gives some details about the BeagleBone Black coreboot port and describes how to build and run it.

The port currently only supports booting coreboot from a micro SD card and has some other limitations listed below.

Supported Boards

The Beaglebone port supports the following boards:

Beaglebone Black
Beaglebone Black Wireless
Beaglebone Pocket (untested, may need tweaking)
Beaglebone Blue (untested, may need tweaking)
Beaglebone Original (untested, may need tweaking)

Use Cases

This port was primarily developed as a learning exercise and there is potentially little reason to use it compared to the defacto bootloader choice of U-Boot. However, it does have some interesting practical use cases compared to U-Boot:

Choosing coreboot as a lightweight alternative to U-Boot. In this case, coreboot is used to do the absolute minimum necessary to boot Linux, forgoing some U-Boot features and functionality. Complex boot logic can then instead be moved into Linux where it can be more flexibly and safely executed. This is essentially the LinuxBoot philosophy. U-Boot Falcon mode has similar goals to this as well.
Facilitating experimenting with coreboot on real hardware. The Beaglebone Black is widely available at a low pricepoint (~$65) making it a great way to experiment with coreboot on real ARMv7 hardware. It also works well as a development platform as it has exposed pads for JTAG and, due to the way it boots, is effectively impossible to brick.
The Beaglebone Black is often used as a external flasher and EHCI debug gadget in the coreboot community, so many members have access to it and can use it as a reference platform.

Quickstart

Run make menuconfig and select TI/Beaglebone in the Mainboard menu.
Add a payload as normal.
Run make.
Copy the resulting build/MLO file to the micro SD card at offset 128k - ie dd if=build/MLO of=/dev/sdcard seek=1 bs=128k.

NOTE: By default, the Beaglebone is configured to try to boot first from eMMC before booting from SD card. To ensure that the Beaglebone boots from SD, either erase the internal eMMC or hold the S2 button while powering on (note that this has to be while powering on - ie when plugging in the USB or DC barrel jack - the boot order doesn't change on reset) to prioritize SD in the boot order.

Serial Console

By default, coreboot uses UART0 as the serial console. UART0 is available through the J1 header on both the Beaglebone Black and Beaglebone Black Wireless. The serial runs at 3.3V and 115200 8n1.

The pin mapping is shown below for J1.

```{eval-rst}
+----------------------------+------------+
| Pin number                 | Function   |
+============================+============+
| 1 (Closest to barrel jack) | GND        |
+----------------------------+------------+
| 4                          | RX         |
+----------------------------+------------+
| 5                          | TX         |
+----------------------------+------------+
```

Boot Process

The AM335x contains ROM code to allow booting in a number of different configurations. More information about the boot ROM code can be found in the AM335x technical reference manual (SPRUH73Q) in the Initialization section.

This coreboot port is currently configured to boot in "SD Raw Mode" where the boot binary, with header ("Table of Contents" in TI's nomenclature), is placed at the offset of 0x20000 (128KB) on the SD card. The boot ROM loads the coreboot bootblock stage into SRAM and executes it.

The bootblock and subsequent romstage and ramstage coreboot stages expect that the coreboot image, containing the CBFS, is located at 0x20000 on the SD card. All stages directly read from the SD card in order to load the next stage in sequence.

Clock Initialization and PMIC

To simplify the port, the TPS65217C Power Management IC (PMIC) on the Beaglebone Black is not configured by coreboot. By default, the PMIC reset values for VDD_MPU (1.1V) and VDD_CORE (1.8V) are within the Operating Performance Point (OPP) for the MPU PLL configuration set by the boot ROM of 500 MHz.

When using Linux as a payload, the kernel will appropriately scale the core voltages for the desired MPU clock frequency as defined in the device tree.

One significant difference because of this to the U-Boot port is that the DCDC1 rail that powers the DDR3 RAM will be 1.5V by default. The Micron DDR3 supports both 1.35V and 1.5V and U-Boot makes use of this by setting it to 1.35V to conserve power. Fortunately, Linux is again able to configure this rail but it involves adding an entry to the device tree:

&dcdc1_reg {
regulator-name = "vdd_ddr3";
regulator-min-microvolt = <1350000>;
regulator-max-microvolt = <1350000>;
regulator-boot-on;
regulator-always-on;
};

If this port was to be extended to work with boards or SoCs with different requirements for the MPU clock frequency or different Operating Performance Points, then the port may need to be extended to set the core voltages and MPU PLL within coreboot, prior to loading a payload. Extending coreboot so that it can configure the PMIC would also be necessary if there was a requirement for coreboot to run at a different MPU frequency than the 500 MHz set by the boot ROM.

Todo

Allow coreboot to run from the Beaglebone Black's internal eMMC. This would require updating the mmc.c driver to support running from both SD and eMMC.
Support the boot ROMs FAT mode so that the coreboot binary can be placed on a FAT partition.
Increase the MMC read speed, it currently takes ~15s to read ~20MB which is a bit slow. To do this, it should be possible to update the MMC driver to:
- Increase the supported blocksize (currently is always set to 1)
- Support 4-bit data width (currently only supports 1-bit data width)
Convert the while loops in the MMC driver to timeout so that coreboot does not hang on a bad SD card or when the SD card is removed during boot.

6.1 KiB Raw Blame History