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>
4.6 KiB
ASRock H81M-HDS
This page describes how to run coreboot on the ASRock H81M-HDS.
Required proprietary blobs
Please see :doc:`../../northbridge/intel/haswell/mrc.bin`.
Building coreboot
A fully working image should be possible just by setting your MAC
address and obtaining the Haswell mrc. You can set the basic config
with the following commands. However, it is strongly advised to use
make menuconfig afterwards (or instead), so that you can see all of
the settings.
make distclean # Note: this will remove your current config, if it exists.
touch .config
./util/scripts/config --enable VENDOR_ASROCK
./util/scripts/config --enable BOARD_ASROCK_H81M_HDS
./util/scripts/config --enable HAVE_MRC
./util/scripts/config --set-str REALTEK_8168_MACADDRESS "xx:xx:xx:xx:xx:xx" # Fill this in!
make olddefconfig
If you don't plan on using coreboot's serial console to collect logs,
you might want to disable it at this point (./util/scripts/config --disable CONSOLE_SERIAL). It should reduce the boot time by several
seconds. However, a more flexible method is to change the console log
level from within an OS using util/nvramtool, or with the nvramcui
payload.
Now, run make to build the coreboot image.
Flashing coreboot
Internal programming
The main SPI flash can be accessed using flashrom. By default, only the BIOS region of the flash is writable. If you wish to change any other region, such as the Management Engine or firmware descriptor, then an external programmer is required (unless you find a clever way around the flash protection).
The following command may be used to flash coreboot:
sudo flashrom -p internal --ifd -i bios --noverify-all -w coreboot.rom
The use of --noverify-all is required since the Management Engine
region is not readable even by the host.
External programming
The flash chip is a 4 MiB socketed DIP-8 chip. Specifically, it's a Winbond W25Q32FV, whose datasheet can be found here. The chip is located to the bottom right-hand side of the board. For a precise location, refer to section 1.4 (Motherboard Layout) of the board manual, where the chip is labelled "32Mb BIOS". Take note of the chip's orientation, remove it from its socket, and flash it with an external programmer. For reference, the notch in the chip should be facing towards the bottom of the board.
Known issues
-
The VGA port doesn't work until the OS reinitialises the display.
-
There is no automatic, OS-independent fan control. This is because the Super I/O hardware monitor can only obtain valid CPU temperature readings from the PECI agent, but the required driver doesn't exist in coreboot. The
coretempdriver can still be used for accurate CPU temperature readings from an OS.
Please also see :doc:`../../northbridge/intel/haswell/known-issues`.
Untested
- parallel port
- PS/2 keyboard
- EHCI debug
- TPM
- infrared module
- chassis intrusion header
- chassis speaker header
Working
- USB
- S3 suspend/resume
- Gigabit Ethernet
- integrated graphics
- PCIe
- SATA
- PS/2 mouse
- serial port
- hardware monitor (see Known issues)
- onboard audio
- front panel audio
- initialisation with Haswell mrc version 1.6.1 build 2
- graphics init with libgfxinit (see Known issues)
- flashrom under the vendor firmware
- flashrom under coreboot
- Wake-on-LAN
- Using
me_cleaner
Technology
+------------------+--------------------------------------------------+
| Northbridge | :doc:`../../northbridge/intel/haswell/index` |
+------------------+--------------------------------------------------+
| Southbridge | Intel Lynx Point (H81) |
+------------------+--------------------------------------------------+
| CPU | Intel Haswell (LGA1150) |
+------------------+--------------------------------------------------+
| Super I/O | Nuvoton NCT6776 |
+------------------+--------------------------------------------------+
| EC | None |
+------------------+--------------------------------------------------+
| Coprocessor | Intel Management Engine |
+------------------+--------------------------------------------------+