sravan/system76-coreboot
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
e60989db3670d02a6d67bcaa76d00b00ef593f68
system76-coreboot/Documentation/mainboard/asus/p8z77-m_pro.md
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.0 KiB
Raw Blame History

ASUS P8Z77-M PRO

This page describes how to run coreboot on the ASUS P8Z77-M PRO

Flashing coreboot

+---------------------+----------------+
| Type                | Value          |
+=====================+================+
| Socketed flash      | yes            |
+---------------------+----------------+
| Model               | W25Q64FVA1Q    |
+---------------------+----------------+
| Size                | 8 MiB          |
+---------------------+----------------+
| Package             | DIP-8          |
+---------------------+----------------+
| Write protection    | yes            |
+---------------------+----------------+
| Dual BIOS feature   | no             |
+---------------------+----------------+
| Internal flashing   | yes            |
+---------------------+----------------+

The flash IC is located right next to one of the SATA ports:

Internal programming

The main SPI flash cannot be written because Asus disables BIOSWE and enables BLE/SMM_BWP flags in BIOS_CNTL for their latest bioses. An external programmer is required. You must flash standalone, flashing in-circuit doesn't work. The flash chip is socketed, so it's easy to remove and reflash.

Working

  • PS/2 keyboard with SeaBIOS & edk2 (in Mint 18.3/19.1)

  • Rear/front headphones connector audio & mic

  • S3 Suspend to RAM (tested with OS installed in a HDD/SSD and also with a Mint 18.3/19.1 LiveUSB pendrive connected to USB3/USB2), but please see [Known issues]

  • USB2 on rear (tested mouse/keyboard plugged there. Also, booting with a Mint 18./19.1 LiveUSB works ok)

  • USB3 (Z77's and Asmedia's works, but please see [Known issues])

  • Gigabit Ethernet (RTL8111F)

  • SATA3, SATA2 and eSATA (tested on all ports, hot-swap and TCG OPAL working) (Blue SATA2) (Blue SATA2) (White SATA3) (Red eSATA SATA3 rear) port 3 port 5 port 1 port 8 port 4 port 6 port 2 port 7

  • NVME SSD boot on PCIe-x16/x8/4x slot using edk2 (tested with M.2-to-PCIe adapter and a M.2 Samsung EVO 970 SSD)

  • CPU Temp sensors (tested PSensor on linux + HWINFO64 on Win10)

  • TPM on TPM-header (tested tpm-tools with Asus TPM 1.2 Infineon SLB9635TT12)

  • Native raminit and also MRC.bin(systemagent-r6.bin) memory initialization (please see [Native raminit compatibility] and [MRC memory compatibility])

  • Integrated graphics with both libgfxinit and the Intel Video BIOS OpROM (VGA/DVI-D/HDMI tested and working)

  • 1x PCIe GPU in PCIe-16x/8x/4x slots (tested using Zotac GeForce GTX 750Ti and FirePro W5100 under Mint 18.3/19.1)

Known issues

  • The rear's USB3s on bottom (closest to the PCB) have problems booting or being used before the OS loads. For better compatibility, please use the Z77's ones above the Ethernet connector or the Asmedia's top one

  • After S3 suspend, some USB3 connectors on rear seem not to work

  • At the moment, the power led does not blink when entering S3 state

  • Currently, we have not setup the SuperIO's Hardware Monitor (HWM), so only the CPU sensors are reported

  • If you use the MRC.bin, the NVRAM variable gfx_uma_size may be ignored as IGP's UMA could be reconfigured by the blob

  • Using edk2 + a PCIe GPU under Windows crashes with an ACPI_BIOS_ERROR fatal code, not sure why. Using just the IGP works perfectly

  • Under Windows 10, if you experiment problems with PS/2 devices, change HKLM\SYSTEM\CurrentControlSet\Services\i8042prt->Start from '3' to '1'

Untested

  • EHCI debugging
  • S/PDIF audio
  • Wake-on-LAN
  • Serial port

Not working

  • PS/2 keyboard in Win10 using edk2 (please see [Known issues])
  • PS/2 mouse using edk2
  • PCIe graphics card on Windows and edk2 (throws critical ACPI_BIOS_ERROR)

Native raminit compatibility

  • GSkill F3-2133C10D-16GAB(XMP,1.60v) 2x8GB kit works at 1333Mhz instead of XMP 2133Mhz

  • Team Xtreem TXD38G2133HC9NDC01(XMP,1.50v) 2x4GB kit works at 1600Mhz instead of XMP 2133Mhz

  • Kingston KVR1066D3N7K2/4G(JEDEC,1.50v) 2x4GB kit works at 1066Mhz but the board only detects half its RAM, because those DIMMs have Double Sided(DS) chips and seems only Single Sided(SS) ones are fully detected

  • GSkill F3-10666CL9T2-24GBRL(JEDEC,1.50v) 6x4GB kit (4 DIMMs used) works perfectly at full speed (1333Mhz)

MRC memory compatibility

  • GSkill F3-2133C10D-16GAB(XMP,1.60v) 2x8GB kit works at 1333Mhz instead of XMP 2133Mhz

  • Team Xtreem TXD38G2133HC9NDC01(XMP,1.50v) 2x4GB kit works at 1600Mhz instead of XMP 2133Mhz

  • Kingston KVR1066D3N7K2/4G(JEDEC,1.50v) 2x4GB kit works at 1066Mhz but the board only detects half its RAM, as those DIMMs have Double Sided(DS) chips and seems only Single Sided(SS) ones are fully detected

  • GSkill F3-10666CL9T2-24GBRL(JEDEC,1.50v) 6x4GB kit (4 DIMMs used) works perfectly at full speed (1333Mhz)

Technology

+------------------+--------------------------------------------------+
| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
+------------------+--------------------------------------------------+
| Southbridge      | bd82x6x                                          |
+------------------+--------------------------------------------------+
| CPU              | model_206ax                                      |
+------------------+--------------------------------------------------+
| Super I/O        | Nuvoton NCT6779D                                 |
+------------------+--------------------------------------------------+
| EC               | None                                             |
+------------------+--------------------------------------------------+
| Coprocessor      | Intel Management Engine                          |
+------------------+--------------------------------------------------+

Extra resources