mainboard: Add ASRock H81M-HDS

Tested with GRUB 2.02 as a payload, booting Debian GNU/Linux 9.5 with
kernel 4.9.

This board works quite well under coreboot. A list of what works and
what doesn't can be found in the documentation part of this commit.

The file `data.vbt` matches the VBT in the latest stable version of the
vendor firmware (version 2.20).

Change-Id: I53483bb9fa335e86e85dfc487fef03fce4b85e2a
Signed-off-by: Tristan Corrick <tristan@corrick.kiwi>
Reviewed-on: https://review.coreboot.org/29390
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Patrick Rudolph <siro@das-labor.org>

1 files changed, 146 insertions, 0 deletions

diff --git a/Documentation/mainboard/asrock/h81m-hds.md b/Documentation/mainboard/asrock/h81m-hds.md
new file mode 100644
index 0000000000..0338aa10bb
--- /dev/null
+++ b/Documentation/mainboard/asrock/h81m-hds.md
@@ -0,0 +1,146 @@
+# ASRock H81M-HDS
+
+This page describes how to run coreboot on the [ASRock H81M-HDS].
+
+## Required proprietary blobs
+
+This board currently requires a proprietary blob in order to initialise
+the RAM and a few other components. The blob largely consists of Intel's
+Memory Reference Code (shortened to mrc), and is just under 200 KiB
+in size. It is also known as a system agent binary. Unfortunately,
+it is not currently possible to distribute this as part of coreboot.
+However, the mrc can be obtained from a Haswell Chromebook firmware
+image, and you might find one online. The mrc from a ChromeOS image can
+be extracted with the following command. If extracting from a "standard"
+coreboot image, omit `-r RO_SECTION`.
+
+```bash
+cbfstool coreboot.rom extract -f mrc.bin -n mrc.bin -r RO_SECTION
+```
+
+Now, place mrc.bin in the root of the coreboot directory.
+Alternatively, place it anywhere you want, and set `MRC_FILE` to its
+location when building coreboot.
+
+## 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.
+
+```bash
+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:
+
+```bash
+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][W25Q32FV].
+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
+
+- PCIe graphics is non-functional. The PCIe 16x slot doesn't work
+  with other devices, either.
+
+- 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 `coretemp` driver can still be used for accurate CPU
+  temperature readings from an OS.
+
+## 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 (but not the 16x slot, see [Known issues](#known-issues))
+- SATA
+- PS/2 mouse
+- serial port
+- hardware monitor (see [Known issues](#known-issues))
+- onboard audio
+- front panel audio
+- initialisation with Haswell mrc version 1.6.1 build 2
+- graphics init with libgfxinit (see [Known issues](#known-issues))
+- flashrom under the vendor firmware
+- flashrom under coreboot
+- Wake-on-LAN
+- Using `me_cleaner`
+
+## Technology
+
+```eval_rst
++------------------+--------------------------------------------------+
+| Northbridge      | Intel Haswell                                    |
++------------------+--------------------------------------------------+
+| Southbridge      | Intel Lynx Point (H81)                           |
++------------------+--------------------------------------------------+
+| CPU              | Intel Haswell (LGA1150)                          |
++------------------+--------------------------------------------------+
+| Super I/O        | Nuvoton NCT6776                                  |
++------------------+--------------------------------------------------+
+| EC               | None                                             |
++------------------+--------------------------------------------------+
+| Coprocessor      | Intel Management Engine                          |
++------------------+--------------------------------------------------+
+```
+
+[ASRock H81M-HDS]: https://www.asrock.com/mb/Intel/H81M-HDS/
+[W25Q32FV]: https://www.winbond.com/resource-files/w25q32fv%20revi%2010202015.pdf
+[flashrom]: https://flashrom.org/Flashrom
+[Board manual]: http://asrock.pc.cdn.bitgravity.com/Manual/H81M-HDS.pdf