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

8.9 KiB

Raw Blame History

OCP Delta Lake

This page describes coreboot support status for the OCP (Open Compute Project) Delta Lake server platform.

Introduction

OCP Delta Lake server platform is a component of multi-host server system Yosemite-V3. Both Delta Lake server design spec and Yosemite-V3 design spec were OCP accepted.

On the other hand, Wiwynn's Yosemite-V3 system and Delta Lake server product along with its OSF implementation, which is based on FSP/coreboot/LinuxBoot stack, was OCP accepted; For details, check:

The OCP blog
The Wiwynn Press Release
The Wiwynn's Yosemite-V3 product in OCP market place Wiwynn and 9Elements formed a partnership to offer the Wiwynn's Yosemite-V3 product and OSF for it.

Delta Lake server is a single socket Cooper Lake Scalable Processor (CPX-SP) server. Intel Cooper Lake Scalable Processor was launched in Q2 2020.

Yosemite-V3 has multiple configurations. Depending on configurations, it may host up to 4 Delta Lake servers (blades) in one sled.

The Yosemite-V3 system is in mass production. Meta, Intel and partners jointly develop Open System Firmware (OSF) solution on Delta Lake as an alternative solution. The OSF solution reached production quality for some use cases in July, 2021.

How to build

OSF code base is publicly available at https://github.com/opencomputeproject/OpenSystemFirmware

Run following commands to build Delta Lake OSF image from scratch: git clone https://github.com/opencomputeproject/OpenSystemFirmware.git cd OpenSystemFirmware/Wiwynn/deltalake && ./download_and_build.sh

The Delta Lake OSF code base leverages osf-builder to sync down coreboot, Linux kernel and u-root code from their upstream repo, and sync down needed binary blobs. osf-builder also provides the top level build system.

Besides coreboot, the Delta Lake OSF solution includes following components:

FSP blob: The blobs (Intel Cooper Lake Scalable Processor Firmware Support Package) is downloaded from https://github.com/intel/FSP/tree/master/CedarIslandFspBinPkg.
Microcode: downloaded from github.com/intel/Intel-Linux-Processor-Microcode-Data-Files.
ME ignition binary: downloaded from https://github.com/tianocore/edk2-non-osi/tree/master/Silicon/Intel/PurleySiliconBinPkg/MeFirmware
ACM binaries: only required for CBnT enablement. Available under NDA with Intel.
Payload: LinuxBoot is necessary when LinuxBoot is used as the coreboot payload. U-root as initramfs, is used in the joint development. It is built following All about u-root.

The Delta Lake OSF solution is updated periodically to newer versions of upstream coreboot code base and other components.

How to verify Delta Lake OSF image

To do in-band FW image update, use flashrom: flashrom -p internal:ich_spi_mode=hwseq -c "Opaque flash chip" --ifd
-i bios --noverify-all -w

From OpenBMC, to update FW image: fw-util slotx --update bios

To power off/on the host: power-util slotx off power-util slotx on

To connect to console through SOL (Serial Over Lan): sol-util slotx

How to work on coreboot for Delta Lake

After the OSF image for Delta Lake is built and verified, under OpenSystemFirmware/Wiwynn/deltalake directory: cd src/osf-builder/projects/craterlake/coreboot

Run "git remote -v" to confirm the origin is from coreboot upstream repo.

Run "git branch -v" to know the confirmed working coreboot commit ID for the Delta Lake OSF solution.

Fetch down the tip of coreboot upstream repo, run "make" to build a new OSF image for Delta Lake, verify that it works.

Now you are in a familiar coreboot environment, happy coding!

Firmware configurations

ChromeOS VPD is used to store most of the firmware configurations. RO_VPD region holds default values, while RW_VPD region holds customized values.

VPD variables supported are:

firmware_version: This variable holds overall firmware version. coreboot uses that value to populate smbios type 1 version field.
bmc_bootorder_override: When it's set to 1 IPMI OEM command can override boot order. The boot order override is done in the u-root LinuxBoot payload.
systemboot_log_level: u-root package systemboot log levels, would be mapped to quiet/verbose in systemboot as that is all we have for now. 5 to 8 would be mapped to verbose, 0 to 4 and 9 would be mapped to quiet.
VPDs affecting coreboot are listed/documented in src/mainboard/ocp/deltalake/vpd.h.

Features

The solution is developed using LinuxBoot payload with Linux kernel 5.2.9, and u-root as initramfs.

SMBIOS:
- Type 0 -- BIOS Information
- Type 1 -- System Information
- Type 2 -- Baseboard Information
- Type 3 -- System Enclosure or Chassis
- Type 4 -- Processor Information
- Type 7 -- Cache Information
- Type 8 -- Port Connector Information
- Type 9 -- PCI Slot Information
- Type 11 -- OEM String
- Type 16 -- Physical Memory Array
- Type 17 -- Memory Device
- Type 19 -- Memory Array Mapped Address
- Type 32 -- System Boot Information
- Type 38 -- IPMI Device Information
- Type 41 -- Onboard Devices Extended Information
- Type 127 -- End-of-Table
BMC integration:
- BMC readiness check
- IPMI commands
- watchdog timer
- POST complete pin acknowledgement
- Check BMC version: ipmidump -device
SEL record generation
Converged Bootguard and TXT (CBnT)
- TPM
- Bootguard profile 0T
- TXT
- SRTM
- DRTM (verified through tboot)
  - unsigned KM/BPM generation
  - KM/BPM signing
  - memory secret clearance upon ungraceful shutdown
Early serial output
port 80h direct to GPIO
ACPI tables: APIC/DMAR/DSDT/EINJ/FACP/FACS/HEST/HPET/MCFG/SPMI/SRAT/SLIT/SSDT
Skipping memory training upon subsequent reboots by using MRC cache
BMC crash dump
Error injection through ITP
Versions
- Check FSP version: cbmem | grep LB_TAG_PLATFORM_BLOB_VERSION
- Check Microcode version: cat /proc/cpuinfo | grep microcode
Devices:
- Boot drive
- All 5 data drives
- NIC card
Power button
localboot
netboot from IPv6
RAS (SMI handlers not upstreamed)
- EINJ/HEST
- error injection through ITP
- memory error handling
- PCIe error handling
- PCIe live error recovery (LER)

Stress/performance tests passed

OS warm reboot (1000 cycles)
DC reboot (1000 cycles)
AC reboot (1000 cycle)
Mprime test (6 hours)
StressAppTest (6 hours)
Ptugen (6 hours)

Performance on par with traditional firmware

coremark
FIO
Iperf(IPv6)
Linpack
Intel MLC (memory latency and bandwidth)
SpecCPU
stream

Other tests passed

Power
Thermal
coreboot address sanitizer (both romstage and ramstage)
Intel selftest tool (all errors analyzed; applicable errors clean)

Known issues

HECI access at OS run time:
- spsInfoLinux64 command fail to return ME version
- ptugen command fail to get memory power
CLTT (Closed Loop Thermal Throttling, eg. thermal protection for DIMMs)
ProcHot (thermal protection for processors)

Feature gaps

flashrom command not able to update ME region
ACPI BERT table
PCIe hotplug through VPP (Virtual Pin Ports)
RO_VPD region as well as other RO regions are not write protected
Not able to selectively enable/disable core

Technology

+------------------------+---------------------------------------------+
| Processor (1 socket)   | Intel Cooper Lake Scalable Processor        |
+------------------------+---------------------------------------------+
| BMC                    | Aspeed AST 2500                             |
+------------------------+---------------------------------------------+
| PCH                    | Intel Lewisburg C620 Series                 |
+------------------------+---------------------------------------------+

8.9 KiB Raw Blame History