Update blobs

This fixes the following:
- Fix smmstore_read_region to actually read stuff
- Make the API ARCH independent (no dependency on size_t)
- clean up the code a little
- Change the loglevel for non error messages to BIOS_DEBUG

Change-Id: I629be25d2a9b65796ae8f7a700b6bdab57b91b22
Signed-off-by: Arthur Heymans <arthur@aheymans.xyz>

.clang-format

@@ -7,7 +7,7 @@ AllowShortIfStatementsOnASingleLine:		false
 IndentCaseLabels:				false
 SortIncludes:					false
 ContinuationIndentWidth:			8
-ColumnLimit:					96
+ColumnLimit:					0
 AlwaysBreakBeforeMultilineStrings:		true
 AllowShortLoopsOnASingleLine:			false
 AllowShortFunctionsOnASingleLine:		false

.editorconfig

@@ -1,11 +0,0 @@
-# EditorConfig: https://EditorConfig.org
-
-root = true
-
-[*]
-indent_style = tab
-tab_width = 8
-charset = utf-8
-insert_final_newline = true
-end_of_line = lf
-trim_trailing_whitespace = true

.gitignore

@@ -54,13 +54,10 @@ util/crossgcc/xgcc
 site-local
 
 *.\#
-*.a
 *.bin
 *.debug
-!Kconfig.debug
 *.elf
 *.o
-*.o.d
 *.out
 *.pyc
 *.sw[po]
@@ -87,6 +84,7 @@ util/*/.dependencies
 util/*/.test
 util/amdfwtool/amdfwtool
 util/archive/archive
+util/bimgtool/bimgtool
 util/bincfg/bincfg
 util/board_status/board-status
 util/bucts/bucts
@@ -116,10 +114,11 @@ util/msrtool/msrtool
 util/nvramtool/.dependencies
 util/nvramtool/nvramtool
 util/optionlist/Options.wiki
-util/pmh7tool/pmh7tool
+util/romcc/build
 util/runfw/googlesnow
 util/superiotool/superiotool
 util/vgabios/testbios
+util/viatool/viatool
 util/autoport/autoport
 util/kbc1126/kbc1126_ec_dump
 util/kbc1126/kbc1126_ec_insert

.gitmodules

@@ -1,44 +1,28 @@
 [submodule "3rdparty/blobs"]
 	path = 3rdparty/blobs
-	url = ../blobs.git
+	url = https://github.com/coreboot/blobs.git
 	update = none
 	ignore = dirty
 [submodule "util/nvidia-cbootimage"]
 	path = util/nvidia/cbootimage
-	url = ../nvidia-cbootimage.git
+	url = https://github.com/coreboot/nvidia-cbootimage.git
 [submodule "vboot"]
 	path = 3rdparty/vboot
-	url = ../vboot.git
+	url = https://github.com/coreboot/vboot.git
 [submodule "arm-trusted-firmware"]
 	path = 3rdparty/arm-trusted-firmware
-	url = ../arm-trusted-firmware.git
+	url = https://github.com/coreboot/arm-trusted-firmware.git
 [submodule "3rdparty/chromeec"]
 	path = 3rdparty/chromeec
-	url = ../chrome-ec.git
+	url = https://github.com/coreboot/chrome-ec.git
 [submodule "libhwbase"]
 	path = 3rdparty/libhwbase
-	url = ../libhwbase.git
+	url = https://github.com/coreboot/libhwbase.git
 [submodule "libgfxinit"]
 	path = 3rdparty/libgfxinit
-	url = ../libgfxinit.git
+	url = https://github.com/coreboot/libgfxinit.git
 [submodule "3rdparty/fsp"]
 	path = 3rdparty/fsp
-	url = ../fsp.git
-	update = none
-	ignore = dirty
-[submodule "opensbi"]
-	path = 3rdparty/opensbi
-	url = ../opensbi.git
-[submodule "intel-microcode"]
-	path = 3rdparty/intel-microcode
-	url = ../intel-microcode.git
-	update = none
-	ignore = dirty
-[submodule "3rdparty/ffs"]
-	path = 3rdparty/ffs
-	url = ../ffs.git
-[submodule "3rdparty/amd_blobs"]
-	path = 3rdparty/amd_blobs
-	url = ../amd_blobs
+	url = https://github.com/coreboot/fsp.git
 	update = none
 	ignore = dirty

AUTHORS

@@ -1,246 +0,0 @@
-# This is the list of coreboot authors for copyright purposes.
-#
-# This does not necessarily list everyone who has contributed code, since in
-# some cases, their employer may be the copyright holder.  To see the full list
-# of contributors, and their email addresses, see the revision history in source
-# control.
-# Run the below commands in the coreboot repo for additional information.
-# To see a list of contributors: git log --pretty=format:%an | sort | uniq
-# For patches adding or removing a name: git log -i -S "NAME" --source --all
-
-3mdeb Embedded Systems Consulting
-9elements Agency GmbH
-Abhinav Hardikar
-Advanced Computing Lab, LANL
-Advanced Micro Devices, Inc.
-AdaCore
-AG Electronics Ltd.
-Alex Thiessen
-Alex Züpke
-Alexander Couzens
-Alexandru Gagniuc
-Analog Devices Inc.
-Analogix Semiconductor
-Andre Heider
-Andriy Gapon
-Andy Fleming
-Angel Pons
-Anton Kochkov
-ARM Limited and Contributors
-Arthur Heymans
-Asami Doi
-ASPEED Technology Inc.
-Atheros Corporation
-Atmel Corporation
-BAP - Bruhnspace Advanced Projects
-Bill Xie
-Bitland Tech Inc.
-Boris Barbulovski
-Carl-Daniel Hailfinger
-Cavium Inc.
-Christoph Grenz
-Code Aurora Forum
-coresystems GmbH
-Corey Osgood
-Curt Brune
-Custom Ideas
-Damien Zammit
-Dave Airlie
-David Brownell
-David Greenman
-David Hendricks
-David Mosberger-Tang
-David Mueller
-David S. Peterson
-Denis 'GNUtoo' Carikli
-Denis Dowling
-DENX Software Engineering
-Derek Waldner
-Digital Design Corporation
-DMP Electronics Inc.
-Donghwa Lee
-Drew Eckhardt
-Dynon Avionics
-Edward O'Callaghan
-Egbert Eich
-ELSOFT AG
-Eltan B.V
-Elyes Haouas
-Eric Biederman
-Eswar Nallusamy
-Evgeny Zinoviev
-Fabian Kunkel
-Fabrice Bellard
-Facebook, Inc.
-Felix Held
-Felix Singer
-Frederic Potter
-Free Software Foundation, Inc.
-Freescale Semiconductor, Inc.
-Gary Jennejohn
-George Trudeau
-Gerald Van Baren
-Gerd Hoffmann
-Gergely Kiss
-Google LLC
-Greg Watson
-Guennadi Liakhovetski
-Hal Martin
-HardenedLinux
-Hewlett-Packard Development Company, L.P.
-Hewlett Packard Enterprise Development LP
-Huaqin Telecom Inc.
-IBM Corporation
-Idwer Vollering
-Igor Pavlov
-Imagination Technologies
-Infineon Technologies
-InKi Dae
-Intel Corporation
-Iru Cai
-Isaku Yamahata
-Ivan Vatlin
-James Ye
-Jason Zhao
-Joe Pillow
-Johanna Schander
-Jonas 'Sortie' Termansen
-Jonathan A. Kollasch
-Jonathan Neuschäfer
-Jordan Crouse
-Joseph Smith
-Keith Hui
-Keith Packard
-Kevin Cody-Little
-Kevin O'Connor
-Kontron Europe GmbH
-Kshitij
-Kyösti Mälkki
-Leah Rowe
-Lei Wen
-Li-Ta Lo
-Libra Li
-Libretrend LDA
-Linaro Limited
-Linus Torvalds
-Linux Networx, Inc.
-LiPPERT ADLINK Technology GmbH
-Lubomir Rintel
-Luc Verhaegen
-Maciej Matuszczyk
-Marc Bertens
-Marc Jones
-Marek Vasut
-Marius Gröger
-Martin Mares
-Martin Renters
-Martin Roth
-Marvell International Ltd.
-Marvell Semiconductor Inc.
-Matt DeVillier
-Maxim Polyakov
-MediaTek Inc.
-Michael Brunner
-Michael Schroeder
-Michael Niewöhner
-Mika Westerberg
-Mondrian Nuessle
-MontaVista Software, Inc.
-Myles Watson
-Network Appliance Inc.
-Nicholas Sielicki
-Nick Barker
-Nico Huber
-Nico Rikken
-Nicola Corna
-Nils Jacobs
-Nir Tzachar
-Nokia Corporation
-NVIDIA Corporation
-Olivier Langlois
-Ollie Lo
-Omar Pakker
-Online SAS
-Orion Technologies, LLC
-Patrick Georgi
-Patrick Rudolph
-Pattrick Hueper
-Paulo Alcantara
-Pavel Sayekat
-PC Engines GmbH
-Per Odlund
-Peter Korsgaard
-Peter Stuge
-Philipp Degler
-Philipp Deppenwiese
-Philipp Hug
-Protectli
-Purism SPC
-Qualcomm Technologies
-Raptor Engineering, LLC
-Red Hat, Inc
-Reinhard Meyer
-Renze Nicolai
-Richard Spiegel
-Richard Woodruff
-Rob Landley
-Robert Reeves
-Robinson P. Tryon
-Rockchip, Inc.
-Romain Lievin
-Roman Zippel
-Ronald G. Minnich
-Rudolf Marek
-Russell King
-Ruud Schramp
-Sage Electronic Engineering, LLC
-Sam Ravnborg
-Samsung Electronics
-Samuel Holland
-SciTech Software, Inc.
-Sebastian Grzywna
-secunet Security Networks AG
-Sencore Inc
-Sergej Ivanov
-Siemens AG
-SiFive, Inc
-Silicon Integrated System Corporation
-Silverback Ltd.
-Stefan Reinauer
-Stefan Tauner
-Steve Magnani
-Steve Shenton
-ST Microelectronics
-SUSE LINUX AG
-Sven Schnelle
-Syed Mohammed Khasim
-System76
-Texas Instruments
-The Android Open Source Project
-The ChromiumOS Authors
-The Linux Foundation
-The Regents of the University of California
-Thomas Winischhofer
-Timothy Pearson
-Tobias Diedrich
-Tristan Corrick
-Tungsten Graphics, Inc.
-Tyan Computer Corp.
-ucRobotics Inc.
-University of Heidelberg
-Uwe Hermann
-VIA Technologies, Inc
-Vikram Narayanan
-Vipin Kumar
-Vladimir Serbinenko
-Vlado Cibic
-Wang Qing Pei
-Ward Vandewege
-Wilbert Duijvenvoorde
-Win Enterprises
-Wiwynn Corp.
-Wolfgang Denk
-YADRO
-Yann Collet
-Yinghai Lu
-Zachary Yedidia

Documentation/Intel/SoC/soc.html

@@ -148,6 +148,7 @@ mv build/coreboot.rom.new build/coreboot.rom
   <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/memmap.c file
     <ol type="A">
       <li>Add the fsp/memmap.h include file</li>
+      <li>Add the mmap_region_granularity routine</li>
     </ol>
   </li>
   <li>Add the necessary .h files to define the necessary values and structures</li>
@@ -657,7 +658,7 @@ Use the following steps to debug the call to TempRamInit:
   The EDK2 data structure is defined in
   MdeModulePkg/Include/IndustryStandard/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStandard/Acpi61.h#l111">Acpi61.h</a>
   The coreboot data structure is defined in
-  src/arch/x86/include/arch/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/acpi/acpi.h;hb=HEAD#l237">acpi.h</a>
+  src/arch/x86/include/arch/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/acpi.h;hb=HEAD#l237">acpi.h</a>
 </p>
 
 <ol>

Documentation/Intel/index.html

@@ -29,6 +29,7 @@
   </li>
   <li><a target="_blank" href="SoC/soc.html">SoC</a> support</li>
   <li><a target="_blank" href="Board/board.html">Board</a> support</li>
+  <li><a target="_blank" href="vboot.html">Verified Boot (vboot)</a> support</li>
 </ul>
 
 

Documentation/Intel/vboot.html

@@ -0,0 +1,402 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>vboot - Verified Boot Support</title>
+  </head>
+  <body>
+
+<h1>vboot - Verified Boot Support</h1>
+
+<p>
+Google's verified boot support consists of:
+</p>
+<ul>
+  <li>A root of trust</li>
+  <li>Special firmware layout</li>
+  <li>Firmware verification</li>
+  <li>Firmware measurements</li>
+  <li>A firmware update mechanism</li>
+  <li>Specific build flags</li>
+  <li>Signing the coreboot image</li>
+</ul>
+
+Google's vboot verifies the firmware and places measurements
+within the TPM.
+
+<hr>
+<h2>Root of Trust</h2>
+<p>
+When using vboot, the root-of-trust is basically the read-only portion of the
+SPI flash.  The following items factor into the trust equation:
+</p>
+<ul>
+  <li>The GCC compiler must reliably translate the code into machine code
+      without inserting any additional code (virus, backdoor, etc.)
+  </li>
+  <li>The CPU must reliably execute the reset sequence and instructions as
+      documented by the CPU manufacturer.
+  </li>
+  <li>The SPI flash must provide only the code programmed into it to the CPU
+      without providing any alternative reset vector or code sequence.
+  </li>
+  <li>The SPI flash must honor the write-protect input and protect the
+      specified portion of the SPI flash from all erase and write accesses.
+  </li>
+</ul>
+
+<p>
+The firmware is typically protected using the write-protect pin on the SPI
+flash part and setting some of the write-protect bits in the status register
+during manufacturing.  The protected area is platform specific and for x86
+platforms is typically 1/4th of the SPI flash
+part size.  Because this portion of the SPI flash is hardware write protected,
+it is not possible to update this portion of the SPI flash in the field,
+without altering the system to eliminate the ground connection to the SPI flash
+write-protect pin.  Without hardware modifications, this portion of the SPI
+flash maintains the manufactured state during the system's lifetime.
+</p>
+
+<hr>
+<h2>Firmware Layout</h2>
+<p>
+Several sections are added to the firmware layout to support vboot:
+</p>
+<ul>
+  <li>Read-only section</li>
+  <li>Google Binary Blob (GBB) area</li>
+  <li>Read/write section A</li>
+  <li>Read/write section B</li>
+</ul>
+<p>
+The following sections describe the various portions of the flash layout.
+</p>
+
+<h3>Read-Only Section</h3>
+<p>
+The read-only section contains a coreboot file system (CBFS) that contains all
+of the boot firmware necessary to perform recovery for the system. This
+firmware is typically protected using the write-protect pin on the SPI flash
+part and setting some of the write-protect bits in the status register during
+manufacturing.  The protected area is typically 1/4th of the SPI flash part
+size and must cover the entire read-only section which consists of:
+</p>
+<ul>
+  <li>Vital Product Data (VPD) area</li>
+  <li>Firmware ID area</li>
+  <li>Google Binary Blob (GBB) area</li>
+  <li>coreboot file system containing read-only recovery firmware</li>
+</ul>
+
+<h3>Google Binary Blob (GBB) Area</h3>
+<p>
+The GBB area is part of the read-only section.  This area contains a 4096 or
+8192 bit public root RSA key that is used to verify the VBLOCK area to obtain
+the firmware signing key.
+</p>
+
+<h3>Recovery Firmware</h3>
+<p>
+The recovery firmware is contained within a coreboot file system and consists
+of:
+</p>
+<ul>
+  <li>reset vector</li>
+  <li>bootblock</li>
+  <li>verstage</li>
+  <li>romstage</li>
+  <li>postcar</li>
+  <li>ramstage</li>
+  <li>payload</li>
+  <li>flash map file</li>
+  <li>config file</li>
+  <li>processor specific files:
+    <ul>
+      <li>Microcode</li>
+      <li>fspm.bin</li>
+      <li>fsps.bin</li>
+    </ul>
+  </li>
+</ul>
+
+<p>
+The recovery firmware is written during manufacturing and typically contains
+code to write the storage device (eMMC device or hard disk).  The recovery
+image is usually contained on a socketed device such as a USB flash drive or
+an SD card.  Depending upon the payload firmware doing the recovery, it may
+be possible for the user to interact with the system to specify the recovery
+image path.  Part of the recovery is also to write the A and B areas of the
+SPI flash device to boot the system.
+</p>
+
+
+<h3>Read/Write Section</h3>
+
+<p>
+The read/write sections contain an area which contains the firmware signing
+key and signature and an area containing a coreboot file system with a subset
+of the firmware.  The firmware files in FW_MAIN_A and FW_MAIN_B are:
+</p>
+<ul>
+  <li>romstage</li>
+  <li>postcar</li>
+  <li>ramstage</li>
+  <li>payload</li>
+  <li>config file</li>
+  <li>processor specific files:
+    <ul>
+      <li>Microcode</li>
+      <li>fspm.bin</li>
+      <li>fsps.bin</li>
+    </ul>
+  </li>
+</ul>
+
+<p>
+The firmware subset enables most issues to be fixed in the field with firmware
+updates.  The firmware files handle memory and most of silicon initialization.
+These files also produce the tables which get passed to the operating system.
+</p>
+
+<hr>
+<h2>Firmware Updates</h2>
+<p>
+The read/write sections exist in one of three states:
+</p>
+<ul>
+  <li>Invalid</li>
+  <li>Ready to boot</li>
+  <li>Successfully booted</li>
+</ul>
+
+<table border="1">
+<tr bgcolor="#ffc0c0">
+<td>
+Where is this state information written?
+<br/>CMOS?
+<br/>RW_NVRAM?
+<br/>RW_FWID_*
+</td>
+</tr>
+</table>
+
+<p>
+Firmware updates are handled by the operating system by writing any read/write
+section that is not in the "successfully booted" state.  Upon the next reboot,
+vboot determines the section to boot.  If it finds one in the "ready to boot"
+state then it attempts to boot using that section.  If the boot fails then
+vboot marks the section as invalid and attempts to fall back to a read/write
+section in the "successfully booted" state.  If vboot is not able to find a
+section in the "successfully booted" state then vboot enters recovery mode.
+</p>
+
+<p>
+Only the operating system is able to transition a section from the "ready to
+boot" state to the "successfully booted" state.  The transition is typically
+done after the operating system has been running for a while indicating
+that successful boot was possible and the operating system is stable.
+</p>
+
+<p>
+Note that as long as the SPI write protection is in place then the system is
+always recoverable.  If the flash update fails then the system will continue
+to boot using the previous read/write area.  The same is true if coreboot
+passes control to the payload or the operating system and then the boot fails.
+In the worst case, the SPI flash gets totally corrupted in which case vboot
+fails the signature checks and enters recovery mode.  There are no times where
+the SPI flash is exposed and the reset vector or part of the recovery firmware
+gets corrupted.
+</p>
+
+<hr>
+<h2>Build Flags</h2>
+<p>
+The following Kconfig values need to be selected to enable vboot:
+</p>
+<ul>
+  <li>COLLECT_TIMESTAMPS</li>
+  <li>VBOOT</li>
+</ul>
+
+<p>
+The starting stage needs to be specified by selecting either
+VBOOT_STARTS_IN_BOOTBLOCK or VBOOT_STARTS_IN_ROMSTAGE.
+</p>
+
+<p>
+If vboot starts in bootblock then vboot may be built as a separate stage by
+selecting VBOOT_SEPARATE_VERSTAGE.  Additionally, if static RAM is too small
+to fit both verstage and romstage then selecting VBOOT_RETURN_FROM_VERSTAGE
+enables bootblock to reuse the RAM occupied by verstage for romstage.
+</p>
+
+<p>
+Non-volatile flash is needed for vboot operation.  This flash area may be in
+CMOS, the EC, or in a read/write area of the SPI flash device.  Select one of
+the following:
+</p>
+<ul>
+  <li>VBOOT_VBNV_CMOS</li>
+  <li>VBOOT_VBNV_EC</li>
+  <li>VBOOT_VBNV_FLASH</li>
+</ul>
+<p>
+More non-volatile storage features may be found in src/vboot/Kconfig.
+</p>
+
+<p>
+A TPM is also required for vboot operation.  TPMs are available in
+drivers/i2c/tpm and drivers/pc80/tpm.
+</p>
+
+<p>
+In addition to adding the coreboot files into the read-only region, enabling
+vboot causes the build script to add the read/write files into coreboot file
+systems in FW_MAIN_A and FW_MAIN_B.
+</p>
+
+<hr>
+<h2>Signing the coreboot Image</h2>
+<p>
+The following command script is an example of how to sign the coreboot image file.
+This script is used on the Intel Galileo board and creates the GBB area and
+inserts it into the coreboot image.  It also updates the VBLOCK areas with the
+firmware signing key and the signature for the FW_MAIN firmware.  More details
+are available in 3rdparty/vboot/README.
+</p>
+
+<pre><code>#!/bin/sh
+#
+#  The necessary tools were built and installed using the following commands:
+#
+#        pushd 3rdparty/vboot
+#        make
+#        sudo make install
+#        popd
+#
+#  The keys were made using the following command
+#
+#        3rdparty/vboot/scripts/keygeneration/create_new_keys.sh  \
+#                --4k --4k-root --output $PWD/keys
+#
+#
+#  The "magic" numbers below are derived from the GBB section in
+#  src/mainboard/intel/galileo/vboot.fmd.
+#
+#  GBB Header Size:     0x80
+#  GBB Offset:      0x611000, 4KiB block number: 1553 (0x611)
+#  GBB Length:       0x7f000, 4KiB blocks:        127  (0x7f)
+#  COREBOOT Offset: 0x690000, 4KiB block number: 1680 (0x690)
+#  COREBOOT Length: 0x170000, 4KiB blocks:        368 (0x170)
+#
+#  0x7f000 (GBB Length) = 0x80 + 0x100 + 0x1000 + 0x7ce80 + 0x1000
+#
+#  Create the GBB area blob
+#  Parameters: hwid_size,rootkey_size,bmpfv_size,recoverykey_size
+#
+gbb_utility -c 0x100,0x1000,0x7ce80,0x1000 gbb.blob
+
+#
+#  Copy from the start of the flash to the GBB region into the signed flash
+#  image.
+#
+#  1553 * 4096 = 0x611 * 0x1000 = 0x611000, size of area before GBB
+#
+dd  conv=fdatasync  ibs=4096  obs=4096  count=1553  \
+    if=build/coreboot.rom  of=build/coreboot.signed.rom
+
+#
+#  Append the empty GBB area to the coreboot.rom image.
+#
+#  1553 * 4096 = 0x611 * 0x1000 = 0x611000, offset to GBB
+#
+dd  conv=fdatasync  obs=4096  obs=4096  seek=1553  if=gbb.blob  \
+    of=build/coreboot.signed.rom
+
+#
+#  Append the rest of the read-only region into the signed flash image.
+#
+#  1680 * 4096 = 0x690 * 0x1000 = 0x690000, offset to COREBOOT area
+#   368 * 4096 = 0x170 * 0x1000 = 0x170000, length of COREBOOT area
+#
+dd  conv=fdatasync  ibs=4096  obs=4096  skip=1680  seek=1680  count=368  \
+    if=build/coreboot.rom  of=build/coreboot.signed.rom
+
+#
+#  Insert the HWID and public root and recovery RSA keys into the GBB area.
+#
+gbb_utility                          \
+   --set --hwid='Galileo'            \
+   -r $PWD/keys/recovery_key.vbpubk  \
+   -k $PWD/keys/root_key.vbpubk      \
+   build/coreboot.signed.rom
+
+#
+#  Sign the read/write firmware areas with the private signing key and update
+#  the VBLOCK_A and VBLOCK_B regions.
+#
+3rdparty/vboot/scripts/image_signing/sign_firmware.sh  \
+   build/coreboot.signed.rom                           \
+   $PWD/keys                                           \
+   build/coreboot.signed.rom
+</code></pre>
+
+<hr>
+<h2>Boot Flow</h2>
+<p>
+The reset vector exist in the read-only area and points to the bootblock entry
+point.  The only copy of the bootblock exists in the read-only area of the SPI
+flash.  Verstage may be part of the bootblock or a separate stage.  If separate
+then the bootblock loads verstage from the read-only area and transfers control
+to it.
+</p>
+
+<p>
+Upon first boot, verstage attempts to verify the read/write section A.  It gets
+the public root key from the GBB area and uses that to verify the VBLOCK area
+in read-write section A.  If the VBLOCK area is valid then it extracts the
+firmware signing key (1024-8192 bits) and uses that to verify the FW_MAIN_A
+area of read/write section A.  If the verification is successful then verstage
+instructs coreboot to use the coreboot file system in read/write section A for
+the contents of the remaining boot firmware (romstage, postcar, ramstage and
+the payload).
+</p>
+
+<p>
+If verification fails for the read/write area and the other read/write area is
+not valid vboot falls back to the read-only area to boot into system recovery.
+</p>
+
+<hr>
+<h2>Chromebook Special Features</h2>
+<p>
+Google's Chromebooks have some special features:
+</p>
+<ul>
+  <li>Developer mode</li>
+  <li>Write-protect screw</li>
+</ul>
+
+<h3>Developer Mode</h3>
+<p>
+Developer mode allows the user to use coreboot to boot another operating system.
+This may be a another (beta) version of Chrome OS, or another flavor of
+GNU/Linux.  Use of developer mode does not void the system warranty.  Upon
+entry into developer mode, all locally saved data on the system is lost.
+This prevents someone from entering developer mode to subvert the system
+security to access files on the local system or cloud.
+</p>
+
+<h3>Write Protect Screw</h3>
+<p>
+Chromebooks have a write-protect screw which provides the ground to the
+write-protect pin of the SPI flash.  Google specifically did this to allow
+the manufacturing line and advanced developers to re-write the entire SPI flash
+part.  Once the screw is removed, any firmware may be placed on the device.
+However, accessing this screw requires opening the case and voids the system
+warranty!
+</p>
+
+<hr>
+<p>Modified: 2 May 2017</p>
+  </body>
+</html>

Documentation/POSTCODES

@@ -16,12 +16,6 @@ This is an (incomplete) list of POST codes emitted by coreboot v4.
 0x66 Devices have been enumerated
 0x88 Devices have been configured
 0x89 Devices have been enabled
-0xe0 Boot media (e.g. SPI ROM) is corrupt
-0xe1 Resource stored within CBFS is corrupt
-0xe2 Vendor binary (e.g. FSP) generated a fatal error
-0xe3 RAM could not be initialized
-0xe4 Critical hardware component could not initialize
-0xe5 Video subsystem failed to initialize
 0xf8 Entry into elf boot
 0xf3 Jumping to payload
 

Documentation/RFC/config.tex

@@ -0,0 +1,290 @@
+		New config language for LinuxBIOS
+
+\begin{abstract}
+We describe the new configuration language for LinuxBIOS.
+\end{abstract}
+
+\section{Scope}
+This document defines the new configuration language for LinuxBIOS.
+
+\section{Goals}
+The goals of the new language are these:
+\begin{itemize}
+\item Simplified Makefiles so people can see what is set
+\item Move from the regular-expression-based language to something
+a bit more comprehensible and flexible
+\item make the specification easier for people to use and understand
+\item allow unique register-set-specifiers for each chip
+\item allow generic register-set-specifiers for each chip
+\item generate static initialization code, as needed, for the
+specifiers.
+\end{itemize}
+
+\section{Language}
+Here is the new language. It is very similar to the old one, differing
+in only a few respects. It borrows heavily from Greg Watson's suggestions.
+
+I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
+in '' are keywords; things in ``'' are strings in the actual text.
+\begin{verbatim}
+#exprs are composed of factor or factor + factor etc.
+expr ::= factor ( ``+'' factor | ``-'' factor | )*
+#factors are term or term * term or term / term or ...
+factor ::=  term ( ``*'' term | ``/'' term | ... )*
+#
+unary-op ::= ``!'' ID
+# term is a number, hexnumber, ID, unary-op, or a full-blown expression
+term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
+
+# Option command. Can be an expression or quote-string.
+# Options are used in the config tool itself (in expressions and 'if')
+# and are also passed to the C compiler when building linuxbios.
+# It is an error to have two option commands in a file.
+# It is an error to have an option command after the ID has been used
+#   in an expression (i.e. 'set after used' is an error)
+option ::= 'option' ID '=' (``value'' | term)
+
+# Default command. The ID is set to this value if no option command
+# is scanned.
+# Multiple defaults for an ID will produce warning, but not errors.
+# It is OK to scan a default command after use of an ID.
+# Options always over-ride defaults.
+default ::= 'default' ID '=' (``value'' | term)
+
+# the mainboard, southbridge, northbridge commands
+# cause sourcing of Config.lb files as in the old config tool
+# as parts are sourced, a device tree is built. The structure
+# of the tree is determined by the structure of the components
+# as they are specified. To attach a superio to a southbridge, for
+# example, one would do this:
+# southbridge acer/5432
+#   superio nsc/123
+#   end
+# end
+# the tool generates static initializers for this hierarchy.
+
+# add C code to the current component (motherboard, etc. )
+# to initialise the component-INDEPENDENT structure members
+init ::= 'init' ``CODE''
+
+# add C code to the current component (motherboard, etc. )
+# to initialise the component-DEPENDENT structure members
+register ::= 'register' ``CODE''
+
+
+# mainboard command
+# statements in this block will set variables controlling the mainboard,
+# and will also place components (northbridge etc.) in the device tree
+# under this mainboard
+mainboard ::= 'mainboard' PATH (statements)* 'end'
+
+# standard linuxbios commands
+southbridge ::= 'southbridge' PATH (statemnts)* 'end'
+northbridge ::= 'northbridge' PATH (statemnts)* 'end'
+superio ::= 'superio PATH (statemnts)* 'end'
+cpu ::= 'cpu' PATH (statemnts)* 'end'
+arch ::= 'arch' PATH (statemnts)* 'end'
+
+# files for building linuxbios
+# include a file in crt0.S
+mainboardinit ::= 'mainboardinit' PATH
+
+# object file
+object ::= 'object' PATH
+# driver objects are just built into the image in a different way
+driver ::= 'driver' PATH
+
+# Use the Config.lb file in the PATH
+dir ::= 'dir' PATH
+
+# add a file to the set of ldscript files
+ldscript ::= 'ldscript' PATH
+
+# dependencies or actions for the makerule command
+dep ::= 'dep' ``dependency-string''
+act ::= 'act' ``actions''
+depsacts ::= (dep | act)*
+# set up a makerule
+#
+makerule ::= 'makerule' PATH depsacts
+
+#defines for use in makefiles only
+# note usable in the config tool, not passed to cc
+makedefine ::= 'makedefine' ``RAWTEXT''
+
+# add an action to an existing make rule
+addaction ::= 'addaction' PATH ``ACTION''
+
+# statements
+statement ::=
+		  option
+		| default
+		| cpu
+		| arch
+		| northbridge
+		| southbridge
+		| superio
+		| object
+		| driver
+		| mainboardinit
+		| makerule
+		| makedefine
+		| addaction
+		| init
+		| register
+		| iif
+		| dir
+		| ldscript
+
+statements ::= (statement)*
+
+# target directory specification
+target ::= 'target' PATH
+
+# and the whole thing
+board ::= target (option)* mainboard
+
+\end{verbatim}
+
+\subsubsection{Command definitions}
+\subsubsubsection{option}
+\subsubsubsection{default}
+\subsubsubsection{cpu}
+\subsubsubsection{arch}
+\subsubsubsection{northbridge}
+\subsubsubsection{southbridge}
+\subsubsubsection{superio}
+\subsubsubsection{object}
+\subsubsubsection{driver}
+\subsubsubsection{mainboardinit}
+\subsubsubsection{makerule}
+\subsubsubsection{makedefine}
+\subsubsubsection{addaction}
+\subsubsubsection{init}
+\subsubsubsection{register}
+\subsubsubsection{iif}
+\subsubsubsection{dir}
+\subsubsubsection{ldscript}
+
+
+A sample file:
+
+\begin{verbatim}
+target x
+
+# over-ride the default ROM size in the mainboard file
+option CONFIG_ROM_SIZE=1024*1024
+mainboard amd/solo
+end
+
+\end{verbatim}
+
+Sample mainboard file
+\begin{verbatim}
+#
+###
+### Set all of the defaults for an x86 architecture
+###
+arch i386 end
+cpu k8 end
+#
+option CONFIG_DEBUG=1
+default CONFIG_USE_FALLBACK_IMAGE=1
+option A=(1+2)
+option B=0xa
+#
+###
+### Build our 16 bit and 32 bit linuxBIOS entry code
+###
+mainboardinit cpu/i386/entry16.inc
+mainboardinit cpu/i386/entry32.inc
+ldscript cpu/i386/entry16.lds
+ldscript cpu/i386/entry32.lds
+#
+###
+### Build our reset vector (This is where linuxBIOS is entered)
+###
+if CONFIG_USE_FALLBACK_IMAGE
+	mainboardinit cpu/i386/reset16.inc
+	ldscript cpu/i386/reset16.lds
+else
+	mainboardinit cpu/i386/reset32.inc
+	ldscript cpu/i386/reset32.lds
+end
+.
+.
+.
+if CONFIG_USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc  end
+#
+###
+### Romcc output
+###
+#makerule ./failover.E dep "$(CONFIG_MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(CONFIG_MAINBOARD)/failover.c > ./failever.E"
+#makerule ./failover.inc dep "./romcc ./failover.E" act "./romcc -O ./failover.E > failover.inc"
+#mainboardinit ./failover.inc
+makerule ./auto.E dep "$(CONFIG_MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(CONFIG_MAINBOARD)/auto.c > ./auto.E"
+makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
+mainboardinit ./auto.inc
+#
+###
+### Include the secondary Configuration files
+###
+northbridge amd/amdk8
+end
+southbridge amd/amd8111
+end
+#mainboardinit arch/i386/smp/secondary.inc
+superio nsc/pc87360
+	register "com1={1} com2={0} floppy=1 lpt=1 keyboard=1"
+end
+dir /pc80
+##dir /src/superio/winbond/w83627hf
+cpu p5 end
+cpu p6 end
+cpu k7 end
+cpu k8 end
+#
+###
+### Build the objects we have code for in this directory.
+###
+##object mainboard.o
+driver mainboard.o
+object static_devices.o
+if CONFIG_HAVE_MP_TABLE object mptable.o end
+if CONFIG_HAVE_PIRQ_TABLE object irq_tables.o end
+### Location of the DIMM EEPROMS on the SMBUS
+### This is fixed into a narrow range by the DIMM package standard.
+###
+option SMBUS_MEM_DEVICE_START=(0xa << 3)
+option SMBUS_MEM_DEVICE_END=(SMBUS_MEM_DEVICE_START +1)
+option SMBUS_MEM_DEVICE_INC=1
+#
+### The linuxBIOS bootloader.
+###
+option CONFIG_PAYLOAD_SIZE            = (CONFIG_ROM_SECTION_SIZE - CONFIG_ROM_IMAGE_SIZE)
+option CONFIG_ROM_PAYLOAD_START = (0xffffffff - CONFIG_ROM_SIZE + CONFIG_ROM_SECTION_OFFSET + 1)
+#
+
+\end{verbatim}
+
+I've found the output of the new tool to be easier to
+handle. Makefile.settings looks like this, for example:
+\begin{verbatim}
+TOP:=/home/rminnich/src/yapps2/freebios2
+TARGET_DIR:=x
+export CONFIG_MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
+export CONFIG_ARCH:=i386
+export CONFIG_RAMBASE:=0x4000
+export CONFIG_ROM_IMAGE_SIZE:=65535
+export CONFIG_PAYLOAD_SIZE:=131073
+export CONFIG_MAX_CPUS:=1
+export CONFIG_HEAP_SIZE:=8192
+export CONFIG_STACK_SIZE:=8192
+export CONFIG_MEMORY_HOLE:=0
+export COREBOOT_VERSION:=1.1.0
+export CC:=$(CONFIG_CROSS_COMPILE)gcc
+
+\end{verbatim}
+
+In other words, instead of expressions, we see the values. It's easier to
+deal with.

Documentation/abi-data-consumption.md

@@ -8,9 +8,8 @@ listed as consumable is subject to change without notice.
 ## Background and Usage
 
 coreboot passes information to downstream users using coreboot tables. These
-table definitions can be found in
-`./src/commonlib/include/commonlib/coreboot_tables.h` and
-`./payloads/libpayload/include/coreboot_tables.h` respectively within coreboot
+table definitions can be found in src/include/boot/coreboot_tables.h and
+payloads/libpayload/include/coreboot_tables.h respectively within coreboot
 and libpayload. One of the most vital and important pieces of information
 found within these tables is the memory map of the system indicating
 available and reserved memory.

Documentation/acpi/devicetree.md

@@ -1,234 +0,0 @@
-# Adding new devices to a device tree
-
-## Introduction
-
-ACPI exposes a platform-independent interface for operating systems to perform
-power management and other platform-level functions.  Some operating systems
-also use ACPI to enumerate devices that are not immediately discoverable, such
-as those behind I2C or SPI busses (in contrast to PCI).  This document discusses
-the way that coreboot uses the concept of a "device tree" to generate ACPI
-tables for usage by the operating system.
-
-## Devicetree and overridetree (if applicable)
-
-For mainboards that are organized around a "reference board" or "baseboard"
-model (see ``src/mainboard/google/octopus`` or ``hatch`` for examples), there is
-typically a devicetree.cb file that all boards share, and any differences for a
-specific board ("variant") are captured in the overridetree.cb file.  Any
-settings changed in the overridetree take precedence over those in the main
-devicetree.  Note, not all mainboards will have the devicetree/overridetree
-distinction, and may only have a devicetree.cb file.  Or you can always just
-write the ASL (ACPI Source Language) code yourself.
-
-## Device drivers
-
-Let's take a look at an example entry from
-``src/mainboard/google/hatch/variant/hatch/overridetree.cb``:
-
-```
-device pci 15.0 on
-	chip drivers/i2c/generic
-		register "hid" = ""ELAN0000""
-		register "desc" = ""ELAN Touchpad""
-		register "irq" = "ACPI_IRQ_WAKE_EDGE_LOW(GPP_A21_IRQ)"
-		register "wake" = "GPE0_DW0_21"
-		device i2c 15 on end
-	end
-end # I2C #0
-```
-
-When this entry is processed during ramstage, it will create a device in the
-ACPI SSDT table (all devices in devicetrees end up in the SSDT table).  The ACPI
-generation routines in coreboot actually generate the raw bytecode that
-represents the device's structure, but looking at ASL code is easier to
-understand; see below for what the disassembled bytecode looks like:
-
-```
-Scope (\_SB.PCI0.I2C0)
-{
-    Device (D015)
-    {
-        Name (_HID, "ELAN0000")  // _HID: Hardware ID
-        Name (_UID, Zero)  // _UID: Unique ID
-        Name (_DDN, "ELAN Touchpad")  // _DDN: DOS Device Name
-        Method (_STA, 0, NotSerialized)  // _STA: Status
-        {
-            Return (0x0F)
-        }
-        Name (_CRS, ResourceTemplate ()  // _CRS: Current Resource Settings
-        {
-            I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
-                AddressingMode7Bit, "\\_SB.PCI0.I2C0",
-                0x00, ResourceConsumer, , Exclusive, )
-            Interrupt (ResourceConsumer, Edge, ActiveLow, ExclusiveAndWake, ,, )
-            {
-                0x0000002D,
-            }
-        })
-        Name (_S0W, 0x04)  // _S0W: S0 Device Wake State
-        Name (_PRW, Package (0x02)  // _PRW: Power Resources for Wake
-        {
-            0x15, // GPE #21
-            0x03  // Sleep state S3
-        })
-    }
-}
-```
-
-You can see it generates _HID, _UID, _DDN, _STA, _CRS, _S0W, and _PRW
-names/methods in the Device's scope.
-
-## Utilizing a device driver
-
-The device driver must be enabled for your build.  There will be a CONFIG option
-in the Kconfig file in the directory that the driver is in (e.g.,
-``src/drivers/i2c/generic`` contains a Kconfig file; the option here is named
-CONFIG_DRIVERS_I2C_GENERIC).  The config option will need to be added to your
-mainboard's Kconfig file (e.g., ``src/mainboard/google/hatch/Kconfig``) in order
-to be compiled into your build.
-
-## Diving into the above example:
-
-Let's take a look at how the devicetree language corresponds to the generated
-ASL.
-
-First, note this:
-
-```
-    chip drivers/i2c/generic
-```
-
-This means that the device driver we're using has a corresponding structure,
-located at ``src/drivers/i2c/generic/chip.h``, named **struct
-drivers_i2c_generic_config** and it contains many properties you can specify to
-be included in the ACPI table.
-
-### hid
-
-```
-    register "hid" = ""ELAN0000""
-```
-
-This corresponds to **const char *hid** in the struct.  In the ACPI ASL, it
-translates to:
-
-```
-    Name (_HID, "ELAN0000") // _HID: Hardware ID
-```
-
-under the device.  **This property is used to match the device to its driver
-during enumeration in the OS.**
-
-### desc
-
-```
-    register "desc" = ""ELAN Touchpad""
-```
-
-corresponds to **const char *desc** and in ASL:
-
-```
-    Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
-```
-
-### irq
-
-It also adds the interrupt,
-
-```
-    Interrupt (ResourceConsumer, Edge, ActiveLow, ExclusiveAndWake, ,, )
-    {
-        0x0000002D,
-    }
-```
-
-which comes from:
-
-```
-    register "irq" = "ACPI_IRQ_WAKE_EDGE_LOW(GPP_A21_IRQ)"
-```
-
-The GPIO pin IRQ settings control the "Edge", "ActiveLow", and
-"ExclusiveAndWake" settings seen above (edge means it is an edge-triggered
-interrupt as opposed to level-triggered; active low means the interrupt is
-triggered on a falling edge).
-
-Note that the ACPI_IRQ_WAKE_EDGE_LOW macro informs the platform that the GPIO
-will be routed through SCI (ACPI's System Control Interrupt) for use as a wake
-source.  Also note that the IRQ names are SoC-specific, and you will need to
-find the names in your SoC's header file.  The ACPI_* macros are defined in
-``src/arch/x86/include/acpi/acpi_device.h``.
-
-Using a GPIO as an IRQ requires that it is configured in coreboot correctly.
-This is often done in a mainboard-specific file named ``gpio.c``.
-
-### wake
-
-The last register is:
-
-```
-    register "wake" = "GPE0_DW0_21"
-```
-
-which indicates that the method of waking the system using the touchpad will be
-through a GPE, #21 associated with DW0, which is set up in devicetree.cb from
-this example.  The "21" indicates GPP_X21, where GPP_X is mapped onto DW0
-elsewhere in the devicetree.
-
-The last bit of the definition of that device includes:
-
-```
-    device i2c 15 on end
-```
-
-which means it's an I2C device, with 7-bit address 0x15, and the device is "on",
-meaning it will be exposed in the ACPI table.  The PCI device that the
-controller is located in determines which I2C bus the device is expected to be
-found on.  In this example, this is I2C bus 0.  This also determines the ACPI
-"Scope" that the device names and methods will live under, in this case
-"\_SB.PCI0.I2C0".
-
-## Other auto-generated names
-
-(see [ACPI specification
-6.3](https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf)
-for more details on ACPI methods)
-
-### _S0W (S0 Device Wake State)
-_S0W indicates the deepest S0 sleep state this device can wake itself from,
-which in this case is 4, representing _D3cold_.
-
-### _PRW (Power Resources for Wake)
-_PRW indicates the power resources and events required for wake.  There are no
-dependent power resources, but the GPE (GPE0_DW0_21) is mentioned here (0x15),
-as well as the deepest sleep state supporting waking the system (3), which is
-S3.
-
-### _STA (Status)
-The _STA method is generated automatically, and its values, 0xF, indicates the
-following:
-
-    Bit [0] – Set if the device is present.
-    Bit [1] – Set if the device is enabled and decoding its resources.
-    Bit [2] – Set if the device should be shown in the UI.
-    Bit [3] – Set if the device is functioning properly (cleared if device failed its diagnostics).
-
-### _CRS (Current resource settings)
-The _CRS method is generated automatically, as the driver knows it is an I2C
-controller, and so specifies how to configure the controller for proper
-operation with the touchpad.
-
-```
-Name (_CRS, ResourceTemplate ()  // _CRS: Current Resource Settings
-{
-    I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
-                    AddressingMode7Bit, "\\_SB.PCI0.I2C0",
-                    0x00, ResourceConsumer, , Exclusive, )
-```
-
-## Notes
-
- - **All fields that are left unspecified in the devicetree are initialized to
-   zero.**
- - **All devices in devicetrees end up in the SSDT table, and are generated in
-   coreboot's ramstage**

Documentation/acpi/gpio.md

@@ -73,15 +73,6 @@ calling the platform specific acpigen_soc_{set,clear}_tx_gpio
 functions internally. Thus, all the ACPI AML calling conventions for
 the platform functions apply to these helper functions as well.
 
-3. Get Rx GPIO
-   int acpigen_get_rx_gpio(struct acpi_gpio gpio)
-
-This function takes as input, an struct acpi_gpio type and outputs
-AML code to read the *logical* value of a gpio (after taking its
-polarity into consideration), into the Local0 variable. It calls
-the platform specific acpigen_soc_read_rx_gpio() to actually read
-the raw Rx gpio value.
-
 ## Implementation Details
 
 ACPI library in coreboot will provide weak definitions for all the

Documentation/acpi/index.md

@@ -1,16 +0,0 @@
-# ACPI-specific documentation
-
-This section contains documentation about coreboot on ACPI. coreboot dropped
-backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
-upwards.
-
-
-- [SSDT UID generation](uid.md)
-
-## GPIO
-
-- [GPIO toggling in ACPI AML](gpio.md)
-
-## devicetree
-
-- [Adding devices to a device tree](devicetree.md)

Documentation/acpi/uid.md

@@ -1,14 +0,0 @@
-# ACPI SSDT \_UID generation
-
-According to the ACPI spec:
-
-> The _UID must be unique across all devices with either a common _HID or _CID.
-
-
-When generating SSDTs in coreboot the independent drivers don't know
-which \_UID is already in use for a specific \_HID or \_CID. To generate
-unique \_UIDs the ACPI device's path is hashed and used as ID. As every ACPI
-device has a different path, the hash will be also different for every device.
-
-Windows 10 verifies all devices with the same \_HID or \_CID and makes
-sure that no \_UID is duplicated. If it is it'll BSOD.

Documentation/arch/riscv/index.md

@@ -15,31 +15,16 @@ Payloads run from the ramstage are started in S mode, and trap delegation
 will have been done. These payloads rely on the SBI and can not replace it.
 
 ## Stage handoff protocol
-On entry to a stage or payload (including SELF payloads),
+On entry to a stage or payload,
 * all harts are running.
 * A0 is the hart ID.
 * A1 is the pointer to the Flattened Device Tree (FDT).
-* A2 contains the additional program calling argument:
-  - cbmem_top for ramstage
-  - the address of the payload for opensbi
 
 ## Additional payload handoff requirements
 The location of cbmem should be placed in a node in the FDT.
 
-## OpenSBI
-In case the payload doesn't install it's own SBI, like the [RISCV-PK] does,
-[OpenSBI] can be used instead.
-It's loaded into RAM after coreboot has finished loading the payload.
-coreboot then will jump to OpenSBI providing a pointer to the real payload,
-which OpenSBI will jump to once the SBI is installed.
-
-Besides providing SBI it also sets protected memory regions and provides
-a platform independent console.
-
-The OpenSBI code is always run in M mode.
-
 ## Trap delegation
-Traps are delegated to the payload.
+Traps are delegated in the ramstage.
 
 ## SMP within a stage
 At the beginning of each stage, all harts save 0 are spinning in a loop on
@@ -59,6 +44,3 @@ The hart blocks until fn is non-null, and then calls it.  If fn returns, we
 will panic if possible, but behavior is largely undefined.
 
 Only hart 0 runs through most of the code in each stage.
-
-[RISCV-PK]: https://github.com/riscv/riscv-pk
-[OpenSBI]: https://github.com/riscv/opensbi

Documentation/arch/x86/index.md

@@ -2,8 +2,6 @@
 
 This section contains documentation about coreboot on x86 architecture.
 
-* [x86 PAE support](pae.md)
-
 ## State of x86_64 support
 At the moment there's no single board that supports x86_64 or to be exact
 `ARCH_RAMSTAGE_X86_64` and `ARCH_ROMSTAGE_X86_64`.
@@ -16,36 +14,24 @@ In order to add support for x86_64 the following assumptions are made:
 * The reference implementation is qemu
 * The CPU supports 1GiB hugepages
 
-## Assuptions for all stages using the reference implementation
-* 0-4GiB are identity mapped using 2MiB-pages as WB
+## Assuptions for ARCH_ROMSTAGE_X86_64 reference implementation
+* 0-4GiB are identity mapped using 1GiB huge-pages
 * Memory above 4GiB isn't accessible
-* page tables reside in memory mapped ROM
-* A stage can install new page tables in RAM
+* pagetables reside in _pagetables
+* Romstage must install new pagetables in CBMEM after RAMINIT
 
-## Page tables
-Page tables are generated by a tool in `util/pgtblgen/pgtblgen`. It writes
-the page tables to a file which is then included into the CBFS as file called
-`pagetables`.
-
-To generate the static page tables it must know the physical address where to
-place the file.
-
-The page tables contains the following structure:
-* PML4E pointing to PDPE
-* PDPE with *$n* entries each pointing to PDE
-* *$n* PDEs with 512 entries each
-
-At the moment *$n* is 4, which results in identity mapping the lower 4 GiB.
+## Assuptions for ARCH_RAMSTAGE_X86_64 reference implementation
+* Romstage installed pagetables according to memory layout
+* Memory above 4GiB is accessible
 
 ## Steps to add basic support for x86_64
 * Add x86_64 toolchain support - *DONE*
 * Fix compilation errors - *DONE*
 * Fix linker errors - *TODO*
-* Add x86_64 rmodule support - *DONE*
+* Add x86_64 rmodule support - *ONGERRIT*
 * Add x86_64 exception handlers - *TODO*
-* Setup page tables for long mode - *DONE*
-* Add assembly code for long mode - *DONE*
-* Add assembly code for postcar stage - *TODO*
+* Setup page tables for long mode - *TODO*
+* Add assembly code for long mode - *TODO*
 * Add assembly code to return to protected mode - *TODO*
 * Implement reference code for mainboard `emulation/qemu-q35` - *TODO*
 

Documentation/arch/x86/pae.md

@@ -1,15 +0,0 @@
-# x86_32 PAE documentation
-
-Due to missing x86_64 support it's required to use PAE enabled x86_32 code.
-The corresponding functions can be found in ``src/cpu/x86/pae/``.
-
-## Memory clearing helper functions
-
-To clear all DRAM on request of the
-[Security API](../../security/memory_clearing.md), a helper function can be used
-called `memset_pae`.
-The function has additional requirements in contrast to `memset`, and has more
-overhead as it uses virtual memory to access memory above 4GiB.
-Memory is cleared in 2MiB chunks, which might take a while.
-
-Make sure to enable caches through MTRRs, otherwise `memset_pae` will be slow!

Documentation/coding_style.md

@@ -80,11 +80,11 @@ Get a decent editor and don't leave whitespace at the end of lines.
 Coding style is all about readability and maintainability using commonly
 available tools.
 
-The limit on the length of lines is 96 columns and this is a strongly
+The limit on the length of lines is 80 columns and this is a strongly
 preferred limit.
 
-Statements longer than 96 columns will be broken into sensible chunks,
-unless exceeding 96 columns significantly increases readability and does
+Statements longer than 80 columns will be broken into sensible chunks,
+unless exceeding 80 columns significantly increases readability and does
 not hide information. Descendants are always substantially shorter than
 the parent and are placed substantially to the right. The same applies
 to function headers with a long argument list. However, never break

Documentation/community/code_of_conduct.md

@@ -22,30 +22,19 @@ Refrain from insulting anyone or the group they belong to. Remember that
 people might be sensitive to other things than you are.
 
 Most of our community members are not native English speakers, thus
-misunderstandings can (and do) happen. Assume that others are friendly
-and may have picked less-than-stellar wording by accident as long as
-you possibly can.
+misunderstandings can (and do) happen. Always assume that others are
+friendly and may have picked less-than-stellar wording by accident.
 
-## Reporting Issues
-
-If you have a grievance due to conduct in this community, we're sorry
-that you have had a bad experience, and we want to hear about it so
-we can resolve the situation.
-
-Please contact members of our arbitration team (listed below) promptly
-and directly, in person (if available) or by email: They will listen
-to you and react in a timely fashion.
-
-If you feel uncomfortable, please don't wait it out, ask for help,
-so we can work on setting things right.
+If you have a grievance due to conduct in this community, we want to hear
+about it so we can handle the situation. Please contact our arbitration
+team directly: They will listen to you and react in a timely fashion.
 
 For transparency there is no alias or private mailing list address for
 you to reach out to, since we want to make sure that you know who will
-and who won't read your message.
+(and who won't) read your message.
 
-However since people might be on travel or otherwise be unavailable
-at times, please reach out to multiple persons at once, especially
-when using email.
+However since people might be on travel or otherwise be unavailable at
+times, consider reaching out to multiple persons.
 
 The team will treat your messages confidential as far as the law permits.
 For the purpose of knowing what law applies, the list provides the usual
@@ -84,10 +73,15 @@ immediately.
 If a community member engages in unacceptable behavior, the community
 organizers may take any action they deem appropriate, up to and including
 a temporary ban or permanent expulsion from the community without warning
-(and without refund in the case of a paid event).
+(and without refund in the case of a paid event). Community organizers
+can be part of the arbitration team, or organizers of events and online
+communities.
+
+## If You Witness or Are Subject to Unacceptable Behavior
+
+If you are subject to or witness unacceptable behavior, or have any other
+concerns, please notify someone from the arbitration team immediately.
 
-Community organizers can be members of the arbitration team, or organizers
-of events and online communities.
 
 ## Addressing Grievances
 
@@ -108,7 +102,7 @@ Our arbitration team consists of the following people
 * Stefan Reinauer <stefan.reinauer@coreboot.org> (USA)
 * Patrick Georgi <patrick@coreboot.org> (Germany)
 * Ronald Minnich <rminnich@coreboot.org> (USA)
-* Martin Roth <martin@coreboot.org> (USA)
+* Marc Jones <mjones@coreboot.org> (USA)
 
 ## License and attribution
 

Documentation/community/services.md

@@ -1,45 +0,0 @@
-# Accounts on coreboot.org
-
-There are a number of places where you can benefit from creaating an account
-in our community. Since there is no single sign-on system in place (at this
-time), they come with their own setup routines.
-
-## Gerrit code review
-We exchange and review patches to the code using our [Gerrit code review
-system](https://review.coreboot.org).
-
-It allows logging in with a Google or GitHub account using OAuth2 as well
-as with any OpenID provider that you may already use.
-
-On the [settings screen](https://review.coreboot.org/settings) you can register
-all your email addresses you intend to use in the context of coreboot
-development so that commits with your email address in them are associated with
-you properly.
-
-### https push access
-When using the https URLs to git repositories, you can push with the "HTTP
-Credentials" you can have Gerrit generate for you on that page. By default,
-git uses `$HOME/.netrc` for http authentication data, so add a line there
-stating:
-
-    machine review.coreboot.org login $your-user-name password $your-password
-
-### Gerrit user avatar
-To setup an avatar to show in Gerrit, clone the avatars repository at
-https://review.coreboot.org/gerrit-avatars.git and add a file named
-$your-user-ID.jpg (the user ID is a number shown on the [settings screen](https://review.coreboot.org/settings)).
-The image must be provided in JPEG format, must be square and have at most 50000
-bytes.
-
-After you push for review, the system will automatically verify your change
-and, if adhering to these constraints, approve it. You can then immediately
-submit it.
-
-## Issue tracker
-We have an [issue tracker](https://ticket.coreboot.org) that is used for
-coreboot and related code, such as libpayload, as well as for the project's
-infrastructure.
-
-It can be helpful to refer to issues we track there in commit messages:
-
-    Fixes: https://ticket.coreboot.org/issues/$id

Documentation/conf.py

@@ -25,8 +25,6 @@ release = subprocess.check_output(('git', 'describe')).decode("utf-8")
 # The short X.Y version.
 version = release.split("-")[0]
 
-extensions = ['sphinxcontrib.ditaa']
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #

Documentation/contributing/documentation_ideas.md

@@ -1,173 +0,0 @@
-# Documentation Ideas
-
-This section collects ideas to improve the coreboot documentation and
-should serve as a pool of ideas for people who want to improve the current
-documentation status of coreboot.
-
-The main purpose of this document is to gather documentation ideas for technical
-writers of the seasons of docs. Nevertheless anyone who wants to help improving
-the current documentation situation can take one of the projects.
-
-Each entry should outline what would be done, the benefit it brings
-to the project, the pre-requisites, both in knowledge and parts. They
-should also list people interested in supporting people who want to work
-on them.
-
-## Restructure Existing Documentation
-
-The goal is to improve the user experience and structure the documentation more
-logically. The current situation makes it very hard for beginners, but also for
-experienced developers to find anything in the coreboot documentation.
-
-One possible approach to restructure the documentation is to split it up such
-that we divide the group of users into:
-
-* (End-)users
-Most probably users which _just_ want to use coreboot as fast as possible. This
-section should include guidelines on how to build coreboot, how to flash coreboot
-and also which hardware is currently supported.
-
-* Developers
-This section should more focus on the developer side-of-view. This section would
-include how to get started developing coreboot, explaining the basic concepts of
-coreboot and also give guideance on how to proceed after the first steps.
-
-* Knowledge area
-This section is very tighlight coupled to the developer section and might be merged
-into it. The _Knowledge area_ can give a technical deep dive on various drivers,
-technologies, etc.
-
-* Community area
-This section gives some room for the community: Youtube channels, conferences,
-meetups, forums, chat, etc.
-
-A [first approach](https://review.coreboot.org/c/coreboot/+/40327) has already been made here and might be a basis for the work.
-Most of the documentation is already there, but scattered around the documentation
-folder.
-
-### Requirements
-* Understanding on how a different groups of users might use the documentation area
-* Basic understanding of how coreboot works (Can be worked out _on-the-fly_)
-
-### Mentors
-* christian.walter@9elements.com
-* TBD
-
-## Update Howto/Guides
-
-An important part to involve new people in the project, either as developer or
-as enduser, are guides and how-to's. There are already some guides which need
-to be updated to work, and could also be extended to multiple platforms, like
-Fedora or Arch-Linux. Also guidance for setting up coreboot with a Windows
-environment would be helpful.
-
-In addition, the vboot guidance needs an update/extensions, that the security
-features within coreboot can be used by non-technical people.
-
-For developers, how to debug coreboot and various debugging techniques need
-documentation.
-
-### Requirements
-* Knowledge of virtual machines, how to install different OSs and set up the
-  toolchain on different operating systems
-* Knowledge of debugging tools like gdb
-
-### Mentors
-* christian.walter@9elements.com
-* TBD
-
-## How to Support a New Board
-
-coreboot benefits from running on as many platforms as possible. Therefore we
-want to encourage new developers on porting existing hardware to coreboot.
-Guidance for those new developers need to be made such that they are able to
-take the first steps supporting new mainboards, when the SoC support already
-exists. There should be a 'how-to' guide for this. Also what are common problems
-and how to solve those.
-
-### Requirements
-* Knowledge of how to add support for a new mainboard in coreboot
-
-### Mentors
-* christian.walter@9elements.com
-* TBD
-
-## Payloads
-
-The current documentation of the payloads is not very effective. There should be
-more detailed documentation on the payloads that can be selected via the make
-menuconfig within coreboot. Also the use-cases should be described in more
-detail: When to use which payload? What are the benefits of using payload X over
-Y in a specific use-case ?
-
-In addition it should be made clear how additional functionality e.g. extend
-LinuxBoot with more commands, can be achieved.
-
-### Requirements
-* Basic knowledge of the supported payloads like SeaBIOS, TinanoCore, LinuxBoot,
-  GRUB, Linux, ...
-
-
-### Mentors
-* christian.walter@9elements.com
-* TBD
-
-
-## coreboot Util Documentation
-
-coreboot inherits a variaty of utilities. The current documentation only
-provides a "one-liner" as an explanation. The list of util should be updated
-with a more detailed explanation where possible. Also more "in-depths"
-explanations should be added with examples if possible.
-
-### Requirements
-* coreboot utilities
-
-### Mentors
-* christian.walter@9elements.com
-* TBD
-
-
-## CBMEM Developer Guide
-
-CBMEM is the API that provides memory buffers for the use at OS runtime. It's a
-core component and thus should be documented. Dos, don'ts and pitfalls when
-using CBMEM. This "in-depth" guide is clearly for developers.
-
-### Requirements
-* Deep understanding of coreboot's internals
-
-### Mentors
-* TBD
-* TBD
-
-
-## CBFS Developer Guide
-
-CBFS is the in-flash filesystem that is used by coreboot. It's a core component
-and thus should be documented. Update the existing CBFS.txt that still shows
-version 1 of the implementation. A [first approach](https://review.coreboot.org/c/coreboot/+/33663/2)
-has been made here.
-This "in-depth" guide is clearly for developers.
-
-### Requirements
-* Deep understanding of coreboot's internals
-
-### Mentors
-* TBD
-* TBD
-
-
-## Region API Developer Guide
-
-The region API is used by coreboot when dealing with memory mapped objects that
-can be split into chunks. It's a core component and thus should be documented.
-This "in-depth" guide is clearly for developers.
-
-### Requirements
-* Deep understanding of coreboot's internals
-
-### Mentors
-* TBD
-* TBD
-

Documentation/contributing/project_ideas.md

@@ -27,15 +27,7 @@ which is a bad experience when trying to build coreboot the first time.
 
 Provide packages/installers of our compiler toolchain for Linux distros,
 Windows, Mac OS. For Windows, this should also include the environment
-(shell, make, ...). A student doesn't have to cover _all_ platforms, but
-pick a set of systems that match their interest and knowledge and lay
-out a plan on how to do this.
-
-The scripts to generate these packages should be usable on a Linux
-host, as that's what we're using for our automated build testing system
-that we could extend to provide current packages going forward. This
-might include automating some virtualization system (eg. QEMU or CrosVM) for
-non-Linux builds or Docker for different Linux distributions.
+(shell, make, ...).
 
 ### Requirements
 * coreboot knowledge: Should know how to build coreboot images and where
@@ -66,6 +58,27 @@ across architectures.
 ### Mentors
 * Timothy Pearson <tpearson@raptorengineering.com>
 
+## Support QEMU AArch64 or MIPS
+Having QEMU support for the architectures coreboot can boot helps with
+some (limited) compatibility testing: While QEMU generally doesn't need
+much hardware init, any CPU state changes in the boot flow will likely
+be quite close to reality.
+
+That could be used as a baseline to ensure that changes to architecture
+code doesn't entirely break these architectures
+
+### Requirements
+* coreboot knowledge: Should know the general boot flow in coreboot.
+* other knowledge: This will require knowing how the architecture
+  typically boots, to adapt the coreboot payload interface to be
+  appropriate and, for example, provide a device tree in the platform's
+  typical format.
+* hardware requirements: since QEMU runs practically everywhere and
+  needs no recovery mechanism, these are suitable projects when no special
+  hardware is available.
+
+### Mentors
+
 ## Add Kernel Address Sanitizer functionality to coreboot
 The Kernel Address Sanitizer (KASAN) is a runtime dynamic memory error detector.
 The idea is to check every memory access (variables) for its validity
@@ -85,7 +98,7 @@ would help to ensure code quality and make the runtime code more robust.
 ### Mentors
 * Werner Zeh <werner.zeh@gmx.net>
 
-## Port payloads to ARM, AArch64 or RISC-V
+## Port payloads to ARM, AArch64, MIPS or RISC-V
 While we have a rather big set of payloads for x86 based platforms, all other
 architectures are rather limited. Improve the situation by porting a payload
 to one of the platforms, for example GRUB2, U-Boot (the UI part), Tianocore,
@@ -132,118 +145,3 @@ their bug reports.
 
 ### Mentors
 * Patrick Georgi <patrick@georgi.software>
-
-## Extend Ghidra to support analysis of firmware images
-[Ghidra](https://ghidra-sre.org) is a recently released cross-platform
-disassembler and decompiler that is extensible through plugins. Make it
-useful for firmware related work: Automatically parse formats (eg. by
-integrating UEFITool, cbfstool, decompressors), automatically identify
-16/32/64bit code on x86/amd64, etc.
-
-This has been done in 2019 with [some neat
-features](https://github.com/al3xtjames/ghidra-firmware-utils) being
-developed, but it may be possible to expand support for all kinds of firmware
-analyses.
-
-## Learn hardware behavior from I/O and memory access logs
-[SerialICE](https://www.serialice.com) is a tool to trace the behavior of
-executable code like firmware images. One result of that is a long log file
-containing the accesses to hardware resources.
-
-It would be useful to have a tool that assists a developer-analyst in deriving
-knowledge about hardware from such logs. This likely can't be entirely
-automatic, but a tool that finds patterns and can propagate them across the
-log (incrementially raising the log from plain I/O accesses to a high-level
-description of driver behavior) would be of great use.
-
-This is a research-heavy project.
-
-### Requirements
-* Driver knowledge: Somebody working on this should be familiar with
-  how hardware works (eg. MMIO based register access, index/data port
-  accesses) and how to read data sheets.
-* Machine Learning: ML techniques may be useful to find structure in traces.
-
-### Mentors
-* Ron Minnich <rminnich@google.com>
-
-## Libpayload based memtest payload
-[Memtest86+](https://www.memtest.org/) has some limitations: first and
-foremost it only works on x86, while it can print to serial console the
-GUI only works in legacy VGA mode.
-
-This project would involve porting the memtest suite to libpayload and
-build a payload around it.
-
-### Requirements
-* coreboot knowledge: Should know how to build coreboot images and
-  include payloads.
-* other knowledge: Knowledge on how dram works is a plus.
-* hardware requirements: Initial work can happen on qemu targets,
-  being able to test on coreboot supported hardware is a plus.
-
-### Mentors
-* TODO
-
-## Fix POST code handling
-coreboot supports writing POST codes to I/O port 80.
-There are various Kconfigs that deal with POST codes, which don't have
-effect on most platforms.
-The code to send POST codes is scattered in C and Assembly, some use
-functions, some use macros and others simply use the `outb` instruction.
-The POST codes are duplicated between stages and aren't documented properly.
-
-
-Tasks:
-* Guard Kconfigs with a *depends on* to only show on supported platforms
-* Remove duplicated Kconfigs
-* Replace `outb(0x80, ...)` with calls to `post_code(...)`
-* Update Documentation/POSTCODES
-* Use defines from console/post_codes.h where possible
-* Drop duplicated POST codes
-* Make use of all possible 255 values
-
-### Requirements
-* knowledge in the coreboot build system and the concept of stages
-* other knowledge: Little experience with C and x86 Assembly
-* hardware requirements: Nothing special
-
-### Mentors
-* Patrick Rudolph <patrick.rudolph@9elements.com>
-* Christian Walter <christian.walter@9elements.com>
-
-## Board status replacement
-The [Board status page](https://coreboot.org/status/board-status.html) allows
-to see last working commit of a board. The page is generated by a cron job
-that runs on a huge git repository.
-
-Build an open source replacement written in Golang using existing tools
-and libraries, consisting of a backend, a frontend and client side
-scripts. The backend should connect to an SQL database with can be
-controlled using a RESTful API. The RESTful API should have basic authentication
-for managment tasks and new board status uploads.
-
-At least one older test result should be keept in the database.
-
-The frontend should use established UI libraries or frameworks (for example
-Angular) to display the current board status, that is if it's working or not
-and some details provided with the last test. If a board isn't working the last
-working commit (if any) should be shown in addition to the broken one.
-
-Provide a script/tool that allows to:
-1. Push mainboard details from coreboot master CI
-2. Push mainboard test results from authenticated users containing
-   * working
-   * commit hash
-   * bootlog (if any)
-   * dmesg (if it's booting)
-   * timestamps (if it's booting)
-   * coreboot config
-
-### Requirements
-* coreboot knowledge: Non-technical, needed to perform requirements analysis
-* software knowledge: Golang, SQL for the backend, JS for the frontend
-
-### Mentors
-* Patrick Rudolph <patrick.rudolph@9elements.com>
-* Christian Walter <christian.walter@9elements.com>

Documentation/distributions.md

@@ -58,6 +58,16 @@ fixes not found in the stock firmware, and offer much broader OS compatibility
 microcode, as well as firmware updates for the device's embedded controller
 (EC). This firmware "takes the training wheels off" your ChromeOS device :)
 
+### John Lewis
+
+[John Lewis](https://johnlewis.ie/custom-chromebook-firmware) also provides
+replacement firmware for ChromeOS devices, for the express purpose of
+running Linux on Chromebooks. John Lewis' firmware supports a much smaller
+set of devices, and uses SeaBIOS as the payload to support Legacy BIOS booting.
+His firmware images are significantly older, and not actively maintained or
+supported, but worth a look if you need Legacy Boot support and is not
+available via Mr Chromebox's firmware.
+
 ### Heads
 
 [Heads](http://osresearch.net) is an open source custom firmware and OS

Documentation/drivers/index.md

@@ -1,8 +0,0 @@
-# Platform independent drivers documentation
-
-The drivers can be found in `src/drivers`. They are intended for onboard
-and plugin devices, significantly reducing integration complexity and
-they allow to easily reuse existing code accross platforms.
-
-* [IPMI KCS](ipmi_kcs.md)
-* [SMMSTORE](smmstore.md)

Documentation/drivers/ipmi_kcs.md

@@ -1,47 +0,0 @@
-# IPMI KCS driver
-
-The driver can be found in `src/drivers/ipmi/`. It works with BMC that provide
-a KCS I/O interface as specified in the [IPMI] standard.
-
-The driver detects the IPMI version, reserves the I/O space in coreboot's
-resource allocator and writes the required ACPI and SMBIOS tables.
-
-## For developers
-
-To use the driver, select the `IPMI_KCS` Kconfig and add the following PNP
-device under the LPC bridge device (in example for the KCS at 0xca2):
-
-```
- chip drivers/ipmi
-   device pnp ca2.0 on end         # IPMI KCS
- end
-```
-
-**Note:** The I/O base address needs to be aligned to 2.
-
-The following registers can be set:
-
-* `have_nv_storage`
-  * Boolean
-  * If true `nv_storage_device_address` will be added to SMBIOS type 38.
-* `nv_storage_device_address`
-  * Integer
-  * The NV storage address as defined in SMBIOS spec for type 38.
-* `bmc_i2c_address`
-  * Integer
-  * The i2c address of the BMC. zero if not applicable.
-* `have_apic`
-  * Boolean
-  * If true the `apic_interrupt` will be added to SPMI table.
-* `apic_interrupt`
-  * Integer
-  * The APIC interrupt used to notify about a change on the KCS.
-* `have_gpe`
-  * Boolean
-  * If true the `gpe_interrupt` will be added to SPMI table.
-* `gpe_interrupt`
-  * Integer
-  * The bit in GPE (SCI) used to notify about a change on the KCS.
-
-
-[IPMI]: https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf

Documentation/drivers/smmstore.md

@@ -1,123 +0,0 @@
-# SMM based flash storage driver
-
-This documents the API exposed by the x86 system management based
-storage driver.
-
-## SMMSTORE
-
-SMMSTORE is a SMM mediated driver to read from, write to and erase a
-predefined region in flash. It can be enabled by setting
-`CONFIG_SMMSTORE=y` in menuconfig.
-
-This can be used by the OS or the payload to implement persistent
-storage to hold for instance configuration data, without needing
-to implement a (platform specific) storage driver in the payload
-itself.
-
-The API provides append-only semantics for key/value pairs.
-
-## API
-
-### Storage region
-
-By default SMMSTORE will operate on a separate FMAP region called
-`SMMSTORE`. The default generated FMAP will include such a region.
-On systems with a locked FMAP, e.g. in an existing vboot setup
-with a locked RO region, the option exists to add a cbfsfile
-called `smm_store` in the `RW_LEGACY` (if CHROMEOS) or in the
-`COREBOOT` FMAP regions. It is recommended for new builds using
-a handcrafted FMD that intend to make use of SMMSTORE to include a
-sufficiently large `SMMSTORE` FMAP region. It is recommended to
-align the `SMMSTORE` region to 64KiB for the largest flash erase
-op compatibility.
-
-When a default generated FMAP is used the size of the FMAP region
-is equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least
-64KiB. Given that the current implementation lacks a way to rewrite
-key-value pairs at least a multiple of this is recommended.
-
-### generating the SMI
-
-SMMSTORE is called via an SMI, which is generated via a write to the
-IO port defined in the smi_cmd entry of the FADT ACPI table. `%al`
-contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO
-port. `%ah` contains the SMMSTORE command. `%ebx` contains the
-parameter buffer to the SMMSTORE command.
-
-### Return values
-
-If a command succeeds, SMMSTORE will return with
-`SMMSTORE_RET_SUCCESS=0` on `%eax`. On failure SMMSTORE will return
-`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
-`SMMSTORE_REG_UNSUPPORTED=2` is returned.
-
-**NOTE1**: The caller **must** check the return value and should make
-no assumption on the returned data if `%eax` does not contain
-`SMMSTORE_RET_SUCCESS`.
-
-**NOTE2**: If the SMI returns without changing `%ax` assume that the
-SMMSTORE feature is not installed.
-
-### Calling arguments
-
-SMMSTORE supports 3 subcommands that are passed via `%ah`, the additional
-calling arguments are passed via `%ebx`.
-
-**NOTE**: The size of the struct entries are in the native word size of
-smihandler. This means 32 bits in almost all cases.
-
-
-#### - SMMSTORE_CMD_CLEAR = 1
-
-This clears the `SMMSTORE` storage region. The argument in `%ebx` is
-unused.
-
-#### - SMMSTORE_CMD_READ = 2
-
-The additional parameter buffer `%ebx` contains a pointer to
-the following struct:
-
-```C
-struct smmstore_params_read {
-	void *buf;
-	ssize_t bufsize;
-};
-```
-
-INPUT:
-- `buf`: is a pointer to where the data needs to be read
-- `bufsize`: is the size of the buffer
-
-OUTPUT:
-- `buf`
-- `bufsize`: returns the amount of data that has actually been read.
-
-#### - SMMSTORE_CMD_APPEND = 3
-
-SMMSTORE takes a key-value approach to appending data. key-value pairs
-are never updated, they are always appended. It is up to the caller to
-walk through the key-value pairs after reading SMMSTORE to find the
-latest one.
-
-The additional parameter buffer `%ebx` contains a pointer to
-the following struct:
-
-```C
-struct smmstore_params_append {
-	void *key;
-	size_t keysize;
-	void *val;
-	size_t valsize;
-};
-```
-
-INPUT:
-- `key`: pointer to the key data
-- `keysize`: size of the key data
-- `val`: pointer to the value data
-- `valsize`: size of the value data
-
-## External links
-
-* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
-Note, this differs significantly from coreboot's implementation.

Documentation/flash_tutorial/int_flashrom.md

@@ -5,7 +5,7 @@
 
 ## Using flashrom
 This method does only work on Linux, if it isn't locked down.
-You may also need to boot with `iomem=relaxed` in the kernel command
+You may also need to boot with 'iomem=relaxed' in the kernel command
 line if CONFIG_IO_STRICT_DEVMEM is set.
 
 

Documentation/getting_started/architecture.md

@@ -1,105 +0,0 @@
-# coreboot architecture
-
-## Overview
-![][architecture]
-
-[architecture]: comparision_coreboot_uefi.svg
-
-## Stages
-coreboot consists of multiple stages that are compiled as separate binaries and
-are inserted into the CBFS with custom compression. The bootblock usually doesn't
-have compression while the ramstage and payload are compressed with LZMA.
-
-Each stage loads the next stage a given address (possibly decompressing it).
-
-Some stages are relocatable and can be placed anywhere in DRAM. Those stages are
-usually cached in CBMEM for faster loading times on ACPI S3 resume.
-
-Supported stage compressions:
-* none
-* LZ4
-* LZMA
-
-## bootblock
-The bootblock is the first stage executed after CPU reset. It is written in
-assembly language and its main task is to set up everything for a C-environment:
-
-Common tasks:
-
-* Cache-As-RAM for heap and stack
-* Set stack pointer
-* Clear memory for BSS
-* Decompress and load the next stage
-
-On x86 platforms that includes:
-
-* Microcode updates
-* Timer init
-* Switching from 16-bit real-mode to 32-bit protected mode
-
-The bootblock loads the romstage or the verstage if verified boot is enabled.
-
-### Cache-As-Ram
-The *Cache-As-Ram*, also called Non-Eviction mode, or *CAR* allows to use the
-CPU cache like regular SRAM. This is particullary usefull for high level
-languages like `C`, which need RAM for heap and stack.
-
-The CAR needs to be activated using vendor specific CPU instructions.
-
-The following stages run when Cache-As-Ram is active:
-* bootblock
-* romstage
-* verstage
-* postcar
-
-## verstage
-The verstage is where the root-of-trust starts. It's assumed that
-it cannot be overwritten in-field (together with the public key) and
-it starts at the very beginning of the boot process.
-The verstage installs a hook to verify a file before it's loaded from
-CBFS or a partition before it's accessed.
-
-The verified boot mechanism allows trusted in-field firmware updates
-combined with a fail-safe recovery mode.
-
-## romstage
-The romstage initializes the DRAM and prepares everything for device init.
-
-Common tasks:
-
-* Early device init
-* DRAM init
-
-## postcar
-To leave the CAR setup and run code from regular DRAM the postcar-stage tears
-down CAR and loads the ramstage. Compared to other stages it's minimal in size.
-
-## ramstage
-
-The ramstage does the main device init:
-
-* PCI device init
-* On-chip device init
-* TPM init (if not done by verstage)
-* Graphics init (optional)
-* CPU init (like set up SMM)
-
-After initialization tables are written to inform the payload or operating system
-about the current hardware existance and state. That includes:
-
-* ACPI tables (x86 specific)
-* SMBIOS tables (x86 specific)
-* coreboot tables
-* devicetree updates (ARM specific)
-
-It also does hardware and firmware lockdown:
-* Write-protection of boot media
-* Lock security related registers
-* Lock SMM mode (x86 specific)
-
-## payload
-The payload is the software that is run after coreboot is done. It resides in
-the CBFS and there's no possibility to choose it at runtime.
-
-For more details have a look at [payloads](../payloads.md).
-

Documentation/getting_started/comparision_coreboot_uefi.svg

@@ -1,176 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="55cm" height="28cm" viewBox="62 37 1088 559" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-  <g>
-    <rect style="fill: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="63.296" y="74.0258" width="1085.8" height="520.893"/>
-  </g>
-  <line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="242.613" y1="107.463" x2="242.698" y2="492.591"/>
-  <g>
-    <line style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" x1="234.964" y1="477.053" x2="1135.15" y2="478.109"/>
-    <polyline style="fill: none; fill-opacity:0; stroke-width: 4; stroke: #000000" points="1124.61,485.597 1139.62,478.114 1124.63,470.597 "/>
-  </g>
-  <text font-size="22.5778" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="482.342" y="58.1574">
-    <tspan x="482.342" y="58.1574">Platform Initialization Firmware Phases</tspan>
-  </text>
-  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="98.4514" y="435.714">
-    <tspan x="98.4514" y="435.714">EDK II - stages</tspan>
-  </text>
-  <text font-size="12.8" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="1073.49" y="499.998">
-    <tspan x="1073.49" y="499.998">time</tspan>
-  </text>
-  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="82.8266" y="330.476">
-    <tspan x="82.8266" y="330.476">coreboot - stages</tspan>
-  </text>
-  <g>
-    <rect style="fill: #faff94" x="250.501" y="404.247" width="130.432" height="69.1471"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="250.501" y="404.247" width="130.432" height="69.1471"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="315.718" y="434.72">
-      <tspan x="315.718" y="434.72">Security</tspan>
-      <tspan x="315.718" y="450.72">(SEC)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #faff94" x="383.033" y="404.781" width="282.702" height="69"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="383.033" y="404.781" width="282.702" height="69"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="524.384" y="427.181">
-      <tspan x="524.384" y="427.181">Pre-EFI</tspan>
-      <tspan x="524.384" y="443.181">Initialization Environment</tspan>
-      <tspan x="524.384" y="459.181">(PEI)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #faff94" x="668.027" y="405.317" width="269.244" height="69"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="668.027" y="405.317" width="269.244" height="69"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="802.649" y="427.717">
-      <tspan x="802.649" y="427.717">Driver Execution</tspan>
-      <tspan x="802.649" y="443.717">Environment</tspan>
-      <tspan x="802.649" y="459.717">(DXE)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #faff94" x="939.541" y="405.727" width="178.75" height="69"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="939.541" y="405.727" width="178.75" height="69"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1028.92" y="436.127">
-      <tspan x="1028.92" y="436.127">Boot Device Selection</tspan>
-      <tspan x="1028.92" y="452.127">(BDS)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="254.747" y="291.309" width="125.314" height="69.1471"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="254.747" y="291.309" width="125.314" height="69.1471"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="317.404" y="329.782">
-      <tspan x="317.404" y="329.782">bootblock</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="476.354" y="290.735" width="89.65" height="69.1471"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="476.354" y="290.735" width="89.65" height="69.1471"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="521.179" y="329.209">
-      <tspan x="521.179" y="329.209">romstage</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="382.317" y="291.011" width="92.1" height="69.1471"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="382.317" y="291.011" width="92.1" height="69.1471"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="428.367" y="321.485">
-      <tspan x="428.367" y="321.485">verstage</tspan>
-      <tspan x="428.367" y="337.485">(optional)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="567.853" y="290.99" width="98.5152" height="69.1471"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="617.11" y="321.464">
-      <tspan x="617.11" y="321.464">postcar</tspan>
-      <tspan x="617.11" y="337.464">(x86 only)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="667.529" y="281.527" width="168.747" height="37"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.529" y="281.527" width="168.747" height="37"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.903" y="303.927">
-      <tspan x="751.903" y="303.927">ramstage</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="667.84" y="321.487" width="167.519" height="53"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.84" y="321.487" width="167.519" height="53"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="751.6" y="343.887">
-      <tspan x="751.6" y="343.887">SMM</tspan>
-      <tspan x="751.6" y="359.887">(x86 only)</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #90c9ff" x="941.841" y="283.151" width="171.98" height="69.1471"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="941.841" y="283.151" width="171.98" height="69.1471"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="1027.83" y="321.624">
-      <tspan x="1027.83" y="321.624">payload</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #d8e5e5" x="253.112" y="209.178" width="82.7" height="27"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="253.112" y="209.178" width="82.7" height="27"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="294.462" y="226.578">
-      <tspan x="294.462" y="226.578">Assembly</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #00c800" x="318.155" y="129.267" width="283.43" height="27"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="318.155" y="129.267" width="283.43" height="27"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="459.87" y="146.667">
-      <tspan x="459.87" y="146.667">Cache-As-RAM</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #ff8484" x="506.676" y="159.67" width="599.421" height="27"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="506.676" y="159.67" width="599.421" height="27"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="806.387" y="177.07">
-      <tspan x="806.387" y="177.07">DRAM</tspan>
-    </text>
-  </g>
-  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.046" y1="392.926" x2="1113.82" y2="391.893"/>
-  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="387.045" y="241.637">
-    <tspan x="387.045" y="241.637"></tspan>
-  </text>
-  <g>
-    <rect style="fill: #ffffff" x="337.438" y="209.383" width="618.831" height="27"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="337.438" y="209.383" width="618.831" height="27"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="646.853" y="226.783">
-      <tspan x="646.853" y="226.783">C</tspan>
-    </text>
-  </g>
-  <g>
-    <rect style="fill: #f6c7c7" x="667.35" y="238.912" width="170.3" height="27"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="667.35" y="238.912" width="170.3" height="27"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="752.5" y="256.312">
-      <tspan x="752.5" y="256.312">ADA SPARK (x86 only)</tspan>
-    </text>
-  </g>
-  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="84.2481" y="233.28">
-    <tspan x="84.2481" y="233.28">coreboot</tspan>
-    <tspan x="84.2481" y="254.446">source languages</tspan>
-  </text>
-  <text font-size="16.9333" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="86.5008" y="153.786">
-    <tspan x="86.5008" y="153.786">code/heap</tspan>
-    <tspan x="86.5008" y="174.953">memory location </tspan>
-  </text>
-  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="175.483" y1="273.35" x2="1109.07" y2="273.582"/>
-  <line style="fill: none; fill-opacity:0; stroke-width: 1; stroke-dasharray: 4; stroke: #000000" x1="176.24" y1="192.463" x2="1109.66" y2="192.132"/>
-  <g>
-    <rect style="fill: #90c9ff" x="838.583" y="281.963" width="100.3" height="53"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" x="838.583" y="281.963" width="100.3" height="53"/>
-    <text font-size="12.8" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:700" x="888.733" y="304.363">
-      <tspan x="888.733" y="304.363">BL31</tspan>
-      <tspan x="888.733" y="320.363">(ARM only)</tspan>
-    </text>
-  </g>
-  <text font-size="12.7998" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="209.772" y="508.772">
-    <tspan x="209.772" y="508.772">Power on</tspan>
-  </text>
-  <g>
-    <rect style="fill: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #ffffff" x="941.939" y="210.26" width="22.4641" height="25.1384"/>
-  </g>
-  <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" d="M 955.029 209.941 C 967.678,210.1 946.349,230.772 955.598,237.021"/>
-</svg>

Documentation/getting_started/gerrit_guidelines.md

@@ -46,11 +46,11 @@ clarification, see the Developer's Certificate of Origin in the coreboot
 * Let non-trivial patches sit in a review state for at least 24 hours
 before submission. Remember that there are coreboot developers in timezones
 all over the world, and everyone should have a chance to contribute.
-Trivial patches would be things like whitespace changes or spelling fixes,
-in general those that don’t impact the final binary output. The
+Trivial patches would be things like whitespace changes or spelling fixes.
+In general, small changes that don’t impact the final binary output. The
 24-hour period would start at submission, and would be restarted at any
 update which significantly changes any part of the patch. Patches can be
-'Fast-tracked' and submitted in under 24 hours with the agreement of at
+'Fast-tracked' and submitted in under this 24 hour with the agreement of at
 least 3 +2 votes.
 
 * Do not +2 patches that you authored or own, even for something as trivial

Documentation/getting_started/gpio.md

@@ -1,136 +0,0 @@
-# Configuring a mainboard's GPIOs in coreboot
-
-## Introduction
-
-Every mainboard needs to appropriately configure its General Purpose Inputs /
-Outputs (GPIOs). There are many facets of this issue, including which boot
-stage a GPIO might need to be configured.
-
-## Boot stages
-
-Typically, coreboot does most of its non-memory related initialization work in
-ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs
-are configured in this stage. However, some boards might need a few GPIOs
-configured before that; think of memory strapping pins which indicate what kind
-of DRAM is installed. These pins might need to be read before initializing the
-memory, so these GPIOs are then typically configured in bootblock or romstage.
-
-## Configuration
-
-Most mainboards will have a ``gpio.c`` file in their mainboard directory. This
-file typically contains tables which describe the configuration of the GPIO
-registers. Since these registers could be different on a per-SoC or per
-SoC-family basis, you may need to consult the datasheet for your SoC to find out
-how to appropriately set these registers. In addition, some mainboards are
-based on a baseboard/variant model, where several variant mainboards may share a
-lot of their circuitry and ICs and the commonality between the boards is
-collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared
-between multiple boards are placed in the baseboard's ``gpio.c`` file, while the
-ones that are board-specific go into each variant's ``gpio.c`` file.
-
-## Intel SoCs
-
-Many newer Intel SoCs share a common IP block for GPIOs, and that commonality
-has been taken advantage of in coreboot, which has a large set of macros that
-can be used to describe the configuration of each GPIO pad. This file lives in
-``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``.
-
-### Older Intel SoCs
-
-Baytrail and Braswell, for example, simply expect the mainboard to supply a
-callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio`
-objects, defining the configuration of each pin.
-
-### AMD SoCs
-
-Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the
-register values configuring each pin, similar to Intel.
-
-### Register details
-
-GPIO configuration registers typically control properties such as:
-1. Input / Output
-2. Pullups / Pulldowns
-3. Termination
-4. Tx / Rx Disable
-5. Which reset signal to use
-6. Native Function / IO
-7. Interrupts
-    * IRQ routing (e.g. on x86, APIC, SCI, SMI)
-    * Edge or Level Triggered
-    * Active High or Active Low
-8. Debouncing
-
-## Configuring GPIOs for pre-ramstage
-
-coreboot provides for several SoC-specific and mainboard-specific callbacks at
-specific points in time, such as bootblock-early, bootblock, romstage entry,
-pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are
-configured in either bootblock or romstage, depending on when they are needed,
-are denoted the "early" GPIOs. Some mainboard will use
-``bootblock_mainboard_init()`` to configure their early GPIOs, and this is
-probably a good place to start. Many mainboards will declare their GPIO
-configuration as structs, i.e. (Intel),
-
-```C
-struct pad_config {
-    /* offset of pad within community */
-        int             pad;
-    /* Pad config data corresponding to DW0, DW1,.... */
-        uint32_t        pad_config[GPIO_NUM_PAD_CFG_REGS];
-};
-```
-
-and will usually place these in an array, one for each pad to be configured.
-Mainboards using Intel SoCs can use a library which combines common
-configurations together into a set of macros, e.g.,
-
-```C
-    /* Native function configuration */
-    #define PAD_CFG_NF(pad, pull, rst, func)
-    /*
-     * Set native function with RX Level/Edge configuration and disable
-     * input/output buffer if necessary
-     */
-    #define PAD_CFG_NF_BUF_TRIG(pad, pull, rst, func, bufdis, trig)
-    /* General purpose output, no pullup/down. */
-    #define PAD_CFG_GPO(pad, val, rst)
-    /* General purpose output, with termination specified */
-    #define PAD_CFG_TERM_GPO(pad, val, pull, rst)
-    /* General purpose output, no pullup/down. */
-    #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull)
-    /* General purpose input */
-    #define PAD_CFG_GPI(pad, pull, rst)
-```
-etc.
-
-## Configuring GPIOs for ramstage and beyond...
-
-In ramstage, most mainboards will configure the rest of their GPIOs for the
-function they will be performing while the device is active. The goal is the
-same as above in bootblock; another ``static const`` array is created, and the
-rest of the GPIO registers are programmed.
-
-In the baseboard/variant model described above, the baseboard will provide the
-configuration for the GPIOs which are configured identically between variants,
-and will provide a mechanism for a variant to override the baseboard's
-configuration. This is usually done via two tables: the baseboard table and the
-variant's override table.
-
-This configuration is often hooked into the mainboard's `enable_dev` callback,
-defined in its `struct chip_operations`.
-
-## Potential issues (gotchas!)
-
-There are a couple of configurations that you need to especially careful about,
-as they can have a large impact on your mainboard.
-
-The first is configuring a pin as an output, when it was designed to be an
-input. There is a real risk in this case of short-circuiting a component which
-could cause catastrophic failures, up to and including your mainboard!
-
-The other configuration option to watch out for deals with unconnected GPIOs.
-If no pullup or pulldown is declared with these, they may end up "floating",
-i.e., not at logical high or logical low. This can cause problems such as
-unwanted power consumption or not reading the pin correctly, if it was intended
-to be strapped.

Documentation/getting_started/index.md

@@ -1,10 +1,8 @@
 # Getting Started
 
-* [coreboot architecture](architecture.md)
 * [Build System](build_system.md)
 * [Submodules](submodules.md)
 * [Kconfig](kconfig.md)
 * [Gerrit Guidelines](gerrit_guidelines.md)
 * [Documentation License](license.md)
 * [Writing Documentation](writing_documentation.md)
-* [Setting up GPIOs](gpio.md)

Documentation/getting_started/kconfig.md

@@ -73,6 +73,9 @@ These variables are typically set in the makefiles or on the make command line.
 These variables were added to Kconfig specifically for coreboot and are not
 included in the Linux version.
 
+- COREBOOT_BUILD_DIR=path for temporary files.   This is used by coreboot’s
+  abuild tool.
+
 - KCONFIG_STRICT=value. Define to enable warnings as errors.   This is enabled
   in coreboot, and should not be changed.
 
@@ -1129,7 +1132,7 @@ the symbol is only inside of an if/endif block where the if expression evaluates
 as false, the symbol STILL gets defined in the config.h file (though not in the
 .config file).
 
-Use \#if CONFIG(SYMBOL) to be sure (it returns false for undefined symbols
+Use \#if IS_ENABLED(CONFIG_*) to be sure (it returns false for undefined symbols
 and defined-to-0 symbols alike).
 
 
@@ -1162,6 +1165,8 @@ saved .config file. As always, a 'select' statement overrides any specified
 - coreboot has added the glob operator '*' for the 'source' keyword.
 - coreboot’s Kconfig always defines variables except for strings. In other
   Kconfig implementations, bools set to false/0/no are not defined.
+- IS_ENABLED() is ‘false’ for undefined variables and ‘0’ variables. In Linux
+  (where the macro comes from) it’s ‘true’ as soon as the variable is defined.
 - coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to
   error out if there are any issues in the Kconfig files.  In the Linux kernel,
   Kconfig will generate a warning, but will still output an updated .config or

Documentation/getting_started/writing_documentation.md

@@ -14,57 +14,18 @@ coreboot uses [Sphinx] documentation tool. We prefer the markdown format
 over reStructuredText so only embedded ReST is supported. Checkout the
 [Markdown Guide] for more information.
 
-### option 1: Use the docker image
-
-The easiest way to build the documentation is using a docker image.
-To build the image run the following in the base directory:
-
-	make -C util/docker/ doc.coreboot.org
-
-Before building the documentation make sure the output directory is given
-the correct permissions before running docker.
-
-	mkdir -p Documentation/_build
-
-To build the documentation:
-
-	make -C util/docker docker-build-docs
-
-To have the documentation build and served over a web server live run:
-
-	make -C util/docker docker-livehtml-docs
-
-On the host machine, open a browser to the address <http://0.0.0.0:8000>.
-
-### option 2: Install Sphinx
+### Install Sphinx
 
 Please follow this official [guide] to install sphinx.
 You will also need python-recommonmark for sphinx to be able to handle
-markdown documentation.
+markdown documenation.
 
-Since some Linux distributions don't package every needed sphinx extension,
-the installation via pip in a venv is recommended. You'll need these python3
-modules:
-
-* sphinx
-* recommonmark
-* sphinx_rtd_theme
-* sphinxcontrib-ditaa
-
-The following combination of versions has been tested: sphinx 2.3.1,
-recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7.
-
-Now change into the `Documentation` folder in the coreboot directory and run
-this command in there
-
-	make sphinx
-
-If no error occurs, you can find the generated HTML documentation in
-`Documentation/_build` now.
+The recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
+recommonmark 0.4.0.
 
 ### Optional
 
-Install [sphinx-autobuild] for rebuilding markdown/rst sources on the fly!
+Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly!
 
 ## Basic and simple rules
 
@@ -139,25 +100,11 @@ If you do only reference the document, but do not include it in any toctree,
 you'll see the following warning:
 **WARNING: document isn't included in any toctree**
 
-## CSV
-
-You can import CSV files and let sphinx automatically convert them to human
-readable tables, using the following reStructuredText snipped:
-
-    ```eval_rst
-    .. csv-table::
-       :header: "Key", "Value"
-       :file: keyvalues.csv
-    ```
-
-Of course this can only be done from a markdown file that is included in the
-TOC tree.
-
 [coreboot]: https://coreboot.org
 [Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
-[sphinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
+[shpinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
 [guide]: http://www.sphinx-doc.org/en/stable/install.html
 [Sphinx]: http://www.sphinx-doc.org/en/master/
 [Markdown Guide]: https://www.markdownguide.org/
-[Gerrit Guidelines]: gerrit_guidelines.md
+[Gerrit Guidelines]: https://doc.coreboot.org/gerrit_guidelines.html
 [review.coreboot.org]: https://review.coreboot.org

Documentation/gfx/display-panel.md

@@ -1,64 +0,0 @@
-Display Panel Specifics
-=======================
-
-Timing Parameters
------------------
-
-From the binary file `edid` in the sys filesystem on Linux, the panel can be
-identified. The exact path may differ slightly. Here is an example:
-
-```sh
-$ strings /sys/devices/pci0000:00/0000:00:02.0/drm/card0/card0-eDP-1/edid
-@0 5
-LG Display
-LP140WF3-SPD1
-```
-
-To figure out the timing parameters, refer to the [Intel Programmer's Reference
-Manuals](https://01.org/linuxgraphics/documentation/hardware-specification-prms)
-and try to find the datasheet of the panel using the information from `edid`.
-In the example above, you would search for `LP140WF3-SPD1`. Find a table listing
-the power sequence timing parameters, which are usually named T[N] and also
-referenced in Intel's respective registers listing. You need the values for
-`PP_ON_DELAYS`, `PP_OFF_DELAYS` and `PP_DIVISOR` for your `devicetree.cb`:
-
-```eval_rst
-+-----------------------------+---------------------------------------+-----+
-| Intel docs                  | devicetree.cb                         | eDP |
-+-----------------------------+---------------------------------------+-----+
-| Power up delay              | `gpu_panel_power_up_delay`            | T3  |
-+-----------------------------+---------------------------------------+-----+
-| Power on to backlight on    | `gpu_panel_power_backlight_on_delay`  | T7  |
-+-----------------------------+---------------------------------------+-----+
-| Power Down delay            | `gpu_panel_power_down_delay`          | T10 |
-+-----------------------------+---------------------------------------+-----+
-| Backlight off to power down | `gpu_panel_power_backlight_off_delay` | T9  |
-+-----------------------------+---------------------------------------+-----+
-| Power Cycle Delay           | `gpu_panel_power_cycle_delay`         | T12 |
-+-----------------------------+---------------------------------------+-----+
-```
-
-Intel GPU Tools and VBT
------------------------
-
-The Intel GPU tools are in a package called either `intel-gpu-tools` or
-`igt-gpu-tools` in most distributions of Linux-based operating systems.
-In the coreboot `util/` directory, you can find `intelvbttool`.
-
-From a running system, you can dump the register values directly:
-```sh
-$ intel_reg dump --all | grep PCH_PP
-                      PCH_PP_STATUS (0x000c7200): 0x80000008
-                     PCH_PP_CONTROL (0x000c7204): 0x00000007
-                   PCH_PP_ON_DELAYS (0x000c7208): 0x07d00001
-                  PCH_PP_OFF_DELAYS (0x000c720c): 0x01f40001
-                     PCH_PP_DIVISOR (0x000c7210): 0x0004af06
-```
-
-You can obtain the timing values from a VBT (Video BIOS Table), which you can
-dump from a vendor UEFI image:
-```sh
-$ intel_vbt_decode data.vbt | grep T3
-                Power Sequence: T3 2000 T7 10 T9 2000 T10 500 T12 5000
-                T3 optimization: no
-```

Documentation/gfx/libgfxinit.md

@@ -7,14 +7,13 @@ Introduction and Current State in coreboot
 *libgfxinit* is a library of full-featured graphics initialization
 (aka. modesetting) drivers. It's implemented in SPARK (a subset of
 Ada with formal verification features). While not restricted to in
-any way, it currently only supports Intel's integrated graphics
-controllers (GMA).
+any way, it currently only supports Intel's integrated gfx control-
+lers (GMA).
 
-Currently, it supports the Intel Core i3/i5/i7 processor line, HDMI
-and DP on the Apollo Lake processors and everything but SDVO on G45
-and GM45 chipsets. At the time of writing, G45, GM45, everything
-from Arrandale to Coffee Lake, and Apollo Lake are verified to work
-within *coreboot*.
+Currently, it supports the Intel Core i3/i5/i7 processor line and
+will support HDMI and DP on the Atom successor Apollo Lake. At the
+time of writing, Sandy Bridge, Ivy Bridge, and Haswell are veri-
+fied to work within *coreboot*.
 
 GMA: Framebuffer Configuration
 ------------------------------
@@ -49,36 +48,24 @@ follows:
 
 * `lightup_ok`: returns whether the initialization succeeded `1` or
                 failed `0`. Currently, only the case that no display
-                could be found counts as failure. A failure at a
-                later stage (e.g. failure to train a DP) is not
-                propagated.
+                could be found counts as failure. A failure at a la-
+                ter stage (e.g. failure to train a DP) is not propa-
+                gated.
 
 GMA: Per Board Configuration
 ----------------------------
 
-In order to set up the display panel, see the
-[display panel-specific documentation](/gfx/display-panel.md).
-
 There are a few Kconfig symbols to consider. To indicate that a
 board can initialize graphics through *libgfxinit*:
 
     select MAINBOARD_HAS_LIBGFXINIT
 
 Internal ports share some hardware blocks (e.g. backlight, panel
-power sequencer). Therefore, each system with an integrated panel
-should set `GFX_GMA_PANEL_1_PORT` to the respective port, e.g.:
+power sequencer). Therefore, each board has to select either eDP
+or LVDS as the internal port, if any:
 
-    config GFX_GMA_PANEL_1_PORT
-            default "DP3"
-
-For the most common cases, LVDS and eDP, exists a shorthand, one
-can select either:
-
-    select GFX_GMA_PANEL_1_ON_EDP	# the default, or
-    select GFX_GMA_PANEL_1_ON_LVDS
-
-Some newer chips feature a second block of panel control logic.
-For this, `GFX_GMA_PANEL_2_PORT` can be set.
+    select GFX_GMA_INTERNAL_IS_EDP	# the default, or
+    select GFX_GMA_INTERNAL_IS_LVDS
 
 Boards with a DVI-I connector share the DDC (I2C) pins for both
 analog and digital displays. In this case, *libgfxinit* needs to
@@ -105,8 +92,7 @@ You can select from the following Ports:
 
     type Port_Type is
       (Disabled,	-- optionally terminates the list
-       LVDS,
-       eDP,
+       Internal,	-- either eDP or LVDS as selected in Kconfig
        DP1,
        DP2,
        DP3,
@@ -122,7 +108,8 @@ both DPx and HDMIx should be listed.
 
 A good example is the mainboard Kontron/KTQM77, it features two
 DP++ ports (DP2/HDMI2, DP3/HDMI3), one DVI-I port (HDMI1/Analog),
-eDP and LVDS. It defines `ports` as follows:
+eDP and LVDS. Due to the constraints mentioned above, only one of
+eDP and LVDS can be enabled. It defines `ports` as follows:
 
     ports : constant Port_List :=
       (DP2,
@@ -131,8 +118,7 @@ eDP and LVDS. It defines `ports` as follows:
        HDMI2,
        HDMI3,
        Analog,
-       LVDS,
-       eDP,
+       Internal,
        others => Disabled);
 
 The `GMA.gfxinit()` procedure probes for display EDIDs in the

Documentation/ifdtool/index.md

@@ -1,6 +0,0 @@
-# ifdtool
-
-Contents:
-
-* [Intel IFD Binary Extraction](binary_extraction.md)
-* [IFD Layout](layout.md)

Documentation/ifdtool/layout.md

@@ -1,78 +0,0 @@
-# IFD Layout
-
-A coreboot image for an Intel SoC contains two separate definitions of the
-layout of the flash. The Intel Flash Descriptor (IFD) which defines offsets and
-sizes of various regions of flash and the [coreboot FMAP](../lib/flashmap.md).
-
-The FMAP should define all of the of the regions defined by the IFD to ensure
-that those regions are accounted for by coreboot and will not be accidentally
-modified.
-
-## IFD mapping
-
-The names of the IFD regions in the FMAP should follow the convention of
-starting with the prefix `SI_` which stands for `silicon initialization` as a
-way to categorize anything required by the SoC but not provided by coreboot.
-
-```eval_rst
-+------------+------------------+-----------+-------------------------------------------+
-| IFD Region | IFD Region name  | FMAP Name | Notes                                     |
-| index      |                  |           |                                           |
-+============+==================+===========+===========================================+
-| 0          | Flash Descriptor | SI_DESC   | Always the top 4KB of flash               |
-+------------+------------------+-----------+-------------------------------------------+
-| 1          | BIOS             | SI_BIOS   | This is the region that contains coreboot |
-+------------+------------------+-----------+-------------------------------------------+
-| 2          | Intel ME         | SI_ME     |                                           |
-+------------+------------------+-----------+-------------------------------------------+
-| 3          | Gigabit Ethernet | SI_GBE    |                                           |
-+------------+------------------+-----------+-------------------------------------------+
-| 4          | Platform Data    | SI_PDR    |                                           |
-+------------+------------------+-----------+-------------------------------------------+
-| 8          | EC Firmware      | SI_EC     | Most Chrome OS devices do not use this    |
-|            |                  |           | region; EC firmware is stored in BIOS     |
-|            |                  |           | region of flash                           |
-+------------+------------------+-----------+-------------------------------------------+
-```
-
-## Validation
-
-The ifdtool can be used to manipulate a firmware image with a IFD. This tool
-will not take into account the FMAP while modifying the image which can lead to
-unexpected and hard to debug issues with the firmware image. For example if the
-ME region is defined at 6 MB in the IFD but the FMAP only allocates 4 MB for the
-ME, then when the ME is added by the ifdtool 6 MB will be written which could
-overwrite 2 MB of the BIOS.
-
-In order to validate that the FMAP and the IFD are compatible the ifdtool
-provides --validate (-t) option. `ifdtool -t` will read both the IFD and the
-FMAP in the image and for every non empty region in the IFD if that region is
-defined in the FMAP but the offset or size is different then the tool will
-return an error.
-
-Example:
-
-```console
-foo@bar:~$ ifdtool -t bad_image.bin
-Region mismatch between bios and SI_BIOS
- Descriptor region bios:
-  offset: 0x00400000
-  length: 0x01c00000
- FMAP area SI_BIOS:
-  offset: 0x00800000
-  length: 0x01800000
-Region mismatch between me and SI_ME
- Descriptor region me:
-  offset: 0x00103000
-  length: 0x002f9000
- FMAP area SI_ME:
-  offset: 0x00103000
-  length: 0x006f9000
-Region mismatch between pd and SI_PDR
- Descriptor region pd:
-  offset: 0x003fc000
-  length: 0x00004000
- FMAP area SI_PDR:
-  offset: 0x007fc000
-  length: 0x00004000
-```

Documentation/index.md

@@ -161,30 +161,28 @@ for example OpenBSD, is probably the closest cousin of our approach.
 Contents:
 
 * [Getting Started](getting_started/index.md)
-* [Tutorial](tutorial/index.md)
+* [Rookie Guide](lessons/index.md)
 * [Coding Style](coding_style.md)
 * [Project Ideas](contributing/project_ideas.md)
-* [Documentation Ideas](contributing/documentation_ideas.md)
 * [Code of Conduct](community/code_of_conduct.md)
 * [Community forums](community/forums.md)
-* [Project services](community/services.md)
 * [coreboot at conferences](community/conferences.md)
+* [Security](security.md)
 * [Payloads](payloads.md)
 * [Distributions](distributions.md)
-* [Technotes](technotes/index.md)
-* [ACPI](acpi/index.md)
+* [Timestamps](timestamp.md)
+* [Intel IFD Binary Extraction](Binary_Extraction.md)
+* [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
+* [ABI data consumption](abi-data-consumption.md)
+* [GPIO toggling in ACPI AML](acpi/gpio.md)
 * [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)
-* [Display panel](gfx/display-panel.md)
-* [CPU Architecture](arch/index.md)
-* [Platform independent drivers](drivers/index.md)
-* [Northbridge](northbridge/index.md)
-* [System on Chip](soc/index.md)
-* [Mainboard](mainboard/index.md)
-* [Payloads](lib/payloads/index.md)
-* [Libraries](lib/index.md)
-* [Security](security/index.md)
-* [SuperIO](superio/index.md)
-* [Vendorcode](vendorcode/index.md)
+* [Architecture-specific documentation](arch/index.md)
+* [Northbridge-specific documentation](northbridge/index.md)
+* [System on Chip-specific documentation](soc/index.md)
+* [Mainboard-specific documentation](mainboard/index.md)
+* [Payload-specific documentation](lib/payloads/index.md)
+* [SuperIO-specific documentation](superio/index.md)
+* [Vendorcode-specific documentation](vendorcode/index.md)
 * [Utilities](util.md)
 * [Release notes for past releases](releases/index.md)
 * [Flashing firmware tutorial](flash_tutorial/index.md)

Documentation/lessons/index.md

@@ -0,0 +1,4 @@
+# Rookie Guide
+
+* [Lesson 1: Starting from scratch](lesson1.md)
+* [Lesson 2: Submitting a patch to coreboot.org](lesson2.md)

Documentation/lessons/lesson1.md

@@ -0,0 +1,169 @@
+coreboot lesson 1 - Starting from scratch
+=========================================
+
+From a fresh Ubuntu 16.04 or 18.04 install, here are all the steps required for
+a very basic build:
+
+Download, configure, and build coreboot
+---------------------------------------
+
+### Step 1 - Install tools and libraries needed for coreboot
+    $ sudo apt-get install -y bison build-essential curl flex git gnat libncurses5-dev m4 zlib1g-dev
+
+### Step 2 - Download coreboot source tree
+    $ git clone https://review.coreboot.org/coreboot
+    $ cd coreboot
+
+### Step 3 - Build the coreboot toolchain
+Please note that this can take a significant amount of time
+
+    $ make crossgcc-i386 CPUS=$(nproc)
+
+Also note that you can possibly use your system toolchain, but the results are
+not reproducible, and may have issues, so this is not recommended.  See step 5
+to use your system toolchain.
+
+### Step 4 - Build the payload - coreinfo
+    $ make -C payloads/coreinfo olddefconfig
+    $ make -C payloads/coreinfo
+
+### Step 5 - Configure the build
+
+##### Configure your mainboard
+    $ make menuconfig
+       select 'Mainboard' menu
+       Beside 'Mainboard vendor' should be '(Emulation)'
+       Beside 'Mainboard model' should be 'QEMU x86 i440fx/piix4'
+       select < Exit >
+These should be the default selections, so if anything else was set, run
+`make distclean` to remove your old config file and start over.
+
+##### Optionally use your system toolchain (Again, not recommended)
+       select 'General Setup' menu
+       select 'Allow building with any toolchain'
+       select < Exit >
+
+##### Select the payload
+       select 'Payload' menu
+       select 'Add a Payload'
+       choose 'An Elf executable payload'
+       select 'Payload path and filename'
+       enter 'payloads/coreinfo/build/coreinfo.elf'
+       select < Exit >
+       select < Exit >
+       select < Yes >
+
+##### check your configuration (optional step):
+
+    $ make savedefconfig
+    $ cat defconfig
+
+There should only be two lines (or 3 if you're using the system toolchain):
+
+    CONFIG_PAYLOAD_ELF=y
+    CONFIG_PAYLOAD_FILE="payloads/coreinfo/build/coreinfo.elf"
+
+### Step 6 - build coreboot
+    $ make
+
+At the end of the build, you should see:
+
+    Build emulation/qemu-i440fx (QEMU x86 i440fx/piix4)
+
+This means your build was successful. The output from the build is in the build
+directory. build/coreboot.rom is the full rom file.
+
+Test the image using QEMU
+-------------------------
+
+### Step 7 - Install QEMU
+    $ sudo apt-get install -y qemu
+
+### Step 8 - Run QEMU
+Start QEMU, and point it to the ROM you just built:
+
+    $ qemu-system-x86_64 -bios build/coreboot.rom -serial stdio
+
+You should see the serial output of coreboot in the original console window, and
+a new window will appear running the coreinfo payload.
+
+Summary
+-------
+
+### Step 1 summary - Install tools and libraries needed for coreboot
+You installed the minimum additional requirements for ubuntu to download and
+build coreboot. Ubuntu already has most of the other tools that would be
+required installed by default.
+
+* `build-essential` is the basic tools for doing builds.  It comes pre-installed
+on some Ubuntu flavors, and not on others.
+* `git` is needed to download coreboot from the coreboot git repository.
+* `libncurses5-dev` is needed to build the menu for 'make menuconfig'
+* `m4, bison, curl, flex, zlib1g-dev, gcc, gnat` and `g++` or `clang`
+are needed to build the coreboot toolchain. `gcc` and `gnat` have to be
+of the same version.
+
+If you started with a different distribution, you might need to install many
+other items which vary by distribution.
+
+### Step 2 summary - Download coreboot source tree
+This will download a 'read-only' copy of the coreboot tree. This just means
+that if you made changes to the coreboot tree, you couldn't immediately
+contribute them back to the community. To pull a copy of coreboot that would
+allow you to contribute back, you would first need to sign up for an account on
+gerrit.
+
+### Step 3 summary - Build the coreboot toolchain.
+This builds one of the coreboot cross-compiler toolchains for X86 platforms.
+Because of the variability of compilers and the other required tools between
+the various operating systems that coreboot can be built on, coreboot supplies
+and uses its own cross-compiler toolchain to build the binaries that end up as
+part of the coreboot ROM. The toolchain provided by the operating system (the
+'host toolchain') is used to build various tools that will run on the local
+system during the build process.
+
+### Step 4 summary - Build the payload
+To actually do anything useful with coreboot, you need to build a payload to
+include in the rom. The idea behind coreboot is that it does the minimum amount
+possible before passing control of the machine to a payload. There are various
+payloads such as grub or SeaBIOS that are typically used to boot the operating
+system. Instead, we used coreinfo, a small demonstration payload that allows the
+user to look at various things such as memory and the contents of coreboot's
+cbfs - the pieces that make up the coreboot rom.
+
+### Step 5 summary - Configure the build
+This step configures coreboot's build options using the menuconfig interface to
+Kconfig. Kconfig is the same configuration program used by the linux kernel. It
+allows you to enable, disable, and change various values to control the coreboot
+build process, including which mainboard(motherboard) to use, which toolchain to
+use, and how the runtime debug console should be presented and saved.
+Anytime you change mainboards in Kconfig, you should always run `make distclean`
+before running `make menuconfig`. Due to the way that Kconfig works, values will
+be kept from the previous mainboard if you skip the clean step. This leads to a
+hybrid configuration which may or may not work as expected.
+
+### Step 6 summary - Build coreboot
+You may notice that a number of other pieces are downloaded at the beginning of
+the build process. These are the git submodules used in various coreboot builds.
+By default, the _blobs_ submodule is not downloaded. This git submodule may be
+required for other builds for microcode or other binaries. To enable downloading
+this submodule, select the option "Allow use of binary-only repository" in the
+"General Setup" menu of Kconfig
+This attempts to build the coreboot rom. The rom file itself ends up in the
+build directory as 'coreboot.rom'. At the end of the build process, the build
+displayed the contents of the rom file.
+
+### Step 7 summary - Install QEMU
+QEMU is a processor emulator which we can use to show coreboot
+
+### Step 8 summary - Run QEMU
+Here's the command line broken down:
+* `qemu-system-x86_64`
+This starts the QEMU emulator with the i440FX host PCI bridge and PIIX3 PCI to
+ISA bridge.
+* `-bios build/coreboot.rom`
+Use the bios rom image that we just built. If this is left off, the standard
+SeaBIOS image that comes with QEMU is used.
+* `-serial stdio`
+Send the serial output to the console. This allows you to view the coreboot
+debug output.

Documentation/lessons/lesson2.md

@@ -0,0 +1,291 @@
+# coreboot Lesson 2: Submitting a patch to coreboot.org
+
+## Part 1: Setting up an account at coreboot.org
+
+If you already have an account, skip to Part 2.
+
+Otherwise, go to <https://review.coreboot.org> in your preferred web browser.
+Select **Register** in the upper right corner.
+
+Select the appropriate sign-in. For example, if you have a Google account,
+select **Google OAuth2** (gerrit-oauth-provider plugin)".**Note:** Your
+username for the account will be the username of the account you used to
+sign-in with. (ex. your Google username).
+
+## Part 2a: Set up RSA Private/Public Key
+
+If you prefer to use an HTTP password instead, skip to Part 2b.
+
+For the most up-to-date instructions on how to set up SSH keys with Gerrit go to
+<https://gerrit-documentation.storage.googleapis.com/Documentation/2.14.2/user-upload.html#configure_ssh)>
+and follow the instructions there. Then, skip to Part 3.
+
+Additionally, that section of the Web site provides explanation on starting
+an ssh-agent, which may be particularly helpful for those who anticipate
+frequently uploading changes.
+
+If you instead prefer to have review.coreboot.org specific instructions,
+follow the steps below. Note that this particular section may have the
+most up-to-date instructions.
+
+If you do not have an RSA key set up on your account already (as is the case
+with a newly created account), follow the instructions below; otherwise,
+doing so could overwrite an existing key.
+
+In the upper right corner, select your name and click on **Settings**.
+Select **SSH Public Keys** on the left-hand side.
+
+In a terminal, run "ssh-keygen" and confirm the default path ".ssh/id_rsa".
+
+Make a passphrase -- remember this phrase. It will be needed whenever you use
+this RSA Public Key. **Note:** You might want to use a short password, or
+forego the password altogether as you will be using it very often.
+
+Open "id_rsa.pub", copy all contents and paste into the textbox under
+"Add SSH Public Key" in the https://review.coreboot.org webpage.
+
+## Part 2b: Setting up an HTTP Password
+
+Alternatively, instead of using SSH keys, you can use an HTTP password. To do so,
+after you select your name and click on **Settings** on the left-hand side, rather
+than selecting **SSH Public Keys**, select **HTTP Password**.
+
+Click **Generate Password**. This should fill the "Password" box with a password. Copy
+the password, and add the following to your $HOME/.netrc file:
+
+	machine review.coreboot.org login YourUserNameHere password YourPasswordHere
+
+where YourUserNameHere is your username, and YourPasswordHere is the password you
+just generated.
+
+## Part 3: Clone coreboot and configure it for submitting patches
+
+On Gerrit, click on the **Browse** tab in the upper left corner and select
+**Repositories**.  From the listing, select the "coreboot" repo.  You may have
+to click the next page arrow at the bottom a few times to find it.
+
+If you are using SSH keys, select **ssh** from the tabs under "Project
+coreboot" and run the "clone with commit-msg hook" command that's provided.
+This should prompt you for your id_rsa passphrase, if you previously set one.
+
+If you are using HTTP, instead, select **http** from the tabs under "Project coreboot"
+and run the command that appears
+
+Now is a good time to configure your global git identity, if you haven't
+already.
+
+	git config --global user.name "Your Name"
+	git config --global user.email "Your Email"
+
+Finally, enter the local git repository and set up repository specific hooks
+and other configurations.
+
+	cd coreboot
+	make gitconfig
+
+## Part 4: Submit a commit
+
+An easy first commit to make is fixing existing checkpatch errors and warnings
+in the source files. To see errors that are already present, build the files in
+the repository by running 'make lint' in the coreboot directory. Alternatively,
+if you want to run 'make lint' on a specific directory, run:
+
+	for file in $(git ls-files | grep src/amd/quadcore); do \
+	util/lint/checkpatch.pl --file $file --terse; done
+
+where <filepath> is the filepath of the directory (ex. src/cpu/amd/car).
+
+Any changes made to files under the src directory are made locally,
+and can be submitted for review.
+
+Once you finish making your desired changes, use the command line to stage
+and submit your changes. An alternative and potentially easier way to stage
+and submit commits is to use git cola, a graphical user interface for git. For
+instructions on how to do so, skip to Part 4b.
+
+## Part 4a: Using the command line to stage and submit a commit
+
+To use the command line to stage a commit, run
+
+	git add <filename>
+
+where `filename` is the name of your file.
+
+To commit the change, run
+
+	git commit -s
+
+**Note:** The -s adds a signed-off-by line by the committer. Your commit should be
+signed off with your name and email (i.e. **Your Name** **<Your Email>**, based on
+what you set with git config earlier).
+
+Running git commit first checks for any errors and warnings using lint. If
+there are any, you must go back and fix them before submitting your commit.
+You can do so by making the necessary changes, and then staging your commit again.
+
+When there are no errors or warnings, your default text editor will open.
+This is where you will write your commit message.
+
+The first line of your commit message is your commit summary. This is a brief
+one-line description of what you changed in the files using the template
+below:
+
+<filepath>: Short description
+*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
+**Note:** It is good practice to use present tense in your descriptions
+and do not punctuate your summary.
+
+Then hit Enter. The next paragraph should be a more in-depth explanation of the
+changes you've made to the files. Again, it is good practice to use present
+tense.
+*ex.  Fix space prohibited between function name and open parenthesis,
+line over 80 characters, unnecessary braces for single statement blocks,
+space required before open brace errors and warnings.*
+
+When you have finished writing your commit message, save and exit the text
+editor. You have finished committing your change. If, after submitting your
+commit, you wish to make changes to it, running "git commit --amend" allows
+you to take back your commit and amend it.
+
+When you are done with your commit, run 'git push' to push your commit to
+coreboot.org. **Note:** To submit as a draft, use
+'git push origin HEAD:refs/drafts/master' Submitting as a draft means that
+your commit will be on coreboot.org, but is only visible to those you add
+as reviewers.
+
+This has been a quick primer on how to submit a change to Gerrit for review
+using git.  You may wish to review the [Gerrit code review workflow
+documentation](https://gerrit-review.googlesource.com/Documentation/intro-user.html#code-review),
+especially if you plan to work on multiple changes at the same time.
+
+## Part 4b: Using git cola to stage and submit a commit
+
+If git cola is not installed on your machine, see
+https://git-cola.github.io/downloads.html for download instructions.
+
+After making some edits to src files, rather than run "git add," run
+'git cola' from the command line. You should see all of the files
+edited under "Modified".
+
+In the textbox labeled "Commit summary" provide a brief one-line
+description of what you changed in the files according to the template
+below:
+
+<filepath>: Short description
+*ex. cpu/amd/pi/00630F01: Fix checkpatch warnings and errors*
+**Note:** It is good practice to use present tense in your descriptions
+and do not punctuate your short description.
+
+In the larger text box labeled 'Extended description...' provide a more
+in-depth explanation of the changes you've made to the files. Again, it
+is good practice to use present tense.
+*ex.  Fix space prohibited between function name and open parenthesis,
+line over 80 characters, unnecessary braces for single statement blocks,
+space required before open brace errors and warnings.*
+
+Then press Enter two times to move the cursor to below your description.
+To the left of the text boxes, there is an icon with an downward arrow.
+Press the arrow and select "Sign Off." Make sure that you are signing off
+with your name and email (i.e. **Your Name** **<Your Email>**, based on what
+you set with git config earlier).
+
+Now, review each of your changes and mark either individual changes or
+an entire file as Ready to Commit by marking it as 'Staged'. To do
+this, select one file from the 'Modified' list. If you only want to
+submit particular changes from each file, then highlight the red and
+green lines for your changes, right click and select 'Stage Selected
+Lines'. Alternatively, if an entire file is ready to be committed, just
+double click on the file under 'Modified' and it will be marked as
+Staged.
+
+Once the descriptions are done and all the edits you would like to
+commit have been staged, press 'Commit' on the right of the text
+boxes.
+
+If the commit fails due to persisting errors, a text box will appear
+showing the errors. You can correct these errors within 'git cola' by
+right-clicking on the file in which the error occurred and selecting
+'Launch Diff Tool'. Make necessary corrections, close the Diff Tool and
+'Stage' the corrected file again. It might be necessary to refresh
+'git cola' in order for the file to be shown under 'Modified' again.
+Note: Be sure to add any other changes that haven't already been
+explained in the extended description.
+
+When ready, select 'Commit' again. Once all errors have been satisfied
+and the commit succeeds, move to the command line and run 'git push'.
+**Note:** To submit as a draft, use 'git push origin HEAD:refs/drafts/master'
+Submitting as a draft means that your commit will be on coreboot.org, but is
+only visible to those you add as reviewers.
+
+## Part 5: Getting your commit reviewed
+
+Your commits can now be seen on review.coreboot.org if you select “Your”
+and click on “Changes” and can be reviewed by others. Your code will
+first be reviewed by build bot (Jenkins), which will either give you a warning
+or verify a successful build; if so, your commit will receive a +1. Other
+users may also give your commit +1.  For a commit to be merged, it needs
+to receive a +2.**Note:** A +1 and a +1 does not make a +2. Only certain users
+can give a +2.
+
+## Part 6 (optional): bash-git-prompt
+
+To help make it easier to understand the state of the git repository
+without running 'git status' or 'git log', there is a way to make the
+command line show the status of the repository at every point. This
+is through bash-git-prompt.
+
+Instructions for installing this are found at:
+https://github.com/magicmonty/bash-git-prompt
+**Note:** Feel free to search for different versions of git prompt,
+as this one is specific to bash.
+
+Alternatively, follow the instructions below:
+Run the following two commands in the command line:
+
+    cd
+    git clone https://github.com/magicmonty/bash-git-prompt.git .bash-git-prompt --depth=1
+
+**Note:** cd will change your directory to your home directory, so the
+git clone command will be run there.
+
+Finally, open the ~/.bashrc file and append the following two lines:
+
+    GIT_PROMPT_ONLY_IN_REPO=1
+    source ~/.bash-git-prompt/gitprompt.sh
+
+Now, whenever you are in a git repository, it will continuously display
+its state.
+
+There also are additional configurations that you can change depending on your
+preferences. If you wish to do so, look at the "All configs for .bashrc" section
+on https://github.com/magicmonty/bash-git-prompt. Listed in that section are
+various lines that you can copy, uncomment and add to your .bashrc file to
+change the configurations. Example configurations include avoid fetching remote
+status, and supporting versions of Git older than 1.7.10.
+
+## Appendix: Miscellaneous Advice
+
+### Updating a commit after running git push:
+
+Suppose you would like to update a commit that has already been pushed to the
+remote repository. If the commit you wish to update is the most recent
+commit you have made, after making your desired changes, stage the files
+(either using git add or in git cola), and amend the commit. To do so,
+if you are using the command line, run "git commit --amend." If you are
+using git cola, click on the gear icon located on the upper left side under
+**Commit** and select **Amend Last Commit** in the drop down menu. Then, stage
+the files you have changed, commit the changes, and run git push to push the
+changes to the remote repository. Your change should be reflected in Gerrit as
+a new patch set.
+
+If, however, the commit you wish to update is not the most recent commit you
+have made, you will first need to checkout that commit. To do so, find the
+URL of the commit on <https://review.coreboot.org> and go to that page; if
+the commit is one that you previously pushed, it can be found by selecting
+**My** and then **Changes** in the upper left corner. To checkout this commit,
+in the upper right corner, click on **Download**, and copy the command listed
+next to checkout by clicking **Copy to clipboard**. Then, run the copied
+command in your coreboot repository. Now, the last commit should be the most
+recent commit to that patch; to update it, make your desired changes, stage
+the files, then amend and push the commit using the instructions in the above
+paragraph.

Documentation/lib/flashmap.md

@@ -1,153 +0,0 @@
-# Flashmap and Flashmap Descriptor in coreboot
-
-## Flashmap
-
-[Flashmap](https://code.google.com/p/flashmap) (FMAP) is a binary format to
-describe partitions in a flash chip. It was added to coreboot to support the
-requirements of Chromium OS firmware but then was also used in other scenarios
-where precise placement of data in flash was necessary, or for data that is
-written to at runtime, as CBFS is considered too fragile for such situations.
-The Flashmap implementation inside coreboot is the de facto standard today.
-
-Flashmap partitions the image into clearly delimited sections and some of those
-sections may be CBFSes that can hold arbitrary-length files (at least one, the
-default CBFS, called `COREBOOT`). General guidance is that everything with
-strict layout requirements (e.g. must be aligned to erase blocks or
-something else) should have its own Flashmap section, and everything else should
-normally go into CBFS.
-
-The Flashmap itself starts with a header `struct fmap` and followed by a list of
-section descriptions in `struct fmap_area`.
-
-### Header
-The header `struct fmap` has following fields:
-* `signature`: 8 characters as `"__FMAP__"`.
-* `ver_major`: one byte for major version (currently only 1).
-* `ver_minor`: one byte for minor version (current value is 1).
-* `base`: 64 bit integer for the address of the firmware binary.
-* `size`: 32 bit integer for the size of firmware binary in bytes.
-* `name`: 32 characters for the name of the firmware binary.
-* `nareas`: 16 bit integer for the number of area definitions (i.e., how many
-  sections are in this firmware image) following the header.
-
-### Area Definition
-The section is defined by `struct fmap_area` with following fields:
-* `offset`: 32 bit integer for where the area starts (relative to `base` in
-  header).
-* `size`: 32 bit integer for the size of area in bytes.
-* `name`: 32 characters for a descriptive name of this area. Should be unique to
-  all sections inside same Flashmap.
-* `flags`: 16 bit integer for attributes of this area (see below).
-
-### Area Flags
-Currently the defined values for `flags` in `struct fmap_area` are:
-* `FMAP_AREA_PRESERVE`: suggesting the section should be preserved when
-  updating firmware, usually for product data like serial number, MAC address,
-  or calibration and cache data.
-* `FMAP_AREA_STATIC`: Not really used today.
-* `FMAP_AREA_COMPRESSED`: Not really used today.
-* `FMAP_AREA_RO`: Not really used today.
-
-### FMAP section
-The whole Flashmap (`struct fmap` and list of `struct fmap_area`) should be
-stored in a standalone section named as `FMAP` (which should be also described
-by the Flashmap itself in `struct fmap_area`). There's no restriction for where
-it should be located (or how large), but usually we need to do a linear or
-binary search on whole firmware binary image to find Flashmap so a properly
-aligned address would be better.
-
-### COREBOOT section
-coreboot firmware images (`coreboot.rom`) should have at least one Flashmap
-section that is reserved for CBFS. Usually it is named as `COREBOOT`.
-
-## Flashmap Descriptor
-
-Since coreboot is starting to use a "partition" of Flashmap to describe the
-flash chip layout (both at runtime and when flashing a new image onto a
-chip), the project needs a reasonably expressive plain text format for
-representing such sections in the source tree.
-
-Flashmap Descriptor (FMD) is a [language and
-compiler](https://chromium-review.googlesource.com/#/c/255031) inside coreboot
-utility folder that can be used to generate final firmware images (i.e.
-`coreboot.rom`) formatted by Flashmap.
-
-The FMD implementation is in coreboot `utils/cbfstool` folder. Here's an
-informal language description:
-
-```
-# <line comment>
-<image name>[@<memory-mapped address>] <image size> {
-    <section name>[(flags)][@<offset from start of image>] [<section size>] [{
-        <subsection name>[@<offset from start of parent section>] [<subsection size>] [{
-            # Sections can be nested as deeply as desired
-            <subsubsection name>[(flags)][@...] [...] [{...}]
-        }]
-        [<subsection name>[(flags)][@...] [...] [{...}]]
-        # There can be many subsections at each level of nesting: they will be inserted
-        # sequentially, and although gaps are allowed, any provided offsets are always
-        # relative to the closest parent node's and must be strictly increasing with neither
-        # overlapping nor degenerate-size sections.
-    }]
-}
-```
-
-Note that the above example contains a few symbols that are actually meta
-syntax, and therefore have neither meaning nor place in a real file. The `<.*>`s
-indicate placeholders for parameters:
-
-* The names are strings, which are provided as single-word (no white space)
-  groups of syntactically unimportant symbols (i.e. every thing except `@`, `{`,
-  and `}`): they are not surrounded by quotes or any other form of delimiter.
-* The other fields are non-negative integers, which may be given as decimal or
-  hexadecimal; in either case, a `K`, `M`, or `G` may be appended (without
-  intermediate white space) as a multiplier.
-* Comments consist of anything one manages to enter, provided it doesn't start a
-  new line.
-
-The `[.*]`s indicate that a portion of the file could be omitted altogether:
-
-* Just because something is noted as optional doesn't mean it is in every case:
-  the answer might actually depend on which other information is---or
-  isn't---provided.
-* The "flag" specifies the attribute or type for given section. The most
-  important supported flag is "CBFS", which indicates the section will contain
-  a CBFS structure.
-* In particular, it is only legal to place a (CBFS) flag on a leaf section; that
-  is, choosing to add child sections excludes the possibility of putting a CBFS
-  in their parent. Such flags are only used to decide where CBFS empty file
-  headers should be created, and do not result in the storage of any additional
-  metadata in the resulting FMAP section.
-
-Additionally, it's important to note these properties of the overall file and
-its values:
-
-* Other than within would-be strings and numbers, white space is ignored. It
-  goes without saying that such power comes with responsibility, which is why
-  this sentence is here.
-* Although the `section name` must be globally unique, one of them may (but is
-  not required to) match the image name.
-* It is a syntax error to supply a number (besides 0) that begins with the
-  character `0`, as there is no intention of adding octals to the mix.
-* The image's memory address should be present on (and only on) layouts for
-  memory-mapped chips.
-* Although it may be evident from above, all `section` offsets are relative only
-  to the immediate parent. There is no way to include an absolute offset (i.e.
-  from the beginning of flash), which means that it is "safe" to reorder the
-  sections within a particular level of nesting, as long as the change doesn't
-  cause their positions and sizes to necessitate overlap or zero sizes.
-* A `section` with omitted offset is assumed to start at as low a position as
-  possible (with no consideration of alignment) and one with omitted size is
-  assumed to fill the remaining space until the next sibling or before the end
-  of its parent.
-* It's fine to omit any `section`'s offset, size, or both, provided its position
-  and size are still unambiguous in the context of its *sibling* sections and
-  its parent's *size*. In particular, knowledge of one .*section 's children or
-  the `section`s' common parent's siblings will not be used for this purpose.
-* Although `section`s are not required to have children, the flash chip as a
-  whole must have at least one.
-* Though the braces after `section`s may be omitted for those that have no
-  children, if they are present, they must contain at least one child.
-
-To see the formal description of the language, please refer to the Lex and Yacc
-files: `fmd_scanner.l` and `fmd_scanner.y`.

Documentation/lib/index.md

@@ -1,9 +0,0 @@
-# Library-specific documentation
-
-This section contains documentation about coreboot internal technical
-information and libraries.
-
-## Structure and layout
-- [Flashmap and Flashmap Descriptor](flashmap.md)
-- [ABI data consumption](abi-data-consumption.md)
-- [Timestamps](timestamp.md)

Documentation/lib/payloads/fit.md

@@ -6,7 +6,6 @@
 ## Supported architectures
 
 * aarch64
-* riscv
 
 ## Supported FIT sections
 
@@ -25,7 +24,6 @@ The section must be named in order to be found by the FIT parser:
 ## Architecture specifics
 
 The FIT parser needs architecure support.
-
 ### aarch64
 The source code can be found in `src/arch/arm64/fit_payload.c`.
 
@@ -33,13 +31,6 @@ On aarch64 the kernel (a section named 'kernel') must be in **Image**
 format and it needs a devicetree (a section named 'fdt') to boot.
 The kernel will be placed close to "*DRAMSTART*".
 
-### RISC-V
-The source code can be found in `src/arch/riscv/fit_payload.c`.
-
-On RISC-V the kernel (a section named 'kernel') must be in **Image**
-format and it needs a devicetree (a section named 'fdt') to boot.
-The kernel will be placed close to "*DRAMSTART*".
-
 ### Other
 Other architectures aren't supported.
 
@@ -58,7 +49,7 @@ Supported compression algorithms:
 The config entries contain a compatible string, that is used to find a
 matching config.
 
-The following mainboard specific functions provide the BOARDID and SKUID:
+The following mainboard specific funtions provide the BOARDID and SKUID:
 
 ```c
 uint32_t board_id(void);

Documentation/mainboard/51nb/x210.md

@@ -1,46 +0,0 @@
-# 51NB X210
-
-## Extracting vendor EC firmware
-
-EC firmware is included in the SPI image. To extract it, run:
-
-```
-dd bs=64K skip=32 count=1 if=bios.rom of=ec.bin
-```
-
-and ensure that you have a file that includes the string "Insyde Software Corp".
-
-## Flashing instructions
-
-This can be performed using the internal SPI controller, even when flashing
-from stock firmware. Use `flashrom -p internal` and follow the appropriate
-flashrom instructions to force it. Alternatively, external flashing has been
-tested with Dediprog SF100 and SF600 and using a Beaglebone Black. The flash
-is located on the upper side of the motherboard, below the keyboard
-connector. It is circled in red here:
-
-![](x210.jpg)
-
-## Flashing a subset of the ROM
-
-If you want to flash coreboot without extracting firmware blobs, you can
-flash coreboot without overwriting those blobs. After building coreboot,
-create a layout file with the following content:
-
-```
-00000000:001fffff me
-00200000:0020ffff ec
-00210000:007fffff main
-```
-
-and run flashrom with the `--layout rom.layout --image main` arguments. This
-will flash the main firmware without overwriting the existing EC or ME
-firmware.
-
-## Working
-
-All hardware features are believed to be working, although the SD reader is
-untested. Note that certain hotkeys don't work (including the ThinkVantage
-button) - this is a limitation of the EC firmware, and these keys also
-generate no events under the stock vendor firmware.
-

Documentation/mainboard/amd/padmelon/padmelon.md

@@ -1,80 +0,0 @@
-# Padmelon board
-
-## Specs (with Merlin Falcon SOC)
-
-* Two 260-pin DDR4 SO-DIMM slots, 1.2V DDR4-1333/1600/1866/2133 SO-DIMMs
-  Supports 4GB, 8GB and 16GB DDR4 unbuffered ECC (Merlin Falcon)SO-DIMMs
-* Can use Prairie Falcon, Brown Falcon, Merlin Falcon, though coreboot
-  code is specific for Merlin Falcon SOC. Some specs will change if not
-  using Merlin Falcon.
-* One half mini PCI-Express slot on back side of mainboard
-* One PCI Express® 3.0 x8 slot
-* Two SATA3 ports with 6Gb/s data transfer rate
-* Two USB 2.0 ports at rear panel
-* Two USB 3.0 ports at rear panel
-* Dual Gigabit Ethernet from Realtek RTL8111F Gigabit controller
-* 6-channel High-Definition audio from Realtek ALC662 codec
-* One soldered down SPI flash with dediprog header
-
-## Mainboard
-
-![mainboard][padmelon]
-
-Three items are marked in this picture
-1. dediprog header
-2. memory dimms, address 0xA0 and 0xA4
-3. SATA cables connected to motherboard
-
-## Back panel
-
-![back panel][padmelon_io]
-
-* The lower serial port is UART A (debug serial)
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+--------------------+
-| Type                | Value              |
-+=====================+====================+
-| Socketed flash      | no                 |
-+---------------------+--------------------+
-| Model               | Macronix MX256435E |
-+---------------------+--------------------+
-| Size                | 8 MiB              |
-+---------------------+--------------------+
-| Flash programing    | dediprog header    |
-+---------------------+--------------------+
-| Package             | SOIC-8             |
-+---------------------+--------------------+
-| Write protection    | No                 |
-+---------------------+--------------------+
-```
-
-## Technology
-
-```eval_rst
-+---------------+------------------------------+
-| Fan control   | Using fintek F81803A         |
-+---------------+------------------------------+
-| CPU           | Merlin Falcon (see reference)|
-+---------------+------------------------------+
-```
-
-## Description of pictures within this document
-
-```eval_rst
-+----------------------------+----------------------------------------+
-|padmelon.jpg                | Motherboard with components identified |
-+----------------------------+----------------------------------------+
-|padmelon_io.jpg             | Back panel picture                     |
-+----------------------------+----------------------------------------+
-```
-
-## Reference
-
-[Merlin Falcon BKDG][merlinfalcon]
-
-[merlinfalcon]: ../../../soc/amd/family15h.md
-[padmelon]: padmelon.jpg
-[padmelon_io]: padmelon_io.jpg

Documentation/mainboard/asrock/h110m-dvs.md

@@ -1,134 +0,0 @@
-# ASRock H110M-DVS
-
-This page describes how to run coreboot on the [ASRock H110M-DVS].
-
-## Required proprietary blobs
-
-Mainboard is based on Intel Skylake/Kaby Lake processor and H110 Chipset.
-Intel company provides [Firmware Support Package (2.0)](../../soc/intel/fsp/index.md)
-(intel FSP 2.0) to initialize this generation silicon. Please see this
-[document](../../soc/intel/code_development_model/code_development_model.md).
-
-FSP Information:
-
-```eval_rst
-+-----------------------------+-------------------+-------------------+
-| FSP Project Name            | Directory         | Specification     |
-+-----------------------------+-------------------+-------------------+
-| 7th Generation Intel® Core™ | KabylakeFspBinPkg | 2.0               |
-| processors  and chipsets    |                   |                   |
-| (formerly Kaby Lake)        |                   |                   |
-+-----------------------------+-------------------+-------------------+
-```
-
-## Building coreboot
-
-The following steps set the default parameters for this board to build a
-fully working image:
-
-```bash
-make distclean
-touch .config
-./util/scripts/config --enable VENDOR_ASROCK
-./util/scripts/config --enable BOARD_ASROCK_H110M_DVS
-./util/scripts/config --set-str REALTEK_8168_MACADDRESS "xx:xx:xx:xx:xx:xx"
-make olddefconfig
-```
-
-However, it is strongly advised to use `make menuconfig` afterwards
-(or instead), so that you can see all of the settings.
-
-Use the following command to disable the serial console if debugging
-output is not required:
-
-```bash
-./util/scripts/config --disable CONSOLE_SERIAL
-```
-
-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). More information about this [here](../../flash_tutorial/index.md).
-
-### External programming
-
-The flash chip is a 8 MiB socketed DIP-8 chip. Specifically, it's a
-Macronix MX25L6473E, whose datasheet can be found [here][MX25L6473E].
-The chip is located to the bottom right-hand side of the board. For
-a precise location, refer to section 1.3 (Motherboard Layout) of the
-[H110M-DVS manual], where the chip is labelled "64Mb 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. Discrete graphic card is used as primary
-  device for display output (if CONFIG_ONBOARD_VGA_IS_PRIMARY is not
-  set). Dynamic switching between iGPU and PEG is not yet supported.
-
-- SuperIO GPIO pin is used to reset Realtek chip. However, since the
-  Logical Device 7 (GPIO6, GPIO7, GPIO8) is not initialized, the network
-  chip is in a reset state all the time.
-
-## Untested
-
-- parallel port
-- PS/2 keyboard
-- PS/2 mouse
-- EHCI debug
-- TPM
-- infrared module
-- chassis intrusion header
-- chassis speaker header
-
-## Working
-
-- integrated graphics init with libgfxinit (see [Known issues](#known-issues))
-- PCIe x1
-- PEG x16 Gen3
-- SATA
-- USB
-- serial port
-- onboard audio
-- using `me_cleaner`
-- using `flashrom`
-
-## TODO
-
-- NCT6791D GPIOs
-- onboard network (see [Known issues](#known-issues))
-- S3 suspend/resume
-- Wake-on-LAN
-- hardware monitor
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| CPU              | Intel Skylake/Kaby Lake (LGA1151)                |
-+------------------+--------------------------------------------------+
-| PCH              | Intel Sunrise Point H110                         |
-+------------------+--------------------------------------------------+
-| Super I/O        | Nuvoton NCT6791D                                 |
-+------------------+--------------------------------------------------+
-| EC               | None                                             |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-[ASRock H110M-DVS]: https://www.asrock.com/mb/Intel/H110M-DVS%20R2.0/
-[MX25L6473E]: http://www.macronix.com/Lists/Datasheet/Attachments/7380/MX25L6473E,%203V,%2064Mb,%20v1.4.pdf
-[flashrom]: https://flashrom.org/Flashrom
-[H110M-DVS manual]: http://asrock.pc.cdn.bitgravity.com/Manual/H110M-DVS%20R2.0.pdf

Documentation/mainboard/asrock/h81m-hds.md

@@ -70,7 +70,7 @@ facing towards the bottom of the board.
 - 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
+  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.

Documentation/mainboard/asus/f2a85-m.md

@@ -1,198 +0,0 @@
-# ASUS F2A85-M
-
-This page describes how to run coreboot on the [ASUS F2A85-M].
-
-## Variants
-- ASUS F2A85-M - Working
-- ASUS F2A85-M LE - Working
-- ASUS F2A85-M PRO - Working
-- ASUS F2A85-M2 - Working
-- ASUS F2A85-M/CSM - Unsure if WIP.
-
-## Technology
-
-Both "Trinity" and "Richland" desktop processing units are working,
-the CPU architecture in these CPUs/APUs is [Piledriver],
-and their GPU is [TeraScale 3] (VLIW4-based).
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| F2A85-M          |                                                  |
-+------------------+--------------------------------------------------+
-| DDR voltage IC   | Nuvoton NCT3933U (AUX SMBUS 0x15)                |
-+------------------+--------------------------------------------------+
-| Network          | Realtek RTL8111F                                 |
-+------------------+--------------------------------------------------+
-| Northbridge      | Integrated into CPU with IMC and GPU (APUs only) |
-+------------------+--------------------------------------------------+
-| Southbridge      | Hudson-D4                                        |
-+------------------+--------------------------------------------------+
-| Sound IC         | Realtek ALC887                                   |
-+------------------+--------------------------------------------------+
-| Super I/O        | ITE 8603E                                        |
-+------------------+--------------------------------------------------+
-| VRM controller   | DIGI VRM ASP1106 (Rebranded RT8894A - SMBUS 0x20)|
-+------------------+--------------------------------------------------+
-```
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| F2A85-M LE       |                                                  |
-+------------------+--------------------------------------------------+
-| DDR voltage IC   | Nuvoton NCT3933U (AUX SMBUS 0x15 - unconfirmed)  |
-+------------------+--------------------------------------------------+
-| Network          | Realtek RTL8111F                                 |
-+------------------+--------------------------------------------------+
-| Northbridge      | Integrated into CPU with IMC and GPU(APUs only)  |
-+------------------+--------------------------------------------------+
-| Southbridge      | Hudson-D4                                        |
-+------------------+--------------------------------------------------+
-| Sound IC         | Realtek ALC887                                   |
-+------------------+--------------------------------------------------+
-| Super I/O        | ITE 8623E                                        |
-+------------------+--------------------------------------------------+
-| VRM controller   | DIGI VRM ASP1106 (Rebranded RT8894A - SMBUS 0x20)|
-+------------------+--------------------------------------------------+
-```
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| F2A85-M PRO      |                                                  |
-+------------------+--------------------------------------------------+
-| DDR voltage IC   | Nuvoton NCT3933U (?)                             |
-+------------------+--------------------------------------------------+
-| Network          | Realtek RTL8111F - Not working                   |
-+------------------+--------------------------------------------------+
-| Northbridge      | Integrated into CPU with IMC and GPU(APUs only)  |
-+------------------+--------------------------------------------------+
-| Southbridge      | Hudson-D4                                        |
-+------------------+--------------------------------------------------+
-| Sound IC         | Realtek ALC887                                   |
-+------------------+--------------------------------------------------+
-| Super I/O        | Nuvoton NCT6779D                                 |
-+------------------+--------------------------------------------------+
-| VRM controller   | DIGI VRM ASP1107                                 |
-+------------------+--------------------------------------------------+
-```
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+------------+
-| Type                | Value      |
-+=====================+============+
-| Socketed flash      | yes        |
-+---------------------+------------+
-| Model               | W25Q64F    |
-+---------------------+------------+
-| Size                | 8 MiB      |
-+---------------------+------------+
-| Package             | DIP-8      |
-+---------------------+------------+
-| Write protection    | no         |
-+---------------------+------------+
-| Dual BIOS feature   | no         |
-+---------------------+------------+
-| Internal flashing   | yes        |
-+---------------------+------------+
-```
-
-### Internal programming
-
-The main SPI flash can be accessed using [flashrom].
-UEFI builds that allow flash chip access:
-> v5016 is untested, but expected to work as well
-> v5018
-> v5103
-> v5104
-> v5107
-> v5202
-> v6002
-> v6004
-> v6102
-> v6402
-> v6404 (requires downgrading to v6402 to flash coreboot)
-> v6501 (requires downgrading to v6402 to flash coreboot)
-> v6502 (requires downgrading to v6402 to flash coreboot)
-
-Build v6502, v6501 and v6404 do not allow access to the flash chip.
-Fortunately it is possible to downgrade build v6502, v6501, v6404 to v6402, with EZFlash.
-Downgrading is done by downloading build v6402 from ASUS' F2A85-M download page
-and copying it to (the root directory of) a FAT32 formatted USB flash drive.
-Enter the EFI setup, switch to advanced mode if necessary,
-open the 'Tool' tab and select "ASUS EZ Flash 2 Utility".
-
-## Integrated graphics
-
-### Option 1: Retrieve the VGA optionrom from the vendor EFI binary by running:
-
-    # dd if=/dev/mem of=vgabios.bin bs=1k count=64 skip=768
-
-### Option 2: Extract from the vendor binary
-
-Download the BIOS from the Support section at [ASUS F2A85-M].
-Using MMTool Aptio (versions 4.5.0 and 5.0.0):
-- Load image, click on 'Extract tab'
-- Select the 'export path' and 'link present' options
-- Choose option ROM '1002,9900' and click on 'Extract'
-
-This version is usable for all the GPUs.
-> 1002,9901 Trinity (Radeon HD 7660D)
-> 1002,9904 Trinity (Radeon HD 7560D)
-> 1002,990c Richland (Radeon HD 8670D)
-> 1002,990e Richland (Radeon HD 8570D)
-> 1002,9991 Trinity (Radeon HD 7540D)
-> 1002,9993 Trinity (Radeon HD 7480D)
-> 1002,9996 Richland (Radeon HD 8470D)
-> 1002,9998 Richland (Radeon HD 8370D)
-> 1002,999d Richland (Radeon HD 8550D)
-
-## Known issues
-
-- buggy USB 3.0 controller (works fine as 2.0 port)
-- reboot, poweroff, S3 suspend/resume (broken since 4.8.1)
-
-## Known issues (untested because of non-working ACPI sleep)
-
-- blink in suspend mode (GP43, program LDN7 F8=23 and blink with F9=2 for 1s blinks)
-- fix immediate resume after suspend (perhaps PCIe STS needs to be cleared)
-- fix resume with USB3.0 used (perhaps there is a bug in resume.c)
-
-## Untested
-
-- audio over HDMI
-- IOMMU
-- PS/2 mouse
-
-## TODOs
-
-- manage to use one ATOMBIOS for all the integrated GPUs
-
-## Working
-
-- ACPI
-- CPU frequency scaling
-- flashrom under coreboot
-- Gigabit Ethernet
-- Hardware monitor
-- Integrated graphics
-- KVM
-- Onboard audio
-- PCIe
-- PS/2 keyboard
-- SATA
-- Serial port
-- SuperIO based fan control
-- USB (XHCI is buggy)
-
-## Extra resources
-
-- [Board manual]
-- Flash chip datasheet [W25Q64FV]
-
-[ASUS F2A85-M]: https://www.asus.com/Motherboards/F2A85M/
-[Board manual]: https://dlcdnets.asus.com/pub/ASUS/mb/SocketFM2/F2A85-M/E8005_F2A85-M.pdf
-[flashrom]: https://flashrom.org/Flashrom
-[Piledriver]: https://en.wikipedia.org/wiki/Piledriver_%28microarchitecture%29#APU_lines
-[TeraScale 3]: https://en.wikipedia.org/wiki/TeraScale_%28microarchitecture%29#TeraScale_3
-[W25Q64FV]: https://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf

Documentation/mainboard/asus/p5q.md

@@ -1,77 +0,0 @@
-# ASUS P5Q
-
-This page describes how to run coreboot on the [ASUS P5Q] desktop board.
-
-## TODO
-
-The following things are working in this coreboot port:
-
-+ PCI slots
-+ PCI-e slots
-+ Onboard Ethernet
-+ USB
-+ Onboard sound card
-+ PS/2 keyboard
-+ All 4 DIMM slots
-+ S3 suspend and resume
-+ Red SATA ports
-
-The following things are still missing from this coreboot port:
-
-+ PS/2 mouse support
-+ PATA aka IDE (because of buggy IDE controller)
-+ Fan control (will be working on 100% power)
-+ TPM module (support not implemented)
-
-The following things are untested on this coreboot port:
-
-+ S/PDIF
-+ CD Audio In
-+ Floppy disk drive
-+ FireWire: PCI device shows up and driver loads, no further test
-
-
-## Flashing coreboot
-
-```eval_rst
-+-------------------+----------------+
-| Type              | Value          |
-+===================+================+
-| Socketed flash    | Yes            |
-+-------------------+----------------+
-| Model             | MX25L8005      |
-+-------------------+----------------+
-| Size              | 1 MiB          |
-+-------------------+----------------+
-| Package           | Socketed DIP-8 |
-+-------------------+----------------+
-| Write protection  | No             |
-+-------------------+----------------+
-| Dual BIOS feature | No             |
-+-------------------+----------------+
-| Internal flashing | Yes            |
-+-------------------+----------------+
-```
-
-You can flash coreboot into your motherboard using [this guide].
-
-## Technology
-
-```eval_rst
-+------------------+---------------------------------------------------+
-| Northbridge      | Intel P45 (called x4x in coreboot code)           |
-+------------------+---------------------------------------------------+
-| Southbridge      | Intel ICH10R (called i82801jx in coreboot code)   |
-+------------------+---------------------------------------------------+
-| CPU (LGA775)     | Model f4x, f6x, 6fx, 1067x (Pentium 4, d, Core 2) |
-+------------------+---------------------------------------------------+
-| SuperIO          | Winbond W83667HG                                  |
-+------------------+---------------------------------------------------+
-| Coprocessor      | No                                                |
-+------------------+---------------------------------------------------+
-| Clockgen (CK505) | ICS 9LPRS918JKLF                                  |
-+------------------+---------------------------------------------------+
-```
-
-[ASUS P5Q]: https://www.asus.com/Motherboards/P5Q
-[this guide]: https://doc.coreboot.org/flash_tutorial/int_flashrom.html

Documentation/mainboard/asus/p8h61-m_lx.md

@@ -49,7 +49,7 @@ region is not readable even by the host.
   suspend.
 
 - There is no automatic, OS-independent fan control. This is because
-  the Super I/O hardware monitor can only obtain valid CPU temperature
+  the super I/O hardware monitor can only obtain valid CPU temperature
   readings from the PECI agent, whose complete initialisation is not
   publicly documented. The `coretemp` driver can still be used for
   accurate CPU temperature readings.

Documentation/mainboard/asus/p8h61-m_pro.md

@@ -1,103 +0,0 @@
-# ASUS P8H61-M Pro
-
-This page describes how to run coreboot on the [ASUS P8H61-M Pro].
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+------------+
-| Type                | Value      |
-+=====================+============+
-| Socketed flash      | yes        |
-+---------------------+------------+
-| Model               | W25Q32BV   |
-+---------------------+------------+
-| Size                | 4 MiB      |
-+---------------------+------------+
-| Package             | DIP-8      |
-+---------------------+------------+
-| Write protection    | no         |
-+---------------------+------------+
-| Dual BIOS feature   | no         |
-+---------------------+------------+
-| Internal flashing   | yes        |
-+---------------------+------------+
-```
-
-The flash IC is located right next to one of the SATA ports:
-![](p8h61-m_pro.jpg)
-
-### 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 (Management Engine or flash descriptor), then an external
-programmer is required.
-
-The following command may be used to flash coreboot:
-
-```
-$ sudo flashrom --noverify-all --ifd -i bios -p internal -w coreboot.rom
-```
-
-The use of `--noverify-all` is required since the Management Engine
-region is not readable even by the host.
-
-## Known issues
-
-- 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, whose complete initialisation is not
-  publicly documented. The `coretemp` driver can still be used for
-  accurate CPU temperature readings.
-
-- me_cleaner breaks LPC bus and attached components!
-- PS/2 mouse doesn't work
-
-## Untested
-
-- parallel port
-- EHCI debug
-- S/PDIF audio
-
-## Working
-
-- PS/2 keyboard
-- PCIe graphics
-- USB
-- Gigabit Ethernet
-- Integrated graphics
-- SATA
-- Serial port
-- hardware monitor (see [Known issues](#known-issues) for caveats)
-- front panel audio
-- Native raminit (2 x 2GB, DDR3-1333)
-- Native graphics init (libgfxinit)
-- Wake-on-LAN
-- TPM on TPM-header
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| Super I/O        | Nuvoton NCT6776                                  |
-+------------------+--------------------------------------------------+
-| EC               | None                                             |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-## Extra resources
-
-- [Flash chip datasheet][W25Q32BV]
-
-[ASUS P8H61-M Pro]: https://www.asus.com/Motherboards/P8H61M_Pro/
-[W25Q32BV]: https://www.winbond.com/resource-files/w25q32bv_revi_100413_wo_automotive.pdf
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/asus/p8z77-m_pro.md

@@ -1,168 +0,0 @@
-# ASUS P8Z77-M PRO
-
-This page describes how to run coreboot on the [ASUS P8Z77-M PRO]
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+----------------+
-| 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:
-![](p8z77-m_pro.jpg)
-
-### 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 & Tianocore (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 Tianocore
-  (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 TianoCore + 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 Tianocore (please see [Known issues])
-- PS/2 mouse using Tianocore
-- PCIe graphics card on Windows and Tianocore (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
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| Super I/O        | Nuvoton NCT6779D                                 |
-+------------------+--------------------------------------------------+
-| EC               | None                                             |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-## Extra resources
-
-- [Flash chip datasheet][W25Q64FVA1Q]
-
-[ASUS P8Z77-M PRO]: https://www.asus.com/Motherboards/P8Z77M_PRO/
-[W25Q64FVA1Q]: https://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/emulation/qemu-aarch64.md

@@ -1,48 +0,0 @@
-# QEMU AArch64 emulator
-This page discribes how to build and run coreboot for QEMU/AArch64.
-You can use LinuxBoot via `make menuconfig` or an arbitrary FIT image
-as a payload for QEMU/AArch64.
-
-## Running coreboot in QEMU
-```bash
-qemu-system-aarch64 -bios ./build/coreboot.rom \
-    -M virt,secure=on,virtualization=on -cpu cortex-a53 \
-    -nographic -m 8192M
-```
-
-- The default CPU in QEMU for AArch64 is a cortex-a15 which is 32-bit
-ARM CPU. You need to specify 64-bit ARM CPU via `-cpu cortex-a53`.
-- The default privilege level in QEMU for AArch64 is EL1 that we can't
-have the right to access EL3/EL2 registers. You need to enable EL3/EL2
-via `-machine secure=on,virtualization=on`.
-- You need to specify the size of memory more than 544 MiB because 512
-MiB is reserved for the kernel.
-- The maximum size of memory is 255GiB (-m 261120).
-
-## Building coreboot with an arbitrary FIT payload
-There are 3 steps to make coreboot.rom for QEMU/AArch64. If you select
-LinuxBoot, step 2 and 3 have done by LinuxBoot.
-1. Get a DTB (Device Tree Blob)
-2. Build a FIT image with a DTB
-3. Add a FIT image to coreboot.rom
-
-### 1. Get a DTB
-You can get the DTB from QEMU with the following command.
-```
-$ qemu-system-aarch64 \
-    -M virt,dumpdtb=virt.dtb,secure=on,virtualization=on \
-    -cpu cortex-a53 -nographic -m 8192M
-```
-
-### 2. Build a FIT image with a DTB
-You need to write an image source file that has an `.its` extension to
-configure kernels, ramdisks, and DTBs.
-See [Flattened uImage Tree documentation](../../lib/payloads/fit.md) for more details.
-
-### 3. Add a FIT image to coreboot.rom
-You can use cbfstool to add the payload you created in step 2 to
-the coreboot.rom.
-```
-$ ./build/cbfstool ./build/coreboot.rom add -f <path-to-a-payload>/uImage \
-    -n fallback/payload -t fit -c lzma
-```

Documentation/mainboard/facebook/fbg1701.md

@@ -1,83 +0,0 @@
-# Facebook FBG-1701
-
-This page describes how to run coreboot on the Facebook FBG1701.
-
-FBG1701 are assembled with different onboard memory modules:
-	Rev 1.0	Onboard Samsung K4B8G1646D-MYKO memory
-	Rev 1.1 and 1.2	Onboard Micron MT41K512M16HA-125A memory
-	Rev 1.3	Onboard Kingston B5116ECMDXGGB memory
-
-Use make menuconfig to configure `onboard memory manufacturer Samsung` in
-Mainboard menu.
-
-## Required blobs
-
-This board currently requires:
-fsp blob	3rdparty/fsp/BraswellFspBinPkg/FspBin/BSWFSP.fd
-Microcode	3rdparty/intel-microcode/intel-ucode/06-4c-04
-
-## Flashing coreboot
-
-### Internal programming
-
-The main SPI flash can be accessed using [flashrom].
-
-### External programming
-
-The system has an internal flash chip which is a 8 MiB soldered SOIC-8 chip.
-This chip is located on the top middle side of the board. It's located
-between SoC and Q7 connector. Use clip (or solder wires) to program
-the chip.
-Specifically, it's a Winbond W25Q64FW (1.8V), whose datasheet can be found
-[here][W25Q64FW].
-
-The system has an external flash chip which is a 8 MiB soldered SOIC-8 chip.
-This chip is located in the middle of carrier board close to the flex cable
-connection.
-Specifically, it's a Winbond W25Q64FV (3.3V), whose datasheet can be found
-[here][W25Q64FV].
-
-## Known issues
-
-- None
-
-## Untested
-
-- hardware monitor
-- SDIO
-- Full Embedded Controller support
-
-## Working
-
-- USB
-- Gigabit Ethernet
-- integrated graphics
-- flashrom
-- external graphics
-- PCIe
-- eMMC
-- SATA
-- serial port
-- SMBus
-- HDA
-- initialization with FSP MR2
-- SeaBIOS payload
-- Embedded Linux (Ubuntu 4.15+)
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| SoC              | Intel Atom Processor N3710                       |
-+------------------+--------------------------------------------------+
-| CPU              | Intel Braswell (N3710)                           |
-+------------------+--------------------------------------------------+
-| Super I/O, EC    | ITE8528                                          |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-[W25Q64FW]: https://www.winbond.com/resource-files/w25q64fw%20revn%2005182017%20sfdp.pdf
-[W25Q64FV]: https://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/facebook/monolith.md

@@ -1,133 +0,0 @@
-# Facebook Monolith
-
-This page describes how to run coreboot on the Facebook Monolith.
-
-Please note: the coreboot implementation for this boards is in its
-Beta state and isn't fully tested yet.
-
-## Required blobs
-
-Mainboard is based on the Intel Kaby Lake U SoC.
-Intel company provides [Firmware Support Package (2.0)](../../soc/intel/fsp/index.md)
-(intel FSP 2.0) to initialize this generation silicon. Please see this
-[document](../../soc/intel/code_development_model/code_development_model.md).
-
-FSP Information:
-
-```eval_rst
-+-----------------------------+-------------------+-------------------+
-| FSP Project Name            | Directory         | Specification     |
-+-----------------------------+-------------------+-------------------+
-| 7th Generation Intel® Core™ | KabylakeFspBinPkg | 2.0               |
-| processors  and chipsets    |                   |                   |
-| (formerly Kaby Lake)        |                   |                   |
-+-----------------------------+-------------------+-------------------+
-```
-
-Microcode: 3rdparty/intel-microcode/intel-ucode
-
-## Flash components
-
-To create a complete flash image, the flash descriptor, GBE and ME blobs are required. The
-complete image can be used when e.g. a blank flash should be programmed. In other cases (when
-only coreboot needs to be replaced) placeholders can be used for the GBE and ME regions.
-
-These can be extracted from the original flash image as follows:
-1) Read the complete image from flash.
-2) Create a layout file with the following content:
-```
-00000000:00000fff fd
-00700000:00ffffff bios
-00003000:006FFFFF me
-00001000:00002fff gbe
-```
-3) Use `ifdtool -n <layout_file> <flash_image>` to resize the *bios* region from the default 6MB
-   to 9 MB, this is required to create sufficient space for LinuxBoot.
-   NOTE: Please make sure only the firmware descriptor (*fd*) region is changed. Older versions
-   	 of the ifdtool corrupt the *me* region.
-4) Use `ifdtool -x <resized_flash_image>` to extract the components.
-
-The regions extracted can be used to generate a full flash image. The *bios* region is
-not needed as this is replaced by the coreboot image.
-
-NOTE: The gbe region contains the MAC address so be careful. When updating the flash using
-      flashrom it is advisable to leave out the *gbe* area.
-
-## Flashing coreboot
-
-### Internal programming
-
-The SPI flash can be accessed using [flashrom].
-
-The descriptor area needs to be updated once to resize the *bios* region.
-`flashrom -p internal --ifd -i fd -w <coreboot.bin>`
-
-After that only the bios area should to be updated.
-`flashrom -p internal --ifd -i bios -w <coreboot.bin>`
-
-The *gbe* and *me* regions should not be updated.
-
-NOTE: As `flashrom --ifd` uses the flash descriptor it is required to update the
-      descriptor and bios regions in the right sequence. Don't update both in one command.
-
-### External programming
-
-The system has an internal flash chip which is a 16 MiB soldered SOIC-8 chip.
-Specifically, it's a Winbond W25Q128JVSIQ (3.3V).
-
-The system has an external flash chip which is a 16 MiB soldered SOIC-8 chip.
-Specifically, it's a Winbond W25Q128JVSIM (3.3V).
-
-Flashing of these devices is very difficult, disassembling the system destroys the cooling
-solution. Wires need to be connected to be able to flash using an external programmer.
-
-## Known issues
-
-- None
-
-## Untested
-
-- Hardware monitor
-- Full Embedded Controller support
-- SATA
-- xDCI
-
-## Working
-
-- USB
-- Gigabit Ethernet (i219 and i210)
-- Graphics (Using FSP GOP)
-- flashrom
-- PCIe including hotplug on FPGA root port
-- EC serial port
-- EC CPU temperature
-- SMBus
-- Initialization with FSP
-- SeaBIOS payload (commit a5cab58e9a3fb6e168aba919c5669bea406573b4)
-- TianoCore payload (commit a5cab58e9a3fb6e168aba919c5669bea406573b4)
-- LinuxBoot (kernel kernel-4_19_97) (uroot commit 9c9db9dbd6b532f5f91a511a0de885c6562aadd7)
-- eMMC
-
-All of the above has been briefly tested by booting Linux from eMMC using the TianoCore payload
-and LinuxBoot.
-
-SeaBios has been checked to the extend that it runs to the boot selection and provides display
-output.
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| SoC              | Intel Kaby Lake U                                |
-+------------------+--------------------------------------------------+
-| CPU              | Intel i3-7100U                                   |
-+------------------+--------------------------------------------------+
-| Super I/O, EC    | ITE8528                                          |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-[W25Q128JVSIQ]: https://www.winbond.com/resource-files/w25q128jv%20revf%2003272018%20plus.pdf
-[W25Q128JVSIM]: https://www.winbond.com/resource-files/w25q128jv%20dtr%20revb%2011042016.pdf
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/gigabyte/ga-h61m-s2pv.md

@@ -39,23 +39,27 @@ leave the backup chip untouched.
 
 The original IFD defines the BIOS region as the whole flash chip. While this is
 not an issue if flashing a complete image, it confuses flashrom and trashes the
-flash chip's contents when using the `--ifd` option. A possible workaround is
-to create a `layout.txt` file with a non-overlapping BIOS region:
+flash chip's contents when using the --ifd option. However, this can be easily
+fixed by reading the IFD with flashrom, editing the correct values into it with
+ifdtool and then reflashing it.
+
+Create a layout.txt with the following contents:
 
 	00000000:00000fff fd
 	00180000:003fffff bios
 	00001000:0017ffff me
 
-After that, use flashrom with the new layout file. For example, to create a
-backup of the BIOS region and then flash a `coreboot.rom`, do:
+After that, simply run:
 
 ```bash
-sudo flashrom -p internal -l layout.txt -i bios -r backup.rom
-sudo flashrom -p internal -l layout.txt -i bios -w coreboot.rom
+sudo flashrom -p internal --ifd -i fd -r ifd.rom
+ifdtool -n layout.txt ifd.rom
+sudo flashrom -p internal --ifd -i fd -w ifd.rom.new
 ```
 
-Modifying the IFD so that the BIOS region does not overlap would work as well.
-However, this makes DualBIOS unable to recover from a bad flash for some reason.
+After flashing, power cycle the computer to ensure the new IFD is being used.
+If only a reboot is done, the old IFD layout is still seen by flashrom, even if
+the IFD on the flash chip is correctly defining the new region layout.
 
 ## Technology
 

Documentation/mainboard/hp/8760w.md

@@ -1,86 +0,0 @@
-# HP EliteBook 8760w
-
-This page describes how to run coreboot on the [HP EliteBook 8760w].
-
-The coreboot code for this laptop is still not merged, you need to
-checkout the [code on gerrit] to build coreboot for the laptop.
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+------------+
-| Type                | Value      |
-+=====================+============+
-| Socketed flash      | no         |
-+---------------------+------------+
-| Model               | W25Q64.V   |
-+---------------------+------------+
-| Size                | 8 MiB      |
-+---------------------+------------+
-| Package             | SOIC-8     |
-+---------------------+------------+
-| Write protection    | no         |
-+---------------------+------------+
-| Dual BIOS feature   | no         |
-+---------------------+------------+
-| In circuit flashing | yes        |
-+---------------------+------------+
-| Internal flashing   | yes        |
-+---------------------+------------+
-```
-
-## Required proprietary blobs
-
-- Intel Firmware Descriptor, ME and GbE firmware
-- EC: please read [HP Laptops with KBC1126 Embedded Controller](hp_kbc1126_laptops)
-
-## Flashing instructions
-
-HP EliteBook 8760w has an 8MB SOIC-8 flash chip on the bottom of the
-mainboard. You just need to remove the service cover, and use an SOIC-8
-clip to read and flash the chip.
-
-![8760w_chip_location](8760w_flash.jpg)
-
-## Untested
-
-- dock: serial port, parallel port, ...
-- TPM
-- S3 suspend/resume
-- Gigabit Ethernet
-
-## Working
-
-- i7-2630QM, 0+4G+8G+0
-- i7-3720QM, 8G+8G+8G+8G
-- Arch Linux boot from SeaBIOS payload
-- EHCI debug: the port is at the right side, next to the charging port
-- SATA
-- eSATA
-- USB2 and USB3
-- keyboard, touchpad, trackpad
-- WLAN
-- WWAN
-- EC ACPI
-- Using `me_cleaner`
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| Super I/O        | SMSC LPC47n217                                   |
-+------------------+--------------------------------------------------+
-| EC               | SMSC KBC1126                                     |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel Management Engine                          |
-+------------------+--------------------------------------------------+
-```
-
-[HP EliteBook 8760w]: https://support.hp.com/us-en/product/hp-elitebook-8760w-mobile-workstation/5071180
-[code on gerrit]: https://review.coreboot.org/c/coreboot/+/30936

Documentation/mainboard/hp/hp_kbc1126_laptops.md

@@ -1,109 +0,0 @@
-# HP Laptops with KBC1126 Embedded Controller
-
-This document is about HP EliteBook series laptops up to Ivy Bridge era
-which use SMSC KBC1126 as embedded controller.
-
-SMSC KBC1126 (and older similar chips like KBC1098) has been used in
-HP EliteBooks for many generations.  BIOS and EC firmware share an SPI
-flash chip in these laptops, so we need to put firmware blobs for the
-EC to the coreboot image.
-
-## EC firmware extraction and coreboot building
-
-The following document takes EliteBook 2760p as an example.
-
-First, you need to extract the blobs needed by EC firmware using util/kbc1126.
-You can extract them from your backup firmware image, or firmware update
-provided by HP with [unar] as follows:
-
-```bash
-wget https://ftp.hp.com/pub/softpaq/sp79501-80000/sp79710.exe
-unar sp79710.exe
-${COREBOOT_DIR}/util/kbc1126/kbc1126_ec_dump sp79710/Rompaq/68SOU.BIN
-mv 68SOU.BIN.fw1 ${COREBOOT_DIR}/2760p-fw1.bin
-mv 68SOU.BIN.fw2 ${COREBOOT_DIR}/2760p-fw2.bin
-```
-
-When you config coreboot, select:
-
-```text
-Chipset --->
-  [*] Add firmware images for KBC1126 EC
-      (2760p-fw1.bin) KBC1126 firmware #1 path and filename
-      (2760p-fw2.bin) KBC1126 filename #2 path and filename
-```
-
-## Porting guide for HP laptops with KBC1126
-
-To port coreboot to an HP laptop with KBC1126, you need to do the
-following:
-
-- select Kconfig option `EC_HP_KBC1126`
-- select Kconfig option `SUPERIO_SMSC_LPC47N217` if there is LPC47n217
-  Super I/O, usually in EliteBook 8000 series, which can be used for
-  debugging via serial port
-- initialize EC and Super I/O in romstage
-- add EC and Super I/O support to devicetree.cb
-
-To get the related values for EC in devicetree.cb, you need to extract the EFI
-module EcThermalInit from the vendor UEFI firmware with [UEFITool]. Usually,
-`ec_data_port`, `ec_cmd_port` and `ec_ctrl_reg` has the following values:
-
-- For EliteBook xx60 series: 0x60, 0x64, 0xca
-- For EliteBook xx70 series: 0x62, 0x66, 0x81
-
-You can use [radare2] and the following [r2pipe] Python script to find
-these values from the EcThermalInit EFI module:
-
-```python
-#!/usr/bin/env python
-
-# install radare2 and use `pip3 install --user r2pipe` to install r2pipe
-
-import r2pipe
-import sys
-
-if len(sys.argv) < 2:
-    fn = "ecthermalinit.efi"
-else:
-    fn = sys.argv[1]
-
-r2 = r2pipe.open(fn)
-r2.cmd("aa")
-entryf = r2.cmdj("pdfj")
-
-for insn in entryf["ops"]:
-    if "lea r8" in insn["opcode"]:
-        _callback = insn["ptr"]
-        break
-
-r2.cmd("af @ {}".format(_callback))
-callbackf_insns = r2.cmdj("pdfj @ {}".format(_callback))["ops"]
-
-def find_port(addr):
-    ops = r2.cmdj("pdfj @ {}".format(addr))["ops"]
-    for insn in ops:
-        if "lea r8d" in insn["opcode"]:
-            return insn["ptr"]
-
-ctrl_reg_found = False
-
-for i in range(0, len(callbackf_insns)):
-    if not ctrl_reg_found and "mov cl" in callbackf_insns[i]["opcode"]:
-        ctrl_reg_found = True
-        ctrl_reg = callbackf_insns[i]["ptr"]
-        print("ec_ctrl_reg = 0x%02x" % ctrl_reg)
-        cmd_port = find_port(callbackf_insns[i+1]["jump"])
-        data_port = find_port(callbackf_insns[i+3]["jump"])
-        print("ec_cmd_port = 0x%02x\nec_data_port = 0x%02x" % (cmd_port, data_port))
-
-    if "mov bl" in callbackf_insns[i]["opcode"]:
-        ctrl_value = callbackf_insns[i]["ptr"]
-        print("ec_fan_ctrl_value = 0x%02x" % ctrl_value)
-```
-
-
-[unar]: https://theunarchiver.com/command-line
-[UEFITool]: https://github.com/LongSoft/UEFITool
-[radare2]: https://radare.org/
-[r2pipe]: https://github.com/radare/radare2-r2pipe

Documentation/mainboard/hp/z220_sff.md

@@ -1,70 +0,0 @@
-# HP Z220 SFF Workstation
-
-This page describes how to run coreboot on the [HP Z220 SFF Workstation] desktop
-from [HP].
-
-## TODO
-
-The following things are still missing from this coreboot port:
-
-- Extended HWM reporting
-- Advanced LED control
-- Advanced power configuration in S3
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+-------------+
-| Type                | Value       |
-+=====================+=============+
-| Socketed flash      | no          |
-+---------------------+-------------+
-| Model               | N25Q128..3E |
-+---------------------+-------------+
-| Size                | 16 MiB      |
-+---------------------+-------------+
-| In circuit flashing | yes         |
-+---------------------+-------------+
-| Package             | SOIC-16     |
-+---------------------+-------------+
-| Write protection    | No          |
-+---------------------+-------------+
-| Dual BIOS feature   | No          |
-+---------------------+-------------+
-| Internal flashing   | yes         |
-+---------------------+-------------+
-```
-
-### Internal programming
-
-The SPI flash can be accessed using [flashrom].
-
-### External programming
-
-External programming with an SPI adapter and [flashrom] does work, but it powers the
-whole southbridge complex. You need to supply enough current through the programming adapter.
-
-If you want to use a SOIC pomona test clip, you have to cut the 2nd DRAM DIMM holder,
-as otherwise there's not enough space near the flash.
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | bd82x6x                                          |
-+------------------+--------------------------------------------------+
-| CPU              | model_206ax                                      |
-+------------------+--------------------------------------------------+
-| SuperIO          | :doc:`../../superio/nuvoton/npcd378`             |
-+------------------+--------------------------------------------------+
-| EC               |                                                  |
-+------------------+--------------------------------------------------+
-| Coprocessor      | Intel ME                                         |
-+------------------+--------------------------------------------------+
-```
-
-[HP Z220 SFF Workstation]: https://support.hp.com/za-en/document/c03386950
-[HP]: https://www.hp.com/
-[flashrom]: https://flashrom.org/Flashrom

Documentation/mainboard/index.md

@@ -2,25 +2,13 @@
 
 This section contains documentation about coreboot on specific mainboards.
 
-## 51NB
+## ASUS
 
-- [X210](51nb/x210.md)
-
-## AMD
-- [padmelon](amd/padmelon/padmelon.md)
+- [P8H61-M LX](asus/p8h61-m_lx.md)
 
 ## ASRock
 
 - [H81M-HDS](asrock/h81m-hds.md)
-- [H110M-DVS](asrock/h110m-dvs.md)
-
-## ASUS
-
-- [F2A85-M](asus/f2a85-m.md)
-- [P5Q](asus/p5q.md)
-- [P8H61-M LX](asus/p8h61-m_lx.md)
-- [P8H61-M Pro](asus/p8h61-m_pro.md)
-- [P8Z77-M Pro](asus/p8z77-m_pro.md)
 
 ## Cavium
 
@@ -32,12 +20,12 @@ The boards in this section are not real mainboards, but emulators.
 
 - [Spike RISC-V emulator](emulation/spike-riscv.md)
 - [Qemu RISC-V emulator](emulation/qemu-riscv.md)
-- [Qemu AArch64 emulator](emulation/qemu-aarch64.md)
 
-## Facebook
+## Intel
 
-- [FBG-1701](facebook/fbg1701.md)
-- [Monolith](facebook/monolith.md)
+- [DG43GT](intel/dg43gt.md)
+- [IceLake RVP](intel/icelake_rvp.md)
+- [KBLRVP11](intel/kblrvp11.md)
 
 ## Foxconn
 
@@ -51,89 +39,33 @@ The boards in this section are not real mainboards, but emulators.
 
 - [Dragonegg](google/dragonegg.md)
 
+## Open Cellular
+
+- [Elgon](opencellular/elgon.md)
+
 ## HP
 
 - [Compaq 8200 Elite SFF](hp/compaq_8200_sff.md)
-- [Z220 Workstation SFF](hp/z220_sff.md)
-
-### EliteBook series
-
-- [HP Laptops with KBC1126 EC](hp/hp_kbc1126_laptops.md)
-- [EliteBook 8760w](hp/8760w.md)
-
-## Intel
-
-- [DG43GT](intel/dg43gt.md)
-- [IceLake RVP](intel/icelake_rvp.md)
-- [KBLRVP11](intel/kblrvp11.md)
 
 ## Lenovo
 
-- [Mainboard codenames](lenovo/codenames.md)
 - [Hardware Maintenance Manual of ThinkPads](lenovo/thinkpad_hmm.md)
-- [R60](lenovo/r60.md)
 - [T4xx common](lenovo/t4xx_series.md)
 - [X2xx common](lenovo/x2xx_series.md)
-- [vboot](lenovo/vboot.md)
-
-### Arrandale series
-
-- [T410](lenovo/t410.md)
-
-### GM45 series
-
-- [X200 / T400 / T500 / X301 common](lenovo/montevina_series.md)
-- [X301](lenovo/x301.md)
 
 ### Sandy Bridge series
 
 - [T420](lenovo/t420.md)
-- [T420 / T520 / X220 / T420s / W520 common](lenovo/Sandy_Bridge_series.md)
-- [X1](lenovo/x1.md)
+- [T420 / T520 / X220 / T420s / W520 common](lenovo/xx20_series.md)
+- [x1](lenovo/x1.md)
 
 ### Ivy Bridge series
 
 - [T430](lenovo/t430.md)
 - [T530](lenovo/w530.md)
 - [W530](lenovo/w530.md)
-- [T430 / T530 / X230 / W530 common](lenovo/Ivy_Bridge_series.md)
+- [T430 / T530 / X230 / W530 common](lenovo/xx30_series.md)
 - [T431s](lenovo/t431s.md)
-- [Internal flashing](lenovo/ivb_internal_flashing.md)
-
-### Haswell series
-
-- [T440p](lenovo/t440p.md)
-
-## Libretrend
-
-- [LT1000](libretrend/lt1000.md)
-
-## MSI
-
-- [MS-7707](msi/ms7707/ms7707.md)
-
-## Open Cellular
-
-- [Elgon](opencellular/elgon.md)
-- [Rotundu](opencellular/rotundu.md)
-
-## PC Engines
-
-- [APU1](pcengines/apu1.md)
-- [APU2](pcengines/apu2.md)
-
-## Portwell
-
-- [PQ7-M107](portwell/pq7-m107.md)
-
-## Protectli
-
-- [FW2B / FW4B](protectli/fw2b_fw4b.md)
-- [FW6A / FW6B / FW6C](protectli/fw6.md)
-
-## Roda
-
-- [RK9 Flash Header](roda/rk9/flash_header.md)
 
 ## SiFive
 
@@ -142,13 +74,3 @@ The boards in this section are not real mainboards, but emulators.
 ## Supermicro
 
 - [X10SLM+-F](supermicro/x10slm-f.md)
-- [X11 LGA1151 series](supermicro/x11-lga1151-series/x11-lga1151-series.md)
-- [Flashing using the BMC](supermicro/flashing_on_vendorbmc.md)
-
-## System76
-
-- [Lemur Pro](system76/lemp9.md)
-
-## UP
-
-- [Squared](up/squared/index.md)

Documentation/mainboard/lenovo/Ivy_Bridge_series.md

@@ -1,93 +0,0 @@
-# Lenovo Ivy Bridge series
-
-This information is valid for all supported models, except T430s and T431s.
-
-## Flashing coreboot
-```eval_rst
-+---------------------+--------------------------------+
-| Type                | Value                          |
-+=====================+================================+
-| Socketed flash      | no                             |
-+---------------------+--------------------------------+
-| Size                | 8 MiB + 4MiB                   |
-+---------------------+--------------------------------+
-| In circuit flashing | Yes                            |
-+---------------------+--------------------------------+
-| Package             | SOIC-8                         |
-+---------------------+--------------------------------+
-| Write protection    | No                             |
-+---------------------+--------------------------------+
-| Dual BIOS feature   | No                             |
-+---------------------+--------------------------------+
-| Internal flashing   | Yes                            |
-+---------------------+--------------------------------+
-```
-
-## Installation instructions
-* Update the EC firmware, as there's no support for EC updates in coreboot.
-* Do **NOT** accidently swap pins or power on the board while a SPI flasher
-  is connected. It will permanently brick your device.
-* It's recommended to only flash the BIOS region. In that case you don't
-  need to extract blobs from vendor firmware.
-  If you want to flash the whole chip, you need blobs when building
-  coreboot.
-* The *Flash layout* shows that by default 7MiB of space are available for
-  the use with coreboot.
-* In that case you only want to use a part of the BIOS region that must not
-  exceed 4MiB in size, which means CONFIG_CBFS_SIZE must be smaller than 4MiB.
-* ROM chip size should be set to 12MiB.
-
-```eval_rst
-Please also have a look at :doc:`../../flash_tutorial/index`.
-```
-
-## Splitting the coreboot.rom
-
-To split the coreboot.rom into two images (one for the 8MiB and one for the
-4 MiB flash IC), run the following commands:
-
-```bash
-dd of=top.rom bs=1M if=build/coreboot.rom skip=8
-dd of=bottom.rom bs=1M if=build/coreboot.rom count=8
-```
-
-That gives one ROM for each flash IC, where *top.rom* is the upper part of the
-flash image, that resides on the 4 MiB flash and *bottom.rom* is the lower part
-of the flash image, that resides on the 8 MiB flash.
-
-## Dumping a full ROM
-
-If you flash externally you need to read both flash chips to get two images
-(one for the 8MiB and one for the 4 MiB flash IC), and then run the following
-command to concatenate the files:
-
-```bash
-cat bottom.rom top.rom > firmware.rom
-```
-
-## Flash layout
-There's one 8MiB and one 4 MiB flash which contains IFD, GBE, ME and
-BIOS region. These two flash ICs appear as a single 12MiB when flashing
-internally.
-On Lenovo's UEFI the EC firmware update is placed at the start of the BIOS
-region. The update is then written into the EC once.
-
-![][fl]
-
-[fl]: flashlayout_Ivy_Bridge.svg
-
-## Reducing Intel Managment Engine firmware size
-
-It is possible to reduce the Intel ME firmware size to free additional
-space for the `bios` region. This is usually referred to as *cleaning the ME* or
-*stripping the ME*.
-After reducing the Intel ME firmware size you must modify the original IFD,
-[split the resulting coreboot ROM](#splitting-the-coreboot-rom) and then write
-each ROM using an [external programmer].
-Have a look at [me_cleaner] for more information.
-
-Tests on Lenovo W530 showed no issues with a stripped and shrunken ME firmware.
-
-
-[me_cleaner]: ../../northbridge/intel/sandybridge/me_cleaner.md
-[external programmer]: ../../flash_tutorial/index.md

Documentation/mainboard/lenovo/Sandy_Bridge_series.md

@@ -1,69 +0,0 @@
-# Lenovo Sandy Bridge series
-
-## Flashing coreboot
-```eval_rst
-+---------------------+--------------------+
-| Type                | Value              |
-+=====================+====================+
-| Socketed flash      | no                 |
-+---------------------+--------------------+
-| Size                | 8 MiB              |
-+---------------------+--------------------+
-| In circuit flashing | Yes                |
-+---------------------+--------------------+
-| Package             | SOIC-8             |
-+---------------------+--------------------+
-| Write protection    | No                 |
-+---------------------+--------------------+
-| Dual BIOS feature   | No                 |
-+---------------------+--------------------+
-| Internal flashing   | Yes                |
-+---------------------+--------------------+
-```
-
-## Installation instructions
-* Update the EC firmware, as there's no support for EC updates in coreboot.
-* Do **NOT** accidently swap pins or power on the board while a SPI flasher
-  is connected. It will destroy your device.
-* It's recommended to only flash the BIOS region. In that case you don't
-  need to extract blobs from vendor firmware.
-  If you want to flash the whole chip, you need blobs when building
-  coreboot.
-* The shipped *Flash layout* allocates 3MiB to the BIOS region, which is the space
-  usable by coreboot.
-* ROM chip size should be set to 8MiB.
-
-Please also have a look at the [flashing tutorial]
-
-## Flash layout
-There's one 8MiB flash which contains IFD, GBE, ME and BIOS regions.
-On Lenovo's UEFI the EC firmware update is placed at the start of the BIOS
-region. The update is then written into the EC once.
-
-![][fl]
-
-[fl]: flashlayout_Sandy_Bridge.svg
-
-## Reducing Intel Managment Engine firmware size
-
-It is possible to reduce the Intel ME firmware size to free additional
-space for the `bios` region. This is usually referred to as *cleaning the ME* or
-*stripping the ME*.
-After reducing the Intel ME firmware size you must modify the original IFD
-and then write a full ROM using an [external programmer].
-Have a look at [me_cleaner] for more information.
-
-Tests on Lenovo X220 showed no issues with a stripped ME firmware.
-
-**Modified flash layout:**
-
-![][fl2]
-
-[fl2]: flashlayout_Sandy_Bridge_stripped_me.svg
-
-The overall size of the `gbe`, `me,` `ifd` region is less than 128KiB, leaving
-the remaining space for the `bios` partition.
-
-
-[me_cleaner]: ../../northbridge/intel/sandybridge/me_cleaner.md
-[external programmer]: ../../flash_tutorial/index.md

Documentation/mainboard/lenovo/codenames.md

@@ -1,7 +0,0 @@
-# Lenovo mainboard codenames
-
-```eval_rst
-.. csv-table::
-   :header: "Marketing name", "Development codename"
-   :file: codenames.csv
-```

Documentation/mainboard/lenovo/flashlayout_Sandy_Bridge_stripped_me.svg

@@ -1,74 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.0//EN" "http://www.w3.org/TR/2001/PR-SVG-20010719/DTD/svg10.dtd">
-<svg width="9cm" height="8cm" viewBox="268 -156 168 158" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-  <g>
-    <g>
-      <g>
-        <rect style="fill: #ffffff" x="307.888" y="-152.131" width="49.1438" height="30.4667"/>
-        <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="307.888" y="-152.131" width="49.1438" height="30.4667"/>
-      </g>
-      <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="307.888" y="-152.131" width="49.1438" height="30.4667"/>
-    </g>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="307.888" y="-152.131" width="49.1438" height="30.4667"/>
-    <text font-size="6.77323" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="332.46" y="-134.831">
-      <tspan x="332.46" y="-134.831">IFD</tspan>
-    </text>
-  </g>
-  <g>
-    <g>
-      <rect style="fill: #ffffff" x="307.934" y="-56.9106" width="49.1438" height="56.1492"/>
-      <rect style="fill: none; fill-opacity:0; stroke-width: 0.02; stroke: #ffffff" x="307.934" y="-56.9106" width="49.1438" height="56.1492"/>
-    </g>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 0.02; stroke: #ffffff" x="307.934" y="-56.9106" width="49.1438" height="56.1492"/>
-  </g>
-  <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="308.096" y="-57.559" width="49.1438" height="57.2839"/>
-  <text font-size="6.77323" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="332.182" y="-24.0245">
-    <tspan x="332.182" y="-24.0245">BIOS</tspan>
-  </text>
-  <g>
-    <g>
-      <g>
-        <rect style="fill: #ffffff" x="308" y="-121.59" width="49.1438" height="30.4667"/>
-        <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="308" y="-121.59" width="49.1438" height="30.4667"/>
-      </g>
-      <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="308" y="-121.59" width="49.1438" height="30.4667"/>
-    </g>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="308" y="-121.59" width="49.1438" height="30.4667"/>
-    <text font-size="6.77323" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="332.572" y="-104.29">
-      <tspan x="332.572" y="-104.29">GBE</tspan>
-    </text>
-  </g>
-  <text font-size="7.15705" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="268.961" y="-148.674">
-    <tspan x="268.961" y="-148.674">0x000000</tspan>
-  </text>
-  <text font-size="6.77323" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="269.152" y="-120.399">
-    <tspan x="269.152" y="-120.399">0x001000</tspan>
-  </text>
-  <text font-size="6.77323" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="269.155" y="-90.6472">
-    <tspan x="269.155" y="-90.6472">0x003000</tspan>
-  </text>
-  <text font-size="6.77323" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="269.461" y="-56.4289">
-    <tspan x="269.461" y="-56.4289">0x020000</tspan>
-  </text>
-  <text font-size="6.77323" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="270.008" y="0.198407">
-    <tspan x="270.008" y="0.198407">0x800000</tspan>
-  </text>
-  <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" d="M 380.877 -151.013 C 401.876,-151.013 379.377,-73.513 400.627,-72.513"/>
-  <path style="fill: none; fill-opacity:0; stroke-width: 1; stroke: #000000" d="M 381.377 -0.763268 C 395.238,-0.763268 387.016,-72.763 400.877,-72.763"/>
-  <text font-size="6.77323" style="fill: #000000;text-anchor:start;font-family:sans-serif;font-style:normal;font-weight:normal" x="406.127" y="-68.513">
-    <tspan x="406.127" y="-68.513">Flash #0</tspan>
-  </text>
-  <g>
-    <g>
-      <g>
-        <rect style="fill: #ffffff" x="308.189" y="-90.5898" width="49.1438" height="33.4161"/>
-        <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="308.189" y="-90.5898" width="49.1438" height="33.4161"/>
-      </g>
-      <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #ffffff" x="308.189" y="-90.5898" width="49.1438" height="33.4161"/>
-    </g>
-    <rect style="fill: none; fill-opacity:0; stroke-width: 2; stroke: #000000" x="308.189" y="-90.5898" width="49.1438" height="32.8215"/>
-    <text font-size="6.77323" style="fill: #000000;text-anchor:middle;font-family:sans-serif;font-style:normal;font-weight:normal" x="331.572" y="-70.23">
-      <tspan x="331.572" y="-70.23">ME</tspan>
-    </text>
-  </g>
-</svg>

Documentation/mainboard/lenovo/ivb_internal_flashing.md

@@ -1,361 +0,0 @@
-# Ivy Bridge Lenovo ThinkPad Internal Flashing
-
-## Introduction
-
-Old versions of stock BIOS for these models have several security issues.
-In order to flash coreboot internally, two of them are of interest.
-
-**First** is the fact the `SMM_BWP` and `BLE` are not enabled in BIOS
-versions released before 2014. We have tested many versions on T430 and
-X230 and found out that `SMM_BWP=1` only since the update, the changelog
-of which contains following line:
-
-> (New) Improved the UEFI BIOS security feature.
-
-**Second** is [S3 Boot Script vulnerability](https://support.lenovo.com/eg/ru/product_security/s3_boot_protect),
-that was discovered and fixed later.
-
-## Requirements
-
-- USB drive (in case you need to downgrade BIOS)
-- Linux install that (can be) loaded in UEFI mode
-- [CHIPSEC](https://github.com/chipsec/chipsec)
-
-## BIOS versions
-
-Below is a table of BIOS versions that are vulnerable enough for our
-goals, per model. The version number means that you need to downgrade to
-that or earlier version.
-
-```eval_rst
-+------------+--------------+
-| Model      | BIOS version |
-+============+==============+
-| X230       | 2.60         |
-+------------+--------------+
-| X230T      | 2.58         |
-+------------+--------------+
-| T430       | 2.64         |
-+------------+--------------+
-| T430s      | 2.59         |
-+------------+--------------+
-| T530       | 2.60         |
-+------------+--------------+
-| W530       | 2.58         |
-+------------+--------------+
-```
-
-If your BIOS version is equal or lower, skip to the
-**[Examining protections](#examining-protections-theory)** section. If not,
-go through the downgrade process, described next.
-
-## Downgrading BIOS
-
-Go to the Lenovo web site and download BIOS Update Bootable CD for your
-machine of needed version (see above).
-
-Lenovo states that BIOS has "security rollback prevention", meaning once
-you update it to some version X, you will not be able to downgrade it to
-pre-X version. That's not true. It seems that this is completely
-client-side restriction in flashing utilities (both Windows utility and
-Bootable CD). You just need to call `winflash.exe` or `dosflash.exe`
-directly. Therefore you need to modify the bootable CD image you just
-downloaded.
-
-Extract an El Torito image:
-
-    geteltorito -o ./bios.img g1uj41us.iso
-
-Mount the partition in that image:
-
-    sudo mount -t vfat ./bios.img /mnt -o loop,offset=16384
-
-List files, find the `AUTOEXEC.BAT` file and the `FLASH` directory:
-
-    ls /mnt
-    ls /mnt/FLASH
-
-Inside the `FLASH` directory, there should be a directory called
-`G1ET93WW` or similar (exact name depends on your ThinkPad model and
-BIOS version). See what's inside:
-
-    ls /mnt/FLASH/G1ET93WW
-
-There must be a file with `.FL1` extension called `$01D2000.FL1` or
-something similar.
-
-Now open the `AUTOEXEC.BAT` file:
-
-    sudo vim /mnt/AUTOEXEC.BAT
-
-You will see a list of commands:
-
-    @ECHO OFF
-    PROMPT $p$g
-    cd c:\flash
-    command.com
-
-Replace the last line (`command.com`) with this (change path to the
-`.FL1` file according to yours):
-
-    dosflash.exe /sd /file G1ET93WW\$01D2000.FL1
-
-Save the file, then unmount the partition:
-
-    sudo umount /mnt
-
-Write this image to a USB drive (replace `/dev/sdX` with your USB drive
-device name):
-
-    sudo dd if=./bios.img of=/dev/sdX bs=1M
-
-Now reboot and press F1 to enter BIOS settings. Open the **Startup** tab
-and set the startup mode to **Legacy** (or **Both**/**Legacy First**):
-
-![](ivb_bios_legacy_only.jpg)
-
-Press F10 to save changes and reboot.
-
-Now, before you process, make sure that AC adapter is connected! If your
-battery will die during the process, you'll likely need external
-programmer to recover.
-
-Boot from the USB drive (press F12 to select boot device), and BIOS
-flashing process should begin:
-
-![](ivb_bios_flashing1.jpg)
-
-![](ivb_bios_flashing2.jpg)
-
-It may reboot a couple of times in the process. Do not interrupt it.
-
-When it's completed, go back to the BIOS settings and set startup mode
-to **UEFI** (or **Both**/**UEFI First**). This is required for
-vulnerability exploitation.
-
-![](ivb_bios_uefi_only.jpg)
-
-Then boot to your system and make sure that `/sys/firmware/efi` or
-`/sys/firmware/efivars` exist.
-
-## Examining protections (theory)
-
-There are two main ways that Intel platform provides to protect BIOS
-chip:
-- **BIOS_CNTL** register of LPC Interface Bridge Registers (accessible
-    via PCI configuration space, offset 0xDC). It has:
-  * **SMM_BWP** (*SMM BIOS Write Protect*) bit. If set to 1, the BIOS is
-    writable only in SMM. Once set to 1, cannot be changed anymore.
-  * **BLE**  (*BIOS Lock Enable*) bit. If set to 1, setting BIOSWE to 1
-    will raise SMI. Once set to 1, cannot be changed anymore.
-  * **BIOSWE** (*BIOS Write Enable*) bit. Controls whether BIOS is
-    writable. This bit is always R/W.
-- SPI Protected Range Registers (**PR0**-**PR4**) of SPI Configuration
-  Registers (SPIBAR+0x74 - SPIBAR+0x84). Each register has bits that
-  define protected range, plus WP bit, that defines whether write
-  protection is enabled.
-
-  There's also **FLOCKDN** bit of HSFS register (SPIBAR+0x04) of SPI
-  Configuration Registers. When set to 1, PR0-PR4 registers cannot be
-  written. Once set to 1, cannot be changed anymore.
-
-To be able to flash, we need `SMM_BWP=0`, `BIOSWE=1`, `BLE=0`, `FLOCKDN=0` or
-SPI protected ranges (PRx) to have a WP bit set to 0.
-
-Let's see what we have. Examine `HSFS` register:
-
-    sudo chipsec_main -m chipsec.modules.common.spi_lock
-
-You should see that `FLOCKDN=1`:
-
-    [x][ =======================================================================
-    [x][ Module: SPI Flash Controller Configuration Locks
-    [x][ =======================================================================
-    [*] HSFS = 0xE009 << Hardware Sequencing Flash Status Register (SPIBAR + 0x4)
-        [00] FDONE            = 1 << Flash Cycle Done
-        [01] FCERR            = 0 << Flash Cycle Error
-        [02] AEL              = 0 << Access Error Log
-        [03] BERASE           = 1 << Block/Sector Erase Size
-        [05] SCIP             = 0 << SPI cycle in progress
-        [13] FDOPSS           = 1 << Flash Descriptor Override Pin-Strap Status
-        [14] FDV              = 1 << Flash Descriptor Valid
-        [15] FLOCKDN          = 1 << Flash Configuration Lock-Down
-
-Then check `BIOS_CNTL` and PR0-PR4:
-
-    sudo chipsec_main -m common.bios_wp
-
-Good news: on old BIOS versions, `SMM_BWP=0` and `BLE=0`.
-
-Bad news: there are 4 write protected SPI ranges:
-
-     [x][ =======================================================================
-     [x][ Module: BIOS Region Write Protection
-     [x][ =======================================================================
-     [*] BC = 0x 8 << BIOS Control (b:d.f 00:31.0 + 0xDC)
-         [00] BIOSWE           = 0 << BIOS Write Enable
-         [01] BLE              = 0 << BIOS Lock Enable
-         [02] SRC              = 2 << SPI Read Configuration
-         [04] TSS              = 0 << Top Swap Status
-         [05] SMM_BWP          = 0 << SMM BIOS Write Protection
-     [-] BIOS region write protection is disabled!
-
-     [*] BIOS Region: Base = 0x00500000, Limit = 0x00BFFFFF
-     SPI Protected Ranges
-     ------------------------------------------------------------
-     PRx (offset) | Value    | Base     | Limit    | WP? | RP?
-     ------------------------------------------------------------
-     PR0 (74)     | 00000000 | 00000000 | 00000000 | 0   | 0
-     PR1 (78)     | 8BFF0B40 | 00B40000 | 00BFFFFF | 1   | 0
-     PR2 (7C)     | 8B100B10 | 00B10000 | 00B10FFF | 1   | 0
-     PR3 (80)     | 8ADE0AD0 | 00AD0000 | 00ADEFFF | 1   | 0
-     PR4 (84)     | 8AAF0800 | 00800000 | 00AAFFFF | 1   | 0
-
-Other way to examine SPI configuration registers is to just dump SPIBAR:
-
-    sudo chipsec_util mmio dump SPIBAR
-
-You will see `SPIBAR` address (0xFED1F800) and registers (for example,
-`00000004` is `HSFS`):
-
-    [mmio] MMIO register range [0x00000000FED1F800:0x00000000FED1F800+00000200]:
-    +00000000: 0BFF0500
-    +00000004: 0004E009
-    ...
-
-As you can see, the only thing we need is to unset WP bit on PR0-PR4.
-But that cannot be done once `FLOCKDN` is set to 1.
-
-Now the fun part!
-
-`FLOCKDN` may only be cleared by a hardware reset, which includes S3
-state. On S3 resume boot path, the chipset configuration has to be
-restored and it's done by executing so-called S3 Boot Scripts. You can
-dump these scripts by executing:
-
-    sudo chipsec_util uefi s3bootscript
-
-There are many entries. Along them, you can find instructions to write
-to `HSFS` (remember, we know that `SPIBAR` is 0xFED1F800):
-
-     Entry at offset 0x2B8F (len = 0x17, header len = 0x0):
-     Data:
-     02 00 17 02 00 00 00 01 00 00 00 04 f8 d1 fe 00 |
-     00 00 00 09 e0 04 00                            |
-     Decoded:
-       Opcode : S3_BOOTSCRIPT_MEM_WRITE (0x0002)
-       Width  : 0x02 (4 bytes)
-       Address: 0xFED1F804
-       Count  : 0x1
-       Values : 0x0004E009
-
-These scripts are stored in memory. The vulnerability is that we can
-overwrite this memory, change these instructions and they will be
-executed on S3 resume. Once we patch that instruction to not set `FLOCKDN`
-bit, we will be able to write to PR0-PR4 registers.
-
-## Creating a backup
-
-Before you proceed, please create a backup of the `bios` region. Then,
-in case something goes wrong, you'll be able to flash it back externally.
-
-The `me` region is locked, so an attempt to create a full dump will fail.
-But you can back up the `bios`:
-
-    sudo flashrom -p internal -r bios_backup.rom --ifd -i bios
-
-If you will ever need to flash it back, use `--ifd -i bios` as well:
-
-    sudo flashrom -p <YOUR_PROGRAMMER> -w bios_backup.rom --ifd -i bios
-
-**Caution:** if you will omit `--ifd -i bios` for flashing, you will
-brick your machine, because your backup has `FF`s in place of `fd` and
-`me` regions. Flash only `bios` region!
-
-## Removing protections (practice)
-
-The original boot script writes 0xE009 to `HSFS`. `FLOCKDN` is 15th bit, so
-let's write 0x6009 instead:
-
-    sudo chipsec_main -m tools.uefi.s3script_modify -a replace_op,mmio_wr,0xFED1F804,0x6009,0x2
-
-You will get a lot of output and in the end you should see something
-like this:
-
-     [*] Modifying S3 boot script entry at address 0x00000000DAF49B8F..
-     [mem] 0x00000000DAF49B8F
-     [*] Original entry:
-      2  0 17  2  0  0  0  1  0  0  0  4 f8 d1 fe  0 |
-      0  0  0  9 e0  4  0                            |
-     [mem] buffer len = 0x17 to PA = 0x00000000DAF49B8F
-      2  0 17  2  0  0  0  1  0  0  0  4 f8 d1 fe  0 |
-      0  0  0  9 60  0  0                            |     `
-     [mem] 0x00000000DAF49B8F
-     [*] Modified entry:
-      2  0 17  2  0  0  0  1  0  0  0  4 f8 d1 fe  0 |
-      0  0  0  9 60  0  0                            |     `
-     [*] After sleep/resume, check the value of register 0xFED1F804 is 0x6009
-     [+] PASSED: The script has been modified. Go to sleep..
-
-Now go to S3, then resume and check `FLOCKDN`. It should be 0:
-
-    sudo chipsec_main -m chipsec.modules.common.spi_lock
-
-    ...
-    [x][ =======================================================================
-    [x][ Module: SPI Flash Controller Configuration Locks
-    [x][ =======================================================================
-    [*] HSFS = 0x6008 << Hardware Sequencing Flash Status Register (SPIBAR + 0x4)
-        [00] FDONE            = 0 << Flash Cycle Done
-        [01] FCERR            = 0 << Flash Cycle Error
-        [02] AEL              = 0 << Access Error Log
-        [03] BERASE           = 1 << Block/Sector Erase Size
-        [05] SCIP             = 0 << SPI cycle in progress
-        [13] FDOPSS           = 1 << Flash Descriptor Override Pin-Strap Status
-        [14] FDV              = 1 << Flash Descriptor Valid
-        [15] FLOCKDN          = 0 << Flash Configuration Lock-Down
-    [-] SPI Flash Controller configuration is not locked
-    [-] FAILED: SPI Flash Controller not locked correctly.
-    ...
-
-Remove WP from protected ranges:
-
-    sudo chipsec_util mmio write SPIBAR 0x74 0x4 0xAAF0800
-    sudo chipsec_util mmio write SPIBAR 0x78 0x4 0xADE0AD0
-    sudo chipsec_util mmio write SPIBAR 0x7C 0x4 0xB100B10
-    sudo chipsec_util mmio write SPIBAR 0x80 0x4 0xBFF0B40
-
-Verify that it worked:
-
-    sudo chipsec_main -m common.bios_wp
-
-    [x][ =======================================================================
-    [x][ Module: BIOS Region Write Protection
-    [x][ =======================================================================
-    [*] BC = 0x 9 << BIOS Control (b:d.f 00:31.0 + 0xDC)
-        [00] BIOSWE           = 1 << BIOS Write Enable
-        [01] BLE              = 0 << BIOS Lock Enable
-        [02] SRC              = 2 << SPI Read Configuration
-        [04] TSS              = 0 << Top Swap Status
-        [05] SMM_BWP          = 0 << SMM BIOS Write Protection
-    [-] BIOS region write protection is disabled!
-
-    [*] BIOS Region: Base = 0x00500000, Limit = 0x00BFFFFF
-    SPI Protected Ranges
-    ------------------------------------------------------------
-    PRx (offset) | Value    | Base     | Limit    | WP? | RP?
-    ------------------------------------------------------------
-    PR0 (74)     | 0AAF0800 | 00800000 | 00AAF000 | 0   | 0
-    PR1 (78)     | 0ADE0AD0 | 00AD0000 | 00ADE000 | 0   | 0
-    PR2 (7C)     | 0B100B10 | 00B10000 | 00B10000 | 0   | 0
-    PR3 (80)     | 0BFF0B40 | 00B40000 | 00BFF000 | 0   | 0
-    PR4 (84)     | 00000000 | 00000000 | 00000000 | 0   | 0
-
-Bingo!
-
-Now you can [flash internally](/flash_tutorial/int_flashrom.md).
-Remember to flash only the `bios` region (use `--ifd -i bios -N`
-flashrom arguments). `fd` and `me` are still locked.
-
-Note that you should have an external SPI programmer as a backup method.
-It will help you recover if you flash non-working ROM by mistake.

Documentation/mainboard/lenovo/montevina_series.md

@@ -1,164 +0,0 @@
-# Lenovo X200 / T400 / T500 / X301 common
-
-These models are sold with either 8 MiB or 4 MiB flash chip. You can identify
-the chip in your machine through flashrom:
-```console
-# flashrom -p internal
-```
-
-Note that this does not allow you to determine whether the chip is in a SOIC-8
-or a SOIC-16 package.
-
-## Installing without ME firmware
-
-```eval_rst
-.. Note::
-   **ThinkPad R500** has slightly different flash layout (it doesn't have
-   ``gbe`` region), so the process would be a little different for that model.
-```
-
-On Montevina machines it's possible to disable ME and remove its firmware from
-SPI flash by modifying the flash descriptor. This also makes it possible to use
-the flash region the ME used for `bios` region, allowing for much larger
-payloads.
-
-First of all create a backup of your ROM with an external programmer:
-```console
-# flashrom -p YOUR_PROGRAMMER -r backup.rom
-```
-
-Then, split the IFD regions into separate files with ifdtool. You will need
-`flashregion_3_gbe.bin` later.
-```console
-$ ifdtool -x backup.rom
-```
-
-Now you need to patch the flash descriptor. You can either [modify the one from
-your backup with **ifdtool**](#modifying-flash-descriptor-using-ifdtool), or
-[generate a completely new one with **bincfg**](#creating-a-new-flash-descriptor-using-bincfg).
-
-#### Modifying flash descriptor using ifdtool
-
-Pick the layout according to your chip size from the table below and save it to
-the `new_layout.txt` file:
-
-```eval_rst
-+---------------------------+---------------------------+---------------------------+
-| 4 MB chip                 | 8 MB chip                 | 16 MB chip                |
-+===========================+===========================+===========================+
-| .. code-block:: none      | .. code-block:: none      | .. code-block:: none      |
-|                           |                           |                           |
-|    00000000:00000fff fd   |    00000000:00000fff fd   |    00000000:00000fff fd   |
-|    00001000:00002fff gbe  |    00001000:00002fff gbe  |    00001000:00002fff gbe  |
-|    00003000:003fffff bios |    00003000:007fffff bios |    00003000:01ffffff bios |
-|    00fff000:00000fff pd   |    00fff000:00000fff pd   |    00fff000:00000fff pd   |
-|    00fff000:00000fff me   |    00fff000:00000fff me   |    00fff000:00000fff me   |
-+---------------------------+---------------------------+---------------------------+
-```
-
-The last two lines define `pd` and `me` regions of negative size. This way
-ifdtool will mark those as unused.
-
-Update regions in the flash descrpitor (it was extracted previously with
-`ifdtool -x`):
-```console
-$ ifdtool -n new_layout.txt flashregion_0_flashdescriptor.bin
-```
-
-Set `MeDisable` bit in ICH0 and MCH0 straps:
-```console
-$ ifdtool -M 1 flashregion_0_flashdescriptor.bin.new
-```
-
-Delete previous descriptors and rename the final one:
-```console
-$ rm flashregion_0_flashdescriptor.bin
-$ rm flashregion_0_flashdescriptor.bin.new
-$ mv flashregion_0_flashdescriptor.bin.new.new flashregion_0_flashdescriptor.bin
-```
-
-Continue to the [Configuring coreboot](#configuring-coreboot) section.
-
-#### Creating a new flash descriptor using bincfg
-
-There is a tool to generate a modified flash descriptor called **bincfg**. Go to
-`util/bincfg` and build it:
-```console
-$ cd util/bincfg
-$ make
-```
-
-If your flash is not 8 MB, you need to change values of `flcomp_density1` and
-`flreg1_limit` in the ifd-x200.set file according to following table:
-
-```eval_rst
-+-----------------+-------+-------+--------+
-|                 | 4 MB  | 8 MB  | 16 MB  |
-+=================+=======+=======+========+
-| flcomp_density1 | 0x3   | 0x4   | 0x5    |
-+-----------------+-------+-------+--------+
-| flreg1_limit    | 0x3ff | 0x7ff | 0x1fff |
-+-----------------+-------+-------+--------+
-```
-
-Then create the flash descriptor:
-```console
-$ ./bincfg ifd-x200.spec ifd-x200.set ifd.bin
-```
-
-#### Configuring coreboot
-
-Now configure coreboot. You need to select correct chip size and specify paths
-to flash descriptor and gbe dump.
-
-```
-Mainboard --->
-    ROM chip size (8192 KB (8 MB)) # According to your chip
-    (0x7fd000) Size of CBFS filesystem in ROM # or 0x3fd000 for 4 MB chip / 0x1ffd000 for 16 MB chip
-
-Chipset --->
-    [*] Add Intel descriptor.bin file
-    # Note: if you used bincfg, specify path to generated util/bincfg/ifd.bin
-    (/path/to/flashregion_0_flashdescriptor.bin) Path and filename of the descriptor.bin file
-
-    [*] Add gigabit ethernet configuration
-    (/path/to/flashregion_3_gbe.bin) Path to gigabit ethernet configuration
-```
-
-Then build coreboot and flash whole `build/coreboot.rom` to the chip.
-
-## Installing with ME firmware
-
-To install coreboot and keep ME working, you don't need to do anything special
-with the flash descriptor. Just flash only `bios` externally and don't touch any
-other regions:
-```console
-# flashrom -p YOUR_PROGRAMMER -w coreboot.rom --ifd -i bios
-```
-
-## Flash layout
-
-The flash layouts of the OEM firmware are as follows:
-
-```eval_rst
-+---------------------------------+---------------------------------+
-| 4 MB chip                       | 8 MB chip                       |
-+=================================+=================================+
-| .. code-block:: none            | .. code-block:: none            |
-|                                 |                                 |
-|    00000000:00000fff fd         |    00000000:00000fff fd         |
-|    00001000:001f5fff me         |    00001000:005f5fff me         |
-|    001f6000:001f7fff gbe        |    005f6000:005f7fff gbe        |
-|    001f8000:001fffff pd         |    005f8000:005fffff pd         |
-|    00200000:003fffff bios       |    00600000:007fffff bios       |
-|    00290000:002affff ec         |    00690000:006affff ec         |
-|    003e0000:003fffff bootblock  |    007e0000:007fffff bootblock  |
-+---------------------------------+---------------------------------+
-```
-
-On each boot of vendor BIOS `ec` area in flash is checked for having firmware
-there, and if there is one, it proceedes to update firmware on H8S/2116 (when
-both external power and main battery are attached). Once update is performed,
-first 64 KB of `ec` area is erased. Visit
-[thinkpad-ec repository](https://github.com/hamishcoleman/thinkpad-ec) to learn
-more about how to extract EC firmware from vendor updates.

Documentation/mainboard/lenovo/r60.md

@@ -1,44 +0,0 @@
-# Lenovo Thinkpad R60
-
-Untested on boards with external Radeon graphics adapter. If you have such
-board, proceed at your own risk and document if it does work.
-
-## Flashing instructions
-
-### External flashing
-
-The flash IC is located at the bottom center of the mainboard. Access to
-the flash chip is blocked by the magnesium frame, so you need to disassemble
-the entire laptop and remove the mainboard. The flash chip is referenced as U49 in
-the schematics and in the boardview.
-
-![](r60_chip.jpg)
-
-To disassemble the laptop, follow the [Hardware Maintenance Manual](https://thinkpads.com/support/hmm/hmm_pdf/42x3749_02.pdf).
-
-### Internal flashing on Vendor BIOS
-
-This [method](https://gist.github.com/ArthurHeymans/c5ef494ada01af372735f237f6c6adbe) describes a way to install coreboot with vendor firmware still
-installed on the Lenovo Thinkpad X60. It is reported to also work in Thinkpad
-R60, with the only difference being the board target you build coreboot for.
-
-### Flashing on coreboot
-
-Default configuration of coreboot doesn't feature any flash restrictions
-like the vendor firmware, therefore flashrom is able to flash any rom without problems.
-
-## Things tested and working in Linux 5.3:
-
-- Intel WiFi card
-- Suspend and resume
-- Native graphics initialization. Both legacy VGA and linear framebuffer work
-- GRUB2 2.04 and SeaBIOS 1.12.1 payloads
-- Reflashing with flashrom (use flashrom-git as of 17.09.2019)
-- 2G+1G memory configuration working
-- 2504 dock USB ports if not hotplugged
-
-## Things tested and not working:
-
-- 2504 dock hotplugging
-- Black bar at the left side of the screen. Doesn't appear in Linux. See picture at top
-- Sometimes it takes several second to run coreboot. Just wait for it

Documentation/mainboard/lenovo/t410.md

@@ -1,44 +0,0 @@
-# Lenovo T410
-
-## Known issues
-* Dock has wrong ACPI ID (causes "AC adapter state cannot be read" in Linux)
-* TPM not working with VBOOT and C_ENV bootblock (works without C_ENV BB)
-
-## Flashing instructions
-```eval_rst
-+---------------------+--------------------------------+
-| Type                | Value                          |
-+=====================+================================+
-| Socketed flash      | no                             |
-+---------------------+--------------------------------+
-| Size                | 8 MiB                          |
-+---------------------+--------------------------------+
-| In circuit flashing | Only in S3/WoL                 |
-+---------------------+--------------------------------+
-| Package             | SOIC-8                         |
-+---------------------+--------------------------------+
-| Write protection    | No                             |
-+---------------------+--------------------------------+
-| Dual BIOS feature   | No                             |
-+---------------------+--------------------------------+
-| Internal flashing   | Yes                            |
-+---------------------+--------------------------------+
-```
-
-The flash IC is located at the bottom center of the mainboard.  Sadly,
-access to the IC is blocked by the magnesum frame, so you need to disassemble
-the entire laptop and remove the mainboard.
-
-Below is a picture of IC on the mainboard, with the pinouts labeled.
-
-![t410_chip_location](t410_chip_location.jpg)
-
-The chip will either be a Macronix MX25L6405D or a Winbond W25Q64CVSIG.
-Do not rely on dots painted in the corner of the chip (such as the blue dot
-pictured) to orient the pins!
-
-[Flashing tutorial](../../flash_tutorial/no_ext_power.md)
-
-Steps to access the flash IC are described here [T4xx series].
-
-[T4xx series]: t4xx_series.md

Documentation/mainboard/lenovo/t420.md

@@ -14,10 +14,12 @@ W25Q64CVSIG.  Do not rely on dots painted in the corner of the chip (such as
 the blue dot pictured) to orient the pins!
 
 For more details have a look at [T420 / T520 / X220 / T420s / W520 common] and
-the general [flashing tutorial].
+
+```eval_rst
+:doc:`../../flash_tutorial/ext_power`
+```
 
 Steps to access the flash IC are described here [T4xx series].
 
 [T4xx series]: t4xx_series.md
-[flashing tutorial]: ../../flash_tutorial/ext_power.md
-[T420 / T520 / X220 / T420s / W520 common]: Sandy_Bridge_series.md
+[T420 / T520 / X220 / T420s / W520 common]: xx20_series.md