WIP: lemp9 vboot support

Change-Id: I47fbc95a8bd242b4261f5fc52b073f0b2b6ab080

.checkpatch.conf

@@ -4,7 +4,6 @@
 # Ignore aspects we don't follow here.
 --ignore C99_COMMENTS
 --ignore GLOBAL_INITIALISERS
---ignore COMPARISON_TO_NULL
 --ignore INITIALISED_STATIC
 --ignore LINE_SPACING
 --ignore NEW_TYPEDEFS
@@ -21,9 +20,6 @@
 --ignore SPDX_LICENSE_TAG
 --ignore UNDOCUMENTED_DT_STRING
 --ignore PRINTK_WITHOUT_KERN_LEVEL
---ignore ASSIGN_IN_IF
---ignore UNNECESSARY_ELSE
---ignore GERRIT_CHANGE_ID
 
 # FILE_PATH_CHANGES seems to not be working correctly. It will
 # choke on added / deleted files even if the MAINTAINERS file
@@ -34,8 +30,5 @@
 # some commits unnecessarily.
 --ignore EXECUTE_PERMISSIONS
 
-# Exclude vendorcode directories that don't follow coreboot's coding style.
---exclude src/vendorcode/amd
---exclude src/vendorcode/cavium
---exclude src/vendorcode/intel
---exclude src/vendorcode/mediatek
+# Exclude the vendorcode directory
+--exclude src/vendorcode

.gitignore

@@ -1,3 +1,6 @@
+payloads/libpayload/install/
+payloads/nvramcui/build
+payloads/nvramcui/libpayload
 junit.xml
 abuild*.xml
 .config
@@ -8,8 +11,46 @@ 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
 
 *.\#
@@ -18,28 +59,77 @@ site-local
 *.debug
 !Kconfig.debug
 *.elf
-*.fd
 *.o
 *.o.d
 *.out
 *.pyc
 *.sw[po]
 /*.rom
-.test
-.dependencies
+coreboot-builds*/
 
 # Development friendly files
 tags
 .clang_complete
-.cache
-compile_commands.json
-.vscode/
 
 # Cross-compile toolkits
 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/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/pmh7tool/pmh7tool
+util/runfw/googlesnow
+util/superiotool/superiotool
+util/vgabios/testbios
+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,67 +1,53 @@
 [submodule "3rdparty/blobs"]
 	path = 3rdparty/blobs
-	url = ../blobs.git
+	url = https://review.coreboot.org/blobs.git
 	update = none
 	ignore = dirty
 [submodule "util/nvidia-cbootimage"]
 	path = util/nvidia/cbootimage
-	url = ../nvidia-cbootimage.git
+	url = https://review.coreboot.org/nvidia-cbootimage.git
 [submodule "vboot"]
 	path = 3rdparty/vboot
-	url = ../vboot.git
-	branch = main
+	url = https://review.coreboot.org/vboot.git
 [submodule "arm-trusted-firmware"]
 	path = 3rdparty/arm-trusted-firmware
-	url = ../arm-trusted-firmware.git
+	url = https://review.coreboot.org/arm-trusted-firmware.git
 [submodule "3rdparty/chromeec"]
 	path = 3rdparty/chromeec
-	url = ../chrome-ec.git
+	url = https://review.coreboot.org/chrome-ec.git
 [submodule "libhwbase"]
 	path = 3rdparty/libhwbase
-	url = ../libhwbase.git
+	url = https://review.coreboot.org/libhwbase.git
 [submodule "libgfxinit"]
 	path = 3rdparty/libgfxinit
-	url = ../libgfxinit.git
+	url = https://review.coreboot.org/libgfxinit.git
 [submodule "3rdparty/fsp"]
 	path = 3rdparty/fsp
-	url = ../fsp.git
+	url = https://review.coreboot.org/fsp.git
 	update = none
 	ignore = dirty
 [submodule "opensbi"]
 	path = 3rdparty/opensbi
-	url = ../opensbi.git
+	url = https://review.coreboot.org/opensbi.git
 [submodule "intel-microcode"]
 	path = 3rdparty/intel-microcode
-	url = ../intel-microcode.git
+	url = https://review.coreboot.org/intel-microcode.git
 	update = none
 	ignore = dirty
-	branch = main
 [submodule "3rdparty/ffs"]
 	path = 3rdparty/ffs
-	url = ../ffs.git
+	url = https://review.coreboot.org/ffs.git
 [submodule "3rdparty/amd_blobs"]
 	path = 3rdparty/amd_blobs
-	url = ../amd_blobs
+	url = https://review.coreboot.org/amd_blobs.git
 	update = none
 	ignore = dirty
 [submodule "3rdparty/cmocka"]
 	path = 3rdparty/cmocka
-	url = ../cmocka.git
+	url = https://review.coreboot.org/cmocka.git
 	update = none
-	branch = stable-1.1
 [submodule "3rdparty/qc_blobs"]
 	path = 3rdparty/qc_blobs
-	url = ../qc_blobs.git
+	url = https://review.coreboot.org/qc_blobs.git
 	update = none
 	ignore = dirty
-[submodule "3rdparty/intel-sec-tools"]
-	path = 3rdparty/intel-sec-tools
-	url = ../9esec-security-tooling.git
-[submodule "3rdparty/stm"]
-	path = 3rdparty/stm
-	url = ../STM
-	branch = stmpe
-[submodule "util/goswid"]
-	path = util/goswid
-	url = ../goswid
-	branch = trunk

.mailmap

@@ -1,425 +0,0 @@
-# Map author and committer names and email addresses to canonical real names and
-# email addresses. https://git-scm.com/docs/gitmailmap
-#
-# Note that this is only needed in the case where someone has contributed
-# with multiple different email addresses or Names.
-#
-# Forms: Proper Name <commit@email.xx>
-#        Proper Name <proper@email.xx> <commit@email.xx>
-#        Proper Name <proper@email.xx> Commit Name <commit@email.xx>
-
-
-Aamir Bohra <aamirbohra@gmail.com> <aamir.bohra@intel.com>
-Aaron Durbin <adurbin@chromium.org>
-Aaron Durbin <adurbin@chromium.org> <adurbin@adurbin.bld.corp.google.com>
-Aaron Durbin <adurbin@chromium.org> <adurbin@google.com>
-Abhay Kumar <abhay.kumar@intel.com>
-Abhinav Hardikar <realdevmaster64@gmail.com> devmaster64 <devmaster64@gmail.com>
-Alex Levin <levinale@google.com> <levinale@chromium.org>
-Alex Miao <alex.miao@mediatek.corp-partner.google.com>
-Alexandru Gagniuc <mr.nuke.me@gmail.com> <alexandrux.gagniuc@intel.com>
-Alexandru Gagniuc <mr.nuke.me@gmail.com> mrnuke <mrnuke@nukelap.gtech>
-Amanda Huang <amanda_hwang@compal.corp-partner.google.com>
-Amol N Sukerkar <amol.n.sukerkar@intel.com>
-Andrea Barberio <barberio@fb.com> <insomniac@slackware.it>
-Andrey Petrov <anpetrov@fb.com> <andrey.petrov@intel.com>
-Andrey Pronin <apronin@chromium.org> <apronin@google.com>
-Andriy Gapon <avg@FreeBSD.org> <avg@icyb.net.ua>
-Anil Kumar <anil.kumar.k@intel.com> <anil.kumar.k@intel.corp-partner.google.com>
-Anish K. Patel <anishp@win-ent.com>
-Anton Kochkov <anton.kochkov@gmail.com> <a.kochkov@securitycode.ru>
-Antonello Dettori <dev@dettori.io> <dettori.an@gmail.com>
-Ariel Fang <ariel_fang@wistron.corp-partner.google.com>
-Arne Georg Gleditsch <arne.gleditsch@numascale.com> <arne.gleditsch@numscale.com>
-Asami Doi <d0iasm.pub@gmail.com> <doiasami1219@gmail.com>
-Ashwin Kumar <ashk@codeaurora.org>
-Axel Holewa <mono@posteo.de> Mono <mono-for-coreboot@donderklumpen.de>
-Axel Holewa <mono@posteo.de> Mono <mono@posteo.de>
-Bao Zheng <fishbaozi@gmail.com>
-Bao Zheng <fishbaozi@gmail.com> <Zheng Bao zheng.bao@amd.com>
-Bao Zheng <fishbaozi@gmail.com> <zheng.bao@amd.com>
-Bayi Cheng <bayi.cheng@mediatek.com>
-Ben Zhang <benzh@google.com> <benzh@chromium.org>
-Bernhard M. Wiedermann <corebootbmw@lsmod.de>
-Bill Xie <persmule@hardenedlinux.org> <persmule@gmail.com>
-Bill Xie <persmule@hardenedlinux.org> Bill XIE <persmule@hardenedlinux.org>
-Bingxun Shi <bingxunshi@gmail.com>
-Bingxun Shi <bingxunshi@gmail.com> <bxshi@msik.com.cn>
-Brandon Breitenstein <brandon.breitenstein@intel.com> <brandon.breitenstein@intel.corp-partner.google.com>
-Bruce Griffith <bruce.griffith@se-eng.com> <Bruce.Griffith@se-eng.com>
-Bryant Ou <Bryant.Ou.Q@gmail.com>
-Carl-Daniel Hailfinger <c-d.hailfinger.devel.2006@gmx.net> <Carl-Daniel Hailfinger>
-Casper Chang<casper_chang@wistron.corp-partner.google.com> <casper.chang@bitland.corp-partner.google.com>
-Caveh Jalali <caveh@chromium.org> <caveh@google.com>
-Caveh Jalali <caveh@chromium.org> caveh jalali <caveh@chromium.org>
-Charles Marslett <charles@scarlettechnologies.com> <charles.marslett@silverbackltd.com>
-Chee Soon Lew <chee.soon.lew@intel.com>
-Cheng-Yi Chiang <cychiang@chromium.org> <cychiang@google.com>
-Chris Ching <chris@ching.codes> <chingcodes@chromium.org>
-Chris Ching <chris@ching.codes> <chingcodes@google.com>
-Chris Wang <chris.wang@amd-corp-partner.google.com> <chriswang@ami.corp-partner.google.com>
-Chris Wang <chris.wang@amd-corp-partner.google.com> Chris Wang <chris.wang@amd-corp-partner.google.com>
-Chris Wang <chris.wang@amd-corp-partner.google.com> chris wang <chris.wang@amd.corp-partner.google.com>
-Chris Wang <chris.wang@amd-corp-partner.google.com> Chris.Wang <chris.wang@amd.corp-partner.google.com>
-Chris Zhou <chris_zhou@compal.corp-partner.google.com>
-Christian Ruppert <idl0r@qasl.de> <idl0r@gentoo.org>
-Chun-Jie Chen <chun-jie.chen@mediatek.corp-partner.google.com>
-Clay Daniels Jr <clay.daniels.jr@gmail.com>
-Cole Nelson<colex.nelson@intel.com>
-Corey Osgood <corey.osgod@gmail.com> <corey_osgood@verizon.net>
-Corey Osgood <corey.osgod@gmail.com> <corey.osgood@gmail.com>
-Cristian Măgherușan-Stanciu <cristi.magherusan@gmail.com>
-Cristian Măgherușan-Stanciu <cristi.magherusan@gmail.com> Cristi Magherusan <cristi.magherusan@net.utcluj.ro>
-Da Lao <dalao@tutanota.com> dalao <dalao@tutanota.com>
-Daisuke Nojiri <dnojiri@chromium.org> dnojiri <dnojiri@chromium.org>
-Dan Elkouby <streetwalkermc@gmail.com> <streetwalrus@codewalr.us>
-Daphne Jansen <dcjansen@chromium.org> Justin TerAvest <teravest@chromium.org>
-Daphne Jansen <dcjansen@chromium.org> Justin TerAvest <teravest@google.com>
-Dave Parker <dparker@chromium.org>
-David Hendricks <davidhendricks@gmail.com> <david.hendricks@gmail.com>
-David Hendricks <davidhendricks@gmail.com> <dhendricks@fb.com>
-David Hendricks <davidhendricks@gmail.com> <dhendrix@chromium.org>
-David Hendricks <davidhendricks@gmail.com> <dhendrix@fb.com>
-David Hendricks <davidhendricks@gmail.com> <dhendrix@google.com>
-David Hendricks <davidhendricks@gmail.com> David W. Hendricks <dwh@lanl.gov>
-David Wu <david_wu@quantatw.com> <david_wu@quanta.corp-partner.google.com>
-David Wu <david_wu@quantatw.com> david <david_wu@quantatw.com>
-Dawei Chien <dawei.chien@mediatek.com>
-Denis 'GNUtoo' Carikli <GNUtoo@cyberdimension.org> <GNUtoo@no-log.org>
-Derek Huang <derek.huang@intel.com> <derek.huang@intel.corp-partner.google.com>
-Dmitry Ponamorev <dponamorev@gmail.com>
-Douglas Anderson <dianders@chromium.org>
-Duncan Laurie <dlaurie@chromium.org> <dlaurie@google.com>
-Ed Swierk <eswierk@aristanetworks.com> <eswierk@arastra.com>
-Edward O'Callaghan <quasisec@google.com> <edward.ocallaghan@koparo.com>
-Edward O'Callaghan <quasisec@google.com> <eocallaghan@alterapraxis.com>
-Edward O'Callaghan <quasisec@google.com> <funfunctor@folklore1984.net>
-Edward O'Callaghan <quasisec@google.com> <quasisec@chromium.org>
-Eric Biederman <ebiederm@xmission.com> <ebiederman@lnxi.com>
-Eric Biederman <ebiederm@xmission.com> Eric W. Biederman <ebiederm@xmission.com>
-Eugene Myers <edmyers@tycho.nsa.gov> <cedarhouse@comcast.net>
-Evgeny Zinoviev <me@ch1p.io> <me@ch1p.com>
-Felix Durairaj <felixx.durairaj@intel.com>
-Felix Held <felix-coreboot@felixheld.de> <felix-github@felixheld.de>
-Felix Held <felix-coreboot@felixheld.de> <felix.held@amd.corp-partner.google.com>
-Felix Singer <felixsinger@posteo.net> <felix.singer@9elements.com>
-Felix Singer <felixsinger@posteo.net> <felix.singer@secunet.com>
-Felix Singer <felixsinger@posteo.net> <migy@darmstadt.ccc.de>
-Francois Toguo Fotso <francois.toguo.fotso@intel.com> Francois Toguo <francois.toguo.fotso@intel.com>
-Frank Chu <frank_chu@pegatron.corp-partner.google.com>
-Frank Chu <frank_chu@pegatron.corp-partner.google.com> Frank Chu <Frank_Chu@pegatron.corp-partner.google.com>
-Frank Chu <frank_chu@pegatron.corp-partner.google.com> FrankChu <Frank_Chu@pegatron.corp-partner.google.com>
-Frank Vibrans <efdesign98@gmail.com> efdesign98 <efdesign98@gmail.com>
-Frank Vibrans <efdesign98@gmail.com> Frank Vibrans <frank.vibrans@amd.com>
-Frank Vibrans <efdesign98@gmail.com> frank vibrans <frank.vibrans@scarletltd.com>
-Frank Vibrans <efdesign98@gmail.com> Frank Vibrans <frank.vibrans@se-eng.com>
-Frank Vibrans <efdesign98@gmail.com> Frank.Vibrans <frank.vibrans@amd.com>
-Furquan Shaikh <furquan@chromium.org> <furquan@google.com>
-G. Pangao <gtk_pangao@mediatek.com> <gtk_pangao@mediatek.corp-partner.google.com>
-Gabe Black <gabeblack@chromium.org> <gabeblack@chromium.com>
-Gabe Black <gabeblack@chromium.org> <gabeblack@google.com>
-Gaggery Tsai <gaggery.tsai@intel.com>
-Georg Wicherski <gwicherski@gmail.com> <gw@oxff.net>
-Gomathi Kumar <gomathi.kumar@intel.com>
-Greg V <greg@unrelenting.technology>
-Greg Watson <gwatson@lanl.gov> <jarrah@users.sourceforge.net>
-Hannah Williams <hannah.williams@dell.com> <hannah.williams@intel.com>
-Hao Chou <hao_chou@pegatron.corp-partner.google.com>
-Haridhar Kalvala <haridhar.kalvala@intel.com> haridhar <haridhar.kalvala@intel.com>
-Harsha Priya <harshapriya.n@intel.com>
-Harsha Priya <harshapriya.n@intel.com> <harhapriya.n@intel.com>
-Harshit Sharma <harshitsharmajs@gmail.com> harshit <harshitsharmajs@gmail.com>
-Henry C Chen <henryc.chen@mediatek.com> henryc.chen <henryc.chen@mediatek.com>
-Himanshu Sahdev <sahdev.himan@gmail.com> <himanshusah@hcl.com>
-Himanshu Sahdev <sahdev.himan@gmail.com> Himanshu Sahdev aka CunningLearner <sahdev.himan@gmail.com>
-Hsuan Ting Chen <roccochen@chromium.org> Hsuan-ting Chen <roccochen@google.com>
-Huang Lin <hl@rock-chips.com>
-Huayang Duan <huayang.duan@mediatek.com>
-Huki Huang <huki.huang@intel.com>
-Idwer Vollering <vidwer@gmail.com> <idwer_v@hotmail.com>
-Igor Bagnucki <bagnucki02@gmail.com> <igor.bagnucki@3mdeb.com>
-Indrek Kruusa <indrek.kruusa@artecdesign.ee>  <Indrek Kruusa>
-Ivy Jian <ivy_jian@compal.com> <ivy_jian@compal.corp-partner.google.com>
-Jacob Laska <jlaska91@gmail.com> <jlaska@xes-inc.com>
-Jakub Czapiga <jacz@semihalf.com>
-Jason Wang <Qingpei.Wang@amd.com> Jason WangQingpei.wang <Jason WangQingpei.wang@amd.com>
-JasonX Z Chen <jasonx.z.chen@intel.com>
-Jens Kühnel <coreboot@jens.kuehnel.org> Jens Kuehnel <coreboot@jens.kuehnel.org>
-Jens Rottmann <JRottmann@LiPPERTembedded.de> <JRottmann@LiPPERTEmbedded.de>
-Jeremy Compostella  <jeremy.compostella@intel.com> <jeremy.compostella@gmail.com>
-Jeremy Soller <jackpot51@gmail.com> <jeremy@system76.com>
-Jiaxin Yu <jiaxin.yu@mediatek.com>
-Jiazi Yang <Tomato_Yang@asus.com>
-Jim Lai <jim.lai@intel.com>
-Jingle Hsu <jingle_hsu@wiwynn.com>
-Jinkun Hong <jinkun.hong@rock-chips.com>
-Joe Moore <awokd@danwin1210.me>
-Joe Pillow <joseph.a.pillow@gmail.com>
-Johanna Schander <coreboot@mimoja.de>
-John Zhao <john.zhao@intel.com>
-Jonathan Kollasch <jakllsch@kollasch.net>
-Jordan Crouse <jordan@cosmicpenguin.net>  <Jordan Crouse>
-Jordan Crouse <jordan@cosmicpenguin.net> <jordan.crouse@amd.com>
-Josef Kellermann <Joseph.Kellermann@heitec.de> <seppk@arcor.de>
-Josef Kellermann <Joseph.Kellermann@heitec.de> Josef Kellermannseppk <Josef Kellermannseppk@arcor.de>
-Joseph Smith <joe@settoplinux.org> <joe@settoplinux.org Acked-by: Joseph Smith joe@settoplinux.org>
-Joseph Smith <joe@settoplinux.org> <joe@smittys.pointclark.net>
-Juergen Beisert <juergen@kreuzholzen.de> <juergen127@kreuzholzen.de>
-Julian Schroeder <julianmarcusschroeder@gmail.com> <julian.schroeder@amd.com>
-Julien Viard de Galbert <julien@vdg.name> <jviarddegalbert@online.net>
-Justin Wu <amersel@runbox.me>
-Kaiyen Chang <kaiyen.chang@intel.com> <kaiyen.chang@intel.corp-partner.google.com>
-Kane Chen <kane.chen@intel.com> <kane_chen@pegatron.corp-partner.google.com>
-Kane Chen <kane.chen@intel.com> <kane.chen@intel.corp-partner.google.com>
-Kane Chen <kane.chen@intel.com> Kane Chenffd <kane_chen@pegatron.corp-partner.google.com>
-Kane Chen <kane.chen@intel.com> kane_chen <kane_chen@pegatron.corp-partner.google.com>
-Kane Chen <kane.chen@intel.com> YanRu Chen <kane_chen@pegatron.corp-partner.google.com>
-Kane Chen <kane.chen@intel.com> YenLu Chen <kane_chen@pegatron.corp-partner.google.com>
-Karthikeyan Ramasubramanian <kramasub@google.com> <kramasub@chromium.org>
-Katie Roberts-Hoffman <katierh@chromium.org>  <katierh@google.com>
-Kerry She <kerry.she@amd.com> <Kerry.she@amd.com>
-Kerry Sheh <shekairui@gmail.com>
-Kevin Chang <kevin.chang@lcfc.corp-partner.google.com>
-Kevin Chiu <kevin.chiu.17802@gmail.com> <kevin.chiu@quanta.corp-partner.google.com>
-Kevin Chiu <kevin.chiu.17802@gmail.com> <kevin.chiu@quantatw.com>
-Kevin Chiu <kevin.chiu.17802@gmail.com> <Kevin.Chiu@quantatw.com>
-Kevin Paul Herbert <kph@platinasystems.com> <kevin@trippers.org>
-Kevin Paul Herbert <kph@platinasystems.com> <kph@meraki.net>
-Kirk Wang <kirk_wang@pegatron.corp-partner.google.com> kirk_wang <kirk_wang@pegatron.corp-partner.google.com>
-Konstantin Aladyshev <aladyshev22@gmail.com> <aladyshev@nicevt.ru>
-Kyösti Mälkki <kyosti.malkki@gmail.com>
-Kyösti Mälkki <kyosti.malkki@gmail.com> <kyosti.malkki@3mdeb.com>
-Lean Sheng Tan <sheng.tan@9elements.com> <lean.sheng.tan@intel.com>
-Lee Leahy <lpleahyjr@gmail.com> <leroy.p.leahy@intel.com>
-Li Cheng Sooi <li.cheng.sooi@intel.com>
-Lijian Zhao <lijian.zhao@intel.com>
-Lin Huang <hl@rock-chips.com>
-Maciej Matuszczyk <maccraft123mc@gmail.com>
-Maggie Li <maggie.li@amd.com> <Maggie.li@amd.com>
-Manideep Kurumella <mkurumel@qualcomm.corp-partner.google.com> <mkurumel@codeaurora.org>
-Marc Jones <marc@marcjonesconsulting.com> <marc.jones@amd.com>
-Marc Jones <marc@marcjonesconsulting.com> <marc.jones@gmail.com>
-Marc Jones <marc@marcjonesconsulting.com> <marc.jones@scarletltd.com>
-Marc Jones <marc@marcjonesconsulting.com> <marc.jones@se-eng.com>
-Marc Jones <marc@marcjonesconsulting.com> <marcj.jones@amd.com>
-Marc Jones <marc@marcjonesconsulting.com> <marcj303@gmail.com>
-Marc Jones <marc@marcjonesconsulting.com> <marcj303@yahoo.com>
-Marc Jones <marc@marcjonesconsulting.com> <marcjones@sysproconsulting.com>
-Marc Jones <marc@marcjonesconsulting.com> Marc Jones (marc.jones <Marc Jones (marc.jones@amd.com)>
-Marc Jones <marc@marcjonesconsulting.com> Marc Jones(marc.jones <Marc Jones(marc.jones@amd.com)>
-Marcello Sylvester Bauer <sylv@sylv.io>
-Marcello Sylvester Bauer <sylv@sylv.io> <info@marcellobauer.com>
-Marcello Sylvester Bauer <sylv@sylv.io> <sylvblck@sylv.io>
-Marco Chen <marcochen@google.com> <marcochen@chromium.org>
-Mariusz Szafrański <mariuszx.szafranski@intel.com> Mariusz Szafranski <mariuszx.szafranski@intel.com>
-Marshall Dawson <marshalldawson3rd@gmail.com> <marshall.dawson@amd.corp-partner.google.com>
-Marshall Dawson <marshalldawson3rd@gmail.com> <marshall.dawson@scarletltd.com>
-Mart Raudsepp <leio@gentoo.org> <mart.raudsepp@artecdesign.ee>
-Martin Kepplinger <martink@posteo.de> <martin.kepplinger@puri.sm>
-Martin Roth <gaumless@gmail.com> <martin.roth@se-eng.com>
-Martin Roth <gaumless@gmail.com> <martin@coreboot.org>
-Martin Roth <gaumless@gmail.com> <martinr@coreboot.org>
-Martin Roth <gaumless@gmail.com> <martinroth@chromium.org>
-Martin Roth <gaumless@gmail.com> <martinroth@google.com>
-Martin Roth <gaumless@gmail.com> Martin Roth <martin@se-eng.com>
-Marx Wang <marx.wang@intel.com>
-Mathias Krause <minipli@googlemail.com> <mathias.krause@secunet.com>
-Mathias Krause <minipli@googlemail.com> <Mathias.Krause@secunet.com>
-Mats Erik Andersson <mats.andersson@gisladisker.org> <mats.andersson@gisladisker.se>
-Matt DeVillier <matt.devillier@gmail.com> <matt.devillier@puri.sm>
-Matt Papageorge <matthewpapa07@gmail.com> <matt.papageorge@amd.corp-partner.google.com>
-Matt Ziegelbaum <ziegs@google.com> <ziegs@chromium.org>
-Maulik V Vaghela <maulik.v.vaghela@intel.com>
-Maulik V Vaghela <maulik.v.vaghela@intel.com> <maulik.v.vaghela@intel.corp-partner.google.com>
-Max Blau <tripleshiftone@gmail.com> Bluemax <1403092+BlueMax@users.noreply.github.com>
-Maxim Polyakov <max.senia.poliak@gmail.com> <m.poliakov@yahoo.com>
-Mengqi Zhang <Mengqi.Zhang@mediatek.com> mengqi.zhang <mengqi.zhang@mediatek.com>
-Michael Niewöhner <foss@mniewoehner.de> <michael.niewoehner@8com.de>
-Michael Xie <Michael.Xie@amd.com> <Michael Xie Michael.Xie@amd.com>
-Michele Guerini Rocco <rnhmjoj@inventati.org>
-Mike Banon <mikebdp2@gmail.com> <mike.banon@3mdeb.com>
-Mike Hsieh <Mike_Hsieh@wistron.com> <mike_hsieh@wistron.corp-partner.google.com>
-Mike Loptien <loptienm@gmail.com> <mike.loptien@se-eng.com>
-Mondrian Nuessle <nuessle@uni-hd.de>
-Mondrian Nuessle <nuessle@uni-hd.de> <nuessle@uni-mannheim.de>
-Motiejus Jakštys <desired.mta@gmail.com>
-Myles Watson <mylesgw@gmail.com>  <myles@pel.cs.byu.edu>
-Nancy Lin <nancy.lin@mediatek.com>
-Naresh Solanki <naresh.solanki@intel.com>
-Naresh Solanki <naresh.solanki@intel.com> <Naresh.Solanki@intel.com>
-Naveen Manohar <naveen.m@intel.com>
-Naveen Manohar <naveen.m@intel.com>
-Neil Chen <neilc@nvidia.com> <neilc%nvidia.com@gtempaccount.com>
-Nick Chen <nick_xr_chen@wistron.corp-partner.google.com>
-Nick Vaccaro <nvaccaro@google.com> <nvaccaro@chromium.org>
-Nicky Sielicki <nlsielicki@wisc.edu>
-Nico Huber <nico.h@gmx.de> <nico.huber@secunet.com>
-Nicolas Boichat <drinkcat@chromium.org> <drinkcat@google.com>
-Nicolas Reinecke <nr@das-labor.org>
-Nils Jacobs <njacobs8@adsltotaal.nl> <njacobs8@hetnet.nl>
-Nina Wu <nina-cm.wu@mediatek.com> <nina-cm.wu@mediatek.corp-partner.google.com>
-Oskar Enoksson <enok@lysator.liu.se>
-Oskar Enoksson <enok@lysator.liu.se> <oskeno@foi.se>
-Pablo Moyano <42.pablo.ms@gmail.com> p4block <p4block@users.noreply.github.com>
-Patrick Georgi <patrick@coreboot.org> <Patrick Georgi patrick.georgi@coresystems.de>
-Patrick Georgi <patrick@coreboot.org> <Patrick Georgi patrick@georgi-clan.de>
-Patrick Georgi <patrick@coreboot.org> <patrick.georgi@coresystems.de>
-Patrick Georgi <patrick@coreboot.org> <patrick.georgi@secunet.com>
-Patrick Georgi <patrick@coreboot.org> <Patrick.Georgi@secunet.com>
-Patrick Georgi <patrick@coreboot.org> <patrick@georgi-clan.de>
-Patrick Georgi <patrick@coreboot.org> <patrick@georgi.software>
-Patrick Georgi <patrick@coreboot.org> Patrick Georgi <pgeorgi@chromium.org>
-Patrick Georgi <patrick@coreboot.org> Patrick Georgi <pgeorgi@google.com>
-Patrick Rudolph  <siro@das-labor.org> <patrick.rudolph@9elements.com>
-Paul Fagerburg <pfagerburg@chromium.org> <pfagerburg@google.com>
-Paul Kocialkowski <contact@paulk.fr>
-Paul Ma <magf@bitland.com.cn> <magf@bitland.corp-partner.google.com>
-Paul Ma <magf@bitland.com.cn> Magf - <magf@bitland.corp-partner.google.com>
-Paul Menzel <pmenzel@molgen.mpg.de> <paulepanter@mailbox.org>
-Paul Menzel <pmenzel@molgen.mpg.de> <paulepanter@users.sourceforge.net>
-Peichao Wang <peichao.wang@bitland.corp-partner.google.com>
-Peichao Wang <peichao.wang@bitland.corp-partner.google.com>
-Philip Chen <philipchen@google.com>
-Philip Chen <philipchen@google.com> <philipchen@chromium.org>
-Philipp Deppenwiese <zaolin.daisuki@gmail.com>
-Philipp Deppenwiese <zaolin.daisuki@gmail.com> <philipp.deppenwiese@9elements.com>
-Philipp Deppenwiese <zaolin.daisuki@gmail.com> <zaolin@das-labor.org>
-Ping-chung Chen <ping-chung.chen@intel.com>
-Ping-chung Chen <ping-chung.chen@intel.com>
-Piotr Kleinschmidt <piotr.kleinschmidt@3mdeb.com> <piotr.kleins@gmail.com>
-Piotr Szymaniak <szarpaj@grubelek.pl>
-Po Xu <jg_poxu@mediatek.com>
-Po Xu <jg_poxu@mediatek.com> <jg_poxu@mediatek.corp-partner.google.com>
-Praveen Hodagatta Pranesh <praveenx.hodagatta.pranesh@intel.com>
-Preetham Chandrian <preetham.chandrian@intel.com>
-Puthikorn Voravootivat <puthik@chromium.org> <puthik@google.com>
-QingPei Wang <wangqingpei@gmail.com>
-Quan Tran <qeed.quan@gmail.com>
-Rasheed Hsueh <rasheed.hsueh@lcfc.corp-partner.google.com>
-Raul Rangel <rrangel@chromium.org>
-Ravi Kumar Bokka <rbokka@codeaurora.org>
-Ravindra <ravindra@intel.com>
-Ravindra <ravindra@intel.com> Ravindra N <ravindra@intel.corp-partner.google.com>
-Ravishankar Sarawadi <ravishankar.sarawadi@intel.com>
-Raymond Chung <raymondchung@ami.corp-partner.google.com>
-Raymond Danks <raymonddanks@gmail.com> <ray.danks@se-eng.com>
-Reka Norman <rekanorman@google.com> <rekanorman@chromium.org>
-Ren Kuo <ren.kuo@quantatw.com>
-Ren Kuo <ren.kuo@quantatw.com> <ren.kuo@quanta.corp-partner.google.com>
-Rex-BC Chen <rex-bc.chen@mediatek.com> <rex-bc.chen@mediatek.corp-partner.google.com>
-Ricardo Ribalda <ribalda@chromium.org> <ricardo.ribalda@gmail.com>
-Richard Spiegel <richard.spiegel@silverbackltd.com> <richard.spiegel@amd.corp-partner.google.com>
-Rishavnath Satapathy <rishavnath.satapathy@intel.com>
-Ritul Guru <ritul.bits@gmail.com>
-Rizwan Qureshi <rizwan.qureshi@intel.com> <rizwan.qureshi@intel.corp-partner.google.com>
-Robbie Zhang <robbie.zhang@intel.com>
-Robert Chen <robert.chen@quanta.corp-partner.google.com>
-Robert Chen <robert.chen@quanta.corp-partner.google.com> = <robert.chen@quanta.corp-partner.google.com>
-Roger Pau Monne <roger.pau@citrix.com>
-Roman Kononov <kononov@dls.net> <kononov195-lbl@yahoo.com>
-Ron Minnich <rminnich@gmail.com>
-Ron Minnich <rminnich@gmail.com> <Ron Minnich>
-Ron Minnich <rminnich@gmail.com> <Ronald G. Minnich rminnich@gmail.com>
-Ron Minnich <rminnich@gmail.com> Ronald G. Minnich <minnich@google.com>
-Ron Minnich <rminnich@gmail.com> Ronald G. Minnich <rminnich@chromium.org>
-Ron Minnich <rminnich@gmail.com> Ronald G. Minnich <rminnich@google.com>
-Ron Minnich <rminnich@gmail.com> Ronald G. Minnich <rminnich@lanl.gov>
-Ron Minnich <rminnich@gmail.com> ronald g. minnich <ronald g. minnich>
-Ron Minnich <rminnich@gmail.com> Ronald G. Minnich <Ronald G. Minnich>
-Ronak Kanabar <ronak.kanabar@intel.com>
-Rudolf Marek <r.marek@assembler.cz> <r.marek@asssembler.cz>
-Ryan Chuang <ryan.chuang@mediatek.com> <ryan.chuang@mediatek.corp-partner.google.com>
-Santhosh Janardhana Hassan <sahassan@google.com>
-Scott Chao <scott_chao@wistron.corp-partner.google.com> <scott.chao@bitland.corp-partner.google.com>
-Scott Duplichan <scott@notabs.org> <sc...@notabs.org>
-Scott Tsai <AT>
-Sebastian "Swift Geek" Grzywna <swiftgeek@gmail.com>
-Selma Bensaid <selma.bensaid@intel.com>
-Seunghwan Kim <sh_.kim@samsung.com>
-Seunghwan Kim <sh_.kim@samsung.com> <sh_.kim@samsung.corp-partner.google.com>
-Seunghwan Kim <sh_.kim@samsung.com> sh.kim <sh_.kim@samsung.corp-partner.google.com>
-Shawn Chang <citypw@gmail.com>
-Shawn Nematbakhsh <shawnn@google.com> <shawnn@chromium.org>
-Shelley Chen <shchen@google.com> <shchen@chromium.org>
-Sheng-Liang Pan <Sheng-Liang.Pan@quantatw.com> <sheng-liang.pan@quanta.corp-partner.google.com>
-Shreesh Chhabbi <shreesh.chhabbi@intel.com> <shreesh.chhabbi@intel.corp-partner.google.com>
-Shunqian Zheng <zhengsq@rock-chips.com>
-Siyuan Wang <wangsiyuanbuaa@gmail.com>
-Sowmya <v.sowmya@intel.com>
-Sridhar Siricilla <sridhar.siricilla@intel.com>
-Sridhar Siricilla <sridhar.siricilla@intel.com> <sridhar.siricilla@intel.corp-partner.google.com>
-Srinidhi Kaushik <srinidhi.n.kaushik@intel.com>
-Stanley Wu <stanley1.wu@lcfc.corp-partner.google.com>
-Stefan Ott <stefan@ott.net> <coreboot@desire.ch>
-Stefan Reinauer <stepan@coreboot.org> <reinauer@chromium.org>
-Stefan Reinauer <stepan@coreboot.org> <reinauer@google.com>
-Stefan Reinauer <stepan@coreboot.org> <Stefan Reinauerstepan@coresystems.de>
-Stefan Reinauer <stepan@coreboot.org> <stefan.reinauer@coreboot.org>
-Stefan Reinauer <stepan@coreboot.org> <stepan@coresystems.de>
-Stefan Reinauer <stepan@coreboot.org> <stepan@openbios.org>
-Stephan Guilloux <stephan.guilloux@free.fr> <mailto:stephan.guilloux@free.fr>
-Subrata Banik <subratabanik@google.com> <subi.banik@gmail.com>
-Subrata Banik <subratabanik@google.com> <subrata.banik@intel.com>
-Subrata Banik <subratabanik@google.com> <subrata.banik@intel.com>
-Sudheer Kumar Amrabadi <samrab@codeaurora.org>
-Sumeet Pawnikar <sumeet.r.pawnikar@intel.com>
-Sunwei Li <lisunwei@huaqin.corp-partner.google.com>
-Susendra Selvaraj <susendra.selvaraj@intel.com>
-Sylvain "ythier" Hitier <sylvain.hitier@gmail.com>
-T Michael Turney <mturney@codeaurora.org> mturney mturney <quic_mturney@quicinc.com>
-T Michael Turney <mturney@codeaurora.org> T Michael Turney <quic_mturney@quicinc.com>
-T.H. Lin <T.H_Lin@quantatw.com> <t.h_lin@quanta.corp-partner.google.com>
-T.H. Lin <T.H_Lin@quantatw.com> T.H.Lin <T.H_Lin@quantatw.com>
-Taniya Das <quic_tdas@quicinc.com> <tdas@codeaurora.org>
-Tao Xia <xiatao5@huaqin.corp-partner.google.com>
-Thejaswani Putta  <thejaswani.putta@intel.com> <thejaswani.putta@intel.corp-partner.google.com>
-Thejaswani Putta <thejaswani.putta@intel.com>
-Thejaswani Putta <thejaswani.putta@intel.com> Thejaswani Puta thejaswani.putta@intel.com <thejaswani.putta@intel.com>
-Thomas Heijligen <thomas.heijligen@secunet.com> <src@posteo.de>
-Tim Chen <Tim-Chen@quantatw.com> <tim-chen@quanta.corp-partner.google.com>
-Tim Chu <Tim.Chu@quantatw.com>
-Tim Wawrzynczak <twawrzynczak@chromium.org> <twawrzynczak@google.com>
-Timothy Pearson <tpearson@raptorengineering.com> <tpearson@raptorengineeringinc.com>
-Tinghan Shen <tinghan.shen@mediatek.com>
-Tobias Diedrich <ranma+coreboot@tdiedrich.de> <ranma+openocd@tdiedrich.de>
-Tracy Wu <tracy.wu@intel.com> <tracy.wu@intel.corp-partner.google.com>
-Tristan Corrick <tristan@corrick.kiwi> <tristancorrick86@gmail.com>
-Tyler Wang <tyler.wang@quanta.corp-partner.google.com> <Tyler.Wang@quanta.corp-partner.google.com>
-Usha P <usha.p@intel.com> <usha.p@intel.corp-partner.google.com>
-V Sujith Kumar Reddy <vsujithk@codeaurora.org>
-Vadim Bendebury <vbendeb@chromium.org> <vbendeb@google.com>
-Vaibhav Shankar <vaibhav.shankar@intel.com>
-Van Chen <van_chen@compal.corp-partner.google.com>
-Varshit Pandya <varshit.b.pandya@intel.com>
-Varshit Pandya <varshit.b.pandya@intel.com> Varshit B Pandya <varshit.b.pandya@intel.com>
-Varun Joshi <varun.joshi@intel.com> <varun.joshi@intel.corp-partner.google.com>
-Vincent Lim <vincent.lim@amd.com>  <Vincent Lim vincent.lim@amd.com>
-Vladimir Serbinenko <phcoder@gmail.com>
-Wayne3 Wang <wayne3_wang@pegatron.corp-partner.google.com> <Wayne3_Wang@pegatron.corp-partner.google.com>
-William Wu <wulf@rock-chips.com>
-Wim Vervoorn <wvervoorn@eltan.com>
-Wisley Chen <wisley.chen@quantatw.com>
-Wisley Chen <wisley.chen@quantatw.com> <wisley.chen@quanta.corp-partner.google.com>
-Xi Chen <xixi.chen@mediatek.com> <xixi.chen@mediatek.corp-partner.google.com>
-Xiang Wang <merle@hardenedlinux.org> <wxjstz@126.com>
-Xingyu Wu <wuxy@bitland.corp-partner.google.com>
-Xuxin Xiong <xuxinxiong@huaqin.corp-partner.google.com>
-Yang A Fang <yang.a.fang@intel.com>
-Yinghai Lu <yinghailu@gmail.com> <yinghai.lu at amd.com>
-Yinghai Lu <yinghailu@gmail.com> <yinghai.lu@amd.com>
-Yinghai Lu <yinghailu@gmail.com> <yinghai@kernel.org>
-Yongkun Yu <yuyongkun@huaqin.corp-partner.google.com>
-Yongqiang Niu <yongqiang.niu@mediatek.com>
-Youness Alaoui <snifikino@gmail.com> <kakaroto@kakaroto.homelinux.net>
-Youness Alaoui <snifikino@gmail.com> <youness.alaoui@puri.sm>
-Yu-Hsuan Hsu <yuhsuan@google.com>
-Yu-Hsuan Hsu <yuhsuan@google.com> <yuhsuan@chromium.org>
-Yu-Ping Wu <yupingso@google.com> <yupingso@chromium.org>
-Yuanlidingm <yuanliding@huaqin.corp-partner.google.com>
-Yuchen Huang <yuchen.huang@mediatek.com> <yuchen.huang@mediatek.corp-partner.google.com>
-Yuji Sasaki <sasakiy@chromium.org> <sasakiy@google.com>
-Zanxi Chen <chenzanxi@huaqin.corp-partner.google.com>
-Zhi Li <lizhi7@huaqin.corp-partner.google.com>
-Zhongze Hu <frankhu@chromium.org> <frankhu@google.com>
-Zhuo-Hao Lee <zhuo-hao.lee@intel.com>
-Zhuohao Lee <zhuohao@chromium.org> <zhuohao@google.com>

AUTHORS

@@ -108,7 +108,6 @@ Jonas 'Sortie' Termansen
 Jonathan A. Kollasch
 Jonathan Neuschäfer
 Jordan Crouse
-Jörg Mische
 Joseph Smith
 Keith Hui
 Keith Packard

Documentation/.gitignore

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

Documentation/.mdl_style.rb

@@ -1,9 +0,0 @@
-# See one of the following URLs for explanations of all the rules
-# https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
-# https://web.archive.org/web/20220424164542/https://github.com/markdownlint/markdownlint/blob/master/docs/RULES.md
-
-all
-exclude_rule 'no-multiple-blanks'
-exclude_rule 'blanks-around-headers'
-exclude_rule 'blanks-around-lists'
-rule 'line-length', :line_length => 72

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_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,730 @@
+<!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>
+    </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/acpi/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_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,128 @@
+<!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>
+</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/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/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/acpi/devicetree.md

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

Documentation/acpi/gpio.md

@@ -84,6 +84,15 @@ 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 +159,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

@@ -10,3 +10,7 @@ upwards.
 ## GPIO
 
 - [GPIO toggling in ACPI AML](gpio.md)
+
+## devicetree
+
+- [Adding devices to a device tree](devicetree.md)

Documentation/arch/x86/index.md

@@ -5,28 +5,27 @@ 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.
-The `emulation/qemu-i440fx` and `emulation/qemu-q35` boards do support
-*ARCH_RAMSTAGE_X86_64* , *ARCH_POSTCAR_X86_64* and *ARCH_ROMSTAGE_X86_64*.
+At the moment there's no single board that supports x86_64 or to be exact
+`ARCH_RAMSTAGE_X86_64` and `ARCH_ROMSTAGE_X86_64`.
 
-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 all stages using the reference implementation
 * 0-4GiB are identity mapped using 2MiB-pages as WB
 * Memory above 4GiB isn't accessible
 * page tables reside in memory mapped ROM
 * A stage can install new page tables in RAM
 
 ## Page tables
-A `pagetables` cbfs file is generated based on an assembly file.
+Page tables are generated by a tool in `util/pgtblgen/pgtblgen`. It writes
+the page tables to a file which is then included into the CBFS as file called
+`pagetables`.
 
 To generate the static page tables it must know the physical address where to
 place the file.
@@ -38,16 +37,18 @@ The page tables contains the following structure:
 
 At the moment *$n* is 4, which results in identity mapping the lower 4 GiB.
 
-## 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
+## Steps to add basic support for x86_64
+* Add x86_64 toolchain support - *DONE*
+* Fix compilation errors - *DONE*
+* Fix linker errors - *TODO*
+* Add x86_64 rmodule support - *DONE*
+* Add x86_64 exception handlers - *DONE*
+* Setup page tables for long mode - *DONE*
+* Add assembly code for long mode - *DONE*
+* Add assembly code for SMM - *DONE*
+* Add assembly code for postcar stage - *TODO*
+* Add assembly code to return to protected mode - *TODO*
+* Implement reference code for mainboard `emulation/qemu-q35` - *TODO*
 
 ## Future work
 
@@ -63,33 +64,3 @@ The reference implementation is
 * 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/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](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/process/4.Coding.rst)
+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
-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.
+Please at least consider the points made here.
 
-Any style questions that are not mentioned in here should be decided
-between the author and reviewers on a case-by-case basis. When modifying
-existing files, authors should try to match the prevalent style in that
-file -- otherwise, they should try to match similar existing files in
-coreboot.
+First off, I'd suggest printing out a copy of the GNU coding standards,
+and NOT read it. Burn them, it's a great symbolic gesture.
 
-Bulk style changes to existing code ("cleanup patches") should avoid
-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.)
+Anyway, here goes:
 
 ## Indentation
 
@@ -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
-always use the `#include <file.h>` notation, except for rare cases where a file
-in the same directory that is not part of a normal include path gets included
-(e.g. local headers in mainboard directories), which should use `#include
-"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
+The header file include/linux/kernel.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
 --------------------------------
 
@@ -960,55 +915,17 @@ asm ("magic %reg1, #42nt"
 	: /* outputs */ : /* inputs */ : /* clobbers */);
 ```
 
-GCC extensions
---------------
-
-GCC is the only officially-supported compiler for coreboot, and a
-variety of its C language extensions are heavily used throughout the
-code base. There have been occasional attempts to add clang as a second
-compiler option, which is generally compatible to the same language
-extensions that have been long-established by GCC.
-
-Some GCC extensions (e.g. inline assembly) are basically required for
-proper firmware development. Others enable more safe or flexible
-coding patterns than can be expressed with standard C (e.g. statement
-expressions and `typeof()` to avoid double evaluation in macros like
-`MAX()`). Yet others just add some simple convenience and reduce
-boilerplate (e.g. `void *` arithmetic).
-
-Since some GCC extensions are necessary either way, there is no gain
-from avoiding other GCC extensions elsewhere. The use of all official
-GCC extensions is expressly allowed within coreboot. In cases where an
-extension can be replaced by a 100% equivalent C standard feature with
-no extra boilerplate or loss of readability, the C standard feature
-should be preferred (this usually only happens when GCC retains an
-older pre-standardization extension for backwards compatibility, e.g.
-the old pre-C99 syntax for designated initializers). But if there is
-any advantage offered by the GCC extension (e.g. using GCC zero-length
-arrays instead of C99 variable-length arrays because they don't inhibit
-`sizeof()`), there is no reason to deprive ourselves of that, and "this
-is not C standard compliant" should not be a reason to argue against
-its use in reviews.
-
-This rule only applies to explicit GCC extensions listed in the
-"Extensions to the C Language Family" section of the GCC manual. Code
-should never rely on incidental GCC translation behavior that is not
-explicitly documented as a feature and could change at any moment.
-
 References
 ----------
 
 The C Programming Language, Second Edition by Brian W. Kernighan and
 Dennis M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8
 (paperback), 0-13-110370-9 (hardback). URL:
-<https://duckduckgo.com/?q=isbn+0-13-110362-8> or
-<https://www.google.com/search?q=isbn+0-13-110362-8>
-
+<http://cm.bell-labs.com/cm/cs/cbook/>
 
 The Practice of Programming by Brian W. Kernighan and Rob Pike.
 Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. URL:
-<https://duckduckgo.com/?q=ISBN+0-201-61586-X> or
-<https://www.google.com/search?q=ISBN+0-201-61586-X>
+<http://cm.bell-labs.com/cm/cs/tpop/>
 
 GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
 gcc internals and indent, all available from

Documentation/community/code_of_conduct.md

@@ -115,4 +115,4 @@ Our arbitration team consists of the following people
 This Code of Conduct is distributed under
 a [Creative Commons Attribution-ShareAlike
 license](http://creativecommons.org/licenses/by-sa/3.0/).  It is based
-on the [Citizen Code of Conduct](https://web.archive.org/web/20200330154000/http://citizencodeofconduct.org/)
+on the [Citizen Code of Conduct](http://citizencodeofconduct.org/)

Documentation/community/conferences.md

@@ -14,7 +14,7 @@ their development kit with them and conduct development sessions.
 
 [Open Source Firmware at Facebook](https://fosdem.org/2019/schedule/event/open_source_firmware_at_facebook/)  by [David Hendricks](https://github.com/dhendrix) and [Andrea Barberio](https://github.com/insomniacslk) at [FOSDEM 2019](https://fosdem.org/2019/) ([video](https://video.fosdem.org/2019/K.4.401/open_source_firmware_at_facebook.mp4)) ([slides](https://insomniac.slackware.it/static/2019_fosdem_linuxboot_at_facebook.pdf)) (2019-02-03)
 
-[Open Source Firmware - A love story](https://www.youtube.com/watch?v=xfqKm190dbU) by [Philipp Deppenwiese](https://cybersecurity.9elements.com) at [35c3](https://web.archive.org/web/20211027210118/https://events.ccc.de/congress/2018/wiki/index.php/Main_Page)
+[Open Source Firmware - A love story](https://www.youtube.com/watch?v=xfqKm190dbU) by [Philipp Deppenwiese](https://cybersecurity.9elements.com) at [35c3](https://events.ccc.de/congress/2018)
 ([slides](https://cdn.media.ccc.de/congress/2018/slides-h264-hd/35c3-9778-deu-eng-Open_Source_Firmware_hd-slides.mp4)) (2018-12-27)
 
 [coreboot mainboard porting with Intel FSP 2.0](https://www.youtube.com/watch?v=qUgo-AVsSCI) by Subrata Banik at OSFC 2018

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),
-also bridged to [Matrix](https://matrix.to/#/#coreboot:libera.chat) and a
-[Discord](https://discord.gg/JqT8NM5Zbg) presence. You can also find us on
-[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/pyt-newq-rbb),
-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.
+We also have a
+[real time chat](https://webchat.freenode.net?channels=%23coreboot)
+on the Freenode IRC network's #coreboot channel.

Documentation/community/index.md

@@ -1,6 +0,0 @@
-# Community
-
-* [Code of Conduct](code_of_conduct.md)
-* [Language style](language_style.md)
-* [Community forums](forums.md)
-* [coreboot at conferences](conferences.md)

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

@@ -0,0 +1,45 @@
+# 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

@@ -48,7 +48,7 @@ try:
 except ImportError:
     print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
 else:
-    extensions += ['sphinxcontrib.ditaa']
+    extensions += 'sphinxcontrib.ditaa'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -185,7 +185,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)

Documentation/contributing/gsoc.md

@@ -1,275 +0,0 @@
-# Google Summer of Code
-
-
-## Contacts
-
-If you are interested in participating in GSoC as a contributor or mentor,
-please have a look at our [community forums] and reach out to us. Working closely
-with the community is highly encouraged, as we've seen that our most successful
-contributors are generally very involved.
-
-Felix Singer, David Hendricks and Martin Roth are the coreboot GSoC admins for
-2022. Please feel free to reach out to them directly if you have any questions.
-
-
-## Why work on coreboot for GSoC?
-
-  * coreboot offers you the opportunity to work with various architectures
-    right on the iron. coreboot supports both current and older silicon for a
-    wide variety of chips and technologies.
-
-  * coreboot has a worldwide developer and user base.
-
-  * We are a very passionate team, so you will interact directly with the
-    project initiators and project leaders.
-
-  * We have a large, helpful community. coreboot has some extremely talented
-    and helpful experts in firmware involved in the project. They are ready to
-    assist and mentor contributors participating in GSoC.
-
-  * One of the last areas where open source software is not common is firmware.
-    Running proprietary firmware can have severe effects on user's freedom and
-    security. coreboot has a mission to change that by providing a common
-    framework for initial hardware initialization and you can help us succeed.
-
-
-## Collection of official GSoC guides & documents
-
-  * [Timeline][GSoC Timeline]
-
-  * [Roles and Responsibilities][GSoC Roles and Responsibilities]
-
-  * [Contributor Guide][GSoC Contributor Guide]
-
-  * [Contributor Advice][GSoC Contributor Advice]
-
-  * [Mentor Guide][GSoC Mentor Guide]
-
-  * [FAQ][GSoC FAQ]
-
-  * [Rules][GSoC Rules]
-
-  * [Glossary][GSoC Glossary]
-
-
-## Contributor requirements & commitments
-
-Google Summer of Code is a significant time commitment for you. Medium-sized
-projects are estimated to take 175 hours, while large-sized projects are
-estimated to take 350 hours. Depending on the project size, this means we
-expect you to work roughly half-time or full-time on your project during the
-three months of coding. We expect to be able to see this level of effort in the
-results.
-
-The standard program duration is 12 weeks and in consultation with the mentor
-it can be extended up to 22 weeks. Please keep in mind that the actual number
-of hours you spend on the project highly depends on your skills and previous
-experience.
-
-Make sure that your schedule (exams, courses, day job) gives you a sufficient
-amount of spare time. If this is not the case, then you should not apply.
-
-
-### Before applying
-
-  * Join the [mailing list] and our other [community forums]. Introduce yourself
-    and mention that you are a prospective GSoC contributor. Ask questions and
-    discuss the project that you are considering. Community involvement is a
-    key component of coreboot development.
-
-  * You accept our [Code of Conduct] and [Language style].
-
-  * Demonstrate that you can work with the coreboot codebase.
-
-    * Look over some of the development processes guidelines: [Getting started],
-      [Tutorial], [Flashing firmware tutorial] and [Coding style].
-
-    * Download, build and boot coreboot in QEMU or on real hardware. Please email
-      your serial output results to the [mailing list].
-
-    * Look through some patches on Gerrit to get an understanding of the review
-      process and common issues.
-
-    * Get signed up for Gerrit and push at least one patch to Gerrit for review.
-      Check the [easy project list][Project ideas] or ask for simple tasks on
-      the [mailing list] or on our other [community forums] if you need ideas.
-
-
-### During the program
-
-  * To pass and to be paid by Google requires that you meet certain milestones.
-
-    * First, you must be in good standing with the community before the official
-      start of the program. We expect you to post some design emails to the
-      [mailing list], and get feedback on them, both before applying, and during
-      the "community bonding period" between acceptance and official start.
-
-    * You must have made progress and committed significant code before the
-      mid-term point and by the final.
-
-    * We require that accepted contributors to maintain a blog, where you are
-      expected to write about your project *WEEKLY*. This is a way to measure
-      progress and for the community at large to be able to help you. GSoC is
-      *NOT* a private contract between your mentor and you.
-
-  * You must be active in the community on IRC and the [mailing list].
-
-  * You are expected to work on development publicly, and to push commits to the
-    project on a regular basis. Depending on the project and what your mentor
-    agrees to, these can be published directly to the project or to a public
-    repository such as Gitlab or Github. If you are not publishing directly to
-    the project codebase, be aware that we do not want large dumps of code that
-    need to be rushed to meet the mid-term and final goals.
-
-We don't expect our contributors to be experts in our problem domain, but we
-don't want you to fail because some basic misunderstanding was in your way of
-completing the task.
-
-
-## Projects
-
-There are many development tasks available in coreboot. We prepared some ideas
-for Summer of Code projects. These are projects that we think can be managed in
-the timeline of GSoC, and they cover areas where coreboot is trying to reach
-new users and new use cases.
-
-Of course your application does not have to be based on any of the ideas listed.
-It is entirely possible that you have a great idea that we just didn't think of
-yet. Please let us know!
-
-The blog posts related to previous GSoC projects might give some insights to
-what it is like to be a coreboot GSoC contributor.
-
-
-## coreboot Summer of Code Application
-
-coreboot welcomes contributors from all backgrounds and levels of experience.
-
-Your application should include a complete project proposal. You should
-document that you have the knowledge and the ability to complete your proposed
-project. This may require a little research and understanding of coreboot prior
-to sending your application. The community and coreboot project mentors are your
-best resource in fleshing out your project ideas and helping with a project
-timeline. We recommend that you get feedback and recommendations on your
-proposal before the application deadline.
-
-Please complete the standard GSoC application and project proposal. Provide the
-following information as part of your application. Make sure to provide multiple
-ways of communicating in case your equipment (such as a laptop) is lost,
-damaged, or stolen, or in case of a natural disaster that disrupts internet
-service. You risk automatically failing if your mentor cannot contact you and if
-you cannot provide updates according to GSoC deadlines.
-
-**Personal Information**
-
-  * Name
-
-  * Email and contact options (IRC, Matrix, …)
-
-  * Phone number (optional, but recommended)
-
-  * Timezone, Usual working hours (UTC)
-
-  * School / University, Degree Program, expected graduation date
-
-  * Short bio / Overview of your background
-
-  * What are your other time commitments? Do you have a job, classes, vacations?
-    When and how long?
-
-**Software experience**
-
-If applicable, please provide the following information:
-
-  * Portfolio, Website, blog, microblog, Github, Gitlab, ...
-
-  * Links to one or more patches submitted
-
-  * Links to posts on the [mailing list] with the serial output of your build.
-
-  * Please comment on your software and firmware experience.
-
-  * Have you contributed to an open source project? Which one? What was your
-    experience?
-
-  * What was your experience while building and running coreboot? Did you have
-    problems?
-
-**Your project**
-
-  * Provide an overview of your project (in your own words).
-
-  * Provide a breakdown of your project in small specific weekly goals. Think
-    about the potential timeline.
-
-  * How will you accomplish this goal? What is your working style?
-
-  * Explain what risks or potential problems your project might experience.
-
-  * What would you expect as a minimum level of success?
-
-  * Do you have a stretch goal?
-
-**Other**
-
-  * Resume (optional)
-
-
-### Advice on how to apply
-
-  * [GSoC Contributor Guide]
-
-  * The Drupal project has a great page on how to write an GSoC application.
-
-  * Secrets for GSoC success: [2]
-
-
-## Mentors
-
-Each accepted project will have at least one mentor. We will match mentors and
-contributors based on the project and experience level. If possible, we also
-will try to match their time zones.
-
-Mentors are expected to stay in frequent contact with the contributor and
-provide guidance such as code reviews, pointers to useful documentation, etc.
-This should generally be a time commitment of several hours per week.
-
-Some projects might have more than one mentor, who can serve as a backup. They
-are expected to coordinate with each other and a contributor on a regular basis,
-and keep track of the contributor process. They should be able to take over
-mentoring duty if one of the mentors is unavailable (vacations, sickness,
-emergencies).
-
-
-### Volunteering to be a mentor
-
-If you'd like to volunteer to be a mentor, please read the [GSoC Mentor Guide].
-This will give you a better idea of expectations, and where to go for help.
-After that, contact Org Admins (see coreboot contacts section above).
-
-The following coreboot developers have volunteered to be GSoC 2022 mentors.
-Please stop by in our community forums and say hi to them and ask them
-questions.
-
-  * Tim Wawrzynczak
-  * Raul Rangel
-  * Ron Minnich
-
-
-[community forums]: ../community/forums.md
-[mailing list]: https://mail.coreboot.org/postorius/lists/coreboot.coreboot.org
-[Getting started]: ../getting_started/index.md
-[Tutorial]: ../tutorial/index.md
-[Flashing firmware tutorial]: ../tutorial/flashing_firmware/index.md
-[Coding style]: coding_style.md
-[Code of Conduct]: ../community/code_of_conduct.md
-[Language style]: ../community/language_style.md
-[Project ideas]: project_ideas.md
-[GSoC Timeline]: https://developers.google.com/open-source/gsoc/timeline
-[GSoC Roles and Responsibilities]: https://developers.google.com/open-source/gsoc/help/responsibilities
-[GSoC Contributor Guide]: https://google.github.io/gsocguides/student
-[GSoC Contributor Advice]: https://developers.google.com/open-source/gsoc/help/student-advice
-[GSoC Mentor Guide]: https://google.github.io/gsocguides/mentor
-[GSoC FAQ]: https://developers.google.com/open-source/gsoc/faq
-[GSoC Rules]: https://summerofcode.withgoogle.com/rules
-[GSoC Glossary]: https://developers.google.com/open-source/gsoc/resources/glossary

Documentation/contributing/index.md

@@ -1,7 +0,0 @@
-# Contributing
-
-* [Coding Style](coding_style.md)
-* [Gerrit Guidelines](gerrit_guidelines.md)
-* [Project Ideas](project_ideas.md)
-* [Documentation Ideas](documentation_ideas.md)
-* [Google Summer of Code](gsoc.md)

Documentation/contributing/project_ideas.md

@@ -20,24 +20,6 @@ doubt if you can bring yourself up to speed in a required time frame
 with the projects. We can then try together to figure out if you're a
 good match for a project, even when requirements might not all be met.
 
-## Easy projects
-
-This is a collection of tasks which don't require deep knowledge on
-coreboot itself. If you are a beginner and want to get familiar with the
-the project and the code base, or if you just want to get your hands
-dirty with some easy tasks, then these are for you.
-
-  * Resolve static analysis issues reported by [scan-build] and
-    [Coverity scan]. More details on the page for
-    [Coverity scan integration].
-
-  * Resolve issues reported by the [linter][Linter issues]
-
-[scan-build]: https://coreboot.org/scan-build/
-[Coverity scan]: https://scan.coverity.com/projects/coreboot
-[Coverity scan integration]: ../infrastructure/coverity.md
-[Linter issues]: https://qa.coreboot.org/job/untested-coreboot-files/lastSuccessfulBuild/artifact/lint.txt
-
 ## Provide toolchain binaries
 Our crossgcc subproject provides a uniform compiler environment for
 working on coreboot and related projects. Sadly, building it takes hours,
@@ -84,10 +66,29 @@ across architectures.
 ### Mentors
 * Timothy Pearson <tpearson@raptorengineering.com>
 
+## 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 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), edk2,
+to one of the platforms, for example GRUB2, U-Boot (the UI part), Tianocore,
 yabits, FILO, or Linux-as-Payload.
 
 Since this is a bit of a catch-all idea, an application to GSoC should pick a
@@ -220,9 +221,9 @@ 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.
+for managment tasks and new board status uploads.
 
-At least one older test result should be kept in the database.
+At least one older test result should be keept in the database.
 
 The frontend should use established UI libraries or frameworks (for example
 Angular) to display the current board status, that is if it's working or not

Documentation/coreboot_logo.svg

@@ -1,40 +0,0 @@
-<?xml version="1.0" encoding="UTF-8" standalone="no"?>
-<svg
-   width="250"
-   height="200"
-   viewBox="0 0 250.00001 200"
-   version="1.1"
-   id="svg4"
-   sodipodi:docname="coreboot_logo.svg"
-   inkscape:version="1.1.2 (0a00cf5339, 2022-02-04)"
-   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
-   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
-   xmlns="http://www.w3.org/2000/svg"
-   xmlns:svg="http://www.w3.org/2000/svg">
-  <defs
-     id="defs8" />
-  <sodipodi:namedview
-     id="namedview6"
-     pagecolor="#ffffff"
-     bordercolor="#666666"
-     borderopacity="1.0"
-     inkscape:pageshadow="2"
-     inkscape:pageopacity="0.0"
-     inkscape:pagecheckerboard="true"
-     showgrid="false"
-     width="250px"
-     height="200px"
-     inkscape:zoom="1.464382"
-     inkscape:cx="-62.825135"
-     inkscape:cy="121.21154"
-     inkscape:window-width="1519"
-     inkscape:window-height="920"
-     inkscape:window-x="209"
-     inkscape:window-y="73"
-     inkscape:window-maximized="0"
-     inkscape:current-layer="svg4" />
-  <path
-     id="path61"
-     d="m 80.661062,0.13961031 c 0,0 8.15178,6.60943399 23.247088,18.58954069 1.05796,0.880056 1.33191,1.294888 1.12373,1.641232 -0.31985,0.543174 -1.75582,-0.08872 -1.75582,-0.08872 -11.664048,-4.438128 -24.834388,-6.953649 -33.759848,-6.376408 -2.95434,0.189259 -3.90102,0.665956 -4.321175,1.508159 -0.19683,0.395552 -0.226549,1.460608 0.765169,2.779745 3.900636,5.157312 13.294036,15.263399 28.921176,24.855056 16.060528,9.852834 44.423978,23.830157 69.508388,34.990773 11.22686,4.992657 19.31714,11.666735 16.74132,19.3658 -2.87674,8.579122 -13.98099,9.747592 -22.85157,6.198982 C 151.07253,100.72135 144.33596,91.685794 133.39489,79.565635 114.43868,58.561649 105.44571,50.180157 73.988942,56.584689 58.21986,59.796417 43.339503,72.701794 31.438885,86.322779 23.497569,96.338376 19.677814,104.66948 18.527118,114.71536 c 0,0 -2.168556,-3.98066 -0.01478,-14.17227 3.764359,-17.803609 -4.428375,-25.450182 -4.428375,-25.450182 -41.49508,58.844472 17.526881,112.045702 63.024789,61.095232 0,0 -14.887006,33.05468 -13.647358,43.34849 -6.349646,2.08185 -9.170023,7.92269 0.332682,14.9707 10.382756,7.69907 35.885136,7.03371 56.001494,-1.61165 37.55849,-16.14193 60.9693,-46.22207 72.57279,-65.32401 2.71019,-4.46651 5.57763,-6.63885 7.56296,-7.34857 3.01112,-1.08635 23.72764,0.16234 33.42717,-5.3451 1.34942,0.65673 3.06678,1.00763 5.33032,0.8354 C 245.71787,115.17969 250,106.76795 250,106.76795 c 0,0 -8.87062,-16.922111 -30.12254,-29.55327 C 199.86141,65.319739 194.02789,69.457093 176.05582,55.128281 147.99814,32.763519 114.02178,7.3201044 80.661062,0.13961031 Z M 102.26692,70.594304 c 13.26505,-0.0029 23.37736,4.660953 25.1286,13.170519 2.97326,14.478329 -27.955978,50.936567 -25.92334,51.521377 0.19683,0.0549 0.6391,-0.16704 1.28637,-0.60991 10.15186,-13.28789 29.37687,-33.69148 36.58765,-32.90227 12.92072,1.41187 17.38079,18.53779 17.38079,18.53779 l -43.07864,38.86837 c 8.89707,2.41684 18.6275,3.29074 28.363,2.54317 -19.24009,13.70237 -40.10745,17.52487 -53.007358,11.85088 20.405928,-14.79629 57.956938,-51.80601 57.956938,-51.80601 0,0 -6.24718,-15.74184 -17.51757,-6.10287 -10.90133,9.32102 -20.97474,20.96607 -24.95486,24.68502 -2.46226,2.29571 -6.636458,6.63454 -9.104398,4.76844 -3.00355,-2.26922 5.935248,-22.37963 12.771298,-39.0458 9.32669,-22.730028 -1.40413,-29.828637 -13.965258,-29.198404 -11.25525,0.565885 -26.629956,7.384774 -37.644841,14.120509 -3.118992,1.909626 -5.249017,3.0833 -6.036334,2.354652 -0.688903,-0.641589 0.03892,-1.850245 2.084808,-3.578182 C 68.148932,76.592284 87.233202,70.597548 102.26692,70.594304 Z"
-     style="stroke-width:1.89259;fill:#ffffff" />
-</svg>

Documentation/distributions.md

@@ -8,24 +8,28 @@ and those providing after-market firmware to extend the usefulness of devices.
 
 ## Hardware shipping with coreboot
 
-### NovaCustom laptops
+### Purism
 
-[NovaCustom](https://configurelaptop.eu/) sells configurable laptops with
-[Dasharo](https://dasharo.com/) coreboot based firmware on board, maintained by
-[3mdeb](https://3mdeb.com/). NovaCustom offers full GNU/Linux and Microsoft
-Windows compatibility. NovaCustom ensures security updates via fwupd for 5 years
-and the firmware is equipped with important security features such as measured
-boot, verified boot, TPM integration and UEFI Secure Boot.
+[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
-functions like battery management, keyboard support, and sensor interfacing –
+running on the Embedded Controller (EC - a small microcontroller which provides
+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
@@ -33,27 +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).
 
-### Star Labs
-
-[Star Labs](https://starlabs.systems/) offers a range of laptops designed and
-built specifically for Linux that are available with coreboot firmware. They
-use edk2 as the payload and include an NVRAM option to disable the Intel
-Management Engine.
-
-### 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
@@ -63,20 +46,11 @@ provides ready-made firmware images for supported devices: those which can be
 built entirely from source code. Their copy of the coreboot repository is
 therefore stripped of all devices that require binary components to boot.
 
-
-### Dasharo
-
-[Dasharo](https://dasharo.com/) is an open-source based firmware distribution
-focusing on clean and simple code, long-term maintenance, transparent
-validation, privacy-respecting implementation, liberty for the owners, and
-trustworthiness for all.
-
-
 ### MrChromebox
 
 [MrChromebox](https://mrchromebox.tech/) provides upstream coreboot firmware
 images for the vast majority of x86-based Chromebooks and Chromeboxes, using
-edk2 as the payload to provide a modern UEFI bootloader. Why replace
+Tianocore as the payload to provide a modern UEFI bootloader. Why replace
 coreboot with coreboot? Mr Chromebox's images are built using upstream
 coreboot (vs Google's older, static tree/branch), include many features and
 fixes not found in the stock firmware, and offer much broader OS compatibility

Documentation/doxygen/Doxyfile.coreboot_platform

@@ -0,0 +1,319 @@
+# Doxyfile 1.8.11
+
+#---------------------------------------------------------------------------
+# Project related configuration options
+#---------------------------------------------------------------------------
+DOXYFILE_ENCODING      = UTF-8
+PROJECT_NAME           = "coreboot for $(DOXYGEN_PLATFORM)"
+PROJECT_NUMBER         =
+PROJECT_BRIEF          = "coreboot is an Open Source project aimed at replacing the proprietary BIOS found in most computers."
+PROJECT_LOGO           = Documentation/coreboot_logo.png
+OUTPUT_DIRECTORY       = $(DOXYGEN_OUTPUT_DIR)
+CREATE_SUBDIRS         = YES
+ALLOW_UNICODE_NAMES    = NO
+OUTPUT_LANGUAGE        = English
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = YES
+ABBREVIATE_BRIEF       =
+ALWAYS_DETAILED_SEC    = YES
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+STRIP_FROM_PATH        =
+STRIP_FROM_INC_PATH    =
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = YES
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+ALIASES                =
+TCL_SUBST              =
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+OPTIMIZE_FOR_FORTRAN   = NO
+OPTIMIZE_OUTPUT_VHDL   = NO
+EXTENSION_MAPPING      =
+MARKDOWN_SUPPORT       = YES
+AUTOLINK_SUPPORT       = YES
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+IDL_PROPERTY_SUPPORT   = YES
+DISTRIBUTE_GROUP_DOC   = NO
+GROUP_NESTED_COMPOUNDS = NO
+SUBGROUPING            = YES
+INLINE_GROUPED_CLASSES = NO
+INLINE_SIMPLE_STRUCTS  = NO
+TYPEDEF_HIDES_STRUCT   = NO
+LOOKUP_CACHE_SIZE      = 0
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = NO
+EXTRACT_PACKAGE        = NO
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = YES
+HIDE_SCOPE_NAMES       = NO
+HIDE_COMPOUND_REFERENCE= NO
+SHOW_INCLUDE_FILES     = YES
+SHOW_GROUPED_MEMB_INC  = NO
+FORCE_LOCAL_INCLUDES   = NO
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_MEMBERS_CTORS_1ST = NO
+SORT_GROUP_NAMES       = NO
+SORT_BY_SCOPE_NAME     = NO
+STRICT_PROTO_MATCHING  = NO
+GENERATE_TODOLIST      = YES
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       =
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_FILES             = YES
+SHOW_NAMESPACES        = YES
+FILE_VERSION_FILTER    =
+LAYOUT_FILE            =
+CITE_BIB_FILES         =
+#---------------------------------------------------------------------------
+# Configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = YES
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+WARN_AS_ERROR          = NO
+WARN_FORMAT            = "$file:$line: $text"
+WARN_LOGFILE           =
+#---------------------------------------------------------------------------
+# Configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT                  = $(DOXYFILES)
+INPUT_ENCODING         = UTF-8
+FILE_PATTERNS          =
+RECURSIVE              = NO
+EXCLUDE                =
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       =
+EXCLUDE_SYMBOLS        =
+EXAMPLE_PATH           =
+EXAMPLE_PATTERNS       =
+EXAMPLE_RECURSIVE      = NO
+IMAGE_PATH             =
+INPUT_FILTER           =
+FILTER_PATTERNS        =
+FILTER_SOURCE_FILES    = NO
+FILTER_SOURCE_PATTERNS =
+USE_MDFILE_AS_MAINPAGE =
+#---------------------------------------------------------------------------
+# Configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = NO
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+SOURCE_TOOLTIPS        = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+CLANG_ASSISTED_PARSING = NO
+CLANG_OPTIONS          =
+#---------------------------------------------------------------------------
+# Configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          =
+#---------------------------------------------------------------------------
+# Configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            =
+HTML_FOOTER            =
+HTML_STYLESHEET        =
+HTML_EXTRA_STYLESHEET  =
+HTML_EXTRA_FILES       =
+HTML_COLORSTYLE_HUE    = 220
+HTML_COLORSTYLE_SAT    = 100
+HTML_COLORSTYLE_GAMMA  = 80
+HTML_TIMESTAMP         = NO
+HTML_DYNAMIC_SECTIONS  = NO
+HTML_INDEX_NUM_ENTRIES = 100
+GENERATE_DOCSET        = NO
+DOCSET_FEEDNAME        = "Doxygen documentation"
+DOCSET_BUNDLE_ID       = org.doxygen.Project
+DOCSET_PUBLISHER_ID    = org.doxygen.Publisher
+DOCSET_PUBLISHER_NAME  = Publisher
+GENERATE_HTMLHELP      = NO
+CHM_FILE               =
+HHC_LOCATION           =
+GENERATE_CHI           = NO
+CHM_INDEX_ENCODING     =
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+GENERATE_QHP           = NO
+QCH_FILE               =
+QHP_NAMESPACE          = org.doxygen.Project
+QHP_VIRTUAL_FOLDER     = doc
+QHP_CUST_FILTER_NAME   =
+QHP_CUST_FILTER_ATTRS  =
+QHP_SECT_FILTER_ATTRS  =
+QHG_LOCATION           =
+GENERATE_ECLIPSEHELP   = NO
+ECLIPSE_DOC_ID         = org.doxygen.Project
+DISABLE_INDEX          = NO
+GENERATE_TREEVIEW      = YES
+ENUM_VALUES_PER_LINE   = 4
+TREEVIEW_WIDTH         = 250
+EXT_LINKS_IN_WINDOW    = NO
+FORMULA_FONTSIZE       = 10
+FORMULA_TRANSPARENT    = YES
+USE_MATHJAX            = NO
+MATHJAX_FORMAT         = HTML-CSS
+MATHJAX_RELPATH        = http://cdn.mathjax.org/mathjax/latest
+MATHJAX_EXTENSIONS     =
+MATHJAX_CODEFILE       =
+SEARCHENGINE           = YES
+SERVER_BASED_SEARCH    = NO
+EXTERNAL_SEARCH        = NO
+SEARCHENGINE_URL       =
+SEARCHDATA_FILE        = searchdata.xml
+EXTERNAL_SEARCH_ID     =
+EXTRA_SEARCH_MAPPINGS  =
+#---------------------------------------------------------------------------
+# Configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = NO
+PAPER_TYPE             = a4wide
+EXTRA_PACKAGES         =
+LATEX_HEADER           =
+LATEX_FOOTER           =
+LATEX_EXTRA_STYLESHEET =
+LATEX_EXTRA_FILES      =
+PDF_HYPERLINKS         = NO
+USE_PDFLATEX           = NO
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+LATEX_SOURCE_CODE      = NO
+LATEX_BIB_STYLE        = plain
+LATEX_TIMESTAMP        = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = NO
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    =
+RTF_EXTENSIONS_FILE    =
+RTF_SOURCE_CODE        = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_SUBDIR             =
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# Configuration options related to the DOCBOOK output
+#---------------------------------------------------------------------------
+GENERATE_DOCBOOK       = NO
+DOCBOOK_OUTPUT         = docbook
+DOCBOOK_PROGRAMLISTING = NO
+#---------------------------------------------------------------------------
+# Configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# Configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX =
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = YES
+EXPAND_ONLY_PREDEF     = YES
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           =
+INCLUDE_FILE_PATTERNS  =
+PREDEFINED             = __attribute__(x)=
+EXPAND_AS_DEFINED      =
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration options related to external references
+#---------------------------------------------------------------------------
+TAGFILES               =
+GENERATE_TAGFILE       =
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+EXTERNAL_PAGES         = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = YES
+MSCGEN_PATH            =
+DIA_PATH               =
+HIDE_UNDOC_RELATIONS   = NO
+HAVE_DOT               = NO
+DOT_NUM_THREADS        = 0
+DOT_FONTNAME           = Helvetica
+DOT_FONTSIZE           = 10
+DOT_FONTPATH           =
+CLASS_GRAPH            = YES
+COLLABORATION_GRAPH    = YES
+GROUP_GRAPHS           = YES
+UML_LOOK               = YES
+UML_LIMIT_NUM_FIELDS   = 10
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = YES
+INCLUDED_BY_GRAPH      = YES
+CALL_GRAPH             = YES
+CALLER_GRAPH           = YES
+GRAPHICAL_HIERARCHY    = YES
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+INTERACTIVE_SVG        = NO
+DOT_PATH               =
+DOTFILE_DIRS           =
+MSCFILE_DIRS           =
+DIAFILE_DIRS           =
+PLANTUML_JAR_PATH      =
+PLANTUML_INCLUDE_PATH  =
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 0
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = YES
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES

Documentation/drivers/cbfs_smbios.md

@@ -1,65 +0,0 @@
-# CBFS SMBIOS hooks
-
-The document describes the coreboot options how to make CBFS files populate
-platform-unique SMBIOS data.
-
-## SMBIOS System UUID
-
-The [DMTF SMBIOS specification] defines a field in the type 1 System
-Information Structure called System UUID. It is a 16 bytes value compliant with
-[RFC4122] and assumed to be unique per platform. Certain mainboard ports have
-SMBIOS hooks to generate the UUID from external data, e.g. Lenovo Thinkpads
-(see DRIVER_LENOVO_SERIALS). This driver aims to provide an option to populate
-the UUID from CBFS for boards that can't generate the UUID from any source.
-
-### Usage
-
-In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers`
-and select an option `System UUID in CBFS`. The Kconfig system will enable
-`DRIVERS_GENERIC_CBFS_UUID` and the relevant code parts will be compiled into
-coreboot image.
-
-After the coreboot build for your board completes, use the cbfstool to include
-the file containing the UUID:
-
-```shell
-./build/cbfstool build/coreboot.rom add -n system_uuid -t raw -f /path/to/uuid_file.txt
-```
-
-Where `uuid_file.txt` is the unterminated string representation of the SMBIOS
-type 1 UUID, e.g. `4c4c4544-0051-3410-8051-b5c04f375931`. If you use vboot with
-1 or 2 RW partitions you will have to specify the RW regions where the file is
-going to be added too. By default the RW CBFS partitions are truncated, so the
-files would probably not fit, one needs to expand them first.
-
-```shell
-./build/cbfstool build/coreboot.rom expand -r FW_MAIN_A
-./build/cbfstool build/coreboot.rom add -n system_uuid -t raw \
-	-f /path/to/uuid_file.txt -r FW_MAIN_A
-./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_A
-
-./build/cbfstool build/coreboot.rom expand -r FW_MAIN_B
-./build/cbfstool build/coreboot.rom add -n system_uuid -t raw \
-	-f /path/to/uuid_file.txt -r FW_MAIN_B
-./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_B
-```
-
-By default cbfstool adds files to COREBOOT region only, so when vboot is
-enabled and the platform is booting from RW partition, the file would not be
-picked up by the driver.
-
-One may retrieve the UUID from running system (if it exists) using the
-following command:
-
-```shell
-echo -n `sudo dmidecode -s system-uuid` > uuid_file.txt
-```
-
-The above command ensures the file does not end with whitespaces like LF and/or
-CR. The above command will not add any whitespaces. But the driver will handle
-situations where up to 2 additional bytes like CR and LF will be included in
-the file. Any more than that will make the driver fail to populate UUID in
-SMBIOS.
-
-[DMTF SMBIOS specification]: https://www.dmtf.org/standards/smbios
-[RFC4122]: https://www.ietf.org/rfc/rfc4122.txt

Documentation/drivers/dptf.md

@@ -43,7 +43,7 @@ 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
+# 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
@@ -69,7 +69,7 @@ data was a 0). The following Methods were removed:
 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
+# 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.
@@ -108,7 +108,7 @@ various informational properties.
 This table describes performance states supported by a participant (typically
 the battery charger).
 
-## ACPI Methods
+# ACPI Methods
 
 The Active and Passive policies also provide for short Methods to define
 different kinds of temperature thresholds.
@@ -141,7 +141,7 @@ a "graceful shutdown".
 
 These are optional, and are enabled by selecting the Critical Policy.
 
-## How to use the devicetree entries
+# How to use the devicetree entries
 
 The `drivers/intel/dptf` chip driver is organized into several sections:
 - Policies
@@ -151,7 +151,7 @@ The `drivers/intel/dptf` chip driver is organized into several sections:
 The Policies section (`policies.active`, `policies.passive`, and
 `policies.critical`) is where the components of each policy are defined.
 
-### Active Policy
+## Active Policy
 
 Each Active Policy is defined in terms of 4 parts:
 1) A Source (this is implicitly defined as TFN1, the system fan)
@@ -182,7 +182,7 @@ the CPU's active cooling capability). When the CPU temperature first crosses
 rest of the table (note that it *must* be defined from highest temperature/
 percentage on down to the lowest).
 
-### Passive Policy
+## Passive Policy
 
 Each Passive Policy is defined in terms of 5 parts:
 1) Source - The device that can be throttled
@@ -201,7 +201,7 @@ 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
+## Critical Policy
 
 Each Critical Policy is defined in terms of 3 parts:
 1) Source - A device that can trigger a critical event
@@ -218,7 +218,7 @@ 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
+## 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
@@ -244,7 +244,7 @@ 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
+## 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
@@ -266,7 +266,7 @@ 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
+## 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
@@ -298,32 +298,16 @@ 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
+## Options
 
-#### Fan
+### 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
+### 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/dt_entries.md

@@ -1,238 +0,0 @@
-# Driver Devicetree Entries
-
-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 "detect" = "1"
-		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``.
-
-### detect
-
-The next register is:
-
-```
-    register "detect" = "1"
-```
-
-This flag tells the I2C driver that it should attempt to detect the presence of
-the device (using an I2C zero-byte write), and only generate a SSDT entry if the
-device is actually present. This alleviates the OS from having to determine if
-a device is present or not (ChromeOS/Linux) and prevents resource conflict/
-driver issues (Windows).
-
-Currently, the detect feature works and is hooked up for all I2C touchpads,
-and should be used any time a board has multiple touchpad options.
-I2C audio devices should also work without issue.
-
-Touchscreens can use this feature as well, but special care is needed to
-implement the proper power sequencing for the device to be detected. Generally,
-this means driving the enable GPIO high and holding the reset GPIO low in early
-GPIO init (bootblock/romstage), then releasing reset in ramstage. While no
-boards in the tree currently implement this, it has been used in downstream
-forks without issue for some time now.
-
-### 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 device driver entries in devicetrees end up in the SSDT table, and are
-   generated in coreboot's ramstage**
-   (The lone exception to this rule is i2c touchpads with the 'detect' flag set;
-    in this case, devices not present will not be added to the SSDT)

Documentation/drivers/index.md

@@ -2,16 +2,8 @@
 
 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.
+they allow to easily reuse existing code accross platforms.
 
-For details on how to connect device drivers to a mainboard, see [Driver Devicetree Entries](dt_entries.md).
-
-Some of the drivers currently available include:
-
-* [Intel DPTF](dptf.md)
 * [IPMI KCS](ipmi_kcs.md)
 * [SMMSTORE](smmstore.md)
-* [SMMSTOREv2](smmstorev2.md)
 * [SoundWire](soundwire.md)
-* [USB4 Retimer](retimer.md)
-* [CBFS SMBIOS hooks](cbfs_smbios.md)

Documentation/drivers/ipmi_kcs.md

@@ -42,15 +42,6 @@ The following registers can be set:
 * `gpe_interrupt`
   * Integer
   * The bit in GPE (SCI) used to notify about a change on the KCS.
-* `wait_for_bmc`
-  * Boolean
-  * Wait for BMC to boot. This can be used if the BMC takes a long time to boot
-    after PoR:
-     - AST2400 on Supermicro X11SSH: 34 s
-* `bmc_boot_timeout`
-  * Integer
-  * The timeout in seconds to wait for the IPMI service to be loaded.
-    Will be used if wait_for_bmc is true.
 
 
 [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/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

@@ -375,7 +375,7 @@ chip and can be decoded for this table with the codec datasheet and board schema
  * @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.
+ * @manufacturer_id: Manufacturer ID from include/device/mipi_ids.h.
  * @part_id: Vendor defined part ID.
  * @class: MIPI class encoding in &enum mipi_class.
  */

Documentation/flash_tutorial/ext_standalone.md

@@ -0,0 +1,23 @@
+# Flashing firmware standalone
+
+If none of the other methods work, there are three possibilities:
+
+## Desolder
+You must remove or desolder the flash IC before you can flash it.
+It's recommended to solder a socket in place of the flash IC.
+
+When flashing the IC, always connect all input pins.
+If in doubt, pull /WP, /HOLD, /RESET and alike up towards Vcc.
+
+## SPI flash emulator
+If you are a developer, you might want to use an [EM100Pro] instead, which sets
+the onboard flash on hold, and allows to run custom firmware.
+It provides a very fast development cycle without actually writing to flash.
+
+## SPI flash overwrite
+It is possible to set the onboard flash on hold and use another flash chip.
+Connect all lines one-to-one, except /HOLD. Pull /HOLD of the soldered flash IC
+low, and /HOLD of your replacement flash IC high.
+
+
+[EM100Pro]: https://www.dediprog.com/product/EM100Pro

Documentation/flash_tutorial/index.md

@@ -0,0 +1,111 @@
+# Flashing firmware tutorial
+
+Updating the firmware is possible using the **internal method**, where the updates
+happen from a running system, or using the **external method**, where the system
+is in a shut down state and an external programmer is attached to write into the
+flash IC.
+
+## Contents
+
+* [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)
+
+## General advice
+
+* It's recommended to only flash the BIOS region.
+* Always verify the firmware image.
+* If you flash externally and have transmission errors:
+  * Use short wires
+  * Reduce clock frequency
+  * Check power supply
+  * Make sure that there are no other bus masters (EC, ME, SoC, ...)
+
+## Internal method
+
+This method using [flashrom] is available on many platforms, as long as they
+aren't locked down.
+
+There are various protection schemes that make it impossible to modify or
+replace a firmware from a running system. coreboot allows to disable these
+mechanisms, making it possible to overwrite (or update) the firmware from a
+running system.
+
+Usually you must use the **external method** once to install a retrofitted
+coreboot and then you can use the **internal method** for future updates.
+
+There are multiple ways to update the firmware:
+* Using flashrom's *internal* programmer to directly write into the firmware
+  flash IC, running on the target machine itself
+* A proprietary software to update the firmware, running on the target machine
+  itself
+* A UEFI firmware update capsule
+
+More details on flashrom's
+* [internal programmer](int_flashrom.md)
+
+## External method
+
+External flashing is possible on many platforms, but requires disassembling
+the target hardware. You need to buy a flash programmer, that
+exposes the same interface as your flash IC (likely SPI).
+
+Please also have a look at the mainboard-specific documentation for details.
+
+After exposing the firmware flash IC, read the schematics and use one of the
+possible methods:
+
+* [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)
+
+**WARNING:** Using the wrong method or accidentally using the wrong pinout might
+  permanently damage your hardware!
+
+**WARNING:** Do not rely on dots *painted* on flash ICs to orient the pins!
+Any dots painted on flash ICs may only indicate if they've been tested.  Dots
+that appear in datasheets to indicate pin 1 correspond to some kind of physical
+marker, such as a drilled hole, or one side being more flat than the other.
+
+## Using a layout file
+On platforms where the flash IC is shared with other components you might want
+to write only a part of the flash IC. On Intel for example there are IFD, ME and
+GBE which don't need to be updated to install coreboot.
+To make [flashrom] only write the *bios* region, leaving Intel ME and Intel IFD
+untouched, you can use a layout file, which can be created with ifdtool and a backup
+of the original firmware.
+
+```bash
+ifdtool -f rom.layout backup.rom
+```
+
+and looks similar to:
+
+```
+00000000:00000fff fd
+00500000:00bfffff bios
+00003000:004fffff me
+00001000:00002fff gbe
+```
+
+By specifying *-l* and *-i* [flashrom] writes a single region:
+```bash
+flashrom -l rom.layout -i bios -w coreboot.rom -p <programmer>
+```
+
+## Using an IFD to determine the layout
+flashrom version 1.0 supports reading the layout from the IFD (first 4KiB of
+the ROM). You don't need to manually specify a layout it, but it only works
+under the following conditions:
+
+* Only available on Intel ICH7+
+* There's only one flash IC when flashing externally
+
+```bash
+flashrom --ifd -i bios -w coreboot.rom -p <programmer>
+```
+
+**TODO** explain FMAP regions, normal/fallback mechanism, flash lock mechanisms
+
+[flashrom]: https://www.flashrom.org/Flashrom

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

@@ -3,7 +3,7 @@
 ## Overview
 ![][architecture]
 
-[architecture]: comparison_coreboot_uefi.svg
+[architecture]: comparision_coreboot_uefi.svg
 
 ## Stages
 coreboot consists of multiple stages that are compiled as separate binaries and
@@ -41,7 +41,7 @@ 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
+CPU cache like regular SRAM. This is particullary usefull for high level
 languages like `C`, which need RAM for heap and stack.
 
 The CAR needs to be activated using vendor specific CPU instructions.
@@ -85,7 +85,7 @@ The ramstage does the main device init:
 * 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:
+about the current hardware existance and state. That includes:
 
 * ACPI tables (x86 specific)
 * SMBIOS tables (x86 specific)

Documentation/getting_started/devicetree.md

@@ -1,87 +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
-
-Platform independent device drivers are hooked up via entries in a devicetree.
-See [Driver Devicetree Entries](drivers/dt_entries.md) for more info.
-
-## Notes
-
- - **All fields that are left unspecified in the devicetree are initialized to
-   zero.**

Documentation/getting_started/gerrit_guidelines.md

@@ -43,45 +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
-since the last significant modification to the change. The purpose is to
-let coreboot developers around the world have a chance to review. Complex
-reworks, even if they don't change the purpose of the patch but the way
-it's implemented, should restart the wait period.
-
-* A change can go in without the wait period if its purpose is to fix
-a recently-introduced issue (build, boot or OS-level compatibility, not
-necessarily identified by coreboot.org facilities). Its commit message
-has to explain what change introduced the problem and the nature of
-the problem so that the emergency need becomes apparent. Avoid stating
-something like "fix build error" in the commit summary, describe what
-the commit does instead, just like any other commit. In addition, it is
-recommended to reference the commit that introduced the issue. 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.
+* Let non-trivial patches sit in a review state for at least 24 hours
+before submission. Remember that there are coreboot developers in timezones
+all over the world, and everyone should have a chance to contribute.
+Trivial patches would be things like whitespace changes or spelling fixes,
+in general those that don’t impact the final binary output. The
+24-hour period would start at submission, and would be restarted at any
+update which significantly changes any part of the patch. Patches can be
+'Fast-tracked' and submitted in under 24 hours with the agreement of at
+least 3 +2 votes.
 
 * 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
@@ -196,10 +166,8 @@ the wip flag:
 * When pushing patches that are not for submission, these should be marked
 as such. This can be done in the title ‘[DONOTSUBMIT]’, or can be pushed as
 private changes, so that only explicitly added reviewers will see them. These
-sorts of patches are frequently posted as ideas or RFCs for the community to
-look at. Note that private changes can still be fetched from Gerrit by anybody
-who knows their commit ID, so don't use this for sensitive changes. To push
-a private change, use the command:
+sorts of patches are frequently posted as ideas or RFCs for the community
+to look at. To push a private change, use the command:
         git push origin HEAD:refs/for/master%private
 
 * Multiple push options can be combined:
@@ -325,47 +293,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

@@ -88,6 +88,11 @@ configurations together into a set of macros, e.g.,
 ```C
     /* Native function configuration */
     #define PAD_CFG_NF(pad, pull, rst, func)
+    /*
+     * Set native function with RX Level/Edge configuration and disable
+     * input/output buffer if necessary
+     */
+    #define PAD_CFG_NF_BUF_TRIG(pad, pull, rst, func, bufdis, trig)
     /* General purpose output, no pullup/down. */
     #define PAD_CFG_GPO(pad, val, rst)
     /* General purpose output, with termination specified */
@@ -115,44 +120,6 @@ 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,
@@ -162,97 +129,8 @@ 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!
 
-### Intel SoCs
-
-As per Intel Platform Controller Hub (PCH) EDS since Skylake, a GPIO PAD register
-supports four different types of GPIO reset as:
-
-```eval_rst
-+------------------------+----------------+-------------+-------------+
-|                        |                |         PAD Reset ?       |
-+ PAD Reset Config       + Platform Reset +-------------+-------------+
-|                        |                |     GPP     |     GPD     |
-+========================+================+=============+=============+
-| | 00 - Power Good      |  Warm Reset    |     N       |    N        |
-| | (GPP: RSMRST,        +----------------+-------------+-------------+
-| | GPD: DSW_PWROK)      |  Cold Reset    |     N       |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  S3/S4/S5      |     N       |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  Global Reset  |     N       |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  Deep Sx       |     Y       |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  G3            |     Y       |    Y        |
-+------------------------+----------------+-------------+-------------+
-| 01 - Deep              |  Warm Reset    |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  Cold Reset    |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  S3/S4/S5      |     N       |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  Global Reset  |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  Deep Sx       |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  G3            |     Y       |    Y        |
-+------------------------+----------------+-------------+-------------+
-| 10 - Host Reset/PLTRST |  Warm Reset    |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  Cold Reset    |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  S3/S4/S5      |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  Global Reset  |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  Deep Sx       |     Y       |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  G3            |     Y       |    Y        |
-+------------------------+----------------+-------------+-------------+
-| | 11 - Resume Reset    |  Warm Reset    |     n/a     |    N        |
-| | (GPP: Reserved,      +----------------+-------------+-------------+
-| | GPD: RSMRST)         |  Cold Reset    |     n/a     |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  S3/S4/S5      |     n/a     |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  Global Reset  |     n/a     |    N        |
-|                        +----------------+-------------+-------------+
-|                        |  Deep Sx       |     n/a     |    Y        |
-|                        +----------------+-------------+-------------+
-|                        |  G3            |     n/a     |    Y        |
-+------------------------+----------------+-------------+-------------+
-```
-
-Each GPIO Community has a Pad Configuration Lock register for a GPP allowing locking
-specific register fields in the PAD configuration register.
-
-The Pad Config Lock registers reset type is default hardcoded to **Power Good** and
-it's **not** configurable by GPIO PAD DW0.PadRstCfg. Hence, it may appear that for a GPP,
-the Pad Reset Config (DW0 Bit 31) is configured differently from `Power Good`.
-
-This would create confusion where the Pad configuration is returned to its `default`
-value but remains `locked`, this would prevent software to reprogram the GPP.
-Additionally, this means software can't rely on GPIOs being reset by PLTRST# or Sx entry.
-
-Hence, as per GPIO BIOS Writers Guide (BWG) it's recommended to change the Pad Reset
-Configuration for lock GPP as `Power Good` so that pad configuration and lock bit are
-always in sync and can be reset at the same time.
-
-## 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.
+The other configuration option to watch out for deals with unconnected GPIOs.
+If no pullup or pulldown is declared with these, they may end up "floating",
+i.e., not at logical high or logical low. This can cause problems such as
+unwanted power consumption or not reading the pin correctly, if it was intended
+to be strapped.

Documentation/getting_started/index.md

@@ -4,6 +4,7 @@
 * [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)
-* [Adding devices to a device tree](devicetree.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
@@ -394,8 +398,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 +605,7 @@ int <expr> \[if <expr>\]
 
 
 ##### Example:
-    config PRE_GRAPHICS_DELAY_MS
+    config PRE_GRAPHICS_DELAY
         int "Graphics initialization delay in ms"
         default 0
         help
@@ -786,7 +788,7 @@ select <symbol> \[if <expr>\]
     config TPM
         bool
         default n
-        select MEMORY_MAPPED_TPM if ARCH_X86
+        select LPC_TPM if ARCH_X86
         select I2C_TPM if ARCH_ARM
         select I2C_TPM if ARCH_ARM64
         help
@@ -1188,7 +1190,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
 
@@ -159,5 +159,5 @@ TOC tree.
 [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]: ../contributing/gerrit_guidelines.md
+[Gerrit Guidelines]: gerrit_guidelines.md
 [review.coreboot.org]: https://review.coreboot.org

Documentation/ifdtool/layout.md

@@ -2,7 +2,7 @@
 
 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).
+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
@@ -19,7 +19,7 @@ way to categorize anything required by the SoC but not provided by coreboot.
 | IFD Region | IFD Region name  | FMAP Name | Notes                                     |
 | index      |                  |           |                                           |
 +============+==================+===========+===========================================+
-| 0          | Flash Descriptor | SI_DESC   | Always the top 4 KiB of flash             |
+| 0          | Flash Descriptor | SI_DESC   | Always the top 4KB of flash               |
 +------------+------------------+-----------+-------------------------------------------+
 | 1          | BIOS             | SI_BIOS   | This is the region that contains coreboot |
 +------------+------------------+-----------+-------------------------------------------+
@@ -40,9 +40,9 @@ way to categorize anything required by the SoC but not provided by coreboot.
 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.
+ME region is defined at 6 MB in the IFD but the FMAP only allocates 4 MB for the
+ME, then when the ME is added by the ifdtool 6 MB will be written which could
+overwrite 2 MB of the BIOS.
 
 In order to validate that the FMAP and the IFD are compatible the ifdtool
 provides --validate (-t) option. `ifdtool -t` will read both the IFD and the

Documentation/index.md

@@ -5,11 +5,6 @@ It is built from Markdown files in the
 [Documentation](https://review.coreboot.org/cgit/coreboot.git/tree/Documentation)
 directory in the source code.
 
-## Spelling of coreboot
-
-The correct spelling of coreboot is completely in lower case characters and in
-one word without a space between the two parts.
-
 ## Purpose of coreboot
 
 coreboot is a project to develop open source boot firmware for various
@@ -26,7 +21,7 @@ initialization routines across many different use cases, no matter if
 they provide standard interfaces or entirely custom boot flows.
 
 Popular [payloads](payloads.md) in use with coreboot are SeaBIOS,
-which provides PCBIOS services, edk2, which provides UEFI services,
+which provides PCBIOS services, Tianocore, which provides UEFI services,
 GRUB2, the bootloader used by many Linux distributions, or depthcharge,
 a custom boot loader used on Chromebooks.
 
@@ -50,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
@@ -173,8 +162,13 @@ Contents:
 
 * [Getting Started](getting_started/index.md)
 * [Tutorial](tutorial/index.md)
-* [Contributing](contributing/index.md)
-* [Community](community/index.md)
+* [Coding Style](coding_style.md)
+* [Project Ideas](contributing/project_ideas.md)
+* [Documentation Ideas](contributing/documentation_ideas.md)
+* [Code of Conduct](community/code_of_conduct.md)
+* [Community forums](community/forums.md)
+* [Project services](community/services.md)
+* [coreboot at conferences](community/conferences.md)
 * [Payloads](payloads.md)
 * [Distributions](distributions.md)
 * [Technotes](technotes/index.md)
@@ -188,13 +182,9 @@ Contents:
 * [Mainboard](mainboard/index.md)
 * [Payloads](lib/payloads/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)
-* [Project infrastructure & services](infrastructure/index.md)
-* [Boards supported in each release directory](releases/boards_supported_on_branches.md)
-* [Release notes](releases/index.md)
-* [Acronyms & Definitions](acronyms.md)
-* [Documentation License](documentation_license.md)
+* [Release notes for past releases](releases/index.md)
+* [Flashing firmware tutorial](flash_tutorial/index.md)

Documentation/infrastructure/builders.md

@@ -1,420 +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 workstation or server class 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
-*   Martin Roth:
-    *   Email: [gaumless@gmail.com](mailto:gaumless@gmail.com)
-    *   IRC: martinr
-
-### Build Machine requirements
-
-For a builder, we need a very 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 6 active jenkins build machines.
-
-These times are taken from the week of Feb 21 - Feb 28, 2022
-
-* Congenialbuilder - 128 threads, 256GiB RAM
-  * Coverity Builds, Toolchain builds, Scanbuild-builds
-  * Fastest Passing coreboot gerrit build: 6 min, 47 sec
-  * Slowest Passing coreboot gerrit build: 14 min
-
-* Gleefulbuilder - 64 threads, 64GiB RAM
-  * Fastest Passing coreboot gerrit build: 10 min
-  * Slowest Passing coreboot gerrit build: 46 min
-
-* Fabulousbuilder - 64 threads, 64GiB RAM
-  * Fastest Passing coreboot gerrit build: 7 min, 56 sec
-  * Slowest Passing coreboot gerrit build: 56 min (No ccache)
-
-* Ultron (9elements) - 48 threads, 128GiB RAM
-  * Fastest Passing coreboot gerrit build: 12 min
-  * Slowest Passing coreboot gerrit build: 58 min
-
-* Bob - 64 threads, 128GiB RAM
-  * Fastest Passing coreboot gerrit build: 7 min
-  * Slowest Passing coreboot gerrit build: 34 min
-
-* Pokeybuilder - 32 Threads, 96GiB RAM
-  * Runs coreboot-checkpatch and other lighter builds
-
-
-### 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](coverity.md) builds.
-
-
-#### Long builds - over 90 minutes on congenialbuilder
-There are a few builds that take a long time even on the fastest
-machines.  These tasks run overnight in the US timezones.
-* coreboot_coverity - 9 to 12 hours
-* coreboot_scanbuild - ~3 hours
-* coreboot_toolchain - ~1 hour 45 minutes
-
-
-#### All builds
-
-You can see all the builds in the main jenkins interface:
-[https://qa.coreboot.org/](https://qa.coreboot.org/)
-
-Most of the time on the builders is taken up by the coreboot master and
-coreboot 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:
-
-```sh
-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.
-
-```sh
-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 the system for the jenkins builder
-
-As a regular user - *Not root*, run:
-
-```sh
-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}
-```
-
-
-#### 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.
-
-```sh
-# 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](https://hub.docker.com/repository/docker/coreboot/coreboot-sdk)
-export DOCKER_COMMIT=2021-09-23_b0d87f753c
-
-# 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
-
-```sh
-make -C util/docker help
-```
-
-This will show you the available targets and variables needed:
-
-```text
-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
-```
-
-
-### Install the coreboot jenkins builder
-
-```sh
-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
-an hour 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
-
-```sh
-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 image 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,
-then 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:
-
-```sh
-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.
-
-```sh
-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
-
-```sh
-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
-
-```sh
-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:
-
-```sh
-make -C util/docker docker-jenkins-server
-make -C util/docker docker-jenkins-attach
-```
-
-#### Running the build directly
-
-From the coreboot directory:
-
-```sh
-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
-
-```sh
-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.
-
-```sh
-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
-on the jenkins server.
-
-[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:
-
-```sh
-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/coverity.md

@@ -1,103 +0,0 @@
-# Coverity Scan for open source firmware
-
-## What’s Coverity and Coverity Scan?
-
-Coverity is a static analysis tool. It hooks into the build process
-and in addition to the compiler creating object files, Coverity collects
-information about the code. That data is then processed in a separate pass
-to identify common programming errors, like out of bounds accesses in C.
-
-Coverity Scan is an online service for Open Source projects providing this
-analysis for free. The analysis pass is done on their servers and issues
-can be handled in their [web UI](https://scan.coverity.com/).
-
-The Scan service has some quotas based on code size to avoid overloading
-the system, but even at one build per week, that’s usually good enough
-because the identified issues still need to be triaged and fixed or they
-will simply be re-identified next week.
-
-### Triage?
-
-The Web UI looks a bit like an issue tracker, even if it’s not a very
-good one. It’s possible to mark identified issues as valid or invalid,
-and annotate them with metadata which CLs fix them. The latter isn’t
-strictly necessary because Coverity Scan simply marks issues it can’t
-find anymore as fixed, but at times it helped identify issues that made
-a comeback.
-
-### Alternatives
-
-There’s also clang’s scan-build, which is fully open-source, and
-finds different issues. As such, it’s less of an alternative and more
-of a complement.
-
-There’s a regular run of that for coreboot but not for the other projects
-hosted at coreboot.org.
-
-One downside is that it emits a bunch of HTML to report on issues,
-but there’s no interactivity (e.g. marking issues solved), no way
-to merge multiple builds (e.g. multiple board builds of a single tree)
-or a simple way to extract burndown charts and the like from that.
-
-#### Looking for a project?
-
-On the upside, it can emit the data in a machine readable format, so if
-anybody needs a project, a scan-build web-frontend like Coverity Scan would
-be feasible without having to go through scan-build’s guts, just by parsing
-text files - plus all the stateful and web parts to build on top.
-
-## Logging into Coverity Scan
-
-Coverity Scan needs an account. It supports its own accounts and GitHub
-OAuth.
-
-Access to the dashboards needs approval: Request and you shall receive.
-
-## coreboot & friends and Coverity Scan
-
-coreboot, flashrom, Chromium EC and other projects of that family have
-been made Coverity aware, that is, their build systems support building
-with a custom compiler configuration passed in “just right” to enable
-Coverity to add its hooks.
-
-The public coreboot CI system at
-[https://qa.coreboot.org/](https://qa.coreboot.org/) regularly does
-builds with Coverity and sends them off to Coverity Scan.
-
-Specifically, it covers:
-
-* Chromium EC: [Coverity Scan site][crECCoverity] ([build job][crECBuildJob])
-* coreboot: [Coverity Scan site][corebootCoverity] ([build job][corebootBuildJob]), [scan-build output][corebootScanBuild] ([build job][corebootScanBuildJob])
-* em100: [Coverity Scan site][em100Coverity] ([build job][em100BuildJob])
-* fcode-utils: [Coverity Scan site][fcodeUtilsCoverity] ([build job][fcodeUtilsBuildJob])
-* flashrom: [Coverity Scan site][flashromCoverity] ([build job][flashromBuildJob])
-* memtest86+: [Coverity Scan site][memtestCoverity] ([build job][memtestBuildJob])
-* vboot: [Coverity Scan site][vbootCoverity] ([build job][vbootBuildJob])
-
-[crECCoverity]: https://scan.coverity.com/projects/chromium-ec
-[corebootCoverity]: https://scan.coverity.com/projects/coreboot
-[em100Coverity]: https://scan.coverity.com/projects/em100
-[fcodeUtilsCoverity]: https://scan.coverity.com/projects/fcode-utils
-[flashromCoverity]: https://scan.coverity.com/projects/flashrom
-[memtestCoverity]: https://scan.coverity.com/projects/memtest86
-[vbootCoverity]: https://scan.coverity.com/projects/vboot
-
-[corebootScanBuild]: https://www.coreboot.org/scan-build/
-
-[crECBuildJob]: https://qa.coreboot.org/view/coverity/job/ChromeEC-Coverity/
-[corebootBuildJob]: https://qa.coreboot.org/view/coverity/job/coreboot-coverity/
-[corebootScanBuildJob]: https://qa.coreboot.org/view/coverity/job/coreboot_scanbuild/
-[em100BuildJob]: https://qa.coreboot.org/view/coverity/job/em100-coverity/
-[fcodeUtilsBuildJob]: https://qa.coreboot.org/view/coverity/job/fcode-utils-coverity/
-[flashromBuildJob]: https://qa.coreboot.org/view/coverity/job/flashrom-coverity/
-[memtestBuildJob]: https://qa.coreboot.org/view/coverity/job/memtest86plus-coverity/
-[vbootBuildJob]: https://qa.coreboot.org/view/coverity/job/vboot-coverity/
-
-Some projects (e.g. Chromium EC) build a different subset of boards on
-each run, ensuring that everything is analyzed eventually. The downside
-is that coverity issues pop up and disappear somewhat randomly as they
-are discovered and go unnoticed in a later build.
-
-More projects that are hosted on review.coreboot.org (potentially as a
-mirror, like vboot and EC) could be served through that pipeline. Reach
-out to {stepan,patrick,martin}@coreboot.org.

Documentation/infrastructure/index.md

@@ -1,12 +0,0 @@
-# Project infrastructure & services
-
-This section contains documentation about our infrastructure
-
-## Services
-
-* [Project services](services.md)
-
-
-## Jenkins builders and builds
-* [Setting up Jenkins build machines](builders.md)
-* [Coverity Scan integration](coverity.md)

Documentation/infrastructure/services.md

@@ -1,60 +0,0 @@
-# Accounts on coreboot.org
-
-There are a number of places where you can benefit from creating 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.
-
-Below is a list of its SSH host keys and fingerprints.
-```Bash
-[review.coreboot.org]:29418 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAvNDn8qGHlWM/5ndFltStlg3QTc8xvGOgyjxxZByhMZx8LVE4cfgF38WP3euq0avyFy7gAJNghHorXpYKoOzuQPn2WNi5QhyGsUhg7ZJz9hC7Z2gqxxsZF3E7rku4Uj9sN7hWx9fBngxD4z2tP4y/18FTT5XTMcC3Q2sBCOLM0XVAO5R/nb2GO3d27avy+sanKAFEwJHnZ996IoTlU8JJFyi1Y6g30dC2K75oFgCtzntxf++wvrkkKPa+CFQub8fp20shat9WwX9kXjpRjt/Yv9LgqFCaI5ztJvWXicAmbgghGVzbzz4GoSjjF9cxxJF//KTmNb4iGQqmP3Olm27xuw==
-
-[review.coreboot.org]:29418 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBBzlwf/bFejt4EEz1QmbNOfK/HN1NtdcefrRs5Gs42uGnIvjxsff+vEF3//jCTvFPadoy3DrPsbQB3ioQAcYppk=
-
-[review.coreboot.org]:29418 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOC3Z32gc+1rJXhKX+SW0vESlXR/h/mhcxd+62B1PWC2
-```
-
-```Bash
-2048 SHA256:WW5prF7YE3MTnkRIxLklr9Gxddj9s5BZKUqWJF5dnTg review.coreboot.org:29418 (RSA)
-256 SHA256:IuLv/DgrBtVn36eMP1zFD0ISAl3IxIoCeiRms6UDhZc review.coreboot.org:29418 (ECDSA)
-256 SHA256:QFZieVHy8dCRl9tDib6qiwELnfa7SVU4ZWJ5VrXoC8k review.coreboot.org:29418 (ED25519)
-```
-
-### 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/lib/flashmap.md

@@ -17,8 +17,7 @@ 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.
+section descriptions in `struct fmap_area`.
 
 ### Header
 The header `struct fmap` has following fields:

Documentation/lib/fw_config.md

@@ -73,18 +73,18 @@ return true.
 
 ## Firmware Configuration Value
 
-The 64-bit value used as the firmware configuration bitmask is meant to be determined at runtime
+The 32bit 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
+The value can be provided with a 32bit 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`.
+raw 32bit 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.
@@ -127,42 +127,6 @@ 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`.
 
@@ -327,8 +291,8 @@ field and option to check.
 struct fw_config {
 	const char *field_name;
 	const char *option_name;
-	uint64_t mask;
-	uint64_t value;
+	uint32_t mask;
+	uint32_t value;
 };
 ```
 

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,7 +5,6 @@
 
 ## Supported architectures
 
-* aarch32
 * aarch64
 * riscv
 
@@ -25,14 +24,7 @@ The section must be named in order to be found by the FIT parser:
 
 ## Architecture specifics
 
-The FIT parser needs architecture 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*".
+The FIT parser needs architecure support.
 
 ### aarch64
 The source code can be found in `src/arch/arm64/fit_payload.c`.

Documentation/mainboard/acer/g43t-am3.md

@@ -1,177 +0,0 @@
-# Acer G43T-AM3
-
-The Acer G43T-AM3 is a microATX-sized desktop board. It was used for the
-Acer models Aspire M3800, Aspire M5800 and possibly more.
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| Northbridge      | Intel G43 (called x4x in coreboot code)          |
-+------------------+--------------------------------------------------+
-| Southbridge      | Intel ICH10R (called i82801jx in coreboot code)  |
-+------------------+--------------------------------------------------+
-| CPU socket       | LGA 775                                          |
-+------------------+--------------------------------------------------+
-| RAM              | 4 x DDR3-1066                                    |
-+------------------+--------------------------------------------------+
-| SuperIO          | ITE IT8720F                                      |
-+------------------+--------------------------------------------------+
-| Audio            | Realtek ALC888S                                  |
-+------------------+--------------------------------------------------+
-| Network          | Intel 82567V-2 Gigabit Ethernet                  |
-+------------------+--------------------------------------------------+
-```
-
-There is no serial port. Serial console output is possible by soldering
-to a point at the corresponding Super I/O pin and patching the
-mainboard-specific code accordingly.
-
-## Status
-
-### Working
-
-Tests were done with SeaBIOS 1.14.0 and slackware64-live from 2019-07-12
-(linux-4.19.50).
-
-+ Intel Core 2 processors at up to FSB 1333
-+ All four DIMM slots at 1066 MHz (tested 2x2GB + 2x4GB)
-+ Integrated graphics (libgfxinit)
-+ HDMI and VGA ports
-+ Both PCI slots
-+ Both PCI-e slots
-+ USB (8 internal, 4 external)
-+ All six SATA ports
-+ Onboard Ethernet
-+ Onboard sound card with output on the rear stereo connector
-+ PS/2 mouse and keyboard
-    + With SeaBIOS, use CONFIG_SEABIOS_PS2_TIMEOUT, tested: 500
-    + With FILO it works without further settings
-+ Temperature readings from the Super I/O (including the CPU temperature
-  via PECI)
-+ Super I/O EC automatic fan control
-+ S3 suspend/resume
-+ Poweroff
-
-### Not working
-
-+ DDR3 memory with 512Mx8 chips (G43 limitation)
-+ 4x4GB of DDR3 memory (works, but showed a single bit error within one
-  pass of Memtest86+ 5.01)
-+ Super I/O voltage reading conversions
-
-### Untested
-
-+ Other audio jacks or the front panel header
-+ S/PDIF output
-+ On-board Firewire
-+ Wake-on-LAN
-
-## Flashing coreboot
-
-```eval_rst
-+-------------------+---------------------+
-| Type              | Value               |
-+===================+=====================+
-| Socketed flash    | No                  |
-+-------------------+---------------------+
-| Model             | Macronix MX25L1605D |
-+-------------------+---------------------+
-| Size              | 2 MiB               |
-+-------------------+---------------------+
-| Package           | 8-Pin SOP           |
-+-------------------+---------------------+
-| Write protection  | No                  |
-+-------------------+---------------------+
-| Dual BIOS feature | No                  |
-+-------------------+---------------------+
-| Internal flashing | Yes                 |
-+-------------------+---------------------+
-```
-
-The flash is divided into the following regions, as obtained with
-`ifdtool -f rom.layout backup.rom`:
-```
-00000000:00001fff fd
-00100000:001fffff bios
-00006000:000fffff me
-00002000:00005fff gbe
-```
-
-In general, flashing is possible internally and from an external header. It
-might be necessary to specify the chip type; `MX25L1605D/MX25L1608D/MX25L1673E`
-is the correct one, not `MX25L1605`.
-
-### Internal flashing
-
-Internal access to the flash chip is unrestricted. When installing coreboot,
-only the BIOS region should be updated by passing the `--ifd` and `-i bios`
-parameters to flashrom. A full backup is advisable.
-
-Here is an example:
-
-```
-$ sudo flashrom \
-  -p internal \
-  -c "MX25L1605D/MX25L1608D/MX25L1673E" \
-  -r backup.rom
-$ sudo flashrom \
-  -p internal \
-  -c "MX25L1605D/MX25L1608D/MX25L1673E" \
-  --ifd -i bios \
-  -w coreboot.rom
-```
-
-```eval_rst
-In addition to the information here, please see the
-:doc:`../../tutorial/flashing_firmware/index`.
-```
-
-### External flashing
-
-The SPI flash chip on this board can be flashed externally through the
-SPI_ROM1 header while the board is off and disconnected from power. There
-seems to be a diode that prevents the external programmer from powering the
-whole board.
-
-The signal assignment on the header is identical to the pinout of the flash
-chip. The pinout diagram below is valid when the PCI slots are on the left
-and the CPU is on the right. Note that HOLD# and WP# must be pulled high
-(to VCC) to be able to flash the chip.
-
-                +---+---+
-     SPI_CSn <- | x | x | -> VCC
-                +---+---+
-    SPI_MISO <- | x | x | -> HOLDn
-                +---+---+
-         WPn <- | x | x | -> SPI_CLK
-                +---+---+
-         GND <- | x | x | -> SPI_MOSI
-                +---+---+
-
-## Intel Management Engine
-
-The Intel Management Engine (ME) can be disabled by setting the ME_DISABLE
-jumper on the board. It pulls GPIO33 on the ICH10 low, causing the "Flash
-Descriptor Security Override Strap" to be set. This disables the ME and also
-disables any read/write restrictions to the flash chip that may be set in the
-Intel Flash Descriptor (IFD) (none on this board). Note that changing this
-jumper only comes into effect when starting the board from a shutdown or
-suspend state, not during normal operation.
-
-To completely remove the ME blob from the flash image and to decrease the size
-of the ME region, thus increasing the size of the BIOS region, `me_cleaner` can
-be used with the `-t`, `-r` and `-S` options.
-
-## Fan control
-
-There are two fan connectors that can be controlled individually. CPU_FAN
-can only control a fan by a PWM signal and SYS_FAN only by voltage. See
-the mainboard's `devicetree.cb` file for how coreboot configures the Super
-I/O to control the fans.
-
-## Variants
-
-Various similar mainboards exist, like the Acer Q45T-AM. During a discussion
-in #coreboot on IRC, ECS was suspected to be the original designer of this
-series of mainboards. They have similar models such as the ECS G43T-WM.

Documentation/mainboard/amd/pademelon/pademelon.md

@@ -1,80 +0,0 @@
-# Pademelon 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][pademelon]
-
-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][pademelon_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
-+----------------------------+----------------------------------------+
-|pademelon.jpg               | Motherboard with components identified |
-+----------------------------+----------------------------------------+
-|pademelon_io.jpg            | Back panel picture                     |
-+----------------------------+----------------------------------------+
-```
-
-## Reference
-
-[Merlin Falcon BKDG][merlinfalcon]
-
-[merlinfalcon]: ../../../soc/amd/family15h.md
-[pademelon]: pademelon.jpg
-[pademelon_io]: pademelon_io.jpg

Documentation/mainboard/amd/padmelon/padmelon.md

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

Documentation/mainboard/asrock/h110m-dvs.md

@@ -58,7 +58,7 @@ 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](../../tutorial/flashing_firmware/index.md).
+the flash protection). More information about this [here](../../flash_tutorial/index.md).
 
 ### External programming
 
@@ -131,4 +131,4 @@ facing towards the bottom of the board.
 [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]: https://web.archive.org/web/20191023230631/http://asrock.pc.cdn.bitgravity.com/Manual/H110M-DVS%20R2.0.pdf
+[H110M-DVS manual]: http://asrock.pc.cdn.bitgravity.com/Manual/H110M-DVS%20R2.0.pdf

Documentation/mainboard/asrock/h77pro4-m.md

@@ -1,174 +0,0 @@
-# ASRock H77 Pro4-M
-
-The ASRock H77 Pro4-M is a microATX-sized desktop board for Intel Sandy
-Bridge and Ivy Bridge CPUs.
-
-## Technology
-
-```eval_rst
-+------------------+--------------------------------------------------+
-| Northbridge      | :doc:`../../northbridge/intel/sandybridge/index` |
-+------------------+--------------------------------------------------+
-| Southbridge      | Intel H77 (bd82x6x)                              |
-+------------------+--------------------------------------------------+
-| CPU socket       | LGA 1155                                         |
-+------------------+--------------------------------------------------+
-| RAM              | 4 x DDR3-1600                                    |
-+------------------+--------------------------------------------------+
-| Super I/O        | Nuvoton NCT6776                                  |
-+------------------+--------------------------------------------------+
-| Audio            | Realtek ALC892                                   |
-+------------------+--------------------------------------------------+
-| Network          | Realtek RTL8111E                                 |
-+------------------+--------------------------------------------------+
-| Serial           | Internal header (RS-232)                         |
-+------------------+--------------------------------------------------+
-```
-
-## Status
-
-Tests were done with SeaBIOS 1.14.0 and slackware64-live from 2019-07-12
-(linux-4.19.50).
-
-### Working
-
-- Sandy Bridge and Ivy Bridge CPUs (tested: i5-2500, Pentium G2120)
-- Native RAM initialization with four DIMMs
-- PS/2 combined port (mouse or keyboard)
-- Integrated GPU by libgfxinit on all monitor ports (DVI-D, HDMI, D-Sub)
-- PCIe graphics in the PEG slot
-- All three additional PCIe slots
-- All rear and internal USB2 ports
-- All rear and internal USB3 ports
-- All six SATA ports from the PCH (two 6 Gb/s, four 3 Gb/s)
-- All two SATA ports from the ASM1061 PCIe-to-SATA bridge (6 Gb/s)
-- Rear eSATA connector (multiplexed with one ASM1061 port)
-- Gigabit Ethernet
-- Console output on the serial port
-- SeaBIOS 1.14.0 and 1.15.0 to boot Windows 10 (needs VGA BIOS) and Linux via
-extlinux
-- Internal flashing with flashrom-1.2, see
-[Internal Programming](#internal-programming)
-- External flashing with flashrom-1.2 and a Raspberry Pi 1
-- S3 suspend/resume from either Linux or Windows 10
-- Poweroff
-
-### Not working
-
-- Booting from the two SATA ports provided by the ASM1061
-- Automatic fan control with the NCT6776D Super I/O
-
-### Untested
-
-- EHCI debug
-- S/PDIF audio
-- Other audio jacks than the green one, and the front panel header
-- Parallel port
-- Infrared/CIR
-- Wakeup from anything but the power button
-
-## Flashing coreboot
-
-```eval_rst
-+---------------------+------------+
-| Type                | Value      |
-+=====================+============+
-| Socketed flash      | yes        |
-+---------------------+------------+
-| Model               | W25Q64.V   |
-+---------------------+------------+
-| Size                | 8 MiB      |
-+---------------------+------------+
-| Package             | DIP-8      |
-+---------------------+------------+
-| Write protection    | no         |
-+---------------------+------------+
-| Dual BIOS feature   | no         |
-+---------------------+------------+
-| Internal flashing   | yes        |
-+---------------------+------------+
-```
-
-The flash is divided into the following regions, as obtained with
-`ifdtool -f rom.layout backup.rom`:
-```
-00000000:00000fff fd
-00200000:007fffff bios
-00001000:001fffff me
-```
-
-### Internal programming
-
-The main SPI flash can be accessed using flashrom. By default, only
-the BIOS region of the flash is writable. If you wish to change any
-other region (Management Engine or flash descriptor), then an external
-programmer is required.
-
-The following command may be used to flash coreboot:
-
-```
-$ sudo flashrom --noverify-all --ifd -i bios -p internal -w coreboot.rom
-```
-
-The use of `--noverify-all` is required since the Management Engine
-region is not readable even by the host.
-
-```eval_rst
-In addition to the information here, please see the
-:doc:`../../tutorial/flashing_firmware/index`.
-```
-
-## Hardware monitoring and fan control
-
-There are two fan headers for the CPU cooler, CPU_FAN1 and CPU_FAN2. They share
-a single fan tachometer input on the Super I/O while some dedicated logic
-selects which one is allowed to reach it. Two GPIO pins on the Super I/O are
-used to control that logic. The firmware has to set them; coreboot selects
-CPU_FAN1 by default, but the user can change that setting if it was built with
-CONFIG_USE_OPTION_TABLE:
-
-```
-$ sudo nvramtool -e cpu_fan_header
-[..]
-$ sudo nvramtool -w cpu_fan_header=CPU_FAN2
-$ sudo nvramtool -w cpu_fan_header=None
-$ sudo nvramtool -w cpu_fan_header=Both
-```
-
-The setting will take effect after a reboot. Selecting and connecting both fan
-headers is possible but the Super I/O will report wrong fan speeds.
-
-Currently there is no automatic, OS-independent fan control, but a software
-like `fancontrol` from the lm-sensors package can be used instead.
-
-## Serial port header
-
-Serial port 1, provided by the Super I/O, is exposed on a pin header. The
-RS-232 signals are assigned to the header so that its pin numbers map directly
-to the pin numbers of a DE-9 connector. If your serial port doesn't seem to
-work, check if your bracket expects a different assignment. Also don't try to
-connect it directly to a device that operates at TTL levels - it would need a
-level converter like a MAX232.
-
-Here is a top view of the serial port header found on this board:
-
-                 +---+---+
-             N/C |   | 9 | RI  -> pin 9
-                 +---+---+
-    Pin 8 <- CTS | 8 | 7 | RTS -> pin 7
-                 +---+---+
-    Pin 6 <- DSR | 6 | 5 | GND -> pin 5
-                 +---+---+
-    Pin 4 <- DTR | 4 | 3 | TxD -> pin 3
-                 +---+---+
-    Pin 2 <- RxD | 2 | 1 | DCD -> pin 1
-                 +---+---+
-
-## eSATA
-
-The eSATA port on the rear I/O panel and the internal connector SATA3_A1 share
-the same controller port on the ASM1061. Attaching an eSATA drive causes a
-multiplexer chip to disconnect the internal port from the SATA controller and
-connect the eSATA port instead. This can be seen on GP23 of the Super I/O
-GPIOs: it is '0' when something is connected to the eSATA port and '1'
-otherwise.

Documentation/mainboard/asrock/h81m-hds.md

@@ -130,4 +130,4 @@ Please also see :doc:`../../northbridge/intel/haswell/known-issues`.
 [ASRock H81M-HDS]: https://www.asrock.com/mb/Intel/H81M-HDS/
 [W25Q32FV]: https://www.winbond.com/resource-files/w25q32fv%20revi%2010202015.pdf
 [flashrom]: https://flashrom.org/Flashrom
-[Board manual]: https://web.archive.org/web/20191231093418/http://asrock.pc.cdn.bitgravity.com/Manual/H81M-HDS.pdf
+[Board manual]: http://asrock.pc.cdn.bitgravity.com/Manual/H81M-HDS.pdf

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

@@ -190,9 +190,9 @@ This version is usable for all the GPUs.
 - [Board manual]
 - Flash chip datasheet [W25Q64FV]
 
-[ASUS F2A85-M]: https://web.archive.org/web/20160320065008/http://www.asus.com/Motherboards/F2A85M/
-[Board manual]: https://web.archive.org/web/20211028063105/https://dlcdnets.asus.com/pub/ASUS/mb/SocketFM2/F2A85-M/E8005_F2A85-M.pdf
+[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://web.archive.org/web/20220127184640/https://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf
+[W25Q64FV]: https://www.winbond.com/resource-files/w25q64fv%20revs%2007182017.pdf