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>

.checkpatch.conf

@@ -20,8 +20,6 @@
 --ignore SPDX_LICENSE_TAG
 --ignore UNDOCUMENTED_DT_STRING
 --ignore PRINTK_WITHOUT_KERN_LEVEL
---ignore ASSIGN_IN_IF
---ignore UNNECESSARY_ELSE
 
 # FILE_PATH_CHANGES seems to not be working correctly. It will
 # choke on added / deleted files even if the MAINTAINERS file
@@ -32,8 +30,5 @@
 # some commits unnecessarily.
 --ignore EXECUTE_PERMISSIONS
 
-# Exclude vendorcode directories that don't follow coreboot's coding style.
+# Exclude the vendorcode directory
---exclude src/vendorcode/amd
+--exclude src/vendorcode
---exclude src/vendorcode/cavium
---exclude src/vendorcode/intel
---exclude src/vendorcode/mediatek

.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

@@ -1,3 +1,6 @@
+payloads/libpayload/install/
+payloads/nvramcui/build
+payloads/nvramcui/libpayload
 junit.xml
 abuild*.xml
 .config
@@ -8,25 +11,58 @@ defconfig
 .ccwrap
 build/
 coreboot-builds/
-coreboot-builds*/
+payloads/coreinfo/lpbuild/
-
+payloads/coreinfo/lp.config*
+payloads/external/depthcharge/depthcharge/
+payloads/external/FILO/filo/
+payloads/external/GRUB2/grub2/
+payloads/external/LinuxBoot/linuxboot/
+payloads/external/SeaBIOS/seabios/
+payloads/external/tianocore/tianocore/
+payloads/external/tint/tint/
+payloads/external/U-Boot/u-boot/
+payloads/external/Memtest86Plus/memtest86plus/
+payloads/external/iPXE/ipxe/
+util/crossgcc/acpica-unix-*/
+util/crossgcc/binutils-*/
+util/crossgcc/build-*BINUTILS/
+util/crossgcc/build-*EXPAT/
+util/crossgcc/build-*GCC/
+util/crossgcc/build-*GDB/
+util/crossgcc/build-*GMP/
+util/crossgcc/build-*LIBELF/
+util/crossgcc/build-*MPC/
+util/crossgcc/build-*MPFR/
+util/crossgcc/build-*PYTHON/
+util/crossgcc/build-*LVM/
+util/crossgcc/build-*IASL/
+util/crossgcc/expat-*/
+util/crossgcc/gcc-*/
+util/crossgcc/gdb-*/
+util/crossgcc/gmp-*/
+util/crossgcc/libelf-*/
+util/crossgcc/mingwrt-*/
+util/crossgcc/mpc-*/
+util/crossgcc/mpfr-*/
+util/crossgcc/Python-*/
+util/crossgcc/*.src/
+util/crossgcc/tarballs/
+util/crossgcc/w32api-*/
+util/crossgcc/xgcc/
+util/crossgcc/xgcc-*/
+util/crossgcc/xgcc
 site-local
 
 *.\#
-*.a
 *.bin
 *.debug
-!Kconfig.debug
 *.elf
-*.fd
 *.o
-*.o.d
 *.out
 *.pyc
 *.sw[po]
 /*.rom
-.test
+coreboot-builds*/
-.dependencies
 
 # Development friendly files
 tags
@@ -36,9 +72,63 @@ tags
 xgcc/
 tarballs/
 
-# editor backup files, temporary files, IDE project files
+#
+# KDE editors create lots of backup files whenever
+# a file is edited, so just ignore them
 *~
 *.kate-swp
+# Ignore Kdevelop project file
 *.kdev4
 
+util/*/.dependencies
+util/*/.test
+util/amdfwtool/amdfwtool
+util/archive/archive
+util/bimgtool/bimgtool
+util/bincfg/bincfg
+util/board_status/board-status
+util/bucts/bucts
+util/cbfstool/cbfs-compression-tool
+util/cbfstool/cbfstool
+util/cbfstool/fmaptool
+util/cbfstool/ifwitool
+util/cbfstool/rmodtool
+util/cbmem/.dependencies
+util/cbmem/cbmem
+util/dumpmmcr/dumpmmcr
+util/ectool/ectool
+util/futility/futility
+util/genprof/genprof
+util/getpir/getpir
+util/ifdtool/ifdtool
+util/intelmetool/intelmetool
+util/inteltool/.dependencies
+util/inteltool/inteltool
+util/intelvbttool/intelvbttool
+util/k8resdump/k8resdump
+util/lbtdump/lbtdump
+util/mptable/mptable
+util/msrtool/Makefile
+util/msrtool/Makefile.deps
+util/msrtool/msrtool
+util/nvramtool/.dependencies
+util/nvramtool/nvramtool
+util/optionlist/Options.wiki
+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
+
+Documentation/*.aux
+Documentation/*.idx
+Documentation/*.log
+Documentation/*.toc
+Documentation/*.out
+Documentation/*.pdf
+Documentation/_build
+
 doxygen/*

.gitmodules

@@ -1,62 +1,28 @@
 [submodule "3rdparty/blobs"]
 	path = 3rdparty/blobs
-	url = https://review.coreboot.org/blobs.git
+	url = https://github.com/coreboot/blobs.git
 	update = none
 	ignore = dirty
 [submodule "util/nvidia-cbootimage"]
 	path = util/nvidia/cbootimage
-	url = https://review.coreboot.org/nvidia-cbootimage.git
+	url = https://github.com/coreboot/nvidia-cbootimage.git
 [submodule "vboot"]
 	path = 3rdparty/vboot
-	url = https://review.coreboot.org/vboot.git
+	url = https://github.com/coreboot/vboot.git
-	branch = main
 [submodule "arm-trusted-firmware"]
 	path = 3rdparty/arm-trusted-firmware
-	url = https://review.coreboot.org/arm-trusted-firmware.git
+	url = https://github.com/coreboot/arm-trusted-firmware.git
 [submodule "3rdparty/chromeec"]
 	path = 3rdparty/chromeec
-	url = https://review.coreboot.org/chrome-ec.git
+	url = https://github.com/coreboot/chrome-ec.git
 [submodule "libhwbase"]
 	path = 3rdparty/libhwbase
-	url = https://review.coreboot.org/libhwbase.git
+	url = https://github.com/coreboot/libhwbase.git
 [submodule "libgfxinit"]
 	path = 3rdparty/libgfxinit
-	url = https://review.coreboot.org/libgfxinit.git
+	url = https://github.com/coreboot/libgfxinit.git
 [submodule "3rdparty/fsp"]
 	path = 3rdparty/fsp
-	url = https://review.coreboot.org/fsp.git
+	url = https://github.com/coreboot/fsp.git
 	update = none
 	ignore = dirty
-[submodule "opensbi"]
-	path = 3rdparty/opensbi
-	url = https://review.coreboot.org/opensbi.git
-[submodule "intel-microcode"]
-	path = 3rdparty/intel-microcode
-	url = https://review.coreboot.org/intel-microcode.git
-	update = none
-	ignore = dirty
-	branch = main
-[submodule "3rdparty/ffs"]
-	path = 3rdparty/ffs
-	url = https://review.coreboot.org/ffs.git
-[submodule "3rdparty/amd_blobs"]
-	path = 3rdparty/amd_blobs
-	url = https://review.coreboot.org/amd_blobs
-	update = none
-	ignore = dirty
-[submodule "3rdparty/cmocka"]
-	path = 3rdparty/cmocka
-	url = https://review.coreboot.org/cmocka.git
-	update = none
-[submodule "3rdparty/qc_blobs"]
-	path = 3rdparty/qc_blobs
-	url = https://review.coreboot.org/qc_blobs.git
-	update = none
-	ignore = dirty
-[submodule "3rdparty/intel-sec-tools"]
-	path = 3rdparty/intel-sec-tools
-	url = https://review.coreboot.org/9esec-security-tooling.git
-[submodule "3rdparty/stm"]
-	path = 3rdparty/stm
-	url = https://review.coreboot.org/STM
-	branch = stmpe

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/.gitignore

@@ -1,7 +0,0 @@
-*.aux
-*.idx
-*.log
-*.toc
-*.out
-*.pdf
-_build

Documentation/Intel/Board/board.html

@@ -0,0 +1,239 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Board</title>
+  </head>
+  <body>
+
+<h1>x86 Board Development</h1>
+<p>
+  Board development requires System-on-a-Chip (SoC) support.
+  The combined steps are listed
+  <a target="_blank" href="../development.html">here</a>.
+  The development steps for the board are listed below:
+</p>
+<ol>
+  <li><a href="#RequiredFiles">Required Files</a></li>
+  <li>Enable <a href="#SerialOutput">Serial Output</a></li>
+  <li>Load the <a href="#SpdData">Memory Timing Data</a></li>
+  <li><a href="#DisablePciDevices">Disable</a> the PCI devices</li>
+  <li><a href="#AcpiTables">ACPI Tables</a></li>
+</ol>
+
+
+<hr>
+<h2><a name="RequiredFiles">Required Files</a></h2>
+<p>
+  Create the board directory as src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;.
+</p>
+
+<p>
+  The following files are required to build a new board:
+</p>
+<ol>
+  <li>Kconfig.name - Defines the Kconfig value for the board</li>
+  <li>Kconfig
+    <ol type="A">
+      <li>Selects the SoC for the board and specifies the SPI flash size
+        <ol type="I">
+          <li>BOARD_ROMSIZE_KB_&lt;Size&gt;</li>
+          <li>SOC_&lt;Vendor&gt;_&lt;Chip Family&gt;</li>
+        </ol>
+      </li>
+      <li>Declare the Kconfig values for:
+        <ol type="I">
+          <li>MAINBOARD_DIR</li>
+          <li>MAINBOARD_PART_NUMBER</li>
+          <li>MAINBOARD_VENDOR</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>devicetree.cb - Enable root bridge and serial port
+    <ol type="A">
+      <li>The first line must be "chip soc/Intel/&lt;soc family&gt;";
+        this path is used by the generated static.c to include the chip.h
+        header file
+      </li>
+    </ol>
+  </li>
+  <li>romstage.c
+    <ol type="A">
+      <li>Add routine mainboard_romstage_entry which calls romstage_common</li>
+    </ol>
+  </li>
+  <li>Configure coreboot build:
+    <ol type="A">
+      <li>Set LOCALVERSION</li>
+      <li>Select vendor for the board</li>
+      <li>Select the board</li>
+      <li>CBFS_SIZE = 0x00100000</li>
+      <li>Set the CPU_MICROCODE_CBFS_LEN</li>
+      <li>Set the CPU_MICROCODE_CBFS_LOC</li>
+      <li>Set the FSP_IMAGE_ID_STRING</li>
+      <li>Set the FSP_LOC</li>
+      <li>No payload</li>
+      <li>Choose the default value for all other options</li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="SerialOutput">Enable Serial Output</a></h2>
+<p>
+  Use the following steps to enable serial output:
+</p>
+<ol>
+  <li>Implement the car_mainboard_pre_console_init routine in the com_init.c
+    file:
+    <ol type="A">
+      <li>Power on and enable the UART controller</li>
+      <li>Connect the UART receive and transmit data lines to the
+        appropriate SoC pins
+      </li>
+    </ol>
+  </li>
+  <li>Add Makefile.inc
+    <ol type="A">
+      <li>Add com_init.c to romstage</li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="SpdData">Memory Timing Data</a></h2>
+<p>
+  Memory timing data is located in the flash.  This data is in the format of
+  <a target="_blank" href="https://en.wikipedia.org/wiki/Serial_presence_detect">serial presence detect</a>
+  (SPD) data.
+  Use the following steps to load the SPD data:
+</p>
+<ol>
+  <li>Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the
+    display of the SPD data being passed to MemoryInit
+  </li>
+  <li>Create an "spd" subdirectory</li>
+  <li>Create an spd/spd.c file for the SPD implementation
+    <ol type="A">
+      <li>Implement the mainboard_fill_spd_data routine
+        <ol type="i">
+          <li>Read the SPD data either from the spd.bin file or using I2C or SMBUS</li>
+          <li>Fill in the pei_data structure with SPD data for each of the DIMMs</li>
+          <li>Set the DIMM channel configuration</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>Add an .spd.hex file containing the memory timing data to the spd subdirectory</li>
+  <li>Create spd/Makefile.inc
+    <ol type="A">
+      <li>Add spd.c to romstage</li>
+      <li>Add the .spd.hex file to SPD_SOURCES</li>
+    </ol>
+  </li>
+  <li>Edit Makefile.inc to add the spd subdirectory</li>
+  <li>Edit romstage.c
+    <ol type="A">
+      <li>Call mainboard_fill_spd_data</li>
+      <li>Add mainboard_memory_init_params to copy the SPD and DRAM
+        configuration data from the pei_data structure into the UPDs
+        for MemoryInit
+      </li>
+    </ol>
+  </li>
+  <li>Edit devicetree.cb
+    <ol type="A">
+      <li>Include the UPD parameters for MemoryInit except for:
+        <ul>
+          <li>Address of SPD data</li>
+          <li>DRAM configuration set above</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>A working FSP
+    <a target="_blank" href="../fsp1_1.html#MemoryInit">MemoryInit</a>
+    routine is required to complete debugging</li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x34:
+        - Just after entering
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
+      </li>
+      <li>0x36:
+        - Just before displaying the
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l106">UPD parameters</a>
+        for FSP MemoryInit
+      </li>
+      <li>0x92: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l219">POST_FSP_MEMORY_INIT</a>
+        - Just before calling FSP
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l125">MemoryInit</a>
+      </li>
+      <li>0x37:
+        - Just after returning from FSP
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l127">MemoryInit</a>
+      </li>
+    </ol>
+  </li>
+  <li>Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called</li>
+</ol>
+
+
+
+<hr>
+<h2><a name="DisablePciDevices">Disable PCI Devices</a></h2>
+<p>
+  Ramstage's BS_DEV_ENUMERATE state displays the PCI vendor and device IDs for all
+  of the devices in the system.  Edit the devicetree.cb file:
+</p>
+<ol>
+  <li>Edit the devicetree.cb file:
+    <ol type="A">
+      <li>Add an entry for a PCI device.function and turn it off.  The entry
+        should look similar to:
+<pre><code>device pci 14.0 off end</code></pre>
+      </li>
+      <li>Turn on the devices for:
+        <ul>
+          <li>Memory Controller</li>
+          <li>Debug serial device</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices</li>
+</ol>
+
+
+
+<hr>
+<h2><a name="AcpiTables">ACPI Tables</a></h2>
+<ol>
+  <li>Edit Kconfig
+    <ol type="A">
+      <li>Add "select HAVE_ACPI_TABLES"</li>
+    </ol>
+  </li>
+  <li>Add the acpi_tables.c module:
+    <ol type="A">
+      <li>Include soc/acpi.h</li>
+      <li>Add the acpi_create_fadt routine
+        <ol type="I">
+          <li>fill in the ACPI header</li>
+          <li>Call the acpi_fill_in_fadt routine</li>
+        </ol>
+      </li>
+    </ol>
+  </li>
+  <li>Add the dsdt.asl module:
+  </li>
+</ol>
+
+
+
+<hr>
+<p>Modified: 20 February 2016</p>
+  </body>
+</html>

Documentation/Intel/Board/galileo.html

@@ -0,0 +1,113 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Galileo</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; Galileo Development Board</h1>
+<table>
+  <tr>
+    <td><a target="_blank" href="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg"><img alt="Galileo Gen 2" src="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg" width=500></a></td>
+    <td>
+      The Intel&reg; Galileo Gen 2 mainboard code was developed along with the Intel&reg;
+      <a target="_blank" href="../SoC/quark.html">Quark&trade;</a> SoC:
+      <ul>
+        <li><a target="_blank" href="../development.html">Overall</a> development</li>
+        <li><a target="_blank" href="../SoC/soc.html">SoC</a> support</li>
+        <li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
+        <li><a target="_blank" href="board.html">Board</a> support</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+
+<hr>
+<h2>Galileo Board Documentation</h2>
+<ul>
+  <li>Common Components
+    <ul>
+      <li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li>
+      <li>Analog Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li>
+      <li>Ethernet (10/100 MB/S): Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/dp83848-ep.pdf">DP83848</a></li>
+      <li>Load Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps22920.pdf">TPS22920x</a></li>
+      <li>Memory (256 MiB): Micron <a target="_blank" href="https://www.micron.com/~/media/Documents/Products/Data%20Sheet/DRAM/DDR3/1Gb_1_35V_DDR3L.pdf">MT41K128M8</a></li>
+      <li>SoC: Intel&reg; Quark&trade; <a target="_blank" href="../SoC/quark.html">X-1000</a></li>
+      <li>Serial EEPROM (1 KiB): ON Semiconductor&reg; <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li>
+      <li>SPI Flash (8 MiB): Winbond&trade; <a target="_blank" href="http://www.winbond-usa.com/resource-files/w25q64fv_revl1_100713.pdf">W25Q64FV</a></li>
+      <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li>
+      <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ug/slvu570/slvu570.pdf">TPS652510</a></li>
+      <li>Termination Regulator: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps51200.pdf">TPS51200</a></li>
+    </ul>
+  </li>
+  <li>Make a bootable <a target="_blank" href="https://software.intel.com/en-us/get-started-galileo-linux-step1">micro SD card</a></li>
+</ul>
+
+<h3>Galileo Gen 2 Board Documentation</h3>
+<ul>
+  <li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_blockdiagram.jpg">Block Diagram</a></li>
+  <li><a target="_blank" href="https://software.intel.com/en-us/iot/library/galileo-getting-started">Getting Started</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-overview.html">Overview</a></li>
+  <li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_ports.jpg">Port Diagram</a></li>
+  <li><a target="_blank" href="http://download.intel.com/support/galileo/sb/intelgalileogen2prodbrief_330736_003.pdf">Product Brief</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g2-schematic.pdf">Schematic</a></li>
+  <li><a target="_blank" href="http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf">User Guide</a></li>
+  <li>Components
+    <ul>
+      <li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li>
+      <li>I2C 16-channel, 12-bit PWM: NXP Semiconductors <a target="_blank" href="http://cache.nxp.com/documents/data_sheet/PCA9685.pdf">PCA9685</a></li>
+      <li>I2C I/O Ports: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/PCAL9535A.pdf">PCAL9535A</a></li>
+      <li>Octal Buffer/Driver: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv541at.pdf">SN74LV541AT</a></li>
+      <li>Quadruple Bus Buffer: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv125a.pdf">SN74LV125A</a></li>
+      <li>Quadruple Bus Buffer with 3-State Outputs: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lvc126a.pdf">SN74LVC126A</a></li>
+      <li>Serial EEPROM (1 KiB): ON Semiconductor&reg; <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li>
+      <li>Single 2-input multiplexer: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/74LVC1G157.pdf">74LVC1G157</a></li>
+      <li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li>
+    </ul>
+  </li>
+</ul>
+
+<h3>Galileo Gen 1 Board Documentation</h3>
+<ul>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/galileo-g1-datasheet.pdf">Datasheet</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g1-schematic.pdf">Schematic</a></li>
+  <li>Components
+    <ul>
+      <li>A/D: Analog Devices <a target="_blank" href="http://www.analog.com/media/en/technical-documentation/data-sheets/AD7298-1.pdf">AD7298</a></li>
+      <li>Analog Switch, 2 channel: Texas Instruments <a target="_blank" href="http://www.ti.com.cn/cn/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li>
+      <li>EEPROM & GPIO: Cypress <a target="_blank" href="http://www.cypress.com/file/37971/download">CY8C9540A</a></li>
+      <li>Power Distribution Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps2044b.pdf">TPS2051BDBVR</a></li>
+      <li>RS232 Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/max3232.pdf">MAX3232</a></li>
+      <li>Voltage-Level Translator: Texas Instruments<a target="_blank" href="http://www.ti.com/lit/ds/symlink/txs0108e.pdf">TXS0108E</a></li>
+    </ul>
+  </li>
+</ul>
+
+
+
+<hr>
+<h2>Debug Tools</h2>
+<ul>
+  <li>Flash Programmer:
+    <ul>
+      <li>Dediprog <a target="_blank" href="http://www.dediprog.com/pd/spi-flash-solution/SF100">SF100</a> ISP IC Programmer</li>
+    </ul>
+  </li>
+  <li>JTAG Connector: <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=Olimex+ARM-JTAG-20-10">Olimex ARM-JTAG-20-10</a></li>
+  <li>JTAG Debugger:
+    <ul>
+      <li>Olimex LTD <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=Olimex+ARM-USB-OCD-H">ARM-USB-OCD-H</a></li>
+      <li>Tincan Tools <a target="_blank" href="https://www.tincantools.com/wiki/Flyswatter2">Flyswatter2</a></li>
+    </ul>
+  </li>
+  <li><a target="_blank" href="http://download.intel.com/support/processors/quark/sb/sourcedebugusingopenocd_quark_appnote_330015_003.pdf">Hardware Setup and Software Installation</a></li>
+  <li>USB Serial cable: FTDI <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=FTDI+TTL-232R-3V3">TTL-232R-3V3</a></li>
+</ul>
+
+
+<hr>
+<p>Modified: 29 February 2016</p>
+  </body>
+</html>

Documentation/Intel/SoC/quark.html

@@ -0,0 +1,220 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Quark&trade; SoC</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; Quark&trade; SoC</h1>
+<table>
+  <tr>
+    <td><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png"><img alt="Quark Block Diagram" src="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png" width=500></a></td>
+    <td>
+      The Quark&trade; SoC code was developed using the
+      <a target="_blank" href="../Board/galileo.html">Galileo Gen 2</a>
+      board:
+      <ul>
+        <li><a target="_blank" href="../development.html">Overall</a> development</li>
+        <li><a target="_blank" href="soc.html">SoC</a> support</li>
+        <li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
+        <li><a target="_blank" href="../Board/board.html">Board</a> support</li>
+        <li><a target="_blank" href="#QuarkFsp">Quark&trade; FSP</a></li>
+        <li><a target="_blank" href="#CorebootPayloadPkg">CorebootPayloadPkg</a></li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+
+<hr>
+<h2>Quark&trade; Documentation</h2>
+<ul>
+  <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png">Block Diagram</a></li>
+  <li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/quark/specifications.html">Specifications</a>:
+    <ul>
+      <li><a target="_blank" href="http://ark.intel.com/products/79084/Intel-Quark-SoC-X1000-16K-Cache-400-MHz">X1000</a>
+        - <a target="_blank" href="http://www.intel.com/content/www/us/en/search.html?keyword=X1000">Documentation</a>:
+        <ul>
+          <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/quark-x1000-datasheet.pdf">Datasheet</a></li>
+          <li><a target="_blank" href="http://www.intel.com/content/dam/support/us/en/documents/processors/quark/sb/intelquarkcore_devman_001.pdf">Developer's Manual</a></li>
+          <li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/intel-quark-product-brief-v3.pdf">Product Brief</a></li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><a target="_blank" href="../index.html#Documentation">More documentation</a></li>
+</ul>
+
+
+
+<hr>
+<h2><a name="CorebootPayloadPkg">Quark&trade; EDK2 CorebootPayloadPkg</a></h2>
+<p>
+Build Instructions:
+</p>
+<ol>
+  <li>Set up <a href="#BuildEnvironment">build environment</a></li>
+  <li>Linux (assumes GCC48):
+<pre><code>build  -p CorebootPayloadPkg/CorebootPayloadPkgIa32.dsc  -a IA32  \
+    -t GCC48  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  \
+    -DDEBUG_PRINT_ERROR_LEVEL=0x80000042  -DSHELL_TYPE=BUILD_SHELL  \
+    -DMAX_LOGICAL_PROCESSORS=1
+ls Build/CorebootPayloadPkgIA32/DEBUG_GCC48/FV/UEFIPAYLOAD.fd
+</code></pre>
+  </li>
+  <li>Windows (assumes Visual Studio 2015):
+<pre><code>build  -p CorebootPayloadPkg\CorebootPayloadPkgIa32.dsc  -a IA32  -t VS2015x86  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  -DDEBUG_PRINT_ERROR_LEVEL=0x80000042  -DSHELL_TYPE=BUILD_SHELL  -DMAX_LOGICAL_PROCESSORS=1
+dir Build\CorebootPayloadPkgIA32\DEBUG_VS2015x86\FV\UEFIPAYLOAD.fd
+</code></pre>
+  </li>
+  <li>In the .config for coreboot, set the following Kconfig values:
+    <ul>
+      <li>CONFIG_PAYLOAD_ELF=y</li>
+      <li>CONFIG_PAYLOAD_FILE="path to UEFIPAYLOAD.fd"</li>
+    </ul>
+  </li>
+  <li>Build coreboot</li>
+  <li>Copy the image build/coreboot.rom into flash</li>
+</ol>
+
+
+
+<hr>
+<h2><a name="BuildEnvironment">Quark&trade; EDK2 Build Environment</a></h2>
+<p>
+  Use the following steps to setup a build environment:
+</p>
+<ol>
+  <li>Get the EDK2 sources:
+    <ol type="A">
+      <li>EDK2: git clone <a target="_blank" href="https://github.com/tianocore/edk2.git">https://github.com/tianocore/edk2.git</a></li>
+      <li>EDK2-non-osi: git clone <a target="_blank" href="https://github.com/tianocore/edk2-non-osi.git">https://github.com/tianocore/edk2-non-osi.git</a></li>
+      <li>Win32 BaseTools: git clone <a target="_blank" href="https://github.com/tianocore/edk2-BaseTools-win32.git">https://github.com/tianocore/edk2-BaseTools-win32.git</a></li>
+    </ol>
+  </li>
+  <li>Set up a build window:
+    <ul>
+      <li>Linux:
+<pre><code>export WORKSPACE=$PWD
+export PACKAGES_PATH="$PWD/edk2:$PWD/edk2-non-osi"
+cd edk2
+export WORKSPACE=$PWD
+. edksetup.sh
+</code></pre>
+      </li>
+      <li>Windows:
+<pre><code>set WORKSPACE=%CD%
+set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi
+set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32
+cd edk2
+edksetup.bat
+</code></pre>
+      </li>
+    </ul>
+  </li>
+</ol>
+
+
+
+<hr>
+<h2><a name="QuarkFsp">Quark&trade; FSP</a></h2>
+<p>
+Getting the Quark FSP source:
+</p>
+<ol>
+  <li>Set up an EDK-II <a href="#BuildEnvironment">Build Environment</a></li>
+  <li>cd edk2</li>
+  <li>mkdir QuarkFspPkg</li>
+  <li>cd QuarkFspPkg</li>
+  <li>Use git to clone <a target="_blank" href="https://review.gerrithub.io/#/admin/projects/LeeLeahy/quarkfsp">QuarkFspPkg</a> into the QuarkFpsPkg directory (.)</li>
+</ol>
+
+<h3>Building QuarkFspPkg</h3>
+<p>
+There are two versions of FSP: FSP 1.1 and FSP 2.0.  There are also two
+different implementations of FSP, one using subroutines without SEC and
+PEI core and the original implementation which relies on SEC and PEI core.
+Finally there are two different build x86 types release (r32) and debug (d32).
+</p>
+<p>Note that the subroutine implementations are a <b>work in progress</b>.</p>
+<p>
+Build commands shown building debug FSP:
+</p>
+<ul>
+  <li>Linux:
+    <ul>
+      <li>QuarkFspPkg/BuildFsp1_1.sh  -d32</li>
+      <li>QuarkFspPkg/BuildFsp1_1Pei.sh  -d32</li>
+      <li>QuarkFspPkg/BuildFsp2_0.sh  -d32</li>
+      <li>QuarkFspPkg/BuildFsp2_0Pei.sh  -d32</li>
+    </ul>
+  <li>Windows:
+    <ul>
+      <li>QuarkFspPkg/BuildFsp1_1.bat  -d32</li>
+      <li>Windows: QuarkFspPkg/BuildFsp2_0.bat  -d32</li>
+    </ul>
+  </li>
+</ul>
+
+<h3>Copying FSP files into coreboot Source Tree</h3>
+<p>
+There are some helper scripts to copy the FSP output into the coreboot
+source tree.  The parameters to these scripts are:
+</p>
+<ol>
+  <li>EDK2 tree root</li>
+  <li>coreboot tree root</li>
+  <li>Build type: DEBUG or RELEASE</li>
+</ol>
+<p>
+Script files:
+</p>
+<ul>
+  <li>Linux:
+    <ul>
+      <li>QuarkFspPkg/coreboot_fsp1_1.sh</li>
+      <li>QuarkFspPkg/coreboot_fsp1_1Pei.sh</li>
+      <li>QuarkFspPkg/coreboot_fsp2_0.sh</li>
+      <li>QuarkFspPkg/coreboot_fsp2_0Pei.sh</li>
+    </ul>
+</ul>
+
+
+<hr>
+<h2>Quark&trade; EDK2 BIOS</h2>
+<p>
+Build Instructions:
+</p>
+<ol>
+  <li>Set up <a href="#BuildEnvironment">build environment</a></li>
+  <li>Build the image:
+    <ul>
+      <li>Linux:
+<pre><code>build -p QuarkPlatformPkg/Quark.dsc  -a IA32  -t GCC48  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  -DDEBUG_PRINT_ERROR_LEVEL=0x80000042
+ls Build/Quark/DEBUG_GCC48/FV/Quark.fd
+</code></pre>
+      </li>
+      <li>Windows:
+<pre><code>build -p QuarkPlatformPkg/Quark.dsc  -a IA32  -t VS2012x86  -b DEBUG  -DDEBUG_PROPERTY_MASK=0x27  -DDEBUG_PRINT_ERROR_LEVEL=0x80000042
+dir Build\Quark\DEBUG_VS2012x86\FV\Quark.fd
+</code></pre>
+  </li>
+    </ul>
+  </li>
+</ol>
+
+<p>
+Documentation:
+</p>
+<ul>
+  <li><a target="_blank" href="https://github.com/tianocore/edk2/tree/master/QuarkPlatformPkg">EDK II firmware for Intel&reg; Quark&trade; SoC X1000 based platforms</a></li>
+  <li>Intel&reg; Quark&trade; SoC X1000 <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/quark-x1000-uefi-firmware-writers-guide.pdf">UEFI Firmware Writer's Guide</a></li>
+</ul>
+
+
+
+<hr>
+<p>Modified: 17 May 2016</p>
+  </body>
+</html>

Documentation/Intel/SoC/soc.html

@@ -0,0 +1,731 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>SoC</title>
+  </head>
+  <body>
+
+<h1>x86 System on a Chip (SoC) Development</h1>
+<p>
+  SoC development is best done in parallel with development for a specific
+  board.  The combined steps are listed
+  <a target="_blank" href="../development.html">here</a>.
+  The development steps for the SoC are listed below:
+</p>
+<ol>
+  <li><a target="_blank" href="../fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
+  <li>SoC <a href="#RequiredFiles">Required Files</a></li>
+  <li><a href="#Descriptor">Start Booting</a></li>
+  <li><a href="#EarlyDebug">Early Debug</a></li>
+  <li><a href="#Bootblock">Bootblock</a></li>
+  <li><a href="#TempRamInit">TempRamInit</a></li>
+  <li><a href="#Romstage">Romstage</a>
+    <ol type="A">
+      <li>Enable <a href="#SerialOutput">Serial Output"</a></li>
+      <li>Get the <a href="#PreviousSleepState">Previous Sleep State</a></li>
+      <li>Add the <a href="#MemoryInit">MemoryInit</a> Support</li>
+      <li>Disable the <a href="#DisableShadowRom">Shadow ROM</a></li>
+    </ol>
+  </li>
+  <li><a href="#Ramstage">Ramstage</a>
+    <ol type="A">
+      <li><a href="#DeviceTree">Start Device Tree Processing</a></li>
+      <li>Set up the <a href="#MemoryMap">Memory Map"</a></li>
+    </ol>
+  </li>
+  <li><a href="#AcpiTables">ACPI Tables</a></li>
+  <li><a href="#LegacyHardware">Legacy Hardware</a></li>
+</ol>
+
+
+<hr>
+<h2><a name="RequiredFiles">Required Files</a></h2>
+<p>
+  Create the directory as src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;.
+</p>
+
+<p>
+  The following files are required to build a new SoC:
+</p>
+<ul>
+  <li>Include files
+    <ul>
+      <li>include/soc/pei_data.h</li>
+      <li>include/soc/pm.h</li>
+    </ul>
+  </li>
+  <li>Kconfig - Defines the Kconfig value for the SoC and selects the tool
+    chains for the various stages:
+    <ul>
+      <li>select ARCH_BOOTBLOCK_&lt;Tool Chain&gt;</li>
+      <li>select ARCH_RAMSTAGE_&lt;Tool Chain&gt;</li>
+      <li>select ARCH_ROMSTAGE_&lt;Tool Chain&gt;</li>
+      <li>select ARCH_VERSTAGE_&lt;Tool Chain&gt;</li>
+    </ul>
+  </li>
+  <li>Makefile.inc - Specify the include paths</li>
+  <li>memmap.c - Top of usable RAM</li>
+</ul>
+
+
+<hr>
+<h2><a name="Descriptor">Start Booting</a></h2>
+<p>
+  Some SoC parts require additional firmware components in the flash.
+  This section describes how to add those pieces.
+</p>
+
+<h3>Intel Firmware Descriptor</h3>
+<p>
+  The Intel Firmware Descriptor (IFD) is located at the base of the flash part.
+  The following command overwrites the base of the flash image with the Intel
+  Firmware Descriptor:
+</p>
+<pre><code>dd if=descriptor.bin of=build/coreboot.rom conv=notrunc >/dev/null 2>&1</code></pre>
+
+
+<h3><a name="MEB">Management Engine Binary</a></h3>
+<p>
+  Some SoC parts contain and require that the Management Engine (ME) be running
+  before it is possible to bring the x86 processor out of reset.  A binary file
+  containing the management engine code must be added to the firmware using the
+  ifdtool.  The following commands add this binary blob:
+</p>
+<pre><code>util/ifdtool/ifdtool -i ME:me.bin  build/coreboot.rom
+mv build/coreboot.rom.new build/coreboot.rom
+</code></pre>
+
+
+<h3><a name="EarlyDebug">Early Debug</a></h3>
+<p>
+  Early debugging between the reset vector and the time the serial port is enabled
+  is most easily done by writing values to port 0x80.
+</p>
+
+
+<h3>Success</h3>
+<p>
+  When the reset vector is successfully invoked, port 0x80 will output the following value:
+</p>
+<ul>
+  <li>0x01: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l45">POST_RESET_VECTOR_CORRECT</a>
+    - Bootblock successfully executed the
+    <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc;hb=HEAD#l4">reset vector</a>
+    and entered the 16-bit code at
+    <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc;hb=HEAD#l35">_start</a>
+  </li>
+</ul>
+
+
+<hr>
+<h2><a name="Bootblock">Bootblock</a></h2>
+<p>
+  Implement the bootblock using the following steps:
+</p>
+<ol>
+  <li>Create the directory as src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/bootblock</li>
+  <li>Add the timestamp.inc file which initializes the floating point registers and saves
+    the initial timestamp.
+  </li>
+  <li>Add the bootblock.c file which:
+    <ol type="A">
+      <li>Enables memory-mapped PCI config access</li>
+      <li>Updates the microcode by calling intel_update_microcode_from_cbfs</li>
+      <li>Enable ROM caching</li>
+    </ol>
+  </li>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Kconfig file
+    <ol type="A">
+      <li>Add the BOOTBLOCK_CPU_INIT value to point to the bootblock.c file</li>
+      <li>Add the CHIPSET_BOOTBLOCK_INCLUDE value to point to the timestamp.inc file</li>
+    </ol>
+  </li>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Makefile.inc file
+    <ol type="A">
+      <li>Add the bootblock subdirectory</li>
+    </ol>
+  </li>
+  <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>
+  <li>When successful port 0x80 will output the following values:
+    <ol type="A">
+      <li>0x01: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l45">POST_RESET_VECTOR_CORRECT</a>
+        - Bootblock successfully executed the
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc;hb=HEAD#l4">reset vector</a>
+        and entered the 16-bit code at
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc;hb=HEAD#l35">_start</a>
+      </li>
+      <li>0x10: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l53">POST_ENTER_PROTECTED_MODE</a>
+        - Bootblock executing in
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/entry32.inc;hb=HEAD#l55">32-bit mode</a>
+      </li>
+      <li>0x10 - Verstage/romstage reached 32-bit mode</li>
+    </ol>
+  </li>
+</ol>
+
+<p>
+  <b>Build Note:</b> The following files are included into the default bootblock image:
+</p>
+<ul>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootblock_romcc.S;hb=HEAD">src/arch/x86/bootblock_romcc.S</a>
+    added by   <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l133">src/arch/x86/Makefile.inc</a>
+    and includes the following files:
+    <ul>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/prologue.inc">src/arch/x86/prologue.inc</a></li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc">src/cpu/x86/16bit/reset16.inc</a></li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc">src/cpu/x86/16bit/entry16.inc</a></li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/entry32.inc">src/cpu/x86/32bit/entry32.inc</a></li>
+      <li>The code in
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootblock_romcc.S">src/arch/x86/bootblock_romcc.S</a>
+        includes src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/bootblock/timestamp.inc using the
+        CONFIG_CHIPSET_BOOTBLOCK_INCLUDE value set above
+      </li>
+      <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/sse_enable.inc">src/cpu/x86/sse_enable.inc</a></li>
+      <li>The code in
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l156">src/arch/x86/Makefile.inc</a>
+        invokes the ROMCC tool to convert the following "C" code into assembler as bootblock.inc:
+        <ul>
+          <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/bootblock_romcc.h">src/arch/x86/include/arch/bootblock_romcc.h</a></li>
+          <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/lapic/boot_cpu.c">src/cpu/x86/lapic/boot_cpu.c</a></li>
+          <li>The CONFIG_BOOTBLOCK_CPU_INIT value set above typically points to the code in
+            src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/bootblock/bootblock.c
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/id.S">src/arch/x86/id.S</a>
+    added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l110">src/arch/x86/Makefile.inc</a>
+  </li>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/fit.S">src/cpu/intel/fit/fit.S</a>
+    added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/Makefile.inc;hb=HEAD">src/cpu/intel/fit/Makefile.inc</a>
+  </li>
+  <li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/walkcbfs.S">src/arch/x86/walkcbfs.S</a>
+    added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l137">src/arch/x86/Makefile.inc</a>
+  </li>
+</ul>
+
+
+<hr>
+<h2><a name="TempRamInit">TempRamInit</a></h2>
+<p>
+  Enable the call to TempRamInit in two stages:
+</p>
+<ol>
+  <li>Finding the FSP binary in the read-only CBFS region</li>
+  <li>Call TempRamInit</li>
+</ol>
+
+
+<h3>Find FSP Binary</h3>
+<p>
+Use the following steps to locate the FSP binary:
+</p>
+<ol>
+  <li>Edit the src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/Kconfig file
+    <ol type="A">
+      <li>Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc">src/drivers/intel/fsp1_1/cache_as_ram.inc</a>
+      </li>
+      <li>Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common
+      </li>
+    </ol>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>Alternating 0xba and 0x01 - The FSP image was not found</li>
+    </ol>
+  </li>
+  <li>Add the <a target="_blank" href="../fsp1_1.html#FspBinary">FSP binary file</a> to the flash image</li>
+  <li>Set the following Kconfig values:
+    <ul>
+      <li>CONFIG_FSP_LOC to the FSP base address specified in the previous step</li>
+      <li>CONFIG_FSP_IMAGE_ID_STRING</li>
+    </ul>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found</li>
+    </ol>
+  </li>
+</ol>
+
+
+<h3>Calling TempRamInit</h3>
+<p>
+Use the following steps to debug the call to TempRamInit:
+</p>
+<ol>
+  <li>Add the CPU microcode update file
+    <ol type="A">
+      <li>Add the microcode file with the following command
+<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b &lt;base address&gt; -f cpu_microcode_blob.bin</code></pre>
+      </li>
+      <li>Set the Kconfig values
+        <ul>
+          <li>CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step</li>
+          <li>CONFIG_CPU_MICROCODE_CBFS_LEN</li>
+        </ul>
+      </li>
+    </ol>
+  </li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
+        - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
+      </li>
+      <li>0x2A - Just before calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">cache_as_ram_main</a>
+        which is the start of the verstage code which may be part of romstage
+      </li>
+    </ol>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="Romstage">Romstage</a></h2>
+
+<h3><a name="SerialOutput">Serial Output</a></h3>
+<p>
+  The following steps add the serial output support for romstage:
+</p>
+<ol>
+  <li>Create the romstage subdirectory</li>
+  <li>Add romstage/romstage.c
+    <ol type="A">
+      <li>Program the necessary base addresses</li>
+      <li>Disable the TCO</li>
+    </ol>
+  </li>
+  <li>Add romstage/Makefile.inc
+    <ol type="A">
+      <li>Add romstage.c to romstage</li>
+    </ol>
+  </li>
+  <li>Add gpio configuration support if necessary</li>
+  <li>Add the necessary .h files to support the build</li>
+  <li>Update Makefile.inc
+    <ol type="A">
+      <li>Add the romstage subdirectory</li>
+      <li>Add the gpio configuration support file to romstage</li>
+    </ol>
+  </li>
+  <li>Set the necessary Kconfig values to enable serial output:
+    <ul>
+      <li>CONFIG_DRIVERS_UART_&lt;driver&gt;=y</li>
+      <li>CONFIG_CONSOLE_SERIAL=y</li>
+      <li>CONFIG_UART_FOR_CONSOLE=&lt;port&gt;</li>
+      <li>CONFIG_CONSOLE_SERIAL_115200=y</li>
+    </ul>
+  </li>
+</ol>
+
+
+<h3><a name="PreviousSleepState">Determine Previous Sleep State</a></h3>
+<p>
+  The following steps implement the code to get the previous sleep state:
+</p>
+<ol>
+  <li>Implement the fill_power_state routine which determines the previous sleep state</li>
+  <li>Debug the result until port 0x80 outputs
+    <ol type="A">
+      <li>0x32:
+        - Just after entering
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l99">romstage_common</a>
+      </li>
+      <li>0x33 - Just after calling
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l113">soc_pre_ram_init</a>
+      </li>
+      <li>0x34:
+        - Just after entering
+        <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
+      </li>
+    </ol>
+</ol>
+
+
+<h3><a name="MemoryInit">MemoryInit Support</a></h3>
+<p>
+  The following steps implement the code to support the FSP MemoryInit call:
+</p>
+<ol>
+  <li>Add the chip.h header file to define the UPD values which get passed
+    to MemoryInit.  Skip the values containing SPD addresses and DRAM
+    configuration data which is determined by the board.
+    <p>
+      <b>Build Note</b>: The src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb
+      file specifies the default values for these parameters.  The build
+      process creates the static.c module which contains the config data
+      structure containing these values.
+    </p>
+  </li>
+  <li>Edit romstage/romstage.c
+    <ol type="A">
+      <li>Implement the romstage/romstage.c/soc_memory_init_params routine to
+        copy the values from the config structure into the UPD structure
+      </li>
+      <li>Implement the soc_display_memory_init_params routine to display
+        the updated UPD parameters by calling fsp_display_upd_value
+      </li>
+    </ol>
+  </li>
+</ol>
+
+
+<h3><a name="DisableShadowRom">Disable Shadow ROM</a></h3>
+<p>
+  A shadow of the SPI flash part is mapped from 0x000e0000 to 0x000fffff.
+  This shadow needs to be disabled to allow RAM to properly respond to
+  this address range.
+</p>
+<ol>
+  <li>Edit romstage/romstage.c and add the soc_after_ram_init routine</li>
+</ol>
+
+
+<hr>
+<h2><a name="Ramstage">Ramstage</a></h2>
+
+<h3><a name="DeviceTree">Start Device Tree Processing</a></h3>
+<p>
+  The src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb file drives the
+  execution during ramstage.  This file is processed by the util/sconfig utility
+  to generate build/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/static.c.  The various
+  state routines in
+  src/lib/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/lib/hardwaremain.c;hb=HEAD#l128">hardwaremain.c</a>
+  call dev_* routines which use the tables in static.c to locate operation tables
+  associated with the various chips and devices.  After location the operation
+  tables, the state routines call one or more functions depending upon the
+  state of the state machine.
+</p>
+
+<h4><a name="ChipOperations">Chip Operations</a></h4>
+<p>
+  Kick-starting the ramstage state machine requires creating the operation table
+  for the chip listed in devicetree.cb:
+</p>
+<ol>
+  <li>Edit src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/chip.c:
+    <ol type="A">
+      <li>
+        This chip's operation table has the name
+        soc_&lt;SoC Vendor&gt;_&lt;SoC Family&gt;_ops which is derived from the
+        chip path specified in the devicetree.cb file.
+      </li>
+      <li>Use the CHIP_NAME macro to specify the name for the chip</li>
+      <li>For FSP 1.1, specify a .init routine which calls intel_silicon_init</li>
+    </ol>
+  </li>
+  <li>Edit src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/Makefile.inc and add chip.c to ramstage</li>
+</ol>
+
+<h4>Domain Operations</h4>
+<p>
+  coreboot uses the domain operation table to initiate operations on all of the
+  devices in the domain.  By default coreboot enables all PCI devices which it
+  finds.  Listing a device in devicetree.cb gives the board vendor control over
+  the device state.  Non-PCI devices may also be listed under PCI device such as
+  the LPC bus or SMbus devices.
+</p>
+<ol>
+  <li>Edit src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/chip.c:
+    <ol type="A">
+      <li>
+        The domain operation table is typically placed in
+        src/soc/&lt;SoC Vendor&gt;/&lt;SoC Family&gt;/chip.c.
+        The table typically looks like the following:
+<pre><code>static struct device_operations pci_domain_ops = {
+	.read_resources	= pci_domain_read_resources,
+	.set_resources	= pci_domain_set_resources,
+	.scan_bus	= pci_domain_scan_bus,
+};
+</code></pre>
+      </li>
+      <li>
+        Create a .enable_dev entry in the chip operations table which points to a
+        routine which sets the domain table for the device with the DEVICE_PATH_DOMAIN.
+<pre><code>	if (dev->path.type == DEVICE_PATH_DOMAIN) {
+		dev->ops = &pci_domain_ops;
+	}
+</code></pre>
+      </li>
+      <li>
+        During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
+        for the PCI devices on the bus.
+      </li>
+    </ol>
+  </li>
+  <li>Set CONFIG_DEBUG_BOOT_STATE=y in the .config file</li>
+  <li>
+    Debug the result until the PCI vendor and device IDs are displayed
+    during the BS_DEV_ENUMERATE state.
+  </li>
+</ol>
+
+
+<h3><a name="DeviceDrivers">PCI Device Drivers</a></h3>
+<p>
+  PCI device drivers consist of a ".c" file which contains a "pci_driver" data
+  structure at the end of the file with the attribute tag "__pci_driver".  This
+  attribute tag places an entry into a link time table listing the various
+  coreboot device drivers.
+</p>
+<p>
+  Specify the following fields in the table:
+</p>
+<ol>
+  <li>.vendor - PCI vendor ID value of the device</li>
+  <li>.device - PCI device ID value of the device or<br>
+  .devices - Address of a zero terminated array of PCI device IDs
+  </li>
+  <li>.ops - Operations table for the device.  This is the address
+    of a "static struct device_operations" data structure specifying
+    the routines to execute during the different states and sub-states
+    of ramstage's processing.
+  </li>
+  <li>Turn on the device in mainboard/&lt;Vendor&gt;/&lt;Board&gt;/devicetree.cb</li>
+  <li>
+    Debug until the device is on and properly configured in coreboot and
+    usable by the payload
+  </li>
+</ol>
+
+<h4><a name="SubsystemIds">Subsystem IDs</a></h4>
+<p>
+  PCI subsystem IDs are assigned during the BS_DEV_ENABLE state.  The device
+  driver may use the common mechanism to assign subsystem IDs by adding
+  the ".ops_pci" to the pci_driver data structure.  This field points to
+  a "struct pci_operations" that specifies a routine to set the subsystem
+  IDs for the device.  The routine might look something like this:
+</p>
+<pre><code>static void pci_set_subsystem(struct device *dev, unsigned vendor, unsigned device)
+{
+	if (!vendor || !device) {
+		vendor = pci_read_config32(dev, PCI_VENDOR_ID);
+		device = vendor >> 16;
+	}
+	printk(BIOS_SPEW,
+		"PCI: %02x:%02x:%d subsystem vendor: 0x%04x, device: 0x%04x\n",
+		0, PCI_SLOT(dev->path.pci.devfn), PCI_FUNC(dev->path.pci.devfn),
+		vendor & 0xffff, device);
+	pci_write_config32(dev, PCI_SUBSYSTEM_VENDOR_ID,
+			((device & 0xffff) << 16) | (vendor & 0xffff));
+}
+</code></pre>
+
+
+
+<h3>Set up the <a name="MemoryMap">Memory Map</a></h3>
+<p>
+  The memory map is built by the various PCI device drivers during the
+  BS_DEV_RESOURCES state of ramstage.  The northcluster driver will typically
+  specify the DRAM resources while the other drivers will typically specify
+  the IO resources.  These resources are hung off the struct device *data structure by
+  src/device/device_util.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/device/device_util.c;hb=HEAD#l448">new_resource</a>.
+</p>
+<p>
+  During the BS_WRITE_TABLES state, coreboot collects these resources and
+  places them into a data structure identified by LB_MEM_TABLE.
+</p>
+<p>
+  Edit the device driver file:
+</p>
+<ol>
+  <li>
+    Implement a read_resources routine which calls macros defined in
+    src/include/device/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/device/device.h;hb=HEAD#l237">device.h</a>
+    like:
+    <ul>
+      <li>ram_resource</li>
+      <li>reserved_ram_resource</li>
+      <li>bad_ram_resource</li>
+      <li>uma_resource</li>
+      <li>mmio_resource</li>
+    </ul>
+  </li>
+</ol>
+
+<p>
+  Testing: Verify that the resources are properly displayed by coreboot during the BS_WRITE_TABLES state.
+</p>
+
+
+
+<hr>
+<h2><a name="AcpiTables">ACPI Tables</a></h2>
+<p>
+  One of the payloads that needs ACPI tables is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>.
+</p>
+
+<h3>FADT</h3>
+<p>
+  The EDK2 module
+  CorebootModulePkg/Library/CbParseLib/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbParseLib/CbParseLib.c#l450">CbParseLib.c</a>
+  requires that the FADT contains the values in the table below.
+  These values are placed into a HOB identified by
+  <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CorebootModulePkg.dec#l36">gUefiAcpiBoardInfoGuid</a>
+  by routine
+  CorebootModulePkg/CbSupportPei/CbSupportPei/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CbSupportPei/CbSupportPei.c#l364">CbPeiEntryPoint</a>.
+</p>
+<table border="1">
+  <tr bgcolor="#c0ffc0">
+    <td>coreboot Field</td>
+    <td>EDK2 Field</td>
+    <td>gUefiAcpiBoardInfoGuid</td>
+    <td>Use</li>
+    <td>
+      <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf">ACPI Spec.</a>
+      Section
+    </td>
+  </tr>
+  <tr>
+    <td>gpe0_blk<br>gpe0_blk_len</td>
+    <td>Gpe0Blk<br>Gpe0BlkLen</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbParseLib/CbParseLib.c#l477">PmGpeEnBase</a>
+    </td>
+    <td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l129">Shutdown</a></td>
+    <td>4.8.4.1</td>
+  </tr>
+  <tr>
+    <td>pm1a_cnt_blk</td>
+    <td>Pm1aCntBlk</td>
+    <td>PmCtrlRegBase</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l139">Shutdown</a><br>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l40">Suspend</a>
+    </td>
+    <td>4.8.3.2.1</td>
+  </tr>
+  <tr>
+    <td>pm1a_evt_blk</td>
+    <td>Pm1aEvtBlk</td>
+    <td>PmEvtBase</td>
+    <td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l134">Shutdown</a></td>
+    <td>4.8.3.1.1</td>
+  </tr>
+  <tr>
+    <td>pm_tmr_blk</td>
+    <td>PmTmrBlk</td>
+    <td>PmTimerRegBase</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/AcpiTimerLib/AcpiTimerLib.c#l55">Timer</a>
+    </td>
+    <td>4.8.3.3</td>
+  </tr>
+  <tr>
+    <td>reset_reg.</td>
+    <td>ResetReg.Address</td>
+    <td>ResetRegAddress</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l71">Cold</a>
+      and
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l98">Warm</a>
+      resets
+    </td>
+    <td>4.3.3.6</td>
+  </tr>
+  <tr>
+    <td>reset_value</td>
+    <td>ResetValue</td>
+    <td>ResetValue</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l71">Cold</a>
+      and
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l98">Warm</a>
+      resets
+    </td>
+    <td>4.8.3.6</td>
+  </tr>
+</table>
+<p>
+  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/arch/acpi.h;hb=HEAD#l237">acpi.h</a>
+</p>
+
+<ol>
+  <li>
+    Select <a target="_blank" href="../Board/board.html#AcpiTables">HAVE_ACPI_TABLES</a>
+    in the board's Kconfig file
+  </li>
+  <li>Create a acpi.c module:
+    <ol type="A">
+      <li>Add the acpi_fill_in_fadt routine and initialize the values above</li>
+    </ol>
+  </li>
+</ol>
+
+
+
+<hr>
+<h2><a name="LegacyHardware">Legacy Hardware</a></h2>
+<p>
+  One of the payloads that needs legacy hardare is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>.
+</p>
+
+<table border="1">
+  <tr bgcolor="c0ffc0">
+    <th>Peripheral</th>
+    <th>Use</th>
+    <th>8259 Interrupt Vector</th>
+    <th>IDT Base Offset</th>
+    <th>Interrupt Handler</th>
+  </tr>
+  <tr>
+    <td>
+      <a target="_blank" href="http://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf">8254</a>
+      Programmable Interval Timer
+    </td>
+    <td>
+      EDK2: PcAtChipsetPkg/8254TimerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Timer.c">Timer.c</a>
+    </td>
+    <td>0</td>
+    <td>0x340</td>
+    <td>
+      <a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Timer.c#l71">TimerInterruptHandler</a>
+    </td>
+  </tr>
+  <tr>
+    <td>
+      <a target="_blank" href="https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwibxYKU3ZDLAhVOzWMKHfuqB40QFggcMAA&url=http%3A%2F%2Fbochs.sourceforge.net%2Ftechspec%2Fintel-8259a-pic.pdf.gz&usg=AFQjCNF1NT0OQ6ys1Pn6Iv9sv6cKRzZbGg&sig2=HfBszp9xTVO_fajjPWCsJw">8259</a>
+      Programmable Interrupt Controller
+    </td>
+    <td>
+      EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8259InterruptControllerDxe/8259.c">8259.c</a>
+    </td>
+    <td>
+      Master interrupts: 0, 2 - 7<br>
+      Slave interrupts: 8 - 15<br>
+      Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15
+    </td>
+    <td>
+      Master: 0x340, 0x350 - 0x378<br>
+      Slave: 0x380 - 0x3b8<br>
+      Interrupt descriptors are 8 bytes each
+    </td>
+    <td>&nbsp;</td>
+  </tr>
+</table>
+
+<hr>
+<p>Modified: 4 March 2016</p>
+  </body>
+</html>

Documentation/Intel/development.html

@@ -0,0 +1,377 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Development</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; x86 coreboot/FSP Development Process</h1>
+<p>
+  The x86 development process for coreboot is broken into the following components:
+</p>
+<ul>
+  <li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li>
+  <li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li>
+  <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li>
+</ul>
+<p>
+  The development process has two main phases:
+</p>
+<ol>
+  <li>Minimal coreboot; This phase is single threaded</li>
+  <li>Adding coreboot features</li>
+</ol>
+
+<h2>Minimal coreboot</h2>
+<p>
+  The combined steps below describe how to bring up a minimal coreboot for a
+  system-on-a-chip (SoC) and a development board:
+</p>
+<table>
+  <tr bgcolor="#ffffc0">
+    <td>The initial coreboot steps are single threaded!
+      The initial minimal FSP development is also single threaded.
+      Progress can speed up by adding more developers after the minimal coreboot/FSP
+      implementation reaches the payload.
+    </td>
+  </tr>
+</table>
+<ol>
+  <li>Get the necessary tools:
+    <ul>
+      <li>Linux: Use your package manager to install m4 bison flex and the libcurses development
+        package.
+        <ul>
+          <li>Ubuntu or other Linux distribution that use apt, run:
+<pre><code>sudo apt-get install m4 bison flex libncurses5-dev
+</code></pre>
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li>Build the cross tools for i386:
+    <ul>
+      <li>Linux:
+<pre><code>make crossgcc-i386</code></pre>
+        To use multiple processors for the toolchain build (which takes a long time), use:
+<pre><code>make crossgcc-i386 CPUS=N</code></pre>
+        where N is the number of cores to use for the build.
+      </li>
+    </ul>
+  </li>
+  <li>Get something to build:
+    <ol type="A">
+      <li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
+      <li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li>
+      <li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li>
+    </ol>
+  </li>
+  <li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
+  <li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
+  <li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
+  <li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
+  <li>Enable the serial port
+    <ol type="A">
+      <li>Power on, enable and configure GPIOs for the
+        <a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a>
+      </li>
+      <li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a>
+        support to romstage
+      </li>
+    </ol>
+  </li>
+  <li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
+  <li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
+  <li>Enable DRAM:
+    <ol type="A">
+      <li>Implement the SoC
+        <a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
+        Support
+      </li>
+      <li>Implement the board support to read the
+        <a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
+      </li>
+    </ol>
+  </li>
+  <li>Disable the
+    <a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a>
+  </li>
+  <li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li>
+  <li>
+    Implement the .init routine for the
+    <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a>
+    structure which calls FSP SiliconInit
+  </li>
+  <li>
+    Start ramstage's
+    <a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a>
+    to display the PCI vendor and device IDs
+  </li>
+  <li>
+    Disable the
+    <a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a>
+  </li>
+  <li>
+    Implement the
+    <a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a>
+  </li>
+  <li>coreboot should now attempt to load the payload</li>
+</ol>
+
+
+
+<h2>Add coreboot Features</h2>
+<p>
+  Most of the coreboot development gets done in this phase.  Implementation tasks in this
+  phase are easily done in parallel.
+</p>
+<ul>
+  <li>Payload and OS Features:
+    <ul>
+      <li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li>
+      <li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li>
+    </ul>
+  </li>
+</ul>
+
+
+
+<hr>
+<table border="1">
+  <tr bgcolor="#c0ffc0">
+    <th colspan=3><h1>Features</h1></th>
+  </tr>
+  <tr bgcolor="#c0ffc0">
+    <th>SoC</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>8254 Programmable Interval Timer</td>
+    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
+    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
+  </tr>
+  <tr>
+    <td>8259 Programmable Interrupt Controller</td>
+    <td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
+    <td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
+  </tr>
+  <tr>
+    <td>Cache-as-RAM</td>
+    <td>
+      <a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
+      FSP binary:
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l38">cache_as_ram.inc</a><br>
+      Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
+      called from
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">cache_as_ram.inc</a><br>
+      Disable: FSP 1.1 TempRamExit called from
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
+    </td>
+    <td>FindFSP: POST code 0x90
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
+      is displayed<br>
+      Enable: POST code
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
+      is displayed<br>
+      Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
+    </td>
+  </tr>
+  <tr>
+    <td>Memory Map</td>
+    <td>
+      Implement a device driver for the
+      <a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a>
+    </td>
+    <td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td>
+  </tr>
+  <tr>
+    <td>MTRRs</td>
+    <td>
+      Set values: src/drivers/intel/fsp1_1/stack.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/stack.c;hb=HEAD#l42">setup_stack_and_mtrrs</a><br>
+      Load values: src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l71">after_raminit.S</a>
+    </td>
+    <td>Set: Post code 0x91
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l213">POST_FSP_TEMP_RAM_EXIT</a>)
+      is displayed by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
+      Load: Post code 0x3C is displayed by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l152">after_raminit.S</a><br>
+      and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td>
+  </tr>
+  <tr>
+    <td>PCI Device Support</td>
+    <td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td>
+    <td>The device is detected by coreboot and usable by the payload</td>
+  </tr>
+  <tr>
+    <td>Ramstage state machine</td>
+    <td>
+      Implement the chip and domain operations to start the
+      <a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a>
+      processing
+    </td>
+    <td>
+      During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
+      for the PCI devices on the bus.
+    </td>
+  </tr>
+  <tr>
+    <td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td>
+    <td>
+      Disable: src/soc/&lt;Vendor&gt;/&lt;Chip Family&gt;/romstage/romstage.c/<a target="_blank" href="SoC/soc.html#DisableShadowRom">soc_after_ram_init routine</a>
+    </td>
+    <td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td>
+  </tr>
+
+
+  <tr bgcolor="#c0ffc0">
+    <th>Board</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>Device Tree</td>
+    <td>
+      <a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting
+      the device tree processing<br>
+      <a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br>
+      Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a>
+    <td>
+      List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br>
+      Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br>
+      Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload
+    </td>
+  </tr>
+  <tr>
+    <td>DRAM</td>
+    <td>
+      Load SPD data: src/soc/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br>
+      UPD Setup:
+      <ul>
+        <li>src/soc&lt;Vendor&gt;//&lt;Chip Family&gt;/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
+        <li>src/mainboard/&lt;Vendor&gt;/&lt;Board&gt;/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
+      </ul>
+      FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l126">raminit.c</a>
+    </td>
+    <td>Select the following Kconfig values
+      <ul>
+        <li>DISPLAY_HOBS</li>
+        <li>DISPLAY_UPD_DATA</li>
+      </ul>
+      Testing successful if:
+      <ul>
+        <li>MemoryInit UPD values are correct</li>
+        <li>MemoryInit returns 0 (success) and</li>
+        <li>The message "ERROR - coreboot's requirements not met by FSP binary!"
+          is not displayed
+        </li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>Serial Port</td>
+    <td>
+      SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
+      Enable: src/soc/mainboard/&lt;Board&gt;/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a>
+    </td>
+    <td>Debug serial output works</td>
+  </tr>
+
+
+  <tr bgcolor="#c0ffc0">
+    <th>Payload</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>ACPI Tables</td>
+    <td>
+      SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br>
+    </td>
+    <td>Verified by payload or OS</td>
+  </tr>
+
+
+  <tr bgcolor="#c0ffc0">
+    <th>FSP</th>
+    <th>Where</th>
+    <th>Testing</th>
+  </tr>
+  <tr>
+    <td>TempRamInit</td>
+    <td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
+    <td>FSP binary found: POST code 0x90
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
+      is displayed<br>
+      TempRamInit successful: POST code
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
+      is displayed<br>
+    </td>
+  </tr>
+  <tr>
+    <td>MemoryInit</td>
+    <td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
+      <a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
+    </td>
+    <td>Select the following Kconfig values
+      <ul>
+        <li>DISPLAY_HOBS</li>
+        <li>DISPLAY_UPD_DATA</li>
+      </ul>
+      Testing successful if:
+      <ul>
+        <li>MemoryInit UPD values are correct</li>
+        <li>MemoryInit returns 0 (success) and</li>
+        <li>The message "ERROR - coreboot's requirements not met by FSP binary!"
+          is not displayed
+        </li>
+      </ul>
+    </td>
+  </tr>
+  <tr>
+    <td>TempRamExit</td>
+    <td>src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l51">after_raminit.S</a></td>
+    <td>Post code 0x91
+      (<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l212">POST_FSP_TEMP_RAM_EXIT</a>)
+      is displayed before calling TempRamExit by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a>,
+      CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and
+      Post code 0x39 is displayed by
+      <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a><br>
+    </td>
+  </tr>
+  <tr>
+    <td>SiliconInit</td>
+    <td>
+      Implement the .init routine for the
+      <a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure
+    </td>
+    <td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td>
+  </tr>
+  <tr>
+    <td>FspNotify</td>
+    <td>
+      The code which calls FspNotify is located in
+      src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/fsp_util.c;hb=HEAD#l182">fsp_util.c</a>.
+      The fsp_notify_boot_state_callback routine is called three times as specified
+      by the BOOT_STATE_INIT_ENTRY macros below the routine.
+    </td>
+    <td>
+      The FspNotify routines are called during:
+      <ul>
+        <li>BS_DEV_RESOURCES - on exit</li>
+        <li>BS_PAYLOAD_LOAD - on exit</li>
+        <li>BS_OS_RESUME - on entry (S3 resume)</li>
+      </ul>
+    </td>
+  </tr>
+</table>
+
+
+
+<hr>
+<p>Modified: 4 March 2016</p>
+  </body>
+</html>

Documentation/Intel/fsp1_1.html

@@ -0,0 +1,79 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>FSP 1.1</title>
+  </head>
+  <body>
+
+<h1>FSP 1.1</h1>
+
+<h2>x86 FSP 1.1 Integration</h2>
+<p>
+  Firmware Support Package (FSP) integration requires System-on-a-Chip (SoC)
+  and board support.  The combined steps are listed
+  <a target="_blank" href="development.html">here</a>.
+  The development steps for FSP are listed below:
+</p>
+<ol>
+  <li><a href="#RequiredFiles">Required Files</a></li>
+  <li>Add the <a href="#FspBinary">FSP Binary File</a> to the coreboot File System</li>
+  <li>Enable <a href="#corebootFspDebugging">coreboot/FSP Debugging</a></li>
+</ol>
+
+<p>
+  FSP Documentation:
+</p>
+<ul>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v1-1.pdf">V1.1</a></li>
+</ul>
+
+<hr>
+<h2><a name="RequiredFiles">Required Files</a></h2>
+<h3><a name="corebootRequiredFiles">coreboot Required Files</a></h3>
+<ol>
+  <li>Create the following directories if they do not already exist:
+    <ul>
+      <li>src/vendorcode/intel/fsp/fsp1_1/&lt;Chip Family&gt;</li>
+      <li>3rdparty/blobs/mainboard/&lt;Board Vendor&gt;/&lt;Board Name&gt;</li>
+    </ul>
+  </li>
+  <li>
+    The following files may need to be copied from the FSP build or release into the
+    directories above if they are not present or are out of date:
+    <ul>
+      <li>FspUpdVpd.h: src/vendorcode/intel/fsp/fsp1_1/&lt;Chip Family&gt;/FspUpdVpd.h</li>
+      <li>FSP.bin: 3rdparty/blobs/mainboard/&lt;Board Vendor&gt;/&lt;Board Name&gt;/fsp.bin</li>
+    </ul>
+  </li>
+</ol>
+
+
+<hr>
+<h2><a name="FspBinary">Add the FSP Binary File to coreboot File System</a></h2>
+<p>
+  Add the FSP binary to the coreboot flash image using the following command:
+</p>
+<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b &lt;base address&gt; -f fsp.bin</code></pre>
+<p>
+  This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the
+  FSP code for TempRamInit may be executed in place.
+</p>
+
+
+<hr>
+<h2><a name="corebootFspDebugging">Enable coreboot/FSP Debugging</a></h2>
+<p>
+  Set the following Kconfig values:
+</p>
+<ul>
+  <li>CONFIG_DISPLAY_FSP_ENTRY_POINTS - Display the FSP entry points in romstage</li>
+  <li>CONFIG_DISPLAY_HOBS - Display and verify the hand-off-blocks (HOBs) returned by MemoryInit</li>
+  <li>CONFIG_DISPLAY_VBT - Display Video BIOS Table (VBT) used for GOP</li>
+  <li>CONFIG_DISPLAY_UPD_DATA - Display the user specified product data passed to MemoryInit and SiliconInit</li>
+</ul>
+
+
+<hr>
+<p>Modified: 17 May 2016</p>
+  </body>
+</html>

Documentation/Intel/index.html

@@ -0,0 +1,129 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Intel&reg; x86</title>
+  </head>
+  <body>
+
+<h1>Intel&reg; x86</h1>
+
+<h2>Intel&reg; x86 Boards</h2>
+<ul>
+  <li><a target="_blank" href="Board/galileo.html">Galileo</a></li>
+  <li><a target="_blank" href="http://wiki.minnowboard.org/Coreboot">MinnowBoard MAX</a></li>
+</ul>
+
+<h2>Intel&reg; x86 SoCs</h2>
+<ul>
+  <li><a target="_blank" href="SoC/quark.html">Quark&trade;</a></li>
+</ul>
+
+
+
+<hr>
+<h2>x86 coreboot Development</h2>
+<ul>
+  <li>Get the <a target="_blank" href="https://www.coreboot.org/Git">coreboot source</li>
+  <li><a target="_blank" href="development.html">Overall</a> development</li>
+  <li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration
+  </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>
+
+
+
+<hr>
+<h2>Payload Development</h2>
+<ul>
+  <li><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>
+    <ul>
+      <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process">EDK II Development Process</a></li>
+      <li>EDK II <a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK%20II%20White%20papers">White Papers</a></li>
+      <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/SourceForge-to-Github-Quick-Start">SourceForge to Github Quick Start</a></li>
+      <li>UEFI <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_5_Errata_A.PDF">2.5 Errata A</a></li>
+    </ul>
+  </li>
+</ul>
+
+
+
+<hr>
+<h2><a name="Documentation">Documentation</a></h2>
+<ul>
+  <li>Intel&reg; 64 and IA-32 Architectures <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Software Developer Manual</a></li>
+  <li><a target="_blank" href="http://www.uefi.org/specifications">UEFI Specifications</a></li>
+</ul>
+
+<h3><a name="Edk2Documentation">EDK-II Documentation</a></h3>
+<ul>
+  <li>Build <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/Build_Spec_1_26.pdf">V1.26</a></li>
+  <li>Coding Standards <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/CCS_2_1_Draft.pdf">V2.1</a></li>
+  <li>DEC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC_Spec_1_25.pdf">V1.25</a></li>
+  <li>DSC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DSC_Spec_1_26.pdf">V1.26</a></li>
+  <li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/UEFI-Driver-Writer's-Guide">Driver Writer's Guide</a></li>
+  <li>Expression Syntax <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/ExpressionSyntax_1.1.pdf">V1.1</a></li>
+  <li>FDF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/FDF_Spec_1_26.pdf">V1.26</a></li>
+  <li>INF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/INF_Spec_1_25.pdf">V1.25</a></li>
+  <li>PCD <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/PCD_Infrastructure.pdf">PCD</a>V0.55</li>
+  <li>UNI <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/UNI_File_Spec_v1_2_Errata_A.pdf">V1.2 Errata A</a></li>
+  <li>VRF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/VFR_1_9.pdf">V1.9</a></li>
+</ul>
+
+<h3><a name="FspDocumentation">FSP Documentation</a></h3>
+<ul>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v2.pdf">V2.0</a></li>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v1-1.pdf">V1.1</a></li>
+  <li>Intel&reg; Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec.pdf">V1.0</a></li>
+</ul>
+
+<h3><a name="FeatureDocumentation">Feature Documentation</a></h3>
+<table border="1">
+  <tr bgcolor="#c0ffc0"><th>Feature/Specification</th><th>Linux View/Test</th><th>EDK-II View/Test</th></tr>
+  <tr>
+    <td><a target="_blank" href="https://en.wikipedia.org/wiki/E820">e820</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/dmesg.1.html">dmesg</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.uefi.org/specifications">ACPI</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/precise/man1/acpidump.1.html">acpidump</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="https://en.wikipedia.org/wiki/Extended_Display_Identification_Data">EDID</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">get-edid | parse-edid</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I2C</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">i2cdetect</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.intel.com/design/archives/processors/pro/docs/242016.htm">Multiprocessor</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/lscpu.1.html">lscpu</a></td>
+    <td>&nbsp;</td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="https://pcisig.com/specifications">PCI</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/lspci.8.html">lspci</a></td>
+    <td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">pci</a></td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.0.0.pdf">SMBIOS</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/dmidecode.8.html">dmidecode</a></td>
+    <td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">smbiosview</a></td>
+  </tr>
+  <tr>
+    <td><a target="_blank" href="http://www.usb.org/developers/docs/">USB</a></td>
+    <td><a target="_blank" href="http://manpages.ubuntu.com/manpages/xenial/man8/lsusb.8.html">lsusb</a></td>
+    <td>&nbsp;</td>
+  </tr>
+</table>
+
+<hr>
+<p>Modified: 18 June 2016</p>
+  </body>
+</html>

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/Makefile.sphinx

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS        ?=
+SPHINXOPTS        =
 SPHINXBUILD       = sphinx-build
 SPHINXAUTOBUILD   = sphinx-autobuild
 PAPER             =

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/chip.tex

@@ -7,7 +7,7 @@ change.
 
 \section{Scope}
 This document defines how LinuxBIOS programmers can specify chips that
-are used, specified, and initialized. The current scope is for superio
+are used, specified, and initalized. The current scope is for superio
 chips, but the architecture should allow for specification of other chips such
 as southbridges. Multiple chips of same or different type are supported.
 

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/RFC/intel-gpio-cleanup.md

@@ -1,98 +0,0 @@
-# Background
-
-CB:31250 ("soc/intel/cannonlake: Configure GPIOs again after FSP-S is
-done") introduced a workaround in coreboot for `soc/intel/cannonlake`
-platforms to save and restore GPIO configuration performed by
-mainboard across call to FSP Silicon Init (FSP-S). This workaround was
-required because FSP-S was configuring GPIOs differently than
-mainboard resulting in boot and runtime issues because of
-misconfigured GPIOs. This issue was observed on `google/hatch`
-mainboard and was raised with Intel to get the FSP behavior
-fixed. Until the fix in FSP was available, this workaround was used to
-ensure that the mainboards can operate correctly and were not impacted
-by the GPIO misconfiguration in FSP-S.
-
-The issues observed on `google/hatch` mainboard were fixed by adding
-(if required) and initializing appropriate FSP UPDs. This UPD
-initialization ensured that FSP did not configure any GPIOs
-differently than the mainboard configuration. Fixes included:
- * CB:31375 ("soc/intel/cannonlake: Configure serial debug uart")
- * CB:31520 ("soc/intel/cannonlake: Assign FSP UPDs for HPD and Data/CLK of DDI ports")
- * CB:32176 ("mb/google/hatch: Update GPIO settings for SD card and SPI1 Chip select")
- * CB:34900 ("soc/intel/cnl: Add provision to configure SD controller write protect pin")
-
-With the above changes merged, it was verified on `google/hatch`
-mainboard that the workaround for GPIO reconfiguration was not
-needed. However, at the time, we missed dropping the workaround in
-'soc/intel/cannonlake`. Currently, this workaround is used by the
-following mainboards:
- * `google/drallion`
- * `google/sarien`
- * `purism/librem_cnl`
- * `system76/lemp9`
-
-As verified on `google/hatch`, FSP v1263 included all UPD additions
-that were required for addressing this issue.
-
-# Proposal
-
-* The workaround can be safely dropped from `soc/intel/cannonlake`
-  only after the above mainboards have verified that FSP-S does not
-  configure any pads differently than the mainboard in coreboot. Since
-  the fix included initialization of FSP UPDs correctly, the above
-  mainboards can use the following diff to check what pads change
-  after FSP-S has run:
-
-```
-diff --git a/src/soc/intel/common/block/gpio/gpio.c b/src/soc/intel/common/block/gpio/gpio.c
-index 28e78fb366..0cce41b316 100644
---- a/src/soc/intel/common/block/gpio/gpio.c
-+++ b/src/soc/intel/common/block/gpio/gpio.c
-@@ -303,10 +303,10 @@ static void gpio_configure_pad(const struct pad_config *cfg)
-                /* Patch GPIO settings for SoC specifically */
-                soc_pad_conf = soc_gpio_pad_config_fixup(cfg, i, soc_pad_conf);
- 
--               if (CONFIG(DEBUG_GPIO))
-+               if (soc_pad_conf != pad_conf)
-                        printk(BIOS_DEBUG,
--                       "gpio_padcfg [0x%02x, %02zd] DW%d [0x%08x : 0x%08x"
--                       " : 0x%08x]\n",
-+                       "%d: gpio_padcfg [0x%02x, %02zd] DW%d [0x%08x : 0x%08x"
-+                       " : 0x%08x]\n", cfg->pad,
-                        comm->port, relative_pad_in_comm(comm, cfg->pad), i,
-                        pad_conf,/* old value */
-                        cfg->pad_config[i],/* value passed from gpio table */
-```
-
-Depending upon the pads that are misconfigured by FSP-S, these
-mainboards will have to set UPDs appropriately. Once this is verified
-by the above mainboards, the workaround implemented in CB:31250 can be
-dropped.
-
-* The fix implemented in FSP/coreboot for `soc/intel/cannonlake`
-  platforms is not really the right long term solution for the
-  problem. Ideally, FSP should not be touching any GPIO configuration
-  and letting coreboot configure the pads as per mainboard
-  design. This recommendation was accepted and implemented by Intel
-  starting with Jasper Lake and Tiger Lake platforms using a single
-  UPD `GpioOverride` that coreboot can set so that FSP does not change
-  any GPIO configuration. However, this implementation is not
-  backported to any older platforms. Given the issues that we have
-  observed across different platforms, the second proposal is to:
-
-  - Add a Kconfig `CHECK_GPIO_CONFIG_CHANGES` that enables checks
-    in coreboot to stash GPIO pad configuration before various calls
-    to FSP and compares the configuration on return from FSP.
-  - This will have to be implemented as part of
-    drivers/intel/fsp/fsp2_0/ to check for the above config selection
-    and make callbacks `gpio_snapshot()` and `gpio_verify_snapshot()`
-    to identify and print information about pads that have changed
-    configuration after calls to FSP.
-  - This config can be kept disabled by default and mainboard
-    developers can enable them as and when required for debug.
-  - This will be helpful not just for the `soc/intel/cannonlake`
-    platforms that want to get rid of the above workaround, but also
-    for all future platforms using FSP to identify and catch any GPIO
-    misconfigurations that might slip in to any platforms (in case the
-    `GpioOverride` UPD is not honored by any code path within FSP).
-

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
+table definitions can be found in src/include/boot/coreboot_tables.h and
-`./src/commonlib/include/commonlib/coreboot_tables.h` and
+payloads/libpayload/include/coreboot_tables.h respectively within coreboot
-`./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,290 +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 buses (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.
-
-### Naming and referencing devices
-
-When declaring a device, it can optionally be given an alias that can be
-referred to elsewhere. This is particularly useful to declare a device in one
-device tree while allowing its configuration to be more easily changed in an
-overlay. For instance, the AMD Picasso SoC definition
-(`soc/amd/picasso/chipset.cb`) declares an IOMMU on a PCI bus that is disabled
-by default:
-
-```
-chip soc/amd/picasso
-	device domain 0 on
-		...
-		device pci 00.2 alias iommu off end
-		...
-	end
-end
-```
-
-A device based on this SoC can override the configuration for the IOMMU without
-duplicating addresses, as in
-`mainboard/google/zork/variants/baseboard/devicetree_trembyle.cb`:
-
-```
-chip soc/amd/picasso
-	device domain 0
-		...
-		device ref iommu on end
-		...
-	end
-end
-```
-
-In this example the override simply enables the IOMMU, but it could also
-set additional properties (or even add child devices) inside the IOMMU `device`
-block.
-
----
-
-It is important to note that devices that use `device ref` syntax to override
-previous definitions of a device by alias must be placed at **exactly the same
-location in the device tree** as the original declaration. If not, this will
-actually create another device rather than overriding the properties of the
-existing one. For instance, if the above snippet from `devicetree_trembyle.cb`
-were written as follows:
-
-```
-chip soc/amd/picasso
-	# NOTE: not inside domain 0!
-	device ref iommu on end
-end
-```
-
-Then this would leave the SoC's IOMMU disabled, and instead create a new device
-with no properties as a direct child of the SoC.
-
-## Device drivers
-
-Let's take a look at an example entry from
-``src/mainboard/google/hatch/variants/hatch/overridetree.cb``:
-
-```
-device pci 15.0 on
-	chip drivers/i2c/generic
-		register "hid" = ""ELAN0000""
-		register "desc" = ""ELAN Touchpad""
-		register "irq" = "ACPI_IRQ_WAKE_LEVEL_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, Level, ActiveLow, ExclusiveAndWake, ,, )
-            {
-                0x0000002D,
-            }
-        })
-        Name (_S0W, ACPI_DEVICE_SLEEP_D3_HOT)  // _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, Level, ActiveLow, ExclusiveAndWake, ,, )
-    {
-        0x0000002D,
-    }
-```
-
-which comes from:
-
-```
-    register "irq" = "ACPI_IRQ_WAKE_LEVEL_LOW(GPP_A21_IRQ)"
-```
-
-The GPIO pin IRQ settings control the "Level", "ActiveLow", and
-"ExclusiveAndWake" settings seen above (level means it is a level-triggered
-interrupt as opposed to edge-triggered; active low means the interrupt is
-triggered when the signal is low).
-
-Note that the ACPI_IRQ_WAKE_LEVEL_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 ACPI_DEVICE_SLEEP_D3_HOT, representing _D3hot_.
-
-### _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,17 +73,17 @@ 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
+above functions with error messages indicating that these functions
+are being used. This allows drivers to conditionally make use of GPIOs
+based on device-tree entries or any other config option. It is
+recommended that the SoC code in coreboot should provide
+implementations of all the above functions generating ACPI AML code
+irrespective of them being used in any driver. This allows mainboards
+to use any drivers and take advantage of this common infrastructure.
+
 Platforms are restricted to using Local5, Local6 and Local7 variables
 only in implementations of the above functions. Any AML methods called
 by the above functions do not have any such restrictions on use of
@@ -150,6 +150,7 @@ for the GPIO.
 	 */
 	acpigen_write_if_and(Local5, TX_BIT);
 	acpigen_write_store_args(ONE_OP, LOCAL0_OP);
+	acpigen_pop_len();
 	acpigen_write_else();
 	acpigen_write_store_args(ZERO_OP, LOCAL0_OP);
 	acpigen_pop_len();

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,96 +2,41 @@
 
 This section contains documentation about coreboot on x86 architecture.
 
-* [x86 PAE support](pae.md)
-
 ## State of x86_64 support
-At the moment there's only experimental x86_64 support.
+At the moment there's no single board that supports x86_64 or to be exact
-The `emulation/qemu-i440fx` and `emulation/qemu-q35` boards do support
+`ARCH_RAMSTAGE_X86_64` and `ARCH_ROMSTAGE_X86_64`.
-*ARCH_RAMSTAGE_X86_64* , *ARCH_POSTCAR_X86_64* and *ARCH_ROMSTAGE_X86_64*.
 
-In order to add support for x86_64 the following assumptions were made:
+In order to add support for x86_64 the following assumptions are made:
 * The CPU supports long mode
 * All memory returned by malloc must be below 4GiB in physical memory
 * All code that is to be run must be below 4GiB in physical memory
 * The high dword of pointers is always zero
 * The reference implementation is qemu
 * The CPU supports 1GiB hugepages
-* x86 payloads are loaded below 4GiB in physical memory and are jumped
-  to in *protected mode*
 
-## Assumptions for all stages using the reference implementation
+## Assuptions for ARCH_ROMSTAGE_X86_64 reference implementation
-* 0-4GiB are identity mapped using 2MiB-pages as WB
+* 0-4GiB are identity mapped using 1GiB huge-pages
 * Memory above 4GiB isn't accessible
-* page tables reside in memory mapped ROM
+* pagetables reside in _pagetables
-* A stage can install new page tables in RAM
+* Romstage must install new pagetables in CBMEM after RAMINIT
 
-## Page tables
+## Assuptions for ARCH_RAMSTAGE_X86_64 reference implementation
-Page tables are generated by a tool in `util/pgtblgen/pgtblgen`. It writes
+* Romstage installed pagetables according to memory layout
-the page tables to a file which is then included into the CBFS as file called
+* Memory above 4GiB is accessible
-`pagetables`.
 
-To generate the static page tables it must know the physical address where to
+## Steps to add basic support for x86_64
-place the file.
+* Add x86_64 toolchain support - *DONE*
-
+* Fix compilation errors - *DONE*
-The page tables contains the following structure:
+* Fix linker errors - *TODO*
-* PML4E pointing to PDPE
+* Add x86_64 rmodule support - *ONGERRIT*
-* PDPE with *$n* entries each pointing to PDE
+* Add x86_64 exception handlers - *TODO*
-* *$n* PDEs with 512 entries each
+* Setup page tables for long mode - *TODO*
-
+* Add assembly code for long mode - *TODO*
-At the moment *$n* is 4, which results in identity mapping the lower 4 GiB.
+* Add assembly code to return to protected mode - *TODO*
-
+* Implement reference code for mainboard `emulation/qemu-q35` - *TODO*
-## Basic x86_64 support
-Basic support for x86_64 has been implemented for QEMU mainboard target.
-
-## Reference implementation
-The reference implementation is
-* [QEMU i440fx](../../mainboard/emulation/qemu-i440fx.md)
-* [QEMU Q35](../../mainboard/emulation/qemu-q35.md)
-
-## TODO
-* Identity map memory above 4GiB in ramstage
-
-## Future work
-
-1. Fine grained page tables for SMM:
-   * Must not have execute and write permissions for the same page.
-   * Must allow only that TSEG pages can be marked executable
-   * Must reside in SMRAM
-2. Support 64bit PCI BARs above 4GiB
-3. Place and run code above 4GiB
 
 ## Porting other boards
 * Fix compilation errors
 * Test how well CAR works with x86_64 and paging
 * Improve mode switches
 * Test libgfxinit / VGA Option ROMs / FSP
-
-## Known bugs on real hardware
-
-According to Intel x86_64 mode hasn't been validated in CAR environments.
-Until now it could be verified on various Intel platforms and no issues have
-been found.
-
-## Known bugs on KVM enabled qemu
-
-The `x86_64` reference code runs fine in qemu soft-cpu, but has serious issues
-when using KVM mode on some machines. The workaround is to *not* place
-page-tables in ROM, as done in
-[CB:49228](https://review.coreboot.org/c/coreboot/+/49228).
-
-Here's a list of known issues:
-
-* After entering long mode, the FPU doesn't work anymore, including accessing
-  MMX registers. It works fine before entering long mode. It works fine when
-  switching back to protected mode. Other registers, like SSE registers, are
-  working fine.
-* Reading from virtual memory, when the page tables are stored in ROM, causes
-  the MMU to abort the "page table walking" mechanism when the lower address
-  bits of the virtual address to be translated have a specific pattern.
-  Instead of loading the correct physical page, the one containing the
-  page tables in ROM will be loaded and used, which breaks code and data as
-  the page table doesn't contain the expected data. This in turn leads to
-  undefined behaviour whenever the 'wrong' address is being read.
-* Disabling paging in compatibility mode crashes the CPU.
-* Returning from long mode to compatibility mode crashes the CPU.
-* Entering long mode crashes on AMD host platforms.

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/cbfstool/index.md

@@ -1,5 +0,0 @@
-# cbfstool
-
-Contents:
-
-* [Handling memory mapped boot media](mmap_windows.md)

Documentation/cbfstool/mmap_windows.md

@@ -1,77 +0,0 @@
-# cbfstool: Handling memory mapped boot media
-
-`cbfstool` is a utility used for managing coreboot file system (CBFS)
-components in a ROM image. x86 platforms are special since they have
-the SPI flash boot media memory mapped into host address space at
-runtime. This requires `cbfstool` to deal with two separate address
-spaces for any CBFS components that are eXecute-In-Place (XIP) - one
-is the SPI flash address space and other is the host address space
-where the SPI flash gets mapped.
-
-By default, all x86 platforms map a maximum of 16MiB of SPI flash at
-the top of 4G in host address space. If the flash is greater than
-16MiB, then only the top 16MiB of the flash is mapped in the host
-address space. If the flash is smaller than 16MiB, then the entire SPI
-flash is mapped at the top of 4G and the rest of the space remains
-unused.
-
-In more recent platforms like Tiger Lake (TGL), it is possible to map
-more than 16MiB of SPI flash. Since the host address space has legacy
-fixed device addresses mapped below `4G - 16M`, the SPI flash is split
-into separate windows when being mapped to the host address space.
-Default decode window of maximum 16MiB size still lives just below the
-4G boundary. The additional decode window is free to live in any
-available MMIO space that the SoC chooses.
-
-Following diagram shows different combinations of SPI flash being
-mapped into host address space when using multiple windows:
-
-![MMAP window combinations with different flash sizes][mmap_windows]
-
-*(a) SPI flash of size 16MiB (b) SPI flash smaller than 16MiB (c) SPI flash
-of size (16MiB+ext window size) (d) SPI flash smaller than (16MiB+ext
-window size)*
-
-The location of standard decode window is fixed in host address space
-`(4G - 16M) to 4G`. However, the platform is free to choose where the
-extended window lives in the host address space. Since `cbfstool`
-needs to know the exact location of the extended window, it allows the
-platform to pass in two parameters `ext-win-base` and `ext-win-size`
-that provide the base and the size of the extended window in host
-address space.
-
-`cbfstool` creates two memory map windows using the knowledge about the
-standard decode window and the information passed in by the platform
-about the extended decode window. These windows are useful in
-converting addresses from one space to another (flash space and host
-space) when dealing with XIP components.
-
-## Assumptions
-
-1. Top 16MiB is still decoded in the fixed decode window just below 4G
-   boundary.
-1. Rest of the SPI flash below the top 16MiB is mapped at the top of
-   the extended window. Even though the platform might support a
-   larger extended window, the SPI flash part used by the mainboard
-   might not be large enough to be mapped in the entire window. In
-   such cases, the mapping is assumed to be in the top part of the
-   extended window with the bottom part remaining unused.
-
-## Example
-
-If the platform supports extended window and the SPI flash size is
-greater, then `cbfstool` creates a mapping for the extended window as
-well.
-
-```
-ext_win_base = 0xF8000000
-ext_win_size = 32 * MiB
-ext_win_limit = ext_win_base + ext_win_size - 1 = 0xF9FFFFFF
-```
-
-If SPI flash is 32MiB, then top 16MiB is mapped from `0xFF000000 -
-0xFFFFFFFF` whereas the bottom 16MiB is mapped from `0xF9000000 -
-0xF9FFFFFF`. The extended window `0xF8000000 - 0xF8FFFFFF` remains
-unused.
-
-[mmap_windows]: mmap_windows.svg

Documentation/coding_style.md

@@ -1,30 +1,16 @@
 # Coding Style
 
-This document describes the preferred C coding style for the
+This is a short document describing the preferred coding style for the
 coreboot project. It is in many ways exactly the same as the Linux
 kernel coding style. In fact, most of this document has been copied from
 the [Linux kernel coding style](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/CodingStyle?id=HEAD)
 
-The guidelines in this file should be seen as a strong suggestion, and
+Please at least consider the points made here.
-should overrule personal preference. But they may be ignored in
-individual instances when there are good practical reasons to do so, and
-reviewers are in agreement.
 
-Any style questions that are not mentioned in here should be decided
+First off, I'd suggest printing out a copy of the GNU coding standards,
-between the author and reviewers on a case-by-case basis. When modifying
+and NOT read it. Burn them, it's a great symbolic gesture.
-existing files, authors should try to match the prevalent style in that
-file -- otherwise, they should try to match similar existing files in
-coreboot.
 
-Bulk style changes to existing code ("cleanup patches") should avoid
+Anyway, here goes:
-changing existing style choices unless they actually violate this style
-guide, or there is broad consensus that the new version is an
-improvement. By default the style choices of the original author should
-be honored. (Note that `checkpatch.pl` is not part of this style guide,
-and neither is `clang-format`. These tools can be useful to find
-potential issues or simplify formatting in new submissions, but they
-were not designed to directly match this guide and may have false
-positives. They should not be bulk-applied to change existing code.)
 
 ## Indentation
 
@@ -94,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,
+Statements longer than 80 columns will be broken into sensible chunks,
-unless exceeding 96 columns significantly increases readability and does
+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
@@ -544,7 +530,7 @@ than desirable (in fact, they are worse than random typing - an infinite
 number of monkeys typing into GNU emacs would never make a good program).
 
 So, you can either get rid of GNU emacs, or change it to use saner values.
-To do the latter, you can stick the following in your .emacs file:
+To do the latter, you can stick the following in your .emacs file: 
 
 ```lisp
 (defun c-lineup-arglist-tabs-only (ignored)
@@ -801,7 +787,7 @@ There are a LOT of cpu cycles that can go into these 5 milliseconds.
 
 A reasonable rule of thumb is to not put inline at functions that have
 more than 3 lines of code in them. An exception to this rule are the
-cases where a parameter is known to be a compile time constant, and as a
+cases where a parameter is known to be a compiletime constant, and as a
 result of this constantness you *know* the compiler will be able to
 optimize most of your function away at compile time. For a good example
 of this later case, see the kmalloc() inline function.
@@ -848,53 +834,22 @@ subject to this rule. Generally they indicate failure by returning some
 out-of-range result. Typical examples would be functions that return
 pointers; they use NULL or the ERR_PTR mechanism to report failure.
 
-Headers and includes
+Don't re-invent the kernel macros
----------------
+----------------------------------
 
-Headers should always be included at the top of the file. Includes should
+The header file include/linux/kernel.h contains a number of macros that
-always use the `#include <file.h>` notation, except for rare cases where a file
+you should use, rather than explicitly coding some variant of them
-in the same directory that is not part of a normal include path gets included
+yourself. For example, if you need to calculate the length of an array,
-(e.g. local headers in mainboard directories), which should use `#include
+take advantage of the macro
-"file.h"`. Local "file.h" includes should always come separately after all
-<file.h> includes.  Headers that can be included from both assembly files and
-.c files should keep all C code wrapped in `#ifndef __ASSEMBLER__` blocks,
-including includes to other headers that don't follow that provision. Where a
-specific include order is required for technical reasons, it should be clearly
-documented with comments.
-
-Files should generally include every header they need a definition from
-directly (and not include any unnecessary extra headers). Excepted from
-this are certain headers that intentionally chain-include other headers
-which logically belong to them and are just factored out into a separate
-location for implementation or organizatory reasons. This could be
-because part of the definitions is generic and part SoC-specific (e.g.
-`<gpio.h>` chain-including `<soc/gpio.h>`), architecture-specific (e.g.
-`<device/mmio.h>` chain-including `<arch/mmio.h>`), separated out into
-commonlib[/bsd] for sharing/license reasons (e.g. `<cbfs.h>`
-chain-including `<commonlib/bsd/cbfs_serialized.h>`) or just split out
-to make organizing subunits of a larger header easier. This can also
-happen when certain definitions need to be in a specific header for
-legacy POSIX reasons but we would like to logically group them together
-(e.g. `uintptr_t` is in `<stdint.h>` and `size_t` in `<stddef.h>`, but
-it's nicer to be able to just include `<types.h>` and get all the common
-type and helper function stuff we need everywhere).
-
-The headers `<kconfig.h>`, `<rules.h>` and `<commonlib/bsd/compiler.h>`
-are always automatically included in all compilation units by the build
-system and should not be included manually.
-
-Don't re-invent common macros
------------------------------
-
-The header file `src/commonlib/bsd/include/commonlib/bsd/helpers.h`
-contains a number of macros that you should use, rather than explicitly
-coding some variant of them yourself. For example, if you need to
-calculate the length of an array, take advantage of the macro
 
 ```c
 #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
 ```
 
+There are also min() and max() macros that do strict type checking if
+you need them. Feel free to peruse that header file to see what else is
+already defined that you shouldn't reproduce in your code.
+
 Editor modelines and other cruft
 --------------------------------
 

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
+misunderstandings can (and do) happen. Always assume that others are
-and may have picked less-than-stellar wording by accident as long as
+friendly and may have picked less-than-stellar wording by accident.
-you possibly can.
 
-## Reporting Issues
+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
-If you have a grievance due to conduct in this community, we're sorry
+team directly: They will listen to you and react in a timely fashion.
-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.
 
 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
+However since people might be on travel or otherwise be unavailable at
-at times, please reach out to multiple persons at once, especially
+times, consider reaching out to multiple persons.
-when using email.
 
 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/forums.md

@@ -11,29 +11,8 @@ You can subscribe on its
 read its
 [archives](https://mail.coreboot.org/hyperkitty/list/coreboot@coreboot.org/).
 
-## Real time chat
+## IRC
 
-We also have a real time chat room on [IRC](ircs://irc.libera.chat/#coreboot),
+We also have a
-also bridged to [Matrix](https://matrix.to/#/#coreboot:libera.chat) and a
+[real time chat](https://webchat.freenode.net?channels=%23coreboot)
-[Discord](https://discord.gg/JqT8NM5Zbg) presence. You can also find us on
+on the Freenode IRC network's #coreboot channel.
-[OSF Slack](https://osfw.slack.com/), which has channels on many open source
-firmware related topics. Slack requires that people come from specific domains
-or are explicitly invited. To work around that, there's an
-[invite bot](https://slack.osfw.dev/) to let people in.
-
-## Fortnightly coreboot leadership meeting
-
-There's a leadership meeting held every 14 days (currently every other
-Wednesday at 10am Pacific Time, usually 18:00 UTC with some deviation
-possible due to daylight saving time related shifts). The meeting
-is open to everyone and provides a forum to discuss general coreboot
-topics, including community and technical matters that benefit from
-an official decision.
-
-We tried a whole lot of different tools, but so far the meetings worked
-best with [Google Meet](https://meet.google.com/syn-toap-agu),
-using [Google Docs](https://docs.google.com/document/d/1NRXqXcLBp5pFkHiJbrLdv3Spqh1Hu086HYkKrgKjeDQ/edit)
-for the agenda and meeting minutes. Neither the video conference nor
-the document require a Google account to participate, although editing
-access to the document is limited to adding comments - any desired
-agenda item added that way will be approved in time before the meeting.

Documentation/community/language_style.md

@@ -1,136 +0,0 @@
-# Language style
-
-Following our [Code of Conduct](code_of_conduct.md) the project aims to
-be a space where people are considerate in natural language communication:
-
-There are terms in computing that were probably considered benign when
-introduced but are uncomfortable to some. The project aims to de-emphasize
-such terms in favor of alternatives that are at least as expressive -
-but often manage to be even more descriptive.
-
-## Political Correctness
-
-A common thread in discussions was that the project merely follows some
-fad, or that this is a "political correctness" measure, designed to please
-one particular "team". While the project doesn't exist in a vacuum and
-so there are outside influences on project members, the proposal wasn't
-made with the purpose of demonstrating allegiance to any given cause -
-except one:
-
-There are people who feel uncomfortable with some terms being used,
-_especially_ when that use takes them out of their grave context
-(e.g. slave when discussing slavery) and applies them to a rather benign
-topic (e.g. coordination of multiple technical systems), taking away
-the gravity of the term.
-
-That gets especially jarring when people aren't exposed to such terms
-in abstract sociological discussions but when they stand for real issues
-they encountered.
-
-When having to choose between using a well-established term that
-affects people negatively who could otherwise contribute more happily
-and undisturbed or an alternative just-as-good term that doesn't, the
-decision should be simple.
-
-## Token gesture
-
-The other major point of contention is that such decisions are a token
-gesture that doesn't change anything. It's true: No slave is freed
-because coreboot rejects the use of the word.
-
-coreboot is ambitious enough as-is, in that the project offers
-an alternative approach to firmware, sometimes against the vested
-interests (and deep pockets) of the leaders of a multi-billion dollar
-industry. Changing the preferred vocabulary isn't another attempt at
-changing the world, it's one thing we do to try to make coreboot (and
-coreboot only) a comfortable environment for everybody.
-
-## For everybody
-
-For everybody, but with a qualifier: We have certain community etiquette,
-and we define some behavior we don't accept in our community, both
-detailed in the Code of Conduct.
-
-Other than that, we're trying to accommodate people: The CoC lays out
-that language should be interpreted as friendly by default, and to be
-graceful in light of accidents. This also applies to the use of terms
-that the project tries to avoid: The consequence of the use of such
-terms (unless obviously employed to provoke a reaction - in that case,
-please contact the arbitration team as outlined in the Code of Conduct)
-should be a friendly reminder. The project is slow to sanction and that
-won't change just because the wrong kind of words is used.
-
-## Interfacing with the world
-
-The project doesn't exist in a vacuum, and that also applies to the choice
-of words made by other initiatives in low-level technology. When JEDEC
-calls the participants of a SPI transaction "master" and "slave", there's
-little we can do about that. We _could_ decide to use different terms,
-but that wouldn't make things easier but harder, because such a deliberate
-departure means that the original terms (and their original use) gain
-lots of visibility every time (so there's no practical advantage) while
-adding confusion, and therefore even more attention, to that situation.
-
-Sometimes there are abbreviations that can be used as substitutes,
-and in that case the recommendation is to do that.
-
-As terms that we found to be best avoided are replaced in such
-initiatives, we can follow up. Members of the community with leverage
-in such organizations are encouraged to raise the concern there.
-
-## Dealing with uses
-
-There are existing uses in our documentation and code. When we decide to
-retire a term that doesn't mean that everybody is supposed to stop doing
-whatever they're doing and spend their time on purging terms. Instead,
-ongoing development should look for alternatives (and so this could come
-up in review).
-
-People can go through existing code and docs and sort out older instances,
-and while that's encouraged it's no "stop the world" event. Changes
-in flight in review may still be merged with such terms intact, but if
-there's more work required for other reasons, we'd encourage moving away
-from such terms.
-
-This document has a section on retired terms, presenting the rationale
-as well as alternative terms that could be used instead. The main goal is
-to be expressive: There's no point in just picking any alternative term,
-choose something that explains the purpose well.
-
-As mentioned, missteps will happen. Point them out, but assume no ill
-intent for as long as you can manage.
-
-## Discussing words to remove from active use
-
-There ought to be some process when terminology is brought up as a
-negative to avoid. Do not to tell people that "they're feeling wrong"
-when they have a negative reaction to certain terms, but also try to
-avoid being offended for the sake of others.
-
-When bringing up a term, on the project's mailing list or, if you don't
-feel safe doing that, by contacting the arbitration team, explain what's
-wrong with the term and offer alternatives for uses within coreboot.
-
-With a term under discussion, see if there's particular value for us to
-continue using the term (maybe in limited situations, like continuing
-to use "slave" in SPI related code).
-
-Once the arbitration team considers the topic discussed completely and
-found a consensus, it will present a decision in a leadership meeting. It
-should explain why a term should or should not be used and in the latter
-case offer alternatives. These decisions shall then be added to this
-document.
-
-## Retired terminology
-
-### slave
-
-Replacing this term for something else had the highest approval rating
-in early discussions, so it seems pretty universally considered a bad
-choice and therefore should be avoided where possible.
-
-An exception is made where it's a term used in current standards and data
-sheets: Trying to "hide" the term in such cases only puts a spotlight
-on it every time code and data sheet are compared.
-
-Alternatives: subordinate, secondary, follower

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

@@ -1,18 +1,6 @@
 # -*- coding: utf-8 -*-
 import subprocess
 from recommonmark.parser import CommonMarkParser
-import sphinx
-
-# Get Sphinx version
-major = 0
-minor = 0
-patchlevel = 0
-version = sphinx.__version__.split(".")
-if len(version) > 1:
-	major = int(version[0])
-	minor = int(version[1])
-	if len(version) > 2:
-		patchlevel = int(version[2])
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -37,19 +25,6 @@ release = subprocess.check_output(('git', 'describe')).decode("utf-8")
 # The short X.Y version.
 version = release.split("-")[0]
 
-extensions = []
-# Load recommonmark, supported since 1.8+
-if major >= 2 or (major == 1 and minor >= 8):
-    extensions += ['recommonmark']
-
-# Try to load DITAA
-try:
-    import sphinxcontrib.ditaa
-except ImportError:
-    print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
-else:
-    extensions += ['sphinxcontrib.ditaa']
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
@@ -185,7 +160,7 @@ texinfo_documents = [
 enable_auto_toc_tree = True
 
 class MyCommonMarkParser(CommonMarkParser):
-    # remove this hack once upstream RecommonMark supports inline code
+    # remove this hack once upsteam RecommonMark supports inline code
     def visit_code(self, mdnode):
         from docutils import nodes
         n = nodes.literal(mdnode.literal, mdnode.literal)
@@ -210,9 +185,7 @@ class MyCommonMarkParser(CommonMarkParser):
 
 def setup(app):
     from recommonmark.transform import AutoStructify
-    # Load recommonmark on old Sphinx
+    app.add_source_parser('.md', MyCommonMarkParser)
-    if major == 1 and minor < 8:
-        app.add_source_parser('.md', MyCommonMarkParser)
 
     app.add_config_value('recommonmark_config', {
         'enable_auto_toc_tree': True,

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
+(shell, make, ...).
-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.
 
 ### Requirements
 * coreboot knowledge: Should know how to build coreboot images and where
@@ -66,7 +58,47 @@ across architectures.
 ### Mentors
 * Timothy Pearson <tpearson@raptorengineering.com>
 
-## Port payloads to ARM, AArch64 or RISC-V
+## 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
+during runtime and find bugs like stack overflow or out-of-bounds accesses.
+Implementing this stub into coreboot like "Undefined behavior sanitizer support"
+would help to ensure code quality and make the runtime code more robust.
+
+### Requirements
+* knowledge in the coreboot build system and the concept of stages
+* the KASAN feature can be improved in a way so that the memory space needed
+  during runtime is not on a fixed address provided during compile time but
+  determined during runtime. For this to achieve a small patch to the GCC will
+  be helpful. Therefore minor GCC knowledge would be beneficial.
+* Implementation can be initially done in QEMU and improved on different
+  mainboards and platforms
+
+### Mentors
+* Werner Zeh <werner.zeh@gmx.net>
+
+## 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,
@@ -113,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 management tasks and new board status uploads.
-
-At least one older test result should be kept 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

@@ -8,15 +8,28 @@ and those providing after-market firmware to extend the usefulness of devices.
 
 ## Hardware shipping with coreboot
 
+### Purism
+
+[Purism](https://www.puri.sm) sells laptops with a focus on user privacy and
+security; part of that effort is to minimize the amount of proprietary and/or
+binary code. Their laptops ship with a blob-free OS and coreboot firmware
+with a neutralized Intel Management Engine (ME) and SeaBIOS as the payload.
+
 ### ChromeOS Devices
 
 All ChromeOS devices ([Chromebooks](https://chromebookdb.com/), Chromeboxes,
 Chromebit, etc) released from 2012 onward use coreboot for their main system
 firmware. Additionally, starting with the 2013 Chromebook Pixel, the firmware
-running on the Embedded Controller (EC) – a small microcontroller which provides
+running on the Embedded Controller (EC - a small microcontroller which provides
-functions like battery management, keyboard support, and sensor interfacing –
+functions like battery management, keyboard support, and sensor interfacing)
 is open source as well.
 
+### Libretrend
+
+[Libretrend](https://libretrend.com) sells the Librebox, a NUC-like PC which
+ships with coreboot firmware.
+
+
 ### PC Engines APUs
 
 [PC Engines](https://pcengines.ch) designs and sells embedded PC hardware that
@@ -24,20 +37,6 @@ ships with coreboot and support upstream maintenance for the devices through a
 third party, [3mdeb](https://3mdeb.com). They provide current and tested
 firmware binaries on [GitHub](https://pcengines.github.io).
 
-### System76
-
-[System76](https://system76.com/) manufactures Linux laptops, desktops, and
-servers. Some models are sold with [System76 Open
-Firmware](https://github.com/system76/firmware-open), an open source
-distribution of coreboot, EDK2, and System76 firmware applications.
-
-### Purism
-
-[Purism](https://www.puri.sm) sells laptops with a focus on user privacy and
-security; part of that effort is to minimize the amount of proprietary and/or
-binary code. Their laptops ship with a blob-free OS and coreboot firmware
-with a neutralized Intel Management Engine (ME) and SeaBIOS as the payload.
-
 ## After-market firmware
 
 ### Libreboot
@@ -59,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/dptf.md

@@ -1,329 +0,0 @@
-# Intel DPTF implementations in coreboot
-
-## Introduction
-
-Intel Dynamic Platform and Thermal Framework is a framework that can be used to
-help regulate the thermal properties (i.e., temperature) of an Intel-based
-computer. It does this by allowing the system designer to specify the different
-components that can generate heat, and/or dissipate heat. Under DPTF, the
-different components are referred to as `participants`. The different types of
-functionality available in DPTF are specified in terms of different `policies`.
-
-## Components ("Participants")
-
-The participants that can be involved in the current implementation are:
-- CPU (monolithic from a DPTF point-of-view)
-  - Note that the CPU's internal temperature sensor is used here
-- 1 fan
-- Up to 4 temperature sensors (TSRs)
-- Battery charger
-
-## Policies
-
-In the current implementation, there are 3 different policies available:
-
-### Passive Policy
-
-The purpose of this policy is to monitor participant temperatures and is capable
-of controlling performance and throttling available on platform devices in order
-to regulate the temperatures of each participant. The temperature threshold
-points are defined by a `_PSV` ACPI object within each participant.
-
-### Critical Policy
-
-The Critical Policy is used for gracefully suspending or powering off the system
-when the temperature of participants exceeds critical threshold
-temperatures. Suspend is effected by specifying temperatures in a `_CRT` object
-for a participant, and poweroff is effected by specifying a temperature
-threshold in a `_HOT` ACPI object.
-
-### Active Policy
-
-This policy monitors the temperature of participants and controls fans to spin
-at varying speeds. These speeds are defined by the platform, and will be enabled
-depending on the various temperatures reported by participants.
-
-# Note about units
-
-ACPI uses unusual units for specifying various physical measurements. For
-example, temperatures are specified in 10ths of a degree K, and time is measured
-in tenths of a second. Those oddities are abstracted away in the DPTF library,
-by using degrees C for temperature, milliseconds for time, mW for power, and mA
-for current.
-
-## Differences from the static ASL files (soc/intel/common/acpi/dptf/*.asl)
-
-1) TCPU had many redundant methods. The many references to \_SB.CP00._* are not
-created anymore in recent SoCs and the ACPI spec says these are optional objects
-anyway. The defaults that were returned by these methods were redundant (all
-data was a 0). The following Methods were removed:
-
-* _TSS
-* _TPC
-* _PTC
-* _TSD
-* _TDL
-* _PSS
-* _PDL
-
-2) There is no more implicit inclusion of _ACn methods for TCPU (these must be
-   specified in the devicetree entries or by calling the DPTF acpigen API).
-
-# ACPI Tables
-
-DPTF relies on an assortment of ACPI tables to provide parameters to the DPTF
-application. We will discuss the more important ones here.
-
-1) _TRT - Thermal Relationship Table
-
-This table is used when the Passive Policy is enabled, and is used to represent
-the thermal relationships in the system that can be controlled passively (i.e.,
-by throttling participants). A passive policy is defined by a Source (which
-generates heat), a Target (typically a temperature sensor), a Sampling Period
-(how often to check the temperature), an activation temperature threshold (for
-when to begin throttling), and a relative priority.
-
-2) _ART - Active Relationship Table
-
-This table is used when the Active Policy is enabled, and is used to represent
-active cooling relationships (i.e., which TSRs the fan can cool). An active
-policy contains a Target (the device the fan can cool), a Weight to control
-which participant needs more attention than others, and a list of temperature /
-fan percentage pairs. The list of pairs defines the fan control percentage that
-should be applied when the TSR reaches each successive threshold (_AC0 is the
-highest threshold, and represents the highest fan control percentage).
-
-3) PPCC - Participant Power Control Capabilities
-
-This table is used to describe parameters for controlling the SoC's Running
-Average Power Limits (RAPL, see below).
-
-4) _FPS - Fan Performance States
-
-This table describes the various fan speeds available for DPTF to use, along with
-various informational properties.
-
-5) PPSS - Participant Performance Supported States
-
-This table describes performance states supported by a participant (typically
-the battery charger).
-
-# ACPI Methods
-
-The Active and Passive policies also provide for short Methods to define
-different kinds of temperature thresholds.
-
-1) _AC0, _AC1, _AC2, _AC3, ..., _AC9
-
-These Methods can provide up to 10 temperature thresholds. What these do is set
-temperatures which act as the thresholds to active rows (fan speeds) in the
-ART. _AC0 is intended to be the highest temperature thresholds, and the lowest
-one can be any of them; leave the rest defined as 0 and they will be omitted
-from the output.
-
-These are optional and are enabled by selecting the Active Policy.
-
-2) _PSV
-
-_PSV is a temperature threshold that is used to indicate to DPTF that it should
-begin taking passive measures (i.e., throttling of the Source) in order to
-reduce the temperature of the Target in question. It will check on the
-temperature according to the given sampling period.
-
-This is optional and is enabled by selecting the Passive Policy.
-
-3) _CRT and _HOT
-
-When the temperature of the Source reaches the threshold specified in _CRT, then
-the system is supposed to execute a "graceful suspend". Similarly, when the Source
-reaches the temperature specified in _HOT, then the system is supposed to execute
-a "graceful shutdown".
-
-These are optional, and are enabled by selecting the Critical Policy.
-
-# How to use the devicetree entries
-
-The `drivers/intel/dptf` chip driver is organized into several sections:
-- Policies
-- Controls
-- Options
-
-The Policies section (`policies.active`, `policies.passive`, and
-`policies.critical`) is where the components of each policy are defined.
-
-## Active Policy
-
-Each Active Policy is defined in terms of 4 parts:
-1) A Source (this is implicitly defined as TFN1, the system fan)
-2) A Target (this is the device that can be affected by the policy, i.e.,
-   this is a device that can be cooled by the fan)
-3) A 'Weight', which is defined as the Source's contribution to the Target's
-   cooling capability (as a percentage, 0-100, often just left at 100).
-4) A list of temperature-fan percentage pairs, which define temperature
-   thresholds that, when the Target reaches, the fan is defined to spin
-   at the corresponding percentage of full duty cycle.
-
-An example definition in the devicetree:
-```C
-register "policies.active[0]" = "{
-    .target=DPTF_CPU,
-    .weight=100,
-    .thresholds={TEMP_PCT(85, 90),
-                 TEMP_PCT(80, 69),
-                 TEMP_PCT(75, 56),
-                 TEMP_PCT(70, 46),
-                 TEMP_PCT(65, 36),}}"
-```
-
-This example sets up a policy wherein the CPU temperature sensor can be cooled
-by the fan. The 'weight' of this policy is 100% (this policy contributes 100% of
-the CPU's active cooling capability). When the CPU temperature first crosses
-65C, the fan is defined to spin at 36% of its duty cycle, and so forth up the
-rest of the table (note that it *must* be defined from highest temperature/
-percentage on down to the lowest).
-
-## Passive Policy
-
-Each Passive Policy is defined in terms of 5 parts:
-1) Source - The device that can be throttled
-2) Target - The device that controls the amount of throttling
-3) Period - How often to check the temperature of the Target
-4) Trip point - What temperature threshold to start throttling
-5) Priority - A number indicating the relative priority between different
-   Policies
-
-An example definition in the devicetree:
-```C
-register "policies.passive[0]" = "DPTF_PASSIVE(CHARGER, TEMP_SENSOR_1, 65, 60000)"
-```
-
-This example sets up a policy to begin throttling the charger performance when
-temperature sensor 1 reaches 65C. The sampling period here is 60000 ms (60 s).
-The Priority is defaulted to 100 in this case.
-
-## Critical Policy
-
-Each Critical Policy is defined in terms of 3 parts:
-1) Source - A device that can trigger a critical event
-2) Type - What type of critical event to trigger (S4-entry or shutdown)
-3) Temperature - The temperature threshold that will cause the entry into S4 or
-   to shutdown the system.
-
-An example definition in the devicetree:
-
-```C
-register "policies.critical[1]" = "DPTF_CRITICAL(CPU, 75, SHUTDOWN)"
-```
-
-This example sets up a policy wherein ACPI will cause the system to shutdown
-(in a "graceful" manner) when the CPU temperature reaches 75C.
-
-## Power Limits
-
-Control over the SoC's Running Average Power Limits (RAPL) is one of the tools
-that DPTF uses to enact Passive policies. DPTF can control both PL1 and PL2, if
-the PPCC table is provided for the TCPU object. Each power limit is given the
-following options:
-1) Minimum power (in mW)
-2) Maximum power (in mW)
-3) Minimum time window (in ms)
-4) Maximum time window (in ms)
-5) Granularity, or minimum step size to control limits (in mW)
-
-An example:
-```C
-register "controls.power_limits.pl1" = "{
-        .min_power = 3000,
-        .max_power = 15000,
-        .time_window_min = 28 * MSECS_PER_SEC,
-        .time_window_max = 32 * MSECS_PER_SEC,
-        .granularity = 200,}"
-```
-
-This example allow DPTF to control the SoC's PL1 level to between 3W and 15W,
-over a time interval ranging from 28 to 32 seconds, and it can move PL1 in
-increments of 200 mW.
-
-## Charger Performance
-
-The battery charger can be a large contributor of unwanted heat in a system that
-has one. Controlling the rate of charging is another tool that DPTF uses to enact
-Passive Policies. Each entry in the PPSS table consists of:
-1) A 'Control' value - an opaque value that the platform firmware uses
-   to initiate a transition to the specified performance state. DPTF will call an
-   ACPI method called `TCHG.SPPC` (Set Participant Performance Capability) if
-   applicable, and will pass this opaque control value as its argument.
-2) The intended charging rate (in mA).
-
-Example:
-```C
-register "controls.charger_perf[0]" = "{ 255, 1700 }"
-register "controls.charger_perf[1]" = "{  24, 1500 }"
-register "controls.charger_perf[2]" = "{  16, 1000 }"
-register "controls.charger_perf[3]" = "{   8,  500 }"
-```
-
-In this example, when DPTF decides to throttle the charger, it has four different
-performance states to choose from.
-
-## Fan Performance
-
-When using DPTF, the system fan (`TFN1`) is the device responsible for actively
-cooling the other temperature sensors on the mainboard. A fan speed table can be
-provided to DPTF to assist with fan control. Each entry holds the following:
-1) Percentage of full duty to spin the fan at
-2) Speed - Speed of the fan at that percentage; informational only, but given in
-   RPM
-3) Noise - Amount of noise created by the fan at that percentage; informational
-   only, but given in tenths of a decibel (centibel).
-4) Power - Amount of power consumed by the fan at that percentage; informational
-   only, but given in mA.
-
-Example:
-```C
-register "controls.fan_perf[0]" = "{  90, 6700, 220, 2200, }"
-register "controls.fan_perf[1]" = "{  80, 5800, 180, 1800, }"
-register "controls.fan_perf[2]" = "{  70, 5000, 145, 1450, }"
-register "controls.fan_perf[3]" = "{  60, 4900, 115, 1150, }"
-register "controls.fan_perf[4]" = "{  50, 3838,  90,  900, }"
-register "controls.fan_perf[5]" = "{  40, 2904,  55,  550, }"
-register "controls.fan_perf[6]" = "{  30, 2337,  30,  300, }"
-register "controls.fan_perf[7]" = "{  20, 1608,  15,  150, }"
-register "controls.fan_perf[8]" = "{  10,  800,  10,  100, }"
-register "controls.fan_perf[9]" = "{   0,    0,   0,   50, }"
-```
-
-In this example, the fan has 10 different performance states, each in an even
-increment of 10 percentage points. This is common when specifying fine-grained
-control of the fan, wherein DPTF will interpolate between the percentages in the
-table for a given temperature threshold.
-
-## Options
-
-### Fan
-1) Fine-grained control - a boolean (see Fan Performance section above)
-2) Step-size - Recommended minimum step size (in percentage points) to adjust
-   the fan speed when using fine-grained control (ranges from 1 - 9).
-3) Low-speed notify - If true, the platform will issue a `Notify (0x80)` to the
-   fan device if a low fan speed is detected.
-
-### Temperature sensors
-1) Hysteresis - The amount of hysteresis implemented in either circuitry or
-   the firmware that reads the temperature sensor (in degrees C).
-2) Name - This name is applied to the _STR property of the sensor
-
-## OEM Variables
-Platform vendors can define an array of OEM-specific values as OEM variables
-to be used under DPTF policy. There are total six OEM variables available.
-These can be used in AP policy for more specific actions. These OEM variables
-can be defined as below mentioned example and can be used any variable between
-[0], [1],...,[5]. Platform vendors can enable and use this for specific platform
-by defining OEM variables macro under board variant.
-
-Example:
-```C
-register "oem_data.oem_variables" = "{
-   [1] = 0x6,
-   [3] = 0x1
-}"
-```

Documentation/drivers/index.md

@@ -1,12 +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 across platforms.
-
-* [Intel DPTF](dptf.md)
-* [IPMI KCS](ipmi_kcs.md)
-* [SMMSTORE](smmstore.md)
-* [SoundWire](soundwire.md)
-* [SMMSTOREv2](smmstorev2.md)
-* [USB4 Retimer](retimer.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/retimer.md

@@ -1,40 +0,0 @@
-# USB4 Retimers
-
-# Introduction
-As USB speeds continue to increase (up to 5G, 10G, and even 20G or higher in
-newer revisions of the spec), it becomes more difficult to maintain signal
-integrity for longer traces. Devices such as retimers and redrivers can be used
-to help signals maintain their integrity over long distances.
-
-A redriver is a device that boosts the high-frequency content of a signal in
-order to compensate for the attenuation typically caused by travelling through
-various circuit components (PCB, connectors, CPU, etc.). Redrivers are not
-protocol-aware, which makes them relatively simple. However, their effectiveness
-is limited, and may not work at all in some scenarios.
-
-A retimer is a device that retransmits a fresh copy of the signal it receives,
-by doing CDR and retransmitting the data (i.e., it is protocol-aware). Since
-this is a digital component, it may have firmware.
-
-
-# Driver Usage
-
-Some operating systems may have the ability to update firmware on USB4 retimers,
-and ultimately will need some way to power the device on and off so that its new
-firmware can be loaded. This is achieved by providing a GPIO signal that can be
-used for this purpose; its active state must be the one in which power is
-applied to the retimer. This driver will generate the required ACPI AML code
-which will toggle the GPIO in response to the kernel's request (through the
-`_DSM` ACPI method). Simply put something like the following in your devicetree:
-
-```
-device pci 0.0 on
-	chip drivers/intel/usb4/retimer
-		register "power_gpio" = "ACPI_GPIO_OUTPUT_ACTIVE_HIGH(GPP_A0)"
-		device generic 0 on end
-	end
-end
-```
-
-replacing the GPIO with the appropriate pin and polarity.
-

Documentation/drivers/smmstore.md

@@ -1,134 +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
-
-#### Security
-
-Pointers provided by the payload or OS are checked to not overlap with the SMM.
-That protects the SMM handler from being manipulated.
-
-*However there's no validation done on the source or destination pointing to
-DRAM. A malicious application that is able to issue SMIs could extract arbitrary
-data or modify the currently running kernel.*
-
-## 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.
-
-[SMM]: ../security/smm.md

Documentation/drivers/smmstorev2.md

@@ -1,221 +0,0 @@
-# SMM based flash storage driver Version 2
-
-This documents the API exposed by the x86 system management based
-storage driver.
-
-## SMMSTOREv2
-
-SMMSTOREv2 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` and `CONFIG_SMMSTORE_V2=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.
-
-### Storage size and alignment
-
-SMMSTORE version 2 requires a minimum alignment of 64 KiB, which should
-be supported by all flash chips. Not having to perform read-modify-write
-operations is desired, as it reduces complexity and potential for bugs.
-
-This can be used by a FTW (FaultTolerantWrite) implementation that uses
-at least two regions in an A/B update scheme. The FTW implementation in
-EDK2 uses three different regions in the store:
-
-- The variable store
-- The FTW spare block
-- The FTW working block
-
-All regions must be block-aligned, and the FTW spare size must be larger
-than that of the variable store. FTW working block can be much smaller.
-With 64 KiB as block size, the minimum size of the FTW-enabled store is:
-
-- The variable store: 1 block = 64 KiB
-- The FTW spare block: 2 blocks = 2 * 64 KiB
-- The FTW working block: 1 block = 64 KiB
-
-Therefore, the minimum size for EDK2 FTW is 4 blocks, or 256 KiB.
-
-## API
-
-The API provides read and write access to an unformatted block storage.
-
-### Storage region
-
-By default SMMSTOREv2 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 mandatory to align the `SMMSTORE` region to 64KiB for
-compatibility with the largest flash erase operation.
-
-When a default generated FMAP is used, the size of the FMAP region is
-equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least 64 KiB.
-To support a fault tolerant write mechanism, at least a multiple of
-this size is recommended.
-
-### Communication buffer
-
-To prevent malicious ring0 code to access arbitrary memory locations,
-SMMSTOREv2 uses a communication buffer in CBMEM/HOB for all transfers.
-This buffer has to be at least 64 KiB in size and must be installed
-before calling any of the SMMSTORE read or write operations. Usually,
-coreboot will install this buffer to transfer data between ring0 and
-the [SMM] handler.
-
-In order to get the communication buffer address, the payload or OS
-has to read the coreboot table with tag `0x0039`, containing:
-
-```C
-struct lb_smmstorev2 {
-	uint32_t tag;
-	uint32_t size;
-	uint32_t num_blocks;	/* Number of writeable blocks in SMM */
-	uint32_t block_size;	/* Size of a block in byte. Default: 64 KiB */
-	uint32_t mmap_addr;	/* MMIO address of the store for read only access */
-	uint32_t com_buffer;	/* Physical address of the communication buffer */
-	uint32_t com_buffer_size;	/* Size of the communication buffer in byte */
-	uint8_t apm_cmd;	/* The command byte to write to the APM I/O port */
-	uint8_t unused[3];	/* Set to zero */
-};
-```
-
-The absence of this coreboot table entry indicates that there's no
-SMMSTOREv2 support.
-
-### Blocks
-
-The SMMSTOREv2 splits the SMMSTORE FMAP partition into smaller chunks
-called *blocks*. Every block is at least the size of 64KiB to support
-arbitrary NOR flash erase ops. A payload or OS must make no further
-assumptions about the block or communication buffer size.
-
-### Generating the SMI
-
-SMMSTOREv2 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 SMMSTOREv2 command. `%ebx` contains the
-parameter buffer to the SMMSTOREv2 command.
-
-### Return values
-
-If a command succeeds, SMMSTOREv2 will return with
-`SMMSTORE_RET_SUCCESS=0` in `%eax`. On failure SMMSTORE will return
-`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
-`SMMSTORE_REG_UNSUPPORTED=2` is returned.
-
-**NOTE 1**: The caller **must** check the return value and should make
-no assumption on the returned data if `%eax` does not contain
-`SMMSTORE_RET_SUCCESS`.
-
-**NOTE 2**: If the SMI returns without changing `%ax`, it can be assumed
-that the SMMSTOREv2 feature is not installed.
-
-### Calling arguments
-
-SMMSTOREv2 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_INIT = 4
-
-This installs the communication buffer to use and thus enables the
-SMMSTORE handler. This command can only be executed once and is done
-by the firmware. Calling this function at runtime has no effect.
-
-The additional parameter buffer `%ebx` contains a pointer to the
-following struct:
-
-```C
-struct smmstore_params_init {
-	uint32_t com_buffer;
-	uint32_t com_buffer_size;
-} __packed;
-```
-
-INPUT:
-- `com_buffer`: Physical address of the communication buffer (CBMEM)
-- `com_buffer_size`: Size in bytes of the communication buffer
-
-#### - SMMSTORE_CMD_RAW_READ = 5
-
-SMMSTOREv2 allows reading arbitrary data. It is up to the caller to
-initialize the store with meaningful data before using it.
-
-The additional parameter buffer `%ebx` contains a pointer to the
-following struct:
-
-```C
-struct smmstore_params_raw_read {
-	uint32_t bufsize;
-	uint32_t bufoffset;
-	uint32_t block_id;
-} __packed;
-```
-
-INPUT:
-- `bufsize`: Size of data to read within the communication buffer
-- `bufoffset`: Offset within the communication buffer
-- `block_id`: Block to read from
-
-#### - SMMSTORE_CMD_RAW_WRITE = 6
-
-SMMSTOREv2 allows writing arbitrary data. It is up to the caller to
-erase a block before writing it.
-
-The additional parameter buffer `%ebx` contains a pointer to
-the following struct:
-
-```C
-struct smmstore_params_raw_write {
-        uint32_t bufsize;
-        uint32_t bufoffset;
-        uint32_t block_id;
-} __packed;
-```
-
-INPUT:
-- `bufsize`: Size of data to write within the communication buffer
-- `bufoffset`: Offset within the communication buffer
-- `block_id`: Block to write to
-
-#### - SMMSTORE_CMD_RAW_CLEAR = 7
-
-SMMSTOREv2 allows clearing blocks. A cleared block will read as `0xff`.
-By providing multiple blocks the caller can implement a fault tolerant
-write mechanism. It is up to the caller to clear blocks before writing
-to them.
-
-
-```C
-struct smmstore_params_raw_clear {
-	uint32_t block_id;
-} __packed;
-```
-
-INPUT:
-- `block_id`: Block to erase
-
-#### Security
-
-Pointers provided by the payload or OS are checked to not overlap with
-SMM. This protects the SMM handler from being compromised.
-
-As all information is exchanged using the communication buffer and
-coreboot tables, there's no risk that a malicious application capable
-of issuing SMIs could extract arbitrary data or modify the currently
-running kernel.
-
-## 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 that this differs significantly from coreboot's implementation.
-
-[SMM]: ../security/smm.md

Documentation/drivers/soundwire.md

@@ -1,496 +0,0 @@
-# SoundWire Implementation in coreboot
-
-## Introduction
-
-SoundWire is an audio interface specification from the MIPI Alliance.
-
-- Low complexity
-- Low power
-- Low latency
-- Two pins (clock and data)
-- Multi-drop capable
-- Multiple audio streams
-- Embedded control/command channel
-
-The main *SoundWire Specification* is at version 1.2 and can be downloaded from
-<https://mipi.org> but it is unfortunately only available to MIPI Alliance members.
-
-There is a separate *SoundWire Discovery and Configuration (DisCo) Specification* which
-is at version 1.0 and is available for non-members after providing name and email at
-<https://resources.mipi.org/disco_soundwire>.
-
-The coreboot implementation is based on the SoundWire DisCo Specification which defines
-object hierarchy and properties for providing topology and configuration information to
-OS kernel drivers via ACPI or DeviceTree.
-
-SoundWire itself is architecture independent and the coreboot basic definition is also not
-specific to any to any SoC.  The examples in this document use ACPI to generate properties,
-but the same structures and properties would be needed in a DeviceTree implementation.
-
-## Bus
-
-The SoundWire bus commonly consists of two pins:
-
-* Clock: A common clock signal distributed from the master to all of the slaves.
-* Data: A shared data signal that can be driven by any of the devices, and has a defined
-value when no device is driving it.
-
-While most designs have one data lane it is possible for a multi-lane device to have up
-to 8 data lanes and thus would have more than two pins.
-
-A SoundWire bus consists of one master device, up to 11 slave devices, and an optional
-monitor interface for debug.
-
-SoundWire is an enumerable bus, but not a discoverable one.  That means it is required
-for firmware to provide details about the connected devices to the OS.
-
-### Controller
-
-A SoundWire controller contains one or more master devices.  The handling of multiple
-masters is left up to the implementation, they may share a clock or be operated
-independently or entirely in tandem.  The master devices connected to a controller are
-also referred to as links.
-
-In coreboot the controller device is provided by the SoC or an add-in PCI card.
-
-### Master
-
-A SoundWire master (or link) device is responsible for clock and data handling, bus
-management, and bit slot allocation.
-
-In coreboot the definition of the master device is left up to the controller and the
-mainboard should only need to know the controller's SoundWire topology (number of masters)
-to configure `devicetree.cb`.
-
-It may however be expected to provide some additional SoC-specific configuration data to
-the controller, such as an input clock rate or a list of available masters that cannot
-be determined at run time.
-
-### Slave
-
-SoundWire slave devices are connected to a master and respond to the two-wire control
-information on the SoundWire bus.  There can be up to 11 slave devices on a bus and they
-are capable of interrupting and waking the host.
-
-Slave devices may also have master links which can be connected to other slave devices.
-It is also possible for a multi-lane slave device to have multiple data lanes connected
-to different combinations of master and slave devices.
-
-In coreboot the slave device is defined by a codec driver which should be found in the
-source tree at `src/drivers/soundwire`.
-
-The mainboard provides:
-
-* Master link that this slave device is connected to.
-* Unique ID that this codec responds to on the SoundWire bus.
-* Multi-lane mapping. (optional)
-
-The codec driver provides:
-
-* Slave device properties.
-* Audio Mode properties including bus frequencies and sampling rates.
-* Data Port 1-14 properties such as word lengths, interrupt support, channels.
-* Data Port 0 and Bulk Register Access properties. (optional)
-
-### Monitor
-
-A SoundWire monitor device is defined that allows for test equipment to snoop the bus and
-take over and issue commands.  The monitor interface is not defined for coreboot.
-
-### Example SoundWire Bus
-
-```
-+---------------+                                       +---------------+
-|               |                       Clock Signal    |               |
-|    Master     |-------+-------------------------------|    Slave      |
-|   Interface   |       |               Data Signal     |  Interface 1  |
-|               |-------|-------+-----------------------|               |
-+---------------+       |       |                       +---------------+
-                        |       |
-                        |       |
-                        |       |
-                     +--+-------+--+
-                     |             |
-                     |   Slave     |
-                     | Interface 2 |
-                     |             |
-                     +-------------+
-```
-
-## coreboot
-
-The coreboot implementation of SoundWire integrates with the device model and takes
-advantage of the hierarchical nature of `devicetree.cb` to populate the topology.
-
-The architecture-independent SoundWire tables are defined at
-
-    src/include/device/soundwire.h
-
-Support for new devices comes in three forms:
-
-1. New controller and master drivers.  The first implementation in coreboot is for an Intel
-SoC but the SoundWire specification is in wide use on various ARM SoCs.
-
-    Controller drivers can be implemented in `src/soc` or `src/drivers` and should
-    strive to re-use code as much as possible between different SoC generations from the
-    same vendor.
-
-2. New codec drivers.  These should be implemented for each codec that is added which
-supports SoundWire.  The properties vary between codecs and careful study of the data sheet
-is necessary to ensure proper operation.
-
-    Codec drivers should be implemented in `src/drivers/soundwire` as separate chip drivers.
-    As every codec is different there may not be opportunities of code re-use except between
-    similar codecs from the same vendor.
-
-3. New mainboards with SoundWire support.  The mainboard will combine controllers and codecs
-to form a topology that is described in `devicetree.cb`.  Some devices may need to provide
-board-specific configuration information, and multi-lane devices will need to provide the
-master/slave lane map.
-
-## ACPI Implementation
-
-The implementation for x86 devices relies on ACPI for providing device properties to the OS
-kernel drivers.
-
-The ACPI implementation can be found at
-
-    src/acpi/soundwire.c
-
-And used by including
-
-    #include <acpi/acpi_soundwire.h>
-
-### Controller
-
-The controller driver should populate a `struct soundwire_controller`:
-
-```c
-/**
- * struct soundwire_controller - SoundWire controller properties.
- * @master_count: Number of masters present on this device.
- * @master_list: One entry for each master device.
- */
-struct soundwire_controller {
-	unsigned int master_list_count;
-	struct soundwire_link master_list[SOUNDWIRE_MAX_DEV];
-};
-```
-
-Once the detail of the master links are specified in the `master_list` variable, the controller
-properties for the ACPI object can be generated:
-
-```c
-struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
-soundwire_gen_controller(dsd, &soc_controller, NULL);
-acpi_dp_write(dsd);
-```
-
-If the controller needs to generate custom properties for links it can provide a callback
-function to `soundwire_gen_controller()` instead of passing NULL:
-
-```c
-static void controller_link_prop_cb(struct acpi_dp *dsd, unsigned int id,
-                                    struct soundwire_controller *controller)
-{
-	acpi_dp_add_integer(dsd, "custom-link-property", 1);
-}
-```
-
-### Codec
-
-The codec driver should populate a *struct soundwire_codec* with necessary properties:
-
-```c
-/**
- * struct soundwire_codec - Contains all configuration for a SoundWire codec slave device.
- * @slave: Properties for slave device.
- * @audio_mode: Properties for Audio Mode for Data Ports 1-14.
- * @dpn: Properties for Data Ports 1-14.
- * @multilane: Properties for slave multilane device. (optional)
- * @dp0_bra_mode: Properties for Bulk Register Access mode for Data Port 0. (optional)
- * @dp0: Properties for Data Port 0 for Bulk Register Access. (optional)
- */
-struct soundwire_codec {
-	struct soundwire_slave *slave;
-	struct soundwire_audio_mode *audio_mode[SOUNDWIRE_MAX_DEV];
-	struct soundwire_dpn_entry dpn[SOUNDWIRE_MAX_DPN - SOUNDWIRE_MIN_DPN];
-	struct soundwire_multilane *multilane;
-	struct soundwire_bra_mode *dp0_bra_mode[SOUNDWIRE_MAX_DEV];
-	struct soundwire_dp0 *dp0;
-};
-```
-
-Many of these properties are optional, and depending on the codec will not be supported.
-
-#### Slave Device Properties
-
-These properties provide information about the codec device and what features it supports:
-
-* Wake capability
-* Clock stop behavior
-* Clock and channel state machine behavior
-* Features like register pages, broadcast read, bank delay, and high performance PHY
-
-#### Multi-lane Slave Device Properties
-
-Most slave devices have a single data pin and a single lane, but it is possible for up to
-7 other lanes to be supported on a device.  These lanes can be connected to other master
-links or to other slave devices.
-
-If a codec supports this feature it must indicate that by providing an entry for
-`struct soundwire_multilane` in the chip configuration.
-
-```c
-/**
- * struct drivers_soundwire_example_config - Example codec configuration.
- * @multilane: Multi-lane slave configuration.
- */
-struct drivers_soundwire_example_config {
-	struct soundwire_multilane multilane;
-};
-```
-
-The mainboard is required to provide the lane map in `devicetree.cb` for any codec that has
-multiple lanes connected.  This includes the definition up to 7 entries that indicate which
-lane number on the slave devices (array index starting at 1) maps to which other device:
-
-```
-chip drivers/soundwire/multilane_codec
-	register "multilane.lane_mapping" = "{
-		{
-			# Slave Lane 1 maps to Master Lane 2
-			.lane = 1,
-			.direction = MASTER_LANE,
-			.connection.master_lane = 2
-		},
-		{
-			# Slave Lane 3 maps to Slave Link B
-			.lane = 3,
-			.direction = SLAVE_LINK,
-			.connection.slave_link = 1
-		}
-	}"
-	device generic 0.0 on end
-end
-```
-
-#### Data Port 0 Properties
-
-SoundWire Data Port 0 (DP0) is a special port used for control and status operation relating
-to the whole device interface, and as a special data port for bulk read/write operations.
-
-The properties for data port 0 are different from that of data ports 1-14 and are about the
-control channel behavior and the overall bulk register mode.
-
-Data port 0 is not required to be supported by the slave device.
-
-#### Bulk Register Access Mode Properties
-
-Bulk Register Access (BRA) is an optional mechanism for transporting higher bandwidth of
-register operations than the typical command mechanism.  The BRA protocol is a particular
-format of the data on the (optional) data port 0 connection between the master and slave.
-
-The BRA protocol may have alignment or timing requirements that are directly related to the
-bus frequencies.  As a result there may be several configurations listed, for symmetry with
-the audio modes paired with data ports 1-14.
-
-#### Data Port 1-14 Properties
-
-Data ports 1-14 are typically dedicated to streaming audio payloads, and each data port can
-have from 1 to 8 channels.  There are different levels of data ports, with some registers
-being required and supported on all data ports and some optional registers only being used
-on some data ports.
-
-Data ports can have both a sink and a source component, and the codec may support one or
-both of these on each port.
-
-Similar to data port 0 the properties defined here describe the capabilities and supported
-features of each data port, and they may be configured separately.  For example the Maxim
-MAX98373 codec supports a 32bit source data port for speaker output, and a 16bit sink data
-port for speaker sense data.
-
-#### Audio Mode Properties
-
-Each data port may be tied to one or more audio modes.  The audio mode describes the actual
-audio capabilities of the codec, including supported frequencies and sample rates.  These
-modes can be shared by multiple data ports and do not need to be duplicated.
-
-For example:
-
-```
-static struct soundwire_audio_mode audio_mode = {
-	.bus_frequency_max = 24 * MHz,
-	.bus_frequency_min = 24 * KHz,
-	.max_sampling_frequency = 192 * KHz,
-	.min_sampling_frequency = 8 * KHz,
-};
-static struct soundwire_dpn codec_dp1 = {
-    [...]
-	.port_audio_mode_count = 1,
-	.port_audio_mode_list = {0}
-};
-static struct soundwire_dpn codec_dp3 = {
-    [...]
-	.port_audio_mode_count = 1,
-	.port_audio_mode_list = {0}
-};
-```
-
-### Generating Codec Properties
-
-Once the properties are known it can generate the ACPI code with:
-
-```c
-struct acpi_dp *dsd = acpi_dp_new_table("_DSD");
-soundwire_gen_codec(dsd, &soundwire_codec, NULL);
-acpi_dp_write(dsd);
-```
-
-If the codec needs to generate custom properties for links it can provide a callback
-function to `soundwire_gen_codec()` instead of passing NULL:
-
-```c
-static void codec_dp_prop_cb(struct acpi_dp *dsd, unsigned int id,
-                             struct soundwire_codec *codec)
-{
-	acpi_dp_add_integer(dsd, "custom-dp-property", 1);
-}
-```
-
-#### Codec Address
-
-SoundWire slave devices use a SoundWire defined ACPI _ADR that requires a 64-bit integer
-and uses the master link ID and slave device unique ID to form a unique address for the
-device on this controller.
-
-SoundWire addresses must be distinguishable from all other slave devices on the same master
-link, so multiple instances of the same manufacturer and part on the same master link will
-need different unique IDs.  The value is typically determined by strapping pins on the codec
-chip and can be decoded for this table with the codec datasheet and board schematics.
-
-```c
-/**
- * struct soundwire_address - SoundWire ACPI Device Address Encoding.
- * @version: SoundWire specification version from &enum soundwire_version.
- * @link_id: Zero-based SoundWire Link Number.
- * @unique_id: Unique ID for multiple devices.
- * @manufacturer_id: Manufacturer ID from include/mipi/ids.h.
- * @part_id: Vendor defined part ID.
- * @class: MIPI class encoding in &enum mipi_class.
- */
-struct soundwire_address {
-	enum soundwire_version version;
-	uint8_t link_id;
-	uint8_t unique_id;
-	uint16_t manufacturer_id;
-	uint16_t part_id;
-	enum mipi_class class;
-};
-```
-
-This ACPI address can be generated by calling the provided acpigen function:
-
-    acpigen_write_ADR_soundwire_device(const struct soundwire_address *sdw);
-
-### Mainboard
-
-The mainboard needs to select appropriate drivers in `Kconfig` and define the topology in
-`devicetree.cb` with the controllers and codecs that exist on the board.
-
-The topology uses the **generic** device to describe SoundWire:
-
-```c
-struct generic_path {
-	unsigned int id;       /* SoundWire Master Link ID */
-	unsigned int subid;    /* SoundWire Slave Unique ID */
-};
-```
-
-This allows devices to be specified in `devicetree.cb` with the necessary information to
-generate ACPI address and device properties.
-
-```
-chip drivers/intel/soundwire
-	# SoundWire Controller 0
-	device generic 0 on
-		chip drivers/soundwire/codec1
-			# SoundWire Link 0 ID 0
-			device generic 0.0 on end
-		end
-		chip drivers/soundwire/codec2
-			# SoundWire Link 1 ID 2
-			device generic 1.2 on end
-		end
-	end
-end
-```
-
-## Volteer Example
-
-This is an example of an Intel Tiger Lake reference board using SoundWire Link 0 for the
-headphone codec connection, and Link 1 for connecting two speaker amps for stereo speakers.
-
-The mainboard can be found at
-
-    src/mainboard/google/volteer
-
-```
-  +------------------+         +-------------------+
-  |                  |         | Headphone Codec   |
-  | Intel Tiger Lake |    +--->| Realtek ALC5682   |
-  |    SoundWire     |    |    |       ID 1        |
-  |    Controller    |    |    +-------------------+
-  |                  |    |
-  |           Link 0 +----+    +-------------------+
-  |                  |         | Left Speaker Amp  |
-  |           Link 1 +----+--->| Maxim MAX98373    |
-  |                  |    |    |       ID 3        |
-  |           Link 2 |    |    +-------------------+
-  |                  |    |
-  |           Link 3 |    |    +-------------------+
-  |                  |    |    | Right Speaker Amp |
-  +------------------+    +--->| Maxim MAX98373    |
-                               |       ID 7        |
-                               +-------------------+
-```
-
-This implementation requires a controller driver for the Intel Tigerlake SoC and a codec
-driver for the Realtek and Maxim chips.  If those drivers did not already exist they would
-need to be added and reviewed separately before adding the support to the mainboard.
-
-The volteer example requires some `Kconfig` options to be selected:
-
-```
-config BOARD_GOOGLE_BASEBOARD_VOLTEER
-	select DRIVERS_INTEL_SOUNDWIRE
-	select DRIVERS_SOUNDWIRE_ALC5682
-	select DRIVERS_SOUNDWIRE_MAX98373
-```
-
-And the following `devicetree.cb` entries to define this topology:
-
-```
-device pci 1f.3 on
-	chip drivers/intel/soundwire
-		# SoundWire Controller 0
-		device generic 0 on
-			chip drivers/soundwire/alc5682
-				# SoundWire Link 0 ID 1
-				register "desc" = ""Headphone Jack""
-				device generic 0.1 on end
-			end
-			chip drivers/soundwire/max98373
-				# SoundWire Link 0 ID 1
-				register "desc" = ""Left Speaker Amp""
-				device generic 1.3 on end
-			end
-			chip drivers/soundwire/max98373
-				# SoundWire Link 1 ID 7
-				register "desc" = ""Right Speaker Amp""
-				device generic 1.7 on end
-			end
-		end
-	end
-end
-```

Documentation/flash_tutorial/index.md

@@ -7,7 +7,7 @@ flash IC.
 
 ## Contents
 
-* [Flashing internally](int_flashrom.md)
+* [Flashing internaly](int_flashrom.md)
 * [Flashing firmware standalone](ext_standalone.md)
 * [Flashing firmware externally supplying direct power](ext_power.md)
 * [Flashing firmware externally without supplying direct power](no_ext_power.md)

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/gcov.txt

@@ -19,7 +19,7 @@ time). The file gcov-io.c is unchanged.
 +#define BITS_PER_UNIT 8
 +#define LONG_LONG_TYPE_SIZE 64
 +
-+/* There are many gcc_assertions. Set the value to 1 if we want a warning
++/* There are many gcc_assertions. Set the vaule to 1 if we want a warning
 +   message if the assertion fails.  */
 +#ifndef ENABLE_ASSERT_CHECKING
 +#define ENABLE_ASSERT_CHECKING 1

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 at 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 useful 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 existence 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

@@ -43,42 +43,15 @@ employer is aware and you are authorized to submit the code. For
 clarification, see the Developer's Certificate of Origin in the coreboot
 [Signed-off-by policy](https://www.coreboot.org/Development_Guidelines#Sign-off_Procedure).
 
-* In general, patches should remain open for review for at least 24 hours
+* Let non-trivial patches sit in a review state for at least 24 hours
-since the last significant modification to the change. The purpose is to
+before submission. Remember that there are coreboot developers in timezones
-let coreboot developers around the world have a chance to review. Complex
+all over the world, and everyone should have a chance to contribute.
-reworks, even if they don't change the purpose of the patch but the way
+Trivial patches would be things like whitespace changes or spelling fixes.
-it's implemented, should restart the wait period.
+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
-* A change can go in without the wait period if its purpose is to fix
+update which significantly changes any part of the patch. Patches can be
-a recently-introduced issue (build, boot or OS-level compatibility, not
+'Fast-tracked' and submitted in under this 24 hour with the agreement of at
-necessarily identified by coreboot.org facilities). Its commit message
+least 3 +2 votes.
-has to explain what change introduced the problem and the nature of
-the problem so that the emergency need becomes apparent. The change
-itself should be as limited in scope and impact as possible to make it
-simple to assess the impact. Such a change can be merged early with 3
-Code-Review+2. For emergency fixes that affect a single project (SoC,
-mainboard, ...) it's _strongly_ recommended to get a review by somebody
-not involved with that project to ensure that the documentation of the
-issue is clear enough.
-
-* Trivial changes that deal with minor issues like inconsistencies in
-whitespace or spelling fixes that don't impact the final binary output
-also don't need to wait. Such changes should point out in their commit
-messages how the the author verified that the binary output is identical
-(e.g. a TIMELESS build for a given configuration). When submitting
-such changes early, the submitter must be different from the author
-and must document the intent in the Gerrit discussion, e.g. "landed the
-change early because it's trivial". Note that trivial fixes shouldn't
-necessarily be expedited: Just like they're not critical enough for
-things to go wrong because of them, they're not critical enough to
-require quick handling. This exception merely serves to acknowledge that
-a round-the-world review just isn't necessary for some types of changes.
-
-* As explained in our Code of Conduct, we try to assume the best of each
-other in this community. It's okay to discuss mistakes (e.g. isolated
-instances of non-trivial and non-critical changes submitted early) but
-try to keep such inquiries blameless. If a change leads to problems with
-our code, the focus should be on fixing the issue, not on assigning blame.
 
 * Do not +2 patches that you authored or own, even for something as trivial
 as whitespace fixes. When working on your own patches, it’s easy to
@@ -281,23 +254,6 @@ commit message itself:
 The script 'util/gitconfig/rebase.sh' can be used to help automate this.
 Other tags such as 'Commit-Queue' can simply be removed.
 
-* Check if there's documentation that needs to be updated to remain current
-after your change. If there's no documentation for the part of coreboot
-you're working on, consider adding some.
-
-* When contributing a significant change to core parts of the code base (such
-as the boot state machine or the resource allocator), or when introducing
-a new way of doing something that you think is worthwhile to apply across
-the tree (e.g. board variants), please bring up your design on the [mailing
-list](../community/forums.md). When changing behavior substantially, an
-explanation of what changes and why may be useful to have, either in the
-commit message or, if the discussion of the subject matter needs way more
-space, in the documentation. Since "what we did in the past and why it isn't
-appropriate anymore" isn't the most useful reading several years down the road,
-such a description could be put into the release notes for the next version
-(that you can find in Documentation/releases/) where it will inform people
-now without cluttering up the regular documentation, and also gives a nice
-shout-out to your contribution by the next release.
 
 Expectations contributors should have
 -------------------------------------
@@ -320,47 +276,6 @@ is criticising your code, but the whole idea is to get better code into our
 codebase. Again, this also applies in the other direction: review code,
 criticize code, but don’t make it personal.
 
-Gerrit user roles
------------------
-There are a few relevant roles a user can have on Gerrit:
-
-- The anonymous user can check out source code.
-- A registered user can also comment and give "+1" and "-1" code reviews.
-- A reviewer can also give "+2" code reviews.
-- A core developer can also give "-2" (that is, blocking) code reviews
-  and submit changes.
-
-Anybody can register an account on our instance, using either an
-OpenID provider or OAuth through GitHub or Google.
-
-The reviewer group is still quite open: Any core developer can add
-registered users to that group and should do so once some activity
-(commits, code reviews, and so on) has demonstrated rough knowledge
-of how we handle things.
-
-A core developer should be sufficiently well established in the
-community so that they feel comfortable when submitting good patches,
-when asking for improvements to less good patches and reasonably
-uncomfortable when -2'ing patches. They're typically the go-to
-person for _some_ part of the coreboot tree and ideally listed as its
-maintainer in our MAINTAINERS registry. To become part of this group,
-a candidate developer who already demonstrated proficiency with the
-code base as a reviewer should be nominated, by themselves or others,
-at the regular [coreboot leadership meetings](../community/forums.md)
-where a decision is made.
-
-Core developers are expected to use their privileges for the good of the
-project, which includes any of their own coreboot development but also beyond
-that. They should make sure that [ready changes] don't linger around needlessly
-just because their authors aren't well-connected with core developers but
-submit them if they went through review and generally look reasonable. They're
-also expected to help clean-up breakage as a result of their submissions.
-
-Since the project expects some activity by core developers, long-term absence
-(as in "years") can lead to removal from the group, which can easily be
-reversed after they come back.
 
 Requests for clarification and suggestions for updates to these guidelines
 should be sent to the coreboot mailing list at <coreboot@coreboot.org>.
-
-[ready changes]: https://review.coreboot.org/q/age:1d+project:coreboot+status:open+is:mergeable+label:All-Comments-Resolved%253Dok+label:Code-Review%253D2+-label:Code-Review%253C0+label:Verified%253D1+-label:Verified-1

Documentation/getting_started/gpio.md

@@ -1,182 +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)
-    /* 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`.
-
-## Unconnected and unused pads
-
-In digital electronics, it is generally recommended to tie unconnected GPIOs to
-a defined signal like VCC or GND by setting their direction to output, adding an
-external pull resistor or configuring an internal pull resistor. This is done to
-prevent floating of the pin state, which can cause various issues like EMI,
-higher power usage due to continuously switching logic, etc.
-
-On Intel PCHs from Sunrise Point onwards, termination of unconnected GPIOs is
-explicitly not required, when the input buffer is disabled by setting the bit
-`GPIORXDIS` which effectively disconnects the pad from the internal logic. All
-pads defaulting to GPIO mode have this bit set. However, in the mainboard's
-GPIO configuration the macro `PAD_NC(pad, NONE)` can be used to explicitly
-configure a pad as unconnected.
-
-In case there are no schematics available for a board and the vendor set a
-pad to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull
-resistor, an unconnected or otherwise unused pad can be assumed. In this case it
-is recommended to keep the pull resistor, because the external circuit might
-rely on it.
-
-Unconnected pads defaulting to a native function (input and output) usually
-don't need to be configured as GPIO with the `GPIORXDIS` bit set. For clarity
-and documentation purpose the macro may be used as well for them.
-
-Some pads configured as native input function explicitly require external
-pull-ups when being unused, according to the PDGs:
-- eDP_HPD
-- SMBCLK/SMBDATA
-- SML0CLK/SML0DATA/SML0ALERT
-- SATAGP*
-
-When the board was designed correctly, nothing needs to be done for them
-explicitly, while using `PAD_NC(pad, NONE)` can act as documentation. If such a
-pad is missing the external pull resistor due to bad board design, the pad
-should be configured with `PAD_NC(pad, NONE)` anyway to disconnect it
-internally.
-
-## 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!
-
-## Soft Straps
-
-Soft straps, that can be configured by the vendor in the Intel Flash Image Tool
-(FIT), can influence some pads' default mode. It is possible to select either a
-native function or GPIO mode for some pads on non-server SoCs, while on server
-SoCs most pads can be controlled. Thus, it is generally recommended to always
-configure all pads and don't just rely on the defaults mentioned in the
-datasheet(s) which might not reflect what the vendor configured.
-
-## Pad-related known issues and workarounds
-
-### LPC_CLKRUNB blocks S0ix states when board uses eSPI
-
-When using eSPI, the pad implementing `LPC_CLKRUNB` must be set to GPIO mode.
-Other pin settings i.e. Rx path enable/disable, Tx path enable/disable, pull up
-enable/disable etc are ignored. Leaving this pin in native mode will keep the
-LPC Controller awake and prevent S0ix entry. This issues is know at least on
-Apollolake and Geminilake.

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

@@ -52,9 +52,13 @@ command line.
   not have an answer yet, it stops and queries the user for the desired value.
 - olddefconfig - Generates a config, using the default value for any symbols not
   listed in the .config file.
-- savedefconfig - Creates a ‘defconfig’ file, stripping out all of the symbols
+- savedefconfig - Creates a ‘mini-config’ file, stripping out all of the symbols
   that were left as default values.  This is very useful for debugging, and is
   how config files should be saved.
+- silentoldconfig - This evaluates the .config file the same way that the
+  oldconfig target does, but does not print out each question as it is
+  evaluated.  It still stops to query the user if an option with no answer in
+  the .config file is found.
 
 
 ### Targets not typically used in coreboot
@@ -69,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.
 
@@ -394,8 +401,6 @@ default <expr> \[if <expr>\]
 - If there is no 'default' entry for a symbol, it gets set to 'n', 0, 0x0, or
   “” depending on the type, however the 'bool' type is the only type that
   should be left without a default value.
-- If possible, the declaration should happen before all default entries to make
-  it visible in Kconfig tools like menuconfig.
 
 --------------------------------------------------------------------------------
 
@@ -603,7 +608,7 @@ int <expr> \[if <expr>\]
 
 
 ##### Example:
-    config PRE_GRAPHICS_DELAY_MS
+    config PRE_GRAPHICS_DELAY
         int "Graphics initialization delay in ms"
         default 0
         help
@@ -1127,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).
 
 
@@ -1160,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
@@ -1188,7 +1195,7 @@ https://github.com/martinlroth/language-kconfig
 ## Syntax Checking:
 
 The Kconfig utility does some basic syntax checking on the Kconfig tree.
-Running "make oldconfig" will show any errors that the Kconfig utility
+Running "make silentoldconfig" will show any errors that the Kconfig utility
 sees.
 
 ### util/kconfig_lint

Documentation/getting_started/writing_documentation.md

@@ -6,7 +6,7 @@
 That said please always try to write documentation! One problem in the
 firmware development is the missing documentation. In this document
 you will get a brief introduction how to write, submit and publish
-documentation to coreboot.
+documenation to coreboot.
 
 ## Preparations
 
@@ -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
+### Install Sphinx
-
-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
 
 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 recommended version is sphinx 1.7.7, sphinx_rtd_theme 0.4.1 and
-the installation via pip in a venv is recommended. You'll need these python3
+recommonmark 0.4.0.
-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.
 
 ### 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
+any way, it currently only supports Intel's integrated gfx control-
-controllers (GMA).
+lers (GMA).
 
-Currently, it supports the Intel Core i3/i5/i7 processor line, HDMI
+Currently, it supports the Intel Core i3/i5/i7 processor line and
-and DP on the Apollo Lake processors and everything but SDVO on G45
+will support HDMI and DP on the Atom successor Apollo Lake. At the
-and GM45 chipsets. At the time of writing, G45, GM45, everything
+time of writing, Sandy Bridge, Ivy Bridge, and Haswell are veri-
-from Arrandale to Coffee Lake, and Apollo Lake are verified to work
+fied to work within *coreboot*.
-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
+                could be found counts as failure. A failure at a la-
-                later stage (e.g. failure to train a DP) is not
+                ter stage (e.g. failure to train a DP) is not propa-
-                propagated.
+                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
+power sequencer). Therefore, each board has to select either eDP
-should set `GFX_GMA_PANEL_1_PORT` to the respective port, e.g.:
+or LVDS as the internal port, if any:
 
-    config GFX_GMA_PANEL_1_PORT
+    select GFX_GMA_INTERNAL_IS_EDP	# the default, or
-            default "DP3"
+    select GFX_GMA_INTERNAL_IS_LVDS
-
-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.
 
 Boards with a DVI-I connector share the DDC (I2C) pins for both
 analog and digital displays. In this case, *libgfxinit* needs to
@@ -88,28 +75,11 @@ know through which interface the EDID can be queried:
     select GFX_GMA_ANALOG_I2C_HDMI_C	# or
     select GFX_GMA_ANALOG_I2C_HDMI_D
 
-*libgfxinit* needs to know which ports are implemented on a board
+Beside Kconfig options, *libgfxinit* needs to know which ports are
-and should be probed for displays. There are two mechanisms to
+implemented on a board and should be probed for displays. The mapping
-constrain the list of ports to probe, 1. port presence straps on
+between the physical ports and these entries depends on the hardware
-the mainboard, and 2. a list of ports provided by *coreboot* (see
+implementation and can be recovered by testing or studying the output
-below).
+of `intelvbttool` or `intel_vbt_decode`.
-
-Presence straps are configured via the state of certains pins of
-the chipset at reset time. They are documented in the chipset's
-datasheets. By default, *libgfxinit* honors these straps for
-safety. However, some boards don't implement the straps correctly.
-If ports are not strapped as implemented by error, one can select
-an option to ignore the straps:
-
-    select GFX_GMA_IGNORE_PRESENCE_STRAPS
-
-In the opposite case, that ports are strapped as implemented,
-but are actually unconnected, one has to make sure that the
-list of ports in *coreboot* omits them.
-
-The mapping between the physical ports and these entries depends on
-the hardware implementation and can be recovered by testing or
-studying the output of `intelvbttool` or `intel_vbt_decode`.
 Each board has to implement the package `GMA.Mainboard` with a list:
 
     ports : HW.GFX.GMA.Display_Probing.Port_List;
@@ -122,8 +92,7 @@ You can select from the following Ports:
 
     type Port_Type is
       (Disabled,	-- optionally terminates the list
-       LVDS,
+       Internal,	-- either eDP or LVDS as selected in Kconfig
-       eDP,
        DP1,
        DP2,
        DP3,
@@ -139,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,
@@ -148,8 +118,7 @@ eDP and LVDS. It defines `ports` as follows:
        HDMI2,
        HDMI3,
        Analog,
-       LVDS,
+       Internal,
-       eDP,
        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 4 KiB 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 MiB in the IFD but the FMAP only allocates 4 MiB for
-the ME, then when the ME is added by the ifdtool 6 MiB will be written which
-could overwrite 2 MiB 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

@@ -45,12 +45,6 @@ to the payload), but it's also a value that is deeply ingrained in the
 project. We fearlessly rip out parts of the architecture and remodel it
 when a better way of doing the same was identified.
 
-That said, since there are attempts to coerce coreboot to move in various
-directions by outside "standardization", long-established practices of
-coreboot as well as aligned projects can be documented as best practices,
-making them standards in their own right. However we reserve the right to
-retire them as the landscape shifts around us.
-
 ### One tree for everything
 
 Another difference to various other firmware projects is that we try
@@ -167,33 +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](contributing/coding_style.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)
-* [Language style](community/language_style.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)
+* [Timestamps](timestamp.md)
-* [ACPI](acpi/index.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)
+* [Architecture-specific documentation](arch/index.md)
-* [CPU Architecture](arch/index.md)
+* [Northbridge-specific documentation](northbridge/index.md)
-* [Platform independent drivers](drivers/index.md)
+* [System on Chip-specific documentation](soc/index.md)
-* [Northbridge](northbridge/index.md)
+* [Mainboard-specific documentation](mainboard/index.md)
-* [System on Chip](soc/index.md)
+* [Payload-specific documentation](lib/payloads/index.md)
-* [Mainboard](mainboard/index.md)
+* [SuperIO-specific documentation](superio/index.md)
-* [Payloads](lib/payloads/index.md)
+* [Vendorcode-specific documentation](vendorcode/index.md)
-* [Libraries](lib/index.md)
-* [Options](lib/option.md)
-* [Security](security/index.md)
-* [SuperIO](superio/index.md)
-* [Vendorcode](vendorcode/index.md)
 * [Utilities](util.md)
-* [coreboot infrastructure](infrastructure/index.md)
 * [Release notes for past releases](releases/index.md)
 * [Flashing firmware tutorial](flash_tutorial/index.md)

Documentation/infrastructure/builders.md

@@ -1,392 +0,0 @@
-# Jenkins builder setup and configuration
-
-## How to set up a new jenkins builder
-
-### Contact a jenkins admin
-
-Let a jenkins admin know that you’re interested in setting up a jenkins
-build system.
-
-For a permanent build system, this should generally be a dedicated
-machine that is not generally being used for other purposes.  The
-coreboot builds are very intensive.
-
-It's also best to be aware that although we don't know of any security
-issues, the jenkins-node image is run with the privileged flag which
-gives the container root access to the build machine.  See
-[this article](https://blog.trendmicro.com/trendlabs-security-intelligence/why-running-a-privileged-container-in-docker-is-a-bad-idea/)
-about why this is discouraged.
-
-It's recommended that you give an admin root access on your machine so
-that they can reset it in case of a failure.  This is not a requirement,
-as the system can just be disabled until someone is available to fix any
-issues.
-
-Currently active Jenkins admins:
-*   Patrick Georgi:
-    *   Email: [patrick@georgi-clan.de](mailto:patrick@georgi-clan.de)
-    *   IRC: pgeorgi
-
-
-### Build Machine requirements
-
-For a builder, we need a fast system with lots of threads and plenty of
-RAM.  The builder builds and stores the git repos and output in tmpfs
-along with the ccache save area, so if there isn't enough memory, the
-builds will slow down because of smaller ccache areas and can run into
-"out of storage space" errors.
-
-#### Current Build Machines
-
-To give an idea of what a suitable build machine might be, currently the
-coreboot project has 3 active jenkins build machines.
-
-* Congenialbuilder - 128 threads, 256GiB RAM
-  *  Fastest Passing coreboot gerrit build: 4 min, 30 sec
-  *  Slowest Passing coreboot gerrit build: 9 min, 56 sec
-
-
-* Gleeful builder - 64 thread, 64GiB RAM
-  *  Fastest Passing coreboot gerrit build: 6 min, 6 sec
-  *  Slowest Passing coreboot gerrit build, 34 min
-
-
-* Ultron (9elements) - 48 threads, 128GiB RAM
-  *  Fastest Passing coreboot gerrit build: 6 min, 32 sec
-  *  Slowest Passing coreboot gerrit build: 44 min
-
-
-### Jenkins Builds
-
-There are a number of builds handled by the coreboot jenkins builders,
-for a number of different projects - coreboot, flashrom, memtest86+,
-em100, etc.  Many of these have builders for their current master branch
-as well as gerrit and coverity builds.
-
-You can see all the builds here:
-[https://qa.coreboot.org/](https://qa.coreboot.org/)
-
-Most of the time on the builders is taken up by the coreboot master and
-gerrit builds.
-
-* [coreboot gerrit build](https://qa.coreboot.org/job/coreboot-gerrit/)
-([Time trend](https://qa.coreboot.org/job/coreboot-gerrit/buildTimeTrend))
-
-
-* [coreboot master build](https://qa.coreboot.org/job/coreboot/)
- ([Time trend](https://qa.coreboot.org/job/coreboot/buildTimeTrend))
-
-
-### Stress test the machine
-
-Test the machine to make sure that building won't stress the hardware
-too much.  Install stress-ng, then run the stress test for at least an
-hour.
-
-On a system with 32 cores, it was tested with this command:
-
-```
-$ stress-ng --cpu 20 --io 6 --vm 6 --vm-bytes 1G --verify --metrics-brief -t 60m
-```
-
-You can watch the temperature with the sensors package or with ‘acpi -t’
-if your machine supports that.
-
-You can check for thermal throttling by running this command and seeing
-if the values go down on any of the cores after it's been running for a
-while.
-
-```
-$ while [ true ]; do clear; cat /proc/cpuinfo | grep 'cpu MHz' ; sleep 1; done
-```
-
-If the machine throttles or resets, you probably need to upgrade the
-cooling system.
-
-
-## jenkins-server docker installation
-
-
-### Manual Installation
-
-If you’ve met all the above requirements, and an admin has agreed to set
-up the builder in jenkins, you’re ready to go on to the next steps.
-
-
-### Set up your network so jenkins can talk to the container
-
-Expose a local port through any firewalls you might have on your router.
-This would generally be in the port forwarding section, and you'd just
-forward a port (typically 49151) from the internet directly to the
-builder’s IP address.
-
-You might also want to set up a port to forward to port 22 on your
-machine and set up openssh so you or the jenkins admins can manage
-the machine remotely (if you allow them).
-
-
-### Install and set up docker
-
-Install docker by following the
-[directions](https://docs.docker.com/engine/install/) on the docker
-site.  These instructions keep changing, so just check the latest
-information.
-
-
-#### Set up environment variables
-
-To make configuration and the later commands easier, these should go in
-your shell's .rc file.  Note that you only need to set them if you're
-using something other than the default.
-
-```
-# Set the port used on your machine to connect to jenkins.
-export COREBOOT_JENKINS_PORT=49151
-
-# Set the revision of the container from docker hub
-export DOCKER_COMMIT=65718760fa
-
-# Set the location of where the jenkins cache directory will be.
-export COREBOOT_JENKINS_CACHE_DIR="/srv/docker/coreboot-builder/cache"
-
-# Set the name of the container
-export COREBOOT_JENKINS_CONTAINER="coreboot_jenkins"
-```
-
-Make sure any variables needed are set in your environment before
-continuing to the next step.
-
-
-### Using the Makefile for docker installation
-
-From the coreboot directory, run
-
-```
-make -C util/docker help
-```
-
-This will show you the available targets and variables needed:
-
-```
-Commands for working with docker images:
-  coreboot-sdk                 - Build coreboot-sdk container
-  upload-coreboot-sdk          - Upload coreboot-sdk to hub.docker.com
-  coreboot-jenkins-node        - Build coreboot-jenkins-node container
-  upload-coreboot-jenkins-node - Upload coreboot-jenkins-node to hub.docker.com
-  doc.coreboot.org             - Build doc.coreboot.org container
-  clean-coreboot-containers    - Remove all docker coreboot containers
-  clean-coreboot-images        - Remove all docker coreboot images
-  docker-clean                 - Remove docker coreboot containers & images
-
-Commands for using docker images
-  docker-build-coreboot        - Build coreboot under coreboot-sdk
-      <BUILD_CMD=target>
-  docker-abuild                - Run abuild under coreboot-sdk
-      <ABUILD_ARGS='-a -B'>
-  docker-what-jenkins-does     - Run 'what-jenkins-does' target
-  docker-shell                 - Bash prompt in coreboot-jenkins-node
-      <USER=root or USER=coreboot>
-  docker-jenkins-server        - Run coreboot-jenkins-node image (for server)
-  docker-jenkins-attach        - Open shell in running jenkins server
-  docker-build-docs            - Build the documentation
-  docker-livehtml-docs         - Run sphinx-autobuild
-
-Variables:
-  COREBOOT_JENKINS_PORT=49151
-  COREBOOT_JENKINS_CACHE_DIR=/srv/docker/coreboot-builder/cache
-  COREBOOT_JENKINS_CONTAINER=coreboot_jenkins
-  COREBOOT_IMAGE_TAG=f2741aa632f
-  DOCKER_COMMIT=65718760fa
-```
-
-### Set up the system for the jenkins builder
-
-As a regular user - *Not root*, run:
-
-```
-sudo mkdir -p ${COREBOOT_JENKINS_CACHE_DIR}
-sudo mkdir -p ${COREBOOT_JENKINS_CCACHE_DIR}
-sudo chown $(whoami):$(whoami) ${COREBOOT_JENKINS_CCACHE_DIR}
-sudo chown $(whoami):$(whoami) ${COREBOOT_JENKINS_CACHE_DIR}
-wget http://www.dediprog.com/save/78.rar/to/EM100Pro.rar
-mv EM100Pro.rar ${COREBOOT_JENKINS_CACHE_DIR}
-```
-
-### Install the coreboot jenkins builder
-
-```
-make -C util/docker docker-jenkins-server
-```
-
-Your installation is complete on your side.
-
-### Tell the Admins that the machine is set up
-Let the admins know that the builder is set up so they can set up the
-machine profile on qa.coreboot.org.
-
-They need to know:
-*   Your external IP address or domain name.  If you don’t have a static
-IP, make sure you have a dynamic dns hostname configured.
-*   The port on your machine and firewall that’s exposed for jenkins:
-`$COREBOOT_JENKINS_PORT`
-*   The core count of the machine.
-*   How much memory is available on the machine.  This helps determine
-the amount of memory used for ccache.
-
-
-### First build
-On the first build after a machine is reset, it will frequently take
-20-25 minutes to do the entire what-jenkins-does build while the ccache
-is getting filled up and the entire coreboot repo gets downloaded.  As
-the ccache gets populated, the build time will drop.
-
-
-## Additional Information
-
-
-### How to log in to the docker instance for debugging
-```
-    $ make -C util/docker docker-jenkins-attach
-    $ su coreboot
-    $ cd ~/slave-root/workspace
-    $ bash
-```
-
-
-WARNING: This should not be used to make changes to the build system,
-but just to debug issues. Changes to the build system are highly
-discouraged as it leads to situations where patches can pass the build
-testing on one builder and fail on another builder. Any changes that are
-made in the image will be lost on the next update, so if you
-accidentally change something, you can remove the containers and images
-and update to get a fresh installation.
-
-
-### How to download containers/images for a fresh installation and remove old containers
-
-To delete the old containers & images:
-
-```
-$ docker stop $COREBOOT_JENKINS_CONTAINER
-$ docker rm $COREBOOT_JENKINS_CONTAINER
-$ docker images # lists all existing images
-$ docker rmi XXXX # Use the image ID found in the above command.
-```
-
-To get and run the new coreboot-jenkins image, change the value in the
-`DOCKER_COMMIT` variable to the new image value.
-
-```
-$ make -C util/docker docker-jenkins-server
-```
-
-#### Getting ready to push the docker images
-
-Set up an account on hub.docker.com
-
-Get an admin to add the account to the coreboot team on hub.docker.com
-
-[https://hub.docker.com/u/coreboot/dashboard/teams/?team=owners](https://hub.docker.com/u/coreboot/dashboard/teams/?team=owners)
-
-Make sure your credentials are configured on your host machine by
-running
-
-```
-$ docker login
-```
-
-This will prompt you for your docker username, password, and your email
-address, and write out to ~/.docker/config.json.  Without this file, you
-won’t be able to push the images.
-
-#### Updating the Dockerfiles:
-
-The coreboot-sdk Dockerfile will need to be updated when any additional
-dependencies are added.  Both the coreboot-sdk and the
-coreboot-jenkins-node Dockerfiles will need to be updated to the new
-version number and git commit id anytime the toolchain is updated. Both
-files are stored in the coreboot repo under coreboot/util/docker.
-
-Read the [dockerfile best practices](https://docs.docker.com/v1.8/articles/dockerfile_best-practices/)
-page before updating the files.
-
-#### Rebuilding the coreboot-sdk docker image to update the toolchain:
-
-```
-$ make -C util/docker coreboot-sdk
-```
-
-This takes a relatively long time.
-
-#### Test the coreboot-sdk docker image:
-
-There are two methods of running the docker image - interactively as a
-shell, or doing the build directly.  Running interactively as a shell is
-useful for early testing, because it allows you to update the image
-(without any changes getting saved) and re-test builds.  This saves the
-time of having to rebuild the image for every issue you find.
-
-#### Running the docker image interactively:
-
-Run:
-
-```
-$ make -C util/docker docker-jenkins-server
-$ make -C util/docker docker-jenkins-attach
-```
-
-#### Running the build directly:
-
-From the coreboot directory:
-
-```
-$ make -C util/docker docker-build-coreboot
-```
-
-You’ll also want to test building the other projects and payloads:
-ChromeEC, flashrom, memtest86+, em100, Grub2, SeaBIOS, iPXE, coreinfo,
-nvramcui, tint...
-
-#### Pushing the coreboot-sdk image to hub.docker.com for use:
-
-When you’re satisfied with the testing, push the coreboot-sdk image to
-the hub.docker.com
-
-```
-$ make -C util/docker upload-coreboot-sdk
-```
-
-#### Building and pushing the coreboot-jenkins-node docker image:
-
-This docker image is pretty simple, so there’s not really any testing
-that needs to be done.
-
-```
-$ make -C util/docker coreboot-jenkins-node
-$ make -C util/docker upload-coreboot-jenkins-node
-```
-
-### Coverity Setup
-
-To run coverity jobs, the builder needs to have the tools available, and
-to be marked as a coverity builder.
-
-
-#### Set up the Coverity tools
-
-Download the Linux-64 coverity build tool and decompress it into your
-cache directory as defined by the `$COREBOOT_JENKINS_CACHE_DIR` variable
-
-[https://scan.coverity.com/download](https://scan.coverity.com/download)
-
-Rename the directory from its original name
-(cov-analysis-linux64-7.7.0.4) to ‘coverity’, or better, create a
-symlink:
-
-```
-ln -s cov-analysis-linux64-7.7.0.4 coverity
-```
-
-
-Let the admins know that the ‘coverity’ label can be added to the
-builder.

Documentation/infrastructure/index.md

@@ -1,6 +0,0 @@
-# coreboot infrastructure
-
-This section contains documentation about coreboot infrastructure
-
-## Jenkins builders and builds
-* [Setting up Jenkins build machines](builders.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,154 +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`. All fields in those structures are
-in little endian format.
-
-### 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/fw_config.md

@@ -1,389 +0,0 @@
-# Firmware Configuration Interface in coreboot
-
-## Motivation
-
-The firmware configuration interface in coreboot is designed to support a wide variety of
-configuration options in that are dictated by the hardware at runtime.  This allows a single
-BIOS image to be used across a wide variety of devices which may have key differences but are
-otherwise similar enough to use the same coreboot build target.
-
-The initial implementation is designed to take advantage of a bitmask returned by the Embedded
-Controller on Google Chrome OS devices which allows the manufacturer to use the same firmware
-image across multiple devices by selecting various options at runtime.  See the Chromium OS
-[Firmware Config][1] documentation for more information.
-
-This firmware configuration interface differs from the CMOS option interface in that this
-bitmask value is not intended as a user-configurable setting as the configuration values must
-match the actual hardware.  In the case where a user was to swap their hardware this value
-would need to be updated or overridden.
-
-## Device Presence
-
-One common example of why a firmware configuration interface is important is determining if a
-device is present in the system.  With some bus topologies and hardware mechanisms it is
-possible to probe and enumerate this at runtime:
-
-- PCI is a self-discoverable bus and is very easy to handle.
-- I2C devices can often be probed with a combination of bus and address.
-- The use of GPIOs with external strap to ground or different voltages can be used to detect
-presence of a device.
-
-However there are several cases where this is insufficient:
-
-- I2C peripherals that require different drivers but have the same bus address cannot be
-uniquely identified at runtime.
-- A mainboard may be designed with multiple daughter board combinations which contain devices
-and configurations that cannot be detected.
-- While presence detect GPIOs are a convenient way for a single device presence, they are
-unable to distinguish between different devices so it can require a large number of GPIOs to
-support relatively few options.
-
-This presence detection can impact different stages of boot:
-
-### ACPI
-
-Devices that are not present should not provide an ACPI device indicating that they are
-present or the operating system may not be able to handle it correctly.
-
-The ACPI devices are largely driven by chips defined in the mainboard `devicetree.cb` and
-the variant overridetree.cb.  This means it is important to be able to specify when a device
-is present or not directly in `devicetree.cb` itself.  Otherwise each mainboard needs custom
-code to parse the tree and disable unused devices.
-
-### GPIO
-
-GPIOs with multiple functions may need to be configured correctly depending on the attached
-device.  Given the wide variety of GPIO configuration possibilities it is not feasible to
-specify all combinations directly in `devicetree.cb` and it is best left to code provided by
-the mainboard.
-
-### FSP UPD
-
-Enabling and disabling devices may require altering FSP UPD values that are provided to the
-various stages of FSP.  These options are also not easy to specify multiple times for
-different configurations in `devicetree.cb` and can be provided by the mainboard as code.
-
-## Firmware Configuration Interface
-
-The firmware configuration interface can be enabled by selecting `CONFIG_FW_CONFIG` and also
-providing a source for the value by defining an additional Kconfig option defined below.
-
-If the firmware configuration interface is disabled via Kconfig then all probe attempts will
-return true.
-
-## Firmware Configuration Value
-
-The 64-bit value used as the firmware configuration bitmask is meant to be determined at runtime
-but could also be defined at compile time if needed.
-
-There are two supported sources for providing this information to coreboot.
-
-### CBFS
-
-The value can be provided with a 64-bit raw value in CBFS that is read by coreboot.  The value
-can be set at build time but also adjusted in an existing image with `cbfstool`.
-
-To enable this select the `CONFIG_FW_CONFIG_CBFS` option in the build configuration and add a
-raw 64-bit value to CBFS with the name of the current prefix at `CONFIG_FW_PREFIX/fw_config`.
-
-When `fw_config_probe_device()` or `fw_config_probe()` is called it will look for the specified
-file in CBFS use the value it contains when matching fields and options.
-
-### Embedded Controller
-
-Google Chrome OS devices support an Embedded Controller interface for reading and writing the
-firmware configuration value, along with other board-specific information.  It is possible for
-coreboot to read this value at boot on systems that support this feature.
-
-This option is selected by default for the mainboards that use it with
-`CONFIG_FW_CONFIG_CHROME_EC_CBI` and it is not typically necessary to adjust the value.  It is
-possible by enabling the CBFS source and coreboot will look in CBFS first for a valid value
-before asking the embedded controller.
-
-It is also possible to adjust the value in the embedded controller *(after disabling write
-protection)* with the `ectool` command in a Chrome OS environment.
-
-For more information on the firmware configuration field on Chrome OS devices see the Chromium
-documentation for [Firmware Config][1] and [Board Info][2].
-
-[1]: http://chromium.googlesource.com/chromiumos/docs/+/master/design_docs/firmware_config.md
-[2]: http://chromium.googlesource.com/chromiumos/docs/+/master/design_docs/cros_board_info.md
-
-## Firmware Configuration Table
-
-The firmware configuration table itself is defined in the mainboard `devicetree.cb` with
-special tokens for defining fields and options.
-
-The table itself is enclosed in a `fw_config` token and terminated with `end` and it contains
-a mix of field and option definitions.
-
-Each field is defined by providing the field name and the start and end bit marking the exact
-location in the bitmask.  Field names must be at least three characters long in order to
-satisfy the sconfig parser requirements and they must be unique with non-overlapping masks.
-
-	field <name> <start-bit> <end-bit> [option...] end
-
-For single-bit fields only one number is needed:
-
-	field <name> <bit> [option...] end
-
-A field definition can also contain multiple sets of bit masks, which can be dis-contiguous.
-They are treated as if they are contiguous when defining option values.  This allows for
-extending fields even after the bits after its current masks are occupied.
-
-	field <name> <start-bit0> <end-bit0> | <start-bit1> <end-bit1> | ...
-
-For example, if more audio options need to be supported:
-
-	field AUDIO 3 3
-		option AUDIO_0  0
-		option AUDIO_1  1
-	end
-	field OTHER 4 4
-		...
-	end
-
-the following can be done:
-
-	field AUDIO 3 3 | 5 5
-		option AUDIO_FOO   0
-		option AUDIO_BLAH  1
-		option AUDIO_BAR   2
-		option AUDIO_BAZ   3
-	end
-	field OTHER 4 4
-		...
-	end
-
-In that case, the AUDIO masks are extended like so:
-
-	#define FW_CONFIG_FIELD_AUDIO_MASK						0x28
-	#define FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_FOO_VALUE	0x0
-	#define FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BLAH_VALUE	0x8
-	#define FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BAR_VALUE	0x20
-	#define FW_CONFIG_FIELD_AUDIO_OPTION_AUDIO_BAz_VALUE	0x28
-
-Each `field` definition starts a new block that can be composed of zero or more field options,
-and it is terminated with `end`.
-
-Inside the field block the options can be defined by providing the option name and the field
-value that this option represents when the bit offsets are used to apply a mask and shift.
-Option names must also be at least three characters for the sconfig parser.
-
-	option <name> <value>
-
-It is possible for there to be multiple `fw_config` blocks and for subsequent `field` blocks
-to add additional `option` definitions to the existing field.  These subsequent definitions
-should not provide the field bitmask as it has already been defined earlier in the file and
-this is just matching an existing field by name.
-
-	field <name> [option...] end
-
-This allows a baseboard to define the major fields and options in `devicetree.cb` and a board
-variant to add specific options to fields in or define new fields in the unused bitmask in
-`overridetree.cb`.
-
-It is not possible to redefine a field mask or override the value of an existing option this
-way, only to add new options to a field or new fields to the table.
-
-### Firmware Configuration Table Example
-
-In this example a baseboard defines a simple boolean feature that is enabled or disabled
-depending on the value of bit 0, and a field at bits 1-2 that indicates which daughter board
-is attached.
-
-The baseboard itself defines one daughter board and the variant adds two more possibilities.
-This way each variant can support multiple possible daughter boards in addition to the one
-that was defined by the baseboard.
-
-#### devicetree.cb
-
-    fw_config
-        field FEATURE 0
-            option DISABLED 0
-            option ENABLED 1
-        end
-        field DAUGHTER_BOARD 1 2
-            option NONE 0
-            option REFERENCE_DB 1
-        end
-    end
-
-#### overridetree.cb
-
-    fw_config
-        field DAUGHTER_BOARD
-            option VARIANT_DB_ONE 2
-            option VARIANT_DB_TWO 3
-        end
-    end
-
-The result of this table defined in `devicetree.cb` is a list of constants that can be used
-to check if fields match the firmware configuration options determined at runtime with a
-simple check of the field mask and the option value.
-
-#### static.h
-
-```c
-/* field: FEATURE */
-#define FW_CONFIG_FIELD_FEATURE_NAME "FEATURE"
-#define FW_CONFIG_FIELD_FEATURE_MASK 0x00000001
-#define FW_CONFIG_FIELD_FEATURE_OPTION_DISABLED_NAME "DISABLED"
-#define FW_CONFIG_FIELD_FEATURE_OPTION_DISABLED_VALUE 0x00000000
-#define FW_CONFIG_FIELD_FEATURE_OPTION_ENABLED_NAME "ENABLED"
-#define FW_CONFIG_FIELD_FEATURE_OPTION_ENABLED_VALUE 0x00000001
-
-/* field: DAUGHTER_BOARD */
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_NAME "DAUGHTER_BOARD"
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_MASK 0x00000006
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_NONE_NAME "NONE"
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_NONE_VALUE 0x00000000
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_REFERENCE_DB_NAME "REFERENCE_DB"
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_REFERENCE_DB_VALUE 0x00000002
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_ONE_NAME "VARIANT_DB_ONE"
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_ONE_VALUE 0x00000004
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_TWO_NAME "VARIANT_DB_TWO"
-#define FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_TWO_VALUE 0x00000006
-```
-
-## Device Probing
-
-One use of the firmware configuration interface in devicetree is to allow device probing to be
-specified directly with the devices themselves.  A new `probe` token is introduced to allow a
-device to be probed by field and option name.  Multiple `probe` entries may be present for
-each device and any successful probe will consider the device to be present.
-
-### Probing Example
-
-Continuing with the previous example this device would be considered present if the field
-`DAUGHTER_BOARD` was set to either `VARIANT_DB_ONE` or `VARIANT_DB_TWO`:
-
-#### overridetree.cb
-
-    chip drivers/generic/example
-        device generic 0 on
-            probe DAUGHTER_BOARD VARIANT_DB_ONE
-            probe DAUGHTER_BOARD VARIANT_DB_TWO
-        end
-    end
-
-If the field were set to any other option, including `NONE` and `REFERENCE_DB` and any
-undefined value then the device would be disabled.
-
-### Probe Overrides
-
-When a device is declared with a probe in the baseboard `devicetree.cb` and the same device
-is also present in the `overridetree.cb` then the probing information from the baseboard
-is discarded and the override device must provide all necessary probing information.
-
-In this example a device is listed in the baseboard with `DAUGHTER_BOARD` field probing for
-`REFERENCE_DB` as a field option,  It is also defined as an override device with the field
-probing for the `VARIANT_DB_ONE` option instead.
-
-In this case only the probe listed in the override is checked and a field option of
-`REFERENCE_DB` will not mark this device present.  If both options are desired then the
-override device must list both.  This allows an override device to remove a probe entry that
-was defined in the baseboard.
-
-#### devicetree.cb
-
-    chip drivers/generic/example
-	    device generic 0 on
-		    probe DAUGHTER_BOARD REFERENCE_DB
-	    end
-	end
-
-#### overridetree.cb
-
-    chip drivers/generic/example
-	    device generic 0 on
-		    probe DAUGHTER_BOARD VARIANT_DB_ONE
-	    end
-	end
-
-### Automatic Device Probing
-
-At boot time the firmware configuration interface will walk the device tree and apply any
-probe entries that were defined in `devicetree.cb`.  This probing takes effect before the
-`BS_DEV_ENUMERATE` step during the boot state machine in ramstage.
-
-Devices that have a probe list but do do not find a match are disabled by setting
-`dev->enabled = 0` but the chip `enable_dev()` and device `enable()` handlers will still
-be executed to allow any device disable code to execute.
-
-The result of this probe definition is to provide an array of structures describing each
-field and option to check.
-
-#### fw_config.h
-
-```c
-/**
- * struct fw_config - Firmware configuration field and option.
- * @field_name: Name of the field that this option belongs to.
- * @option_name: Name of the option within this field.
- * @mask: Bitmask of the field.
- * @value: Value of the option within the mask.
- */
-struct fw_config {
-	const char *field_name;
-	const char *option_name;
-	uint64_t mask;
-	uint64_t value;
-};
-```
-
-#### static.c
-
-```c
-STORAGE struct fw_config __devN_probe_list[] = {
-	{
-		.field_name = FW_CONFIG_FIELD_DAUGHTER_BOARD_NAME,
-		.option_name = FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_ONE_NAME,
-		.mask = FW_CONFIG_FIELD_DAUGHTER_BOARD_MASK,
-		.value = FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_ONE_VALUE
-	},
-	{
-		.field_name = FW_CONFIG_FIELD_DAUGHTER_BOARD_NAME,
-		.option_name = FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_TWO_NAME,
-		.mask = FW_CONFIG_FIELD_DAUGHTER_BOARD_MASK,
-		.value = FW_CONFIG_FIELD_DAUGHTER_BOARD_OPTION_VARIANT_DB_TWO_VALUE
-	},
-	{ }
-};
-```
-
-### Runtime Probing
-
-The device driver probing allows for seamless integration with the mainboard but it is only
-effective in ramstage and for specific devices declared in devicetree.cb.  There are other
-situations where code may need to probe or check the value of a field in romstage or at other
-points in ramstage.  For this reason it is also possible to use the firmware configuration
-interface directly.
-
-```c
-/**
- * fw_config_probe() - Check if field and option matches.
- * @match: Structure containing field and option to probe.
- *
- * Return %true if match is found, %false if match is not found.
- */
-bool fw_config_probe(const struct fw_config *match);
-```
-
-The argument provided to this function can be created from a macro for easy use:
-
-	FW_CONFIG(field, option)
-
-This example has a mainboard check if a feature is disabled and set an FSP UPD before memory
-training.  This example expects that the default value of this `register` is set to `true` in
-`devicetree.cb` and this code is disabling that feature before FSP is executed.
-
-```c
-#include <fw_config.h>
-
-void mainboard_memory_init_params(FSPM_UPD *mupd)
-{
-	if (fw_config_probe_one(FW_CONFIG(FEATURE, DISABLED))
-		mupd->ExampleFeature = false;
-}
-```

Documentation/lib/index.md

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

Documentation/lib/option.md

@@ -1,31 +0,0 @@
-# Option API
-
-The option API around the `set_option(const char *name, void *val)` and
-`get_option(void *dest, const char *name)` functions deprecated in favor
-of a type-safe API.
-
-Historically, options were stored in RTC battery-backed CMOS RAM inside
-the chipset on PC platforms. Nowadays, options can also be stored in the
-same flash chip as the boot firmware or through some BMC interface.
-
-The new type-safe option framework can be used by calling
-`enum cb_err set_uint_option(const char *name, unsigned int value)` and
-`unsigned int get_uint_option(const char *name, const unsigned int fallback)`.
-
-The default setting is `OPTION_BACKEND_NONE`, which disables any runtime
-configurable options. If supported by a mainboard, the `USE_OPTION_TABLE`
-and `USE_MAINBOARD_SPECIFIC_OPTION_BACKEND` choices are visible, and can
-be selected to enable runtime configurability.
-
-# Mainboard-specific option backend
-
-Mainboards with a mainboard-specific (vendor-defined) method to access
-options can select `HAVE_MAINBOARD_SPECIFIC_OPTION_BACKEND` to provide
-implementations of the option API accessors. To allow choosing between
-multiple option backends, the mainboard-specific implementation should
-only be built when `USE_MAINBOARD_SPECIFIC_OPTION_BACKEND` is selected.
-
-Where possible, using a generic, mainboard-independent mechanism should
-be preferred over reinventing the wheel in mainboard-specific code. The
-mainboard-specific approach should only be used when the option storage
-mechanism has to satisfy externally-imposed, vendor-defined constraints.

Documentation/lib/payloads/fit.md

@@ -5,9 +5,7 @@
 
 ## Supported architectures
 
-* aarch32
 * aarch64
-* riscv
 
 ## Supported FIT sections
 
@@ -25,15 +23,7 @@ The section must be named in order to be found by the FIT parser:
 
 ## Architecture specifics
 
-The FIT parser needs architecture support.
+The FIT parser needs architecure support.
-
-### aarch32
-The source code can be found in `src/arch/arm/fit_payload.c`.
-
-On aarch32 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*".
-
 ### aarch64
 The source code can be found in `src/arch/arm64/fit_payload.c`.
 
@@ -41,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.
 
@@ -66,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 programming   | 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/a88xm-e.md

@@ -1,170 +0,0 @@
-# ASUS A88XM-E
-
-This page describes how to run coreboot on the [ASUS A88XM-E].
-
-## Technology
-
-Both "Trinity" and "Richland" FM2 desktop processing units are working,
-the CPU architecture in these CPUs/APUs are [Piledriver],
-and their GPU is [TeraScale 3] (VLIW4-based).
-
-Kaveri is non-working at the moment (FM2+),
-the CPU architecture in these CPUs/APUs are [Steamroller],
-and their GPU is [Sea Islands] (GCN2-based).
-
-A10 Richland is recommended for the best performance and working IOMMU.
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| A88XM-E          |                                                  |
-+------------------+--------------------------------------------------+
-| DDR voltage IC   | Nuvoton 3101S                                    |
-+------------------+--------------------------------------------------+
-| Network          | Realtek RTL8111G                                 |
-+------------------+--------------------------------------------------+
-| Northbridge      | Integrated into CPU with IMC and GPU (APUs only) |
-+------------------+--------------------------------------------------+
-| Southbridge      | Bolton-D4                                        |
-+------------------+--------------------------------------------------+
-| Sound IC         | Realtek ALC887                                   |
-+------------------+--------------------------------------------------+
-| Super I/O        | ITE IT8603E                                      |
-+------------------+--------------------------------------------------+
-| VRM controller   | DIGI VRM ASP1206                                 |
-+------------------+--------------------------------------------------+
-```
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+------------+
-| Type                | Value      |
-+=====================+============+
-| Socketed flash      | yes        |
-+---------------------+------------+
-| Model               | [GD25Q64]  |
-+---------------------+------------+
-| Size                | 8 MiB      |
-+---------------------+------------+
-| Package             | DIP-8      |
-+---------------------+------------+
-| Write protection    | yes        |
-+---------------------+------------+
-| Dual BIOS feature   | no         |
-+---------------------+------------+
-| Internal flashing   | yes        |
-+---------------------+------------+
-```
-
-### Internal programming
-
-The main SPI flash can be accessed using [flashrom], if the
-AmdSpiRomProtect modules have been deleted in the factory image previously.
-
-### External flashing
-
-Using a PLCC Extractor or any other appropriate tool, carefully remove the
-DIP-8 BIOS chip from its' socket while avoiding the bent pins, if possible.
-To flash it, use a [flashrom]-supported USB CH341A programmer - preferably with a
-green PCB - and double check that it's giving a 3.3V voltage on the socket pins.
-
-## Integrated graphics
-
-### Retrieve the VGA optionrom ("Retrieval via Linux kernel" method)
-
-Make sure a proprietary UEFI is flashed and boot Linux with iomem=relaxed flag.
-Some Linux drivers (e.g. radeon for AMD) make option ROMs like the video blob
-available to user space via sysfs. To use that to get the blob you need to
-enable it first. To that end you need to determine the path within /sys
-corresponding to your graphics chip. It looks like this:
-
-    # /sys/devices/pci<domain>:<bus>/<domain>:<bus>:<slot>.<function>/rom.
-
-You can get the respective information with lspci, for example:
-
-    # lspci -tv
-    # -[0000:00]-+-00.0  Advanced Micro Devices, Inc. [AMD] Family 16h Processor Root Complex
-    #            +-01.0  Advanced Micro Devices, Inc. [AMD/ATI] Kabini [Radeon HD 8210]
-    # ...
-
-Here the the needed bits (for the ROM of the Kabini device) are:
-
-    # PCI domain: (almost always) 0000
-    # PCI bus: (also very commonly) 00
-    # PCI slot: 01 (logical slot; different from any physical slots)
-    # PCI function: 0 (a PCI device might have multiple functions... shouldn't matter here)
-
-To enable reading of the ROM you need to write 1 to the respective file, e.g.:
-
-    # echo 1 > /sys/devices/pci0000:00/0000:00:01.0/rom
-
-The same file should then contain the video blob and it should be possible to simply copy it, e.g.:
-
-    # cp /sys/devices/pci0000:00/0000:00:01.0/rom vgabios.bin
-
-romheaders should print reasonable output for this file.
-
-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)
-    1002,130f Kaveri (Radeon R7)
-
-## Known issues
-
-- AHCI hot-plug
-- S3 resume (sometimes)
-- Windows 7 can't boot because of the incomplete ACPI implementation
-- XHCI
-
-### XHCI ports can break after using any of the blobs, restarting the
-board with factory image makes it work again as fallback.
-Tested even with/without the Bolton and Hudson blobs.
-
-## Untested
-
-- audio over HDMI
-
-## TODOs
-
-- one ATOMBIOS module for all the integrated GPUs
-- manage to work with Kaveri/Godavary (they are using a binaryPI)
-- IRQ routing is done incorrect way - common problem of fam15h boards
-
-## Working
-
-- ACPI
-- CPU frequency scaling
-- flashrom under coreboot
-- Gigabit Ethernet
-- Hardware monitoring
-- Integrated graphics
-- KVM virtualization
-- Onboard audio
-- PCI
-- PCIe
-- PS/2 keyboard mouse (during payload, bootloader)
-- SATA
-- Serial port
-- SuperIO based fan control
-- USB (disabling XHCI controller makes to work as fallback USB2.0 ports)
-- IOMMU
-
-## Extra resources
-
-- [Board manual]
-
-[ASUS A88XM-E]: https://www.asus.com/Motherboards/A88XME/
-[Board manual]: https://dlcdnets.asus.com/pub/ASUS/mb/SocketFM2/A88XM-E/E9125_A88XM-E.pdf
-[flashrom]: https://flashrom.org/Flashrom
-[GD25Q64]: http://www.elm-tech.com/ja/products/spi-flash-memory/gd25q64/gd25q64.pdf
-[Piledriver]: https://en.wikipedia.org/wiki/Piledriver_%28microarchitecture%29#APU_lines
-[Sea Islands]: https://en.wikipedia.org/wiki/Graphics_Core_Next#GCN_2nd_generation
-[Steamroller]: https://en.wikipedia.org/wiki/Steamroller_(microarchitecture)
-[TeraScale 3]: https://en.wikipedia.org/wiki/TeraScale_%28microarchitecture%29#TeraScale_3

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,134 +0,0 @@
-# ASUS P5Q
-
-This page describes how to run coreboot on the [ASUS P5Q] desktop board.
-
-## Working
-
-+ 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
-+ Fan control through the W83667HG chip
-+ FireWire
-
-## Not working
-
-+ PS/2 mouse support
-+ PATA aka IDE (because of buggy IDE controller)
-+ Fan profiles with Q-Fan
-+ TPM module (support not implemented)
-
-## Untested
-
-+ S/PDIF
-+ CD Audio In
-+ Floppy disk drive
-
-
-## 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                                  |
-+------------------+---------------------------------------------------+
-```
-
-## Controlling fans
-
-With vendor firmware, the P5Q uses the ATK0110 ACPI device to control its fans
-according to the parameters configured in the BIOS setup menu. With coreboot,
-one can instead control the Super I/O directly as described in the
-[kernel docs]:
-
-+ pwm1 controls fan1 (CHA_FAN1) and fan4 (CHA_FAN2)
-+ pwm2 controls fan2 (CPU_FAN)
-+ fan3 (PWR_FAN) cannot be controlled
-+ temp1 (board) can be used to control fan1 and fan4
-+ temp2 (CPU) can be used to control fan2
-
-### Manual fan speed
-
-These commands set the chassis fans to a constant speed:
-
-    # Use PWM output
-    echo 1 >/sys/class/hwmon/hwmon2/pwm1_mode
-    # Set to manual mode
-    echo 1 >/sys/class/hwmon/hwmon2/pwm1_enable
-    # Set relative speed: 0 (stop) to 255 (full)
-    echo 150 >/sys/class/hwmon/hwmon2/pwm1
-
-### Automatic fan speed
-
-The W83667HG can adjust fan speeds when things get too warm. These settings will
-control the chassis fans:
-
-    # Set to "Thermal Cruise" mode
-    echo 2 >/sys/class/hwmon/hwmon2/pwm1_enable
-    # Target temperature: 60°C
-    echo 60000 >/sys/class/hwmon/hwmon2/pwm1_target
-    # Minimum fan speed when spinning up
-    echo 135 >/sys/class/hwmon/hwmon2/pwm1_start_output
-    # Minimum fan speed when spinning down
-    echo 135 >/sys/class/hwmon/hwmon2/pwm1_stop_output
-    # Tolerance: 2°C
-    echo 2000 >/sys/class/hwmon/hwmon2/pwm1_tolerance
-    # Turn fans off after 600 seconds when below defined range
-    echo 600000 >/sys/class/hwmon/hwmon2/pwm1_stop_time
-
-You can also control the CPU fan with similar rules:
-
-    # Switch to "Thermal Cruise" mode
-    echo 2 >/sys/class/hwmon/hwmon2/pwm2_enable
-    # Target temperature: 55°C
-    echo 55000 >/sys/class/hwmon/hwmon2/pwm2_target
-    # Minimum fan speed when spinning down
-    echo 50 >/sys/class/hwmon/hwmon2/pwm2_stop_output
-    # Rate of fan speed change
-    echo 50 >/sys/class/hwmon/hwmon2/pwm2_step_output
-    # Maximum fan speed
-    echo 200 >/sys/class/hwmon/hwmon2/pwm2_max_output
-    # Tolerance: 2°C
-    echo 2000 >/sys/class/hwmon/hwmon2/pwm1_tolerance
-
-[ASUS P5Q]: https://www.asus.com/Motherboards/P5Q
-[this guide]: https://doc.coreboot.org/flash_tutorial/int_flashrom.html
-[kernel docs]: https://www.kernel.org/doc/Documentation/hwmon/w83627ehf.rst