.checkpatch.conf

@@ -1,16 +1,15 @@
-# Override checkpatch's default max line length 100
---max-line-length=96
-
 # Not Linux, so don't expect a Linux tree.
 --no-tree
 
 # 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
+--ignore PREFER_ALIGNED
+--ignore PREFER_PACKED
+--ignore PREFER_PRINTF
 --ignore SPLIT_STRING
 --ignore BLOCK_COMMENT_STYLE
 --ignore AVOID_EXTERNS
@@ -23,7 +22,6 @@
 --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

.clang-format

@@ -1,228 +1,21 @@
-# SPDX-License-Identifier: GPL-2.0-only
-#
-# clang-format configuration file. Intended for clang-format >= 16.
-#
-# For more information, see:
-#
-#   https://clang.llvm.org/docs/ClangFormat.html
-#   https://clang.llvm.org/docs/ClangFormatStyleOptions.html
-#   https://clang-format-configurator.site/
-#
-
----
-Language:        Cpp
-AccessModifierOffset: -4
-AlignAfterOpenBracket: Align
-AlignArrayOfStructures: Left
-AlignConsecutiveAssignments:
-  Enabled:         false
-  AcrossEmptyLines: false
-  AcrossComments:  true
-  AlignCompound:   false
-  PadOperators:    true
-AlignConsecutiveBitFields:
-  Enabled:         true
-  AcrossEmptyLines: false
-  AcrossComments:  false
-  AlignCompound:   false
-  PadOperators:    true
-AlignConsecutiveDeclarations:
-  Enabled:         false
-  AcrossEmptyLines: false
-  AcrossComments:  false
-  AlignCompound:   false
-  PadOperators:    true
-AlignConsecutiveMacros:
-  Enabled:         true
-  AcrossEmptyLines: false
-  AcrossComments:  false
-  AlignCompound:   false
-  PadOperators:    true
-AlignEscapedNewlines: Left
-AlignOperands:   Align
-AlignTrailingComments:
-  Kind:            Always
-  OverEmptyLines:  0
-AllowAllArgumentsOnNextLine: true
-AllowAllParametersOfDeclarationOnNextLine: false
-AllowShortBlocksOnASingleLine: Never
-AllowShortCaseLabelsOnASingleLine: false
-AllowShortEnumsOnASingleLine: true
-AllowShortFunctionsOnASingleLine: None
-AllowShortIfStatementsOnASingleLine: Never
-AllowShortLambdasOnASingleLine: All
-AllowShortLoopsOnASingleLine: false
-AlwaysBreakAfterDefinitionReturnType: None
-AlwaysBreakAfterReturnType: None
-AlwaysBreakBeforeMultilineStrings: false
-AlwaysBreakTemplateDeclarations: MultiLine
-
-# git grep '^#define [^[:space:]]*__.*[^[:space:]]*__attribute__' | grep -v "vendorcode\|payloads\|util" | sed "s|.*:||;s|^#define \([^[:space:]]*__[^([:space:]]*\).*$|  - '\1'|" | LC_ALL=C sort -u
-AttributeMacros:
-  - '__aligned'
-  - '__always_inline'
-  - '__always_unused'
-  - '__cpu_driver'
-  - '__fallthrough'
-  - '__maybe_unused'
-  - '__must_check'
-  - '__noreturn'
-  - '__packed'
-  - '__pci_driver'
-  - '__printf'
-  - '__weak'
-BinPackArguments: true
-BinPackParameters: true
-BitFieldColonSpacing: Both
-BraceWrapping:
-  AfterCaseLabel:  false
-  AfterClass:      false
-  AfterControlStatement: Never
-  AfterEnum:       false
-  AfterExternBlock: false
-  AfterFunction:   true
-  AfterNamespace:  true
-  AfterObjCDeclaration: false
-  AfterStruct:     false
-  AfterUnion:      false
-  BeforeCatch:     false
-  BeforeElse:      false
-  BeforeLambdaBody: false
-  BeforeWhile:     false
-  IndentBraces:    false
-  SplitEmptyFunction: true
-  SplitEmptyRecord: true
-  SplitEmptyNamespace: true
-BreakAfterAttributes: Never
-BreakAfterJavaFieldAnnotations: false
-BreakArrays:     false
-BreakBeforeBinaryOperators: None
-BreakBeforeConceptDeclarations: Always
-BreakBeforeBraces: Custom
-BreakBeforeInlineASMColon: OnlyMultiline
-BreakBeforeTernaryOperators: false
-BreakConstructorInitializers: AfterColon
-BreakInheritanceList: AfterColon
-BreakStringLiterals: false
-ColumnLimit:     96
-CommentPragmas:  '^ IWYU pragma:'
-CompactNamespaces: false
-ConstructorInitializerIndentWidth: 8
-ContinuationIndentWidth: 8
-Cpp11BracedListStyle: true
-DerivePointerAlignment: false
-DisableFormat:   false
-EmptyLineAfterAccessModifier: Never
-EmptyLineBeforeAccessModifier: LogicalBlock
-ExperimentalAutoDetectBinPacking: false
-FixNamespaceComments: false
-
-# git grep '^#define [^[:space:]]*for_each[^[:space:]]*(' | grep -v "vendorcode\|payloads\|util" | sed "s|.*:||;s|^#define \([^[:space:]]*for_each[^[:space:]]*\)(.*$|  - '\1'|" | LC_ALL=C sort -u
-ForEachMacros:
-  - 'list_for_each'
-
-# git grep -i '^#define \+if[^[:space:]]*(' | grep -v "vendorcode\|payloads\|util" | sed "s|.*:||;s|^#define \([^[:space:]]*if[^[:space:]]*\)(.*$|  - '\1'|I" | grep -v IFIX | LC_ALL=C sort -u
-IfMacros:
-  - 'IF_CHANNEL_POPULATED'
-  - 'IF_DIMM_POPULATED'
-  - 'IF_RANK_POPULATED'
-  - 'IfBit0'
-IncludeBlocks:   Preserve
-IncludeIsMainSourceRegex: ''
-IndentAccessModifiers: false
-IndentCaseBlocks: false
-IndentCaseLabels: false
-IndentExternBlock: AfterExternBlock
-IndentGotoLabels: false
-IndentPPDirectives: None
-IndentRequiresClause: true
-IndentWidth:     8
-IndentWrappedFunctionNames: false
-InsertBraces:    false
-InsertNewlineAtEOF: true
-InsertTrailingCommas: None
-IntegerLiteralSeparator:
-  Binary:          0
-  BinaryMinDigits: 0
-  Decimal:         0
-  DecimalMinDigits: 0
-  Hex:             0
-  HexMinDigits:    0
-JavaScriptQuotes: Leave
-JavaScriptWrapImports: true
-KeepEmptyLinesAtTheStartOfBlocks: false
-LambdaBodyIndentation: Signature
-LineEnding:      LF
-MacroBlockBegin: ''
-MacroBlockEnd:   ''
-MaxEmptyLinesToKeep: 1
-NamespaceIndentation: None
-ObjCBinPackProtocolList: Auto
-ObjCBlockIndentWidth: 8
-ObjCBreakBeforeNestedBlockParam: true
-ObjCSpaceAfterProperty: true
-ObjCSpaceBeforeProtocolList: true
-PackConstructorInitializers: BinPack
-PenaltyBreakAssignment: 10
-PenaltyBreakBeforeFirstCallParameter: 30
-PenaltyBreakComment: 10
-PenaltyBreakFirstLessLess: 0
-PenaltyBreakOpenParenthesis: 0
-PenaltyBreakString: 10
-PenaltyBreakTemplateDeclaration: 10
-PenaltyExcessCharacter: 100
-PenaltyIndentedWhitespace: 0
-PenaltyReturnTypeOnItsOwnLine: 60
-PointerAlignment: Right
-PPIndentWidth:   -1
-QualifierAlignment: Left
-ReferenceAlignment: Pointer
-ReflowComments:  false
-RemoveBracesLLVM: false
-RemoveSemicolon: false
-RequiresClausePosition: OwnLine
-RequiresExpressionIndentation: OuterScope
-SeparateDefinitionBlocks: Leave
-ShortNamespaceLines: 1
-SortIncludes:    Never
-SortJavaStaticImport: Before
-SortUsingDeclarations: Never
-SpaceAfterCStyleCast: false
-SpaceAfterLogicalNot: false
-SpaceAfterTemplateKeyword: true
-SpaceAroundPointerQualifiers: Default
-SpaceBeforeAssignmentOperators: true
-SpaceBeforeCaseColon: false
-SpaceBeforeCpp11BracedList: false
-SpaceBeforeCtorInitializerColon: true
-SpaceBeforeInheritanceColon: true
-SpaceBeforeParens: ControlStatementsExceptControlMacros
-SpaceBeforeParensOptions:
-  AfterControlStatements: true
-  AfterForeachMacros: false
-  AfterFunctionDefinitionName: false
-  AfterFunctionDeclarationName: false
-  AfterIfMacros:   false
-  AfterOverloadedOperator: false
-  AfterRequiresInClause: false
-  AfterRequiresInExpression: false
-  BeforeNonEmptyParentheses: false
-SpaceBeforeRangeBasedForLoopColon: true
-SpaceBeforeSquareBrackets: false
-SpaceInEmptyBlock: false
-SpaceInEmptyParentheses: false
-SpacesBeforeTrailingComments: 1
-SpacesInAngles:  Never
-SpacesInConditionalStatement: false
-SpacesInContainerLiterals: false
-SpacesInCStyleCastParentheses: false
-SpacesInLineCommentPrefix:
-  Minimum:         1
-  Maximum:         1
-SpacesInParentheses: false
-SpacesInSquareBrackets: false
-Standard:        c++17
-TabWidth:        8
-UseTab:          ForContinuationAndIndentation
-...
-
+BasedOnStyle:					LLVM
+Language:					Cpp
+IndentWidth:					8
+UseTab:						Always
+BreakBeforeBraces:				Linux
+AllowShortIfStatementsOnASingleLine:		false
+IndentCaseLabels:				false
+SortIncludes:					false
+ContinuationIndentWidth:			8
+ColumnLimit:					96
+AlwaysBreakBeforeMultilineStrings:		true
+AllowShortLoopsOnASingleLine:			false
+AllowShortFunctionsOnASingleLine:		false
+AlignEscapedNewlinesLeft:			false
+AlignTrailingComments:				true
+AllowAllParametersOfDeclarationOnNextLine:	false
+AlignAfterOpenBracket:				true
+SpaceAfterCStyleCast:				false
+MaxEmptyLinesToKeep:				2
+BreakBeforeBinaryOperators:			NonAssignment
+BreakStringLiterals:				false

.editorconfig

@@ -9,7 +9,3 @@ charset = utf-8
 insert_final_newline = true
 end_of_line = lf
 trim_trailing_whitespace = true
-
-[*.sh]
-indent_style = space
-indent_size = 2

.gitignore

@@ -9,7 +9,6 @@ defconfig
 build/
 coreboot-builds/
 coreboot-builds*/
-generated/
 
 site-local
 
@@ -32,10 +31,6 @@ site-local
 # Development friendly files
 tags
 .clang_complete
-.cache
-compile_commands.json
-.vscode/
-.clangd
 
 # Cross-compile toolkits
 xgcc/
@@ -45,3 +40,5 @@ tarballs/
 *~
 *.kate-swp
 *.kdev4
+
+doxygen/*

.gitmodules

@@ -1,81 +1,62 @@
 [submodule "3rdparty/blobs"]
 	path = 3rdparty/blobs
-	url = https://review.coreboot.org/blobs.git
+	url = ../blobs.git
 	update = none
 	ignore = dirty
 [submodule "util/nvidia-cbootimage"]
 	path = util/nvidia/cbootimage
-	url = https://review.coreboot.org/nvidia-cbootimage.git
+	url = ../nvidia-cbootimage.git
 [submodule "vboot"]
 	path = 3rdparty/vboot
-	url = https://review.coreboot.org/vboot.git
+	url = ../vboot.git
 	branch = main
 [submodule "arm-trusted-firmware"]
 	path = 3rdparty/arm-trusted-firmware
-	url = https://review.coreboot.org/arm-trusted-firmware.git
+	url = ../arm-trusted-firmware.git
+[submodule "3rdparty/chromeec"]
+	path = 3rdparty/chromeec
+	url = ../chrome-ec.git
 [submodule "libhwbase"]
 	path = 3rdparty/libhwbase
-	url = https://review.coreboot.org/libhwbase.git
+	url = ../libhwbase.git
 [submodule "libgfxinit"]
 	path = 3rdparty/libgfxinit
-	url = https://review.coreboot.org/libgfxinit.git
+	url = ../libgfxinit.git
 [submodule "3rdparty/fsp"]
 	path = 3rdparty/fsp
-	url = https://review.coreboot.org/fsp.git
+	url = ../fsp.git
 	update = none
 	ignore = dirty
 [submodule "opensbi"]
 	path = 3rdparty/opensbi
-	url = https://review.coreboot.org/opensbi.git
+	url = ../opensbi.git
 [submodule "intel-microcode"]
 	path = 3rdparty/intel-microcode
-	url = https://review.coreboot.org/intel-microcode.git
+	url = ../intel-microcode.git
 	update = none
 	ignore = dirty
 	branch = main
 [submodule "3rdparty/ffs"]
 	path = 3rdparty/ffs
-	url = https://review.coreboot.org/ffs.git
+	url = ../ffs.git
 [submodule "3rdparty/amd_blobs"]
 	path = 3rdparty/amd_blobs
-	url = https://review.coreboot.org/amd_blobs
+	url = ../amd_blobs
 	update = none
 	ignore = dirty
 [submodule "3rdparty/cmocka"]
 	path = 3rdparty/cmocka
-	url = https://review.coreboot.org/cmocka.git
+	url = ../cmocka.git
 	update = none
-	branch = stable-1.1
 [submodule "3rdparty/qc_blobs"]
 	path = 3rdparty/qc_blobs
-	url = https://review.coreboot.org/qc_blobs.git
+	url = ../qc_blobs.git
 	update = none
 	ignore = dirty
 [submodule "3rdparty/intel-sec-tools"]
 	path = 3rdparty/intel-sec-tools
-	url = https://review.coreboot.org/9esec-security-tooling.git
-	ignore = dirty
+	url = ../9esec-security-tooling.git
 [submodule "3rdparty/stm"]
 	path = 3rdparty/stm
-	url = https://review.coreboot.org/STM
+	url = ../STM
 	branch = stmpe
-[submodule "util/goswid"]
-	path = util/goswid
-	url = https://review.coreboot.org/goswid
-	branch = trunk
-	ignore = dirty
-[submodule "src/vendorcode/amd/opensil/genoa_poc/opensil"]
-	path = src/vendorcode/amd/opensil/genoa_poc/opensil
-	url = https://review.coreboot.org/opensil_genoa_poc.git
-[submodule "3rdparty/open-power-signing-utils"]
-	path = 3rdparty/open-power-signing-utils
-	url = https://review.coreboot.org/open-power-signing-utils.git
-[submodule "src/vendorcode/amd/opensil/phoenix_poc/opensil"]
-	path = src/vendorcode/amd/opensil/phoenix_poc/opensil
-	url = https://github.com/openSIL/openSIL.git
-	branch = phoenix_poc
-[submodule "src/vendorcode/amd/opensil/turin_poc/opensil"]
-	path = src/vendorcode/amd/opensil/turin_poc/opensil
-	url = https://github.com/openSIL/openSIL.git
-	branch = turin_poc
-

.gitreview

@@ -2,4 +2,4 @@
 host=review.coreboot.org
 port=29418
 project=coreboot
-defaultbranch=main
+defaultbranch=master

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

3rdparty/amd_blobs

@@ -1 +1 @@
-Subproject commit aa9288a33c6d7a67e55b8757390029207593fa9f
+Subproject commit f638765f17cdca735b69229f4f0479562bcb7526

3rdparty/arm-trusted-firmware

@@ -1 +1 @@
-Subproject commit 9109143417b24337d39a2a9583828a44996f8aac
+Subproject commit 586aafa3a4b13971339f78e430075592c3fe74b5

3rdparty/blobs

@@ -1 +1 @@
-Subproject commit 4a8de0324e7d389454ec33cdf66939b653bf6800
+Subproject commit f388b6794e6f1f93b847de353f5eab8ba3e3b328

3rdparty/chromeec

@@ -0,0 +1 @@
+Subproject commit 4c21b57eb9619cc3dc86d11226917d25f62f1bc8

3rdparty/cmocka

@@ -1 +1 @@
-Subproject commit 8be37372097d1aa5e03b565936db7891b6180e73
+Subproject commit 672c5cee79eb412025c3dd8b034e611c1f119055

3rdparty/fsp

@@ -1 +1 @@
-Subproject commit 81399b3b61479abc379c2d01362d4b6dc6f515c9
+Subproject commit 10eae55b8eb0febfa2dfabf4017701b072866170

3rdparty/intel-microcode

@@ -1 +1 @@
-Subproject commit 250941fb670645d7d91f761cc63656ad3a1ec367
+Subproject commit 3f97690f0da8011f52209b232450a1e5c4f2e1f6

3rdparty/libgfxinit

@@ -1 +1 @@
-Subproject commit 3c3828add50024e90e57d6fbe0e660d1b66302d9
+Subproject commit 1b04c517b377468b3b470d38607fb539187391dd

3rdparty/libhwbase

@@ -1 +1 @@
-Subproject commit 584629b9f4771b7618951cec57df2ca3af9c6981
+Subproject commit fc2102f560f25e0f2e5be91ec36646dcb69e6e1b

3rdparty/open-power-signing-utils

@@ -1 +0,0 @@
-Subproject commit 591c8f53482243626901e1cc8a4ae321f314040d

3rdparty/opensbi

@@ -1 +1 @@
-Subproject commit 5019fd124b4c46e1581129c5154fc2cdd3b777ed
+Subproject commit 215421ca610a64b8ec188c96ea8588ae2de41fb7

3rdparty/qc_blobs

@@ -1 +1 @@
-Subproject commit 6379308814bd00a8b6e36a4715bdb86ba019a3a7
+Subproject commit 98db38671b651dd7e7966fb629d65ff5dd23865b

3rdparty/vboot

@@ -1 +1 @@
-Subproject commit 5c360ef458b0a013d8a6d47724bb0fffb5accbcf
+Subproject commit 13f601fbd4c1b128f333391e4552082594f0ff25

AUTHORS

@@ -10,901 +10,237 @@
 
 3mdeb Embedded Systems Consulting
 9elements Agency GmbH
-Aamir Bohra
-Aaron Durbin
-Abe Levkoy
-Abel Briggs
 Abhinav Hardikar
-Abhishek Pandit-Subedi
-AdaCore
-Adam Liu
-Adam Mills
 Advanced Computing Lab, LANL
 Advanced Micro Devices, Inc.
+AdaCore
 AG Electronics Ltd.
-Agogo
-Ahamed Husni
-Akshu Agrawal
-Al Hirani
-Alan Huang
-AlanKY Lee
-Alec Wang
-Alex James
-Alex Levin
-Alex Miao
 Alex Thiessen
 Alex Züpke
-Alex1 Kao
 Alexander Couzens
-Alexander Goncharov
 Alexandru Gagniuc
-Alexey Buyanov
-Alexey Vazhnov
-Alice Sell
-Alicja Michalska
-Allen-KH Cheng
-Alok Agarwal
-Alper Nebi Yasak
-Amanda Hwang
-American Megatrends International, LLC
-Amersel
-Amit Caleechurn
-Ana Carolina Cabral
 Analog Devices Inc.
 Analogix Semiconductor
-Anand Mistry
-Anand Vaikar
-Anastasios Koutian
-Andre
 Andre Heider
-Andrew McRae
-Andrew SH Cheng
-Andrey Pronin
 Andriy Gapon
-Andy
 Andy Fleming
-Andy Pont
-Andy-ld Lu
 Angel Pons
-Angela Czubak
-Anil Kumar K
-Anna Karaś
-Annie Chen
 Anton Kochkov
-Ao Zhong
-Appukuttan V K
-Arashk Mahshidfar
-Arec Kao
-Ariel Fang
-Ariel Otilibili
 ARM Limited and Contributors
 Arthur Heymans
 Asami Doi
-Aseda Aboagye
-Ashish Kumar Mishra
-Ashqti
 ASPEED Technology Inc.
 Atheros Corporation
 Atmel Corporation
-Avi Uday
-Avinash Munduru
-Balaji Manigandan
-Balázs Vinarz
 BAP - Bruhnspace Advanced Projects
-Bartłomiej Grzesik
-Baruch Siach
-Ben Chuang
-Ben Kao
-Ben McMillen
-Ben Zhang
-Benjamin Doron
-Bernardo Perez Priego
-Bhanu Prakash Maiya
 Bill Xie
-Bin Meng
-Bincai Liu
 Bitland Tech Inc.
-Bob Moragues
-Bora Guvendik
 Boris Barbulovski
-Boris Mittelberg
-Brandon Breitenstein
-Brandon Weeks
-Brian Hsu
-Brian Norris
-Bryant Ou
 Carl-Daniel Hailfinger
-Carlos López
-Casper Chang
-Cathy Xu
-Caveh Jalali
 Cavium Inc.
-Chao Gui
-Chen-Tsung Hsieh
-Chen. Gang C
-Chia-Ling Hou
-Chien-Chih Tseng
-Chris Wang
-Christian Gmeiner
-Christian Walter
 Christoph Grenz
-Christopher Meis
-Chuangwei Technology Co., Ltd
-Chun-Jie Chen
-Cirrus Logic, Inc.
-CK HU
-Clay Daniels
-Cliff Huang
 Code Aurora Forum
-Compal Electronics, Inc.
-Cong Yang
-CoolStar
 coresystems GmbH
 Corey Osgood
-Crystal Guo
 Curt Brune
-Curtis Chen
 Custom Ideas
-Cyberus Technology GmbH
-Da Lao
-Daisuke Nojiri
 Damien Zammit
-Dan Callaghan
-Dan Campbell
-Daniel Campello
-Daniel Gröber
-Daniel Kang
-Daniel Maslowski
-Daniel Peng
-Daniel Rosa Franzini
 Dave Airlie
 David Brownell
 David Greenman
 David Hendricks
-David Li
-David Lin
-David Milosevic
 David Mosberger-Tang
 David Mueller
 David S. Peterson
-David Wu
-Dawei Chien
-Deepika Punyamurtula
-Deepti Deshatty
-Dehui Sun
 Denis 'GNUtoo' Carikli
 Denis Dowling
 DENX Software Engineering
-Deomid 'rojer' Ryabkov
-Derek Basehore
-Derek Huang
 Derek Waldner
 Digital Design Corporation
-Dinesh Gehlot
-Divya S Sasidharan
-Dmitry Ponamorev
-Dmitry Torokhov
 DMP Electronics Inc.
-Dolan Liu
-Dominik Behr
 Donghwa Lee
 Drew Eckhardt
-Dtrain Hsu
-Duan Huayang
-Dun Tan
-Duncan Laurie
 Dynon Avionics
-Ed Sharma
-Eddy Lu
-Edward Hill
 Edward O'Callaghan
-Edward-JW Yang
 Egbert Eich
-Elias Souza
-Eloy Degen
 ELSOFT AG
 Eltan B.V
-Eltan B.V.
 Elyes Haouas
-Emilie Roberts
-Enzo Potenza
-Eran Mitrani
-Eren Peng
 Eric Biederman
-Eric Lai
-Eric Peers
-EricKY Cheng
-EricR Lai
-Erik van den Bogaert
 Eswar Nallusamy
-Ethan Tsao
-Eugene Myers
-Evan Green
 Evgeny Zinoviev
-Evie (Ivi) Ballou
-Fabian Groffen
 Fabian Kunkel
-Fabian Meyer
-Fabio Aiuto
 Fabrice Bellard
 Facebook, Inc.
-Federico Amedeo Izzo
-Fei Yan
-Felix Friedlander
 Felix Held
 Felix Singer
-Fengquan Chen
-Filip Brozovic
-Filip Lewiński
-Flora Fu
-Florian Laufenböck
-Francois Toguo Fotso
-Frank Chu
-Frank Wu
-Franklin Lin
-Frans Hendriks
-Fred Reitberger
 Frederic Potter
 Free Software Foundation, Inc.
 Freescale Semiconductor, Inc.
-Furquan Shaikh
-Gaggery Tsai
-Gang C Chen
-Garen Wu
-Gareth Yu
-Garmin Chang
 Gary Jennejohn
-Gavin Liu
-George Burgess
 George Trudeau
 Gerald Van Baren
 Gerd Hoffmann
 Gergely Kiss
 Google LLC
 Greg Watson
-Grzegorz Bernacki
-Guangjie Song
 Guennadi Liakhovetski
-Guodong Liu
-Gwendal Grignou
 Hal Martin
-Hao Chou
-Hao Wang
 HardenedLinux
-Harrie Paijmans
-Harsha B R
-Harshit Sharma
-Henry C Chen
-Herbert Wu
-Hewlett Packard Enterprise Development LP
 Hewlett-Packard Development Company, L.P.
-Himanshu Sahdev
-Hope Wang
-Housong Zhang
-Hsiao Chien Sung
-Hsin-hsiung wang
-Hsin-Te Yuan
-Hsuan Ting Chen
-Hualin Wei
-Huaqin Technology Co., Ltd
+Hewlett Packard Enterprise Development LP
 Huaqin Telecom Inc.
-Hui Liu
-Huijuan Xie
-Hung-Te Lin
-Ian Douglas Scott
-Ian Feng
 IBM Corporation
 Idwer Vollering
-Igor Bagnucki
 Igor Pavlov
-Ikjoon Jang
 Imagination Technologies
 Infineon Technologies
-Ingo Reitz
 InKi Dae
-INSPUR Co., Ltd
 Intel Corporation
-Inventec Corp
 Iru Cai
-Isaac Lee
 Isaku Yamahata
-Ivan Chen
 Ivan Vatlin
-Ivy Jian
-Jack Rosenthal
-Jacob Garber
-Jairaj Arava
-Jakub Czapiga
-James Chao
-James Lo
 James Ye
-Jameson Thies
-Jamie Chen
-Jamie Ryu
-Jan Dabros
-Jan Philipp Groß
-Jan Samek
-Jan Tatje
-Jarried Lin
-Jason Glenesk
-Jason Nein
-Jason V Le
-Jason Z Chen
 Jason Zhao
-jason-ch chen
-Jason-jh Lin
-Jay Patel
-Jayvik Desai
-Jean Lucas
-Jędrzej Ciupis
-Jeff Chase
-Jeff Daly
-Jeff Li
-Jérémy Compostella
-Jeremy Soller
-Jes Klinke
-Jesper Lin
-Jessy Jiang
-Jett Rink
-Jg Daolongzhu
-Jian Tong
-Jianeng Ceng
-Jianjun Wang
-Jim Lai
-Jimmy Su
-Jincheng Li
-Jingle Hsu
-Jitao Shi
 Joe Pillow
-Joe Tessler
-Joel Bueno
-Joel Kitching
-Joel Linn
-Joey Peng
 Johanna Schander
-Johannes Hahn
-John Su
-John Zhao
-Johnny Li
-Johnny Lin
-johnson wang
-Jon Murphy
 Jonas 'Sortie' Termansen
-Jonas Loeffelholz
 Jonathan A. Kollasch
 Jonathan Neuschäfer
-Jonathan Zhang
-Jonathon Hall
 Jordan Crouse
-Jörg Mische
 Joseph Smith
-Josie Nordrum
-Juan José García-Castro Crespo
-Julia Kittlinger
-Julia Tsai
-Julian Intronati
-Julian Schroeder
-Julian Stecklina
-Julien Viard de Galbert
-Julius Werner
-Kacper Stojek
-Kaiyen Chang
-Kane Chen
-Kangheui Won
-KangMin Wang
-Kapil Porwal
-Karol Zmyslowski
-Karthik Ramasubramanian
-Ke Zheng
-Kei Hiroyoshi
 Keith Hui
 Keith Packard
-Kenneth Chan
-Kevin Chang
-Kevin Cheng
-Kevin Chiu
-Kevin Chowski
 Kevin Cody-Little
-Kevin Keijzer
 Kevin O'Connor
-Kevin Yang
-Kevin3 Yang
-kewei xu
-Kilari Raasi
-Kirk Wang
-Kiwi Liu
-Konrad Adamczyk
 Kontron Europe GmbH
-Kornel Dulęba
-Krishna P Bhat D
-Krystian Hebel
 Kshitij
-Kshitiz Godara
-Kulkarni. Srinivas
-Kun Liu
-KunYi Chen
-Kyle Lin
 Kyösti Mälkki
-Lance Zhao
-Lawrence Chang
 Leah Rowe
-Lean Sheng Tan
 Lei Wen
-Lennart Eichhorn
-Lenovo Group Ltd
-Leo Chou
 Li-Ta Lo
-Li1 Feng
-Liam Flaherty
 Libra Li
 Libretrend LDA
-Lijian Zhao
-Liju-Clr Chen
 Linaro Limited
-linear
 Linus Torvalds
 Linux Networx, Inc.
 LiPPERT ADLINK Technology GmbH
-Liu Liu
-Liya Li
-Lu Tang
-Lu. Pen-ChunX
 Lubomir Rintel
 Luc Verhaegen
-Luca Lai
-Lucas Chen
-Lukas Wunner
-Mac Chiang
 Maciej Matuszczyk
-Maciej Pijanowski
-Macpaul Lin
-Madhusudanarao Amara
-Magf
-Malik Hsu
-Mandy Liu
-Manoj Gupta
 Marc Bertens
 Marc Jones
-Marco Chen
-Marek Kasiewicz
-Marek Maślanka
 Marek Vasut
-Mario Scheithauer
 Marius Gröger
-Mariusz Szafranski
-Mariusz Szafrański
-Mark Chang
-Mark Hasemeyer
-Mark Hsieh
-Mars Chen
-Marshall Dawson
 Martin Mares
 Martin Renters
 Martin Roth
 Marvell International Ltd.
 Marvell Semiconductor Inc.
-Marx Wang
-Masa Nakura
-Masanori Ogino
-Máté Kukri
-Matei Dibu
-Mathew King
-Matt Chen
-Matt Delco
 Matt DeVillier
-Matt Papageorge
-Matt Turner
-Matthew Blecker
-Matthew Ziegelbaum
-Mattias Nissler
-Maulik V Vaghela
-MAULIK V VAGHELA
-Maulik Vaghela
-Max Fritz
 Maxim Polyakov
-Maximilian Brune
-Mediatek Inc.
 MediaTek Inc.
-Meera Ravindranath
-Melongmelong
-Meng-Huan Yu
-Meta Platforms, Inc
-mgabryelski1
-Mice Lin
 Michael Brunner
-Michael Büchler
-Michael Niewöhner
 Michael Schroeder
-Michael Strosche
-Michael Walle
-Michał Kopeć
-Michal Suchanek
-Michał Zieliński
-Michał Żygowski
-Micro-Star INT'L CO., LTD.
+Michael Niewöhner
 Mika Westerberg
-Mike Banon
-Mike Lin
-Mike Shih
-Mingjin Ge
-Miriam Polzer
-mkurumel
-Moises Garcia
-Momoko Hattori
 Mondrian Nuessle
-Monika A
-Monikaanan
 MontaVista Software, Inc.
-Morgan Jang
-Moritz Fischer
-Morris Hsu
-mtk15698
-mturney mturney
-Musse Abdullahi
 Myles Watson
-Nancy Lin
-Naresh Solanki
-Nathan Lu
-Naveen R. Iyer
-Neill Corlett
 Network Appliance Inc.
-Nicholas Chin
 Nicholas Sielicki
-Nicholas Sudsgaard
 Nick Barker
-Nick Chen
-Nick Kochlowski
-Nick Vaccaro
 Nico Huber
 Nico Rikken
 Nicola Corna
-Nicolas Boichat
-Nicole Faerber
-Nigel Tao
-Nikolai Vyssotski
 Nils Jacobs
-Nina Wu
 Nir Tzachar
 Nokia Corporation
-Nuvoton Technology Corporation
 NVIDIA Corporation
 Olivier Langlois
 Ollie Lo
 Omar Pakker
 Online SAS
-Opal Voravootivat
 Orion Technologies, LLC
-Ot_chhao.chang
-Ot_hao.han
-Ot_song Fan
-Pablo
-Pablo Ceballos
-Pablo Stebler
-Pan Gao
 Patrick Georgi
-Patrick Huang
 Patrick Rudolph
-Patrik Tesarik
 Pattrick Hueper
-Paul Fagerburg
-Paul Menzel
-Paul2 Huang
 Paulo Alcantara
-Pavan Holla
 Pavel Sayekat
-Paz Zcharya
 PC Engines GmbH
-Pegatron Corp
-Peichao Li
 Per Odlund
 Peter Korsgaard
-Peter Lemenkov
-Peter Marheine
 Peter Stuge
-Petr Cvek
-Philip Chen
-Philipp Bartsch
 Philipp Degler
 Philipp Deppenwiese
 Philipp Hug
-Pierce Chou
-Piotr Kleinschmidt
-Po Xu
-Poornima Tom
-Pranava Y N
-Prasad Malisetty
-Prashant Malani
-Pratik Vishwakarma
-Pratikkumar Prajapati
-Pratikkumar V Prajapati
 Protectli
-PugzAreCute
-Purdea Andrei
-Purism, SPC
-Qii Wang
-Qinghong Zeng
-Qualcomm Technologies, Inc.
-Quanta Computer INC
-Raihow Shi
-Rajat Jain
-Rajesh Patil
+Purism SPC
+Qualcomm Technologies
 Raptor Engineering, LLC
-Rasheed Hsueh
-Raul Rangel
-Ravi Kumar
-Ravi Mistry
-Ravindra
-Ravishankar Sarawadi
-Ray Han Lim Ng
-Raymond Chung
-Reagan
 Red Hat, Inc
-ReddestDream
-Rehan Ghori
 Reinhard Meyer
-Reka Norman
-Ren Kuo
 Renze Nicolai
-Reto Buerki
-Rex Chou
-Rex-BC Chen
-Ricardo Quesada
-Ricardo Ribalda
 Richard Spiegel
 Richard Woodruff
-Rick Lee
-Ricky Chang
-Riku Viitanen
-Rishika Raj
-Ritul Guru
-Rizwan Qureshi
-Rnhmjoj
-Rob Barnes
 Rob Landley
-Robert Chen
 Robert Reeves
-Robert Zieba
 Robinson P. Tryon
 Rockchip, Inc.
-Rocky Phagura
-Roger Lu
-Roger Wang
-Roja Rani Yarubandi
 Romain Lievin
 Roman Zippel
-Ron Lee
-Ron Minnich
-Ronak Kanabar
-Ronald Claveau
 Ronald G. Minnich
-Rory Liu
 Rudolf Marek
-Rui Zhou
-Ruihai Zhou
-Runyang Chen
 Russell King
 Ruud Schramp
-Ruwen Liu
-Ryan Chuang
-Ryan Lin
 Sage Electronic Engineering, LLC
-Sajida Bhanu
-Sam Lewis
-Sam McNally
 Sam Ravnborg
 Samsung Electronics
 Samuel Holland
-Sandeep Maheswaram
-Sathya Prakash M R
-Satya Priya Kakitapalli
-Satya SreenivasL
-Saurabh Mishra
 SciTech Software, Inc.
-Scott Chao
-SDC Systems Ltd
-Sean Rhodes
-Sebastian 'Swift Geek' Grzywna
+Sebastian Grzywna
 secunet Security Networks AG
-Selma Bensaid
-Semihalf
-Sen Chu
 Sencore Inc
 Sergej Ivanov
-Sergii Dmytruk
-Serin Yeh
-Seven Lee
-SH Kim
-Shahina Shaik
-Shaocheng Wang
-Shaoming Chen
-Shaunak Saha
-Shelley Chen
-Shelly Chang
-Sheng-Liang Pan
-Shiyu Sun
-Shon Wang
-Shou-Chieh Hsu
-Shreesh Chhabbi
-Shunxi Zhang
-Shuo Liu
 Siemens AG
 SiFive, Inc
-Silicom Ltd.
 Silicon Integrated System Corporation
 Silverback Ltd.
-Simon Glass
-Simon Yang
-Simon Zhou
-Sindhoor Tilak
-Solomon Alan-Dei
-Song Fan
-Sowmya Aralguppe
-Sridhar Siricilla
-Srinidhi N Kaushik
-Srinivasa Rao Mandadapu
-ST Microelectronics
-Stanisław Kardach
-Stanley Wu
-Star Labs Online Ltd
-Stefan Binding
-Stefan Ott
 Stefan Reinauer
 Stefan Tauner
-Stephen Edworthy
 Steve Magnani
 Steve Shenton
-Subrata Banik
-Sudheer Amrabadi
-Sugnan Prabhu S
-Sukumar Ghorai
-Sumeet R Pawnikar
-Sunwei Li
+ST Microelectronics
 SUSE LINUX AG
 Sven Schnelle
 Syed Mohammed Khasim
-System76, Inc.
-szarpaj
-T Michael Turney
-TangYiwei
-Taniya Das
-Tao Xia
-Tarun Tuli
-Teddy Shih
-Terry Chen
-Terry Cheong
+System76
 Texas Instruments
 The Android Open Source Project
 The ChromiumOS Authors
 The Linux Foundation
 The Regents of the University of California
-Thejaswani Putta
-Thomas Heijligen
 Thomas Winischhofer
-Tim Chen
-Tim Chu
-Tim Crawford
-Tim Van Patten
-Tim Wawrzynczak
-Timofey Komarov
 Timothy Pearson
-tinghan shen
 Tobias Diedrich
-Tom Hiller
-Tomasz Michalec
-Tommie Lin
-Tongtong Pan
-Tony Huang
-Tracy Wu
-Trevor Wu
 Tristan Corrick
 Tungsten Graphics, Inc.
 Tyan Computer Corp.
-Tyler Wang
-Tzung-Bi Shih
-U.S. National Security Agency
 ucRobotics Inc.
-Uday Bhat
 University of Heidelberg
-Usha P
 Uwe Hermann
-Uwe Poeche
-V Sowmya
-Vladimir Epifantsev
-Václav Straka
-Vadim Bendebury
-Valentyn Sudomyr
-Van Chen
-Varshit B Pandya
-Varun Upadhyay
-Veerabhadrarao Badiganti
-Venkat Thogaru
-Venkata Krishna Nimmagadda
 VIA Technologies, Inc
-Victor Ding
-Vidya Gopalakrishnan
 Vikram Narayanan
-Vikrant L Jadeja
-Vince Liu
-Vinod Polimera
 Vipin Kumar
-Vitaly Rodionov
 Vladimir Serbinenko
 Vlado Cibic
-Vsujithk
 Wang Qing Pei
-Wanghao11
 Ward Vandewege
-Wayne Wang
-Weimin Wu
-Weiyi Lu
-Wen Zhang
-Wenbin Mei
-Wentao Qin
-Wenzhen Yu
-Werner Zeh
 Wilbert Duijvenvoorde
-William Wei
-Wilson Chou
-Wim Vervoorn
 Win Enterprises
-Wisley Chen
-Wistron Corp
 Wiwynn Corp.
-Wiwynn Corporation
-Wizard Shen
-Wojciech Macek
 Wolfgang Denk
-Won Chung
-Wonkyu Kim
-Wuxy
-Xiang W
-Xin Ji
-Xiwen Shao
-Xixi Chen
-Xue Yao
-Xueqi Zhang
-Xuxin Xiong
 YADRO
-Yan Liu
-Yang Wu
 Yann Collet
-Yanqiong Huang
-Yaroslav Kurlaev
-YH Lin
-Yidi Lin
-Yilin Yang
 Yinghai Lu
-Yolk Shih
-Yong Zhi
-Yongkun Yu
-Yongqiang Niu
-Yu-hsuan Hsu
-Yu-Ping Wu
-Yuanliding
-Yuchen He
-Yuchen Huang
-Yuchiche
-Yunlong Jia
-Yuval Peress
 Zachary Yedidia
-Zanxi Chen
-Zebreus
-Zhanyong Wang
-Zhaoming Luo
-Zhaoqing Jiu
-Zheng Bao
-Zhenguo Li
-Zhi7 Li
-Zhigang Qin
-Zhiqiang Ma
-Zhixing Ma
-Zhiyong Tao
-Zhongtian Wu
-Zhuohao Lee
-Ziang Wang
-Zoey Wu
-Zoltan Baldaszti
-一颗小土豆
-小田喜陽彦
-忧郁沙茶
-陳建宏

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

@@ -1,24 +1,49 @@
-## SPDX-License-Identifier: GPL-2.0-only
 #
 # Makefile for coreboot paper.
 # hacked together by Stefan Reinauer <stepan@openbios.org>
 #
 
-BUILDDIR ?= _build
-SPHINXOPTS ?= -j auto -W --keep-going
+PDFLATEX=pdflatex -t a4
 
-export SPHINXOPTS
+FIGS=codeflow.pdf hypertransport.pdf
 
-all: sphinx
+all: corebootPortingGuide.pdf
 
-$(BUILDDIR):
-	mkdir -p $(BUILDDIR)
+SVG2PDF=$(shell which svg2pdf)
+INKSCAPE=$(shell which inkscape)
+CONVERT=$(shell which convert)
 
-sphinx: $(BUILDDIR)
-	$(MAKE) -f Makefile.sphinx html BUILDDIR="$(BUILDDIR)"
+codeflow.pdf: codeflow.svg
+ifneq ($(strip $(SVG2PDF)),)
+	svg2pdf $< $@
+else ifneq ($(strip $(INKSCAPE)),)
+	inkscape $< --export-pdf=$@
+else ifneq ($(strip $(CONVERT)),)
+	convert $< $@
+endif
+
+hypertransport.pdf: hypertransport.svg
+ifneq ($(strip $(SVG2PDF)),)
+	svg2pdf $< $@
+else ifneq ($(strip $(INKSCAPE)),)
+	inkscape $< --export-pdf=$@
+else ifneq ($(strip $(CONVERT)),)
+	convert $< $@
+endif
+
+corebootPortingGuide.toc: $(FIGS) corebootBuildingGuide.tex
+	# 2 times to make sure we have a current toc.
+	$(PDFLATEX) corebootBuildingGuide.tex
+	$(PDFLATEX) corebootBuildingGuide.tex
+
+corebootPortingGuide.pdf: $(FIGS) corebootBuildingGuide.tex corebootPortingGuide.toc
+	$(PDFLATEX) corebootBuildingGuide.tex
+
+sphinx:
+	$(MAKE) -f Makefile.sphinx html
 
 clean-sphinx:
-	$(MAKE) -f Makefile.sphinx clean BUILDDIR="$(BUILDDIR)"
+	$(MAKE) -f Makefile.sphinx clean
 
 clean: clean-sphinx
 	rm -f *.aux *.idx *.log *.toc *.out $(FIGS)
@@ -26,24 +51,5 @@ clean: clean-sphinx
 distclean: clean
 	rm -f corebootPortingGuide.pdf
 
-livesphinx: $(BUILDDIR)
-	$(MAKE) -f Makefile.sphinx livehtml BUILDDIR="$(BUILDDIR)"
-
-test:
-	@echo "Test for logging purposes - Failing tests will not fail the build"
-	-$(MAKE) -f Makefile.sphinx clean && $(MAKE) -k -f Makefile.sphinx html
-
-help:
-	@echo "all            - Builds all documentation targets"
-	@echo "sphinx         - Builds html documentation in _build directory"
-	@echo "clean          - Cleans intermediate files"
-	@echo "clean-sphinx   - Removes sphinx output files"
-	@echo "distclean      - Removes PDF files as well"
-	@echo "test           - Runs documentation tests"
-	@echo
-	@echo "  Makefile.sphinx builds - run with $(MAKE) -f Makefile-sphinx [target]"
-	@echo
-	@$(MAKE) -s -f Makefile.sphinx help 2>/dev/null
-
-.phony: help livesphinx sphinx test
-.phony: distclean clean clean-sphinx
+livesphinx:
+	$(MAKE) -f Makefile.sphinx livehtml SPHINXOPTS="$(SPHINXOPTS)"

Documentation/Makefile.sphinx

@@ -1,29 +1,233 @@
-## SPDX-License-Identifier: GPL-2.0-only
-# Minimal makefile for Sphinx documentation
+# Makefile for Sphinx documentation
 #
 
-# You can set these variables from the command line, and also
-# from the environment for the first two.
-SPHINXOPTS    ?=
-SPHINXBUILD   ?= sphinx-build
-SPHINXAUTOBUILD = sphinx-autobuild
-SOURCEDIR     = .
-BUILDDIR      = _build
+# You can set these variables from the command line.
+SPHINXOPTS        ?=
+SPHINXBUILD       = sphinx-build
+SPHINXAUTOBUILD   = sphinx-autobuild
+PAPER             =
+BUILDDIR          = _build
 
-# Put it first so that "make" without argument is like "make help".
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help
 help:
-	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  applehelp  to make an Apple Help Book"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  epub3      to make an epub3"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  xml        to make Docutils-native XML files"
+	@echo "  pseudoxml  to make pseudoxml-XML files for display purposes"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+	@echo "  coverage   to run coverage check of the documentation (if enabled)"
+	@echo "  dummy      to check syntax errors of document sources"
 
-.PHONY: help Makefile.sphinx
+.PHONY: clean
+clean:
+	rm -rf $(BUILDDIR)
+
+.PHONY: html
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
 
 .PHONY: livehtml
 livehtml:
 	@echo "Starting sphinx-autobuild. The HTML pages are in $(BUILDDIR)."
 	@echo "Press Ctrl-C to stop."
 	@echo
-	$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
 
-# Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile.sphinx
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+.PHONY: dirhtml
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+.PHONY: singlehtml
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+.PHONY: pickle
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+.PHONY: json
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+.PHONY: htmlhelp
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+.PHONY: qthelp
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/coreboot.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/coreboot.qhc"
+
+.PHONY: applehelp
+applehelp:
+	$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
+	@echo
+	@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
+	@echo "N.B. You won't be able to view it unless you put it in" \
+	      "~/Library/Documentation/Help or install it in your application" \
+	      "bundle."
+
+.PHONY: devhelp
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/coreboot"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/coreboot"
+	@echo "# devhelp"
+
+.PHONY: epub
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+.PHONY: epub3
+epub3:
+	$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
+	@echo
+	@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
+
+.PHONY: latex
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+.PHONY: latexpdf
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: latexpdfja
+latexpdfja:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through platex and dvipdfmx..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+.PHONY: text
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+.PHONY: man
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+.PHONY: texinfo
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+.PHONY: info
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+.PHONY: gettext
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+.PHONY: changes
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+.PHONY: linkcheck
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+.PHONY: doctest
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."
+
+.PHONY: coverage
+coverage:
+	$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
+	@echo "Testing of coverage in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/coverage/python.txt."
+
+.PHONY: xml
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
+	@echo
+	@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
+
+.PHONY: pseudoxml
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
+
+.PHONY: dummy
+dummy:
+	$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
+	@echo
+	@echo "Build finished. Dummy builder generates no files."

Documentation/POSTCODES

@@ -5,7 +5,7 @@ coreboot POST Codes
 This is an (incomplete) list of POST codes emitted by coreboot v4.
 
 0x10 Entry into protected mode
-0x01 Entry into 'entry16.S' reset code jumps to here
+0x01 Entry into 'crt0.s' reset code jumps to here
 0x11 Start copying coreboot to RAM with decompression if compressed
 0x12 Copy/decompression finished jumping to RAM
 0x80 Entry into coreboot in RAM

Documentation/RFC/intel-gpio-cleanup.md

@@ -1,7 +1,3 @@
-```{eval-rst}
-:orphan:
-```
-
 # Background
 
 CB:31250 ("soc/intel/cannonlake: Configure GPIOs again after FSP-S is
@@ -55,7 +51,7 @@ index 28e78fb366..0cce41b316 100644
 @@ -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,

Documentation/acpi/devicetree.md

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

Documentation/acpi/index.md

@@ -5,30 +5,12 @@ backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
 upwards.
 
 
-```{toctree}
-:maxdepth: 1
-
-SSDT UID generation <uid.md>
-```
+- [SSDT UID generation](uid.md)
 
 ## GPIO
 
-```{toctree}
-:maxdepth: 1
+- [GPIO toggling in ACPI AML](gpio.md)
 
-GPIO toggling in ACPI AML <gpio.md>
-```
+## devicetree
 
-## Windows-specific ACPI documentation
-
-```{toctree}
-:maxdepth: 1
-
-Windows-specific documentation <windows.md>
-```
-
-##  ACPI specification - Useful links
-
-- [ACPI Specification 6.5](https://uefi.org/specs/ACPI/6.5/index.html)
-- [ASL 2.0 Syntax](https://uefi.org/specs/ACPI/6.5/19_ASL_Reference.html#asl-2-0-symbolic-operators-and-expressions)
-- [Predefined ACPI Names](https://uefi.org/specs/ACPI/6.5/05_ACPI_Software_Programming_Model.html#predefined-acpi-names)
+- [Adding devices to a device tree](devicetree.md)

Documentation/acpi/windows.md

@@ -1,9 +0,0 @@
-# Testing ACPI changes under Windows
-
-When testing ACPI changes in coreboot against Windows 8 or newer, beware that
-during a normal boot after a clean shutdown, Windows will use the fast startup
-mechanism which results in it not evaluating the changed ACPI code but instead
-using some cached version which won't include the changes that were supposed to
-be tested. In order for Windows to actually use the new ACPI tables, either
-disable the fast startup or just tell Windows to do a reboot which will make it
-read and use the ACPI tables in memory instead of an outdated cached version.

Documentation/arch/index.md

@@ -5,15 +5,7 @@ architectures.
 
 ## RISC-V
 
-```{toctree}
-:maxdepth: 1
-
-RISC-V documentation <riscv/index.md>
-```
+- [RISC-V documentation](riscv/index.md)
 
 ## x86
-```{toctree}
-:maxdepth: 1
-
-x86 documentation <x86/index.md>
-```
+- [x86 documentation](x86/index.md)

Documentation/arch/x86/index.md

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

Documentation/arch/x86/x86_64.md

@@ -1,109 +0,0 @@
-# x86_64 architecture documentation
-
-This section documents coreboot's x86_64 support. When enabled,
-every coreboot stage is built for x86_64, contrary to UEFI's implementation
-that only runs some stages in x86_64.
-On UEFI the PEI phase, which is x86_32, brings up DRAM and installs
-page tables for the x86_64 DXE and BDS phases.
-
-## Toolchain requirements for x86_64 support
-* The compiler must support generating code for the *large memory model*
-  (-mcmodel=large). It's supported since GCC 4.4.
-
-  Page tables can be used to provide security benefits, such as by marking
-  memory as non-executable or removing it entirely. This could be useful
-  for SMM to mark regular DRAM as NX.
-
-  The large memory model causes the compiler to emit 64bit addressing
-  instructions, which increases code size. In theory, this is roughly
-  made up for by the faster execution of the x86_64 code.
-
-* All x86 coreboot stages and payloads must be loaded below 4GiB in
-  physical memory. When jumping to the payload coreboot will drop from
-  long mode back to protected mode to keep compatibility with these payloads.
-
-## Comparison to UEFI
-On UEFI the SEC and PEI phases (similar to coreboot's bootblock and romstage)
-are run in x86_32 mode. The following (guessed) reasons are likely:
-* There's no need for x86_64 as memory hasn't been trained yet. The whole 4GiB
-  address space, including CAR, memory mapped SPI flash and PCI BARs, are
-  accessible in x86_32.
-* When the EFI specification was written compilers did not support
-  *large memory model*, required in CAR when using a 1:1 page mapping
-* Code is 20% bigger in x86_64 due to *large memory model* where pointers and
-  function calls always use 8 byte addressing. However flash size was very
-  limited, compared to today's flash chips, when the EFI spec was written.
-
-## Current software constraints for x86_64 support
-The following constraints are coreboot limitations as it was intended to run in
-protected mode only. The code still assumes 32bit pointers in some places and thus:
-* The high dword of pointers must always be zero.
-* 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.
-* CBMEM must reside below 4GiB in physical memory.
-
-Any software within coreboot must not access memory resources above 4GiB until
-end of BS_DEV_RESOURCES in ramstage. Only at that point the full memory map is
-known and identity mapped.
-
-## Supported boards
-On the supported boards you can enable x86_64 compilation by setting the
-Kconfig `USE_X86_64_SUPPORT`. This config option is enabled if the SOC/CPU
-selects `HAVE_X86_64_SUPPORT`.
-
-## Protected mode wrappers
-On some platforms binary blobs are run to initialize parts of the hardware.
-When these binary blobs have been compiled for x86_32, then coreboot must
-switch to protected mode in order to call and run the blobs. Once the invoked
-blobs finish running, coreboot needs to switch back to long mode.
-
-Since every BLOB is different a SoC must be enabled to support x86_64 mode
-by providing the correct wrapper around the x86_32 BLOBs.
-
-## TODO
-* Support more platforms
-* Fix running VGA Option ROMs
-* Fix running MRC.bin (Sandy Bridge / Haswell boards)
-* Identity map memory above 4GiB in ramstage
-* Fine grained page tables for SMM:
-   * Must not have execute and write permissions for the same page.
-   * Must only allow TSEG pages to be marked as executable.
-   * Must reside in SMRAM.
-   * Must be placed together with SMM rmodule.
-* Support 64bit PCI BARs above 4GiB
-* Jump to compatible payloads in long mode
-
-## Porting other boards
-* Fix compilation errors
-* Test how well CAR works with x86_64 and paging
-* Improve mode switches
-* Test libgfxinit / VGA Option ROMs / FSP
-
-## Known bugs on real hardware
-
-According to Intel x86_64 mode hasn't been validated in CAR environments.
-However, coreboot developers working on x86_64 support have tried this on
-various Intel platforms, and so far haven't found any issues with CAR when
-running in x86_64 mode.
-
-## Known bugs on KVM enabled QEMU
-
-The `x86_64` reference code runs fine in QEMU's soft-cpu, but has serious issues
-when using KVM mode on some machines. This is due to various mechanisms trying
-to accelerate the code execution.
-
-Known issues in QEMU:
-* 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/cbfstool/index.md

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

Documentation/cbfstool/mmap_windows.md

@@ -36,8 +36,9 @@ The location of standard decode window is fixed in host address space
 `(4G - 16M) to 4G`. However, the platform is free to choose where the
 extended window lives in the host address space. Since `cbfstool`
 needs to know the exact location of the extended window, it allows the
-platform to pass in one parameter `mmap` that provide the base and the
-size of the extended window in host address space.
+platform to pass in two parameters `ext-win-base` and `ext-win-size`
+that provide the base and the size of the extended window in host
+address space.
 
 `cbfstool` creates two memory map windows using the knowledge about the
 standard decode window and the information passed in by the platform

Documentation/community/code_of_conduct.md

@@ -86,13 +86,8 @@ organizers may take any action they deem appropriate, up to and including
 a temporary ban or permanent expulsion from the community without warning
 (and without refund in the case of a paid event).
 
-As a part of running the project, coreboot leadership has the right to
-revoke privileges as they see fit. This is not done lightly. Over the
-history of the coreboot project, there have been only a handful of times
-where an action needed to be taken.
-
-Community organizers can be members of the arbitration team, the
-leadership board, or organizers of events and online communities.
+Community organizers can be members of the arbitration team, or organizers
+of events and online communities.
 
 ## Addressing Grievances
 
@@ -100,22 +95,6 @@ If you feel you have been falsely or unfairly accused of violating this
 Code of Conduct, you should notify the arbitration team with a concise
 description of your grievance.
 
-Discussions about these actions are not done publicly, for obvious
-reasons. If someone believes that the circumstances that led to an
-action have changed, please send an email to all the members of the
-arbitration team and/or leadership board for discussion.
-
-## Legal action
-
-Threatening or starting legal action against the project, sibling
-projects hosted on coreboot.org infrastructure, project or infrastructure
-maintainers leads to an immediate ban from coreboot.org and related
-systems.
-
-The ban can be reconsidered, but it's the default action because the
-people who pour lots of time and money into the projects aren't interested
-in seeing their resources used against them.
-
 ## Scope
 
 We expect all community participants (contributors, paid or otherwise;
@@ -125,21 +104,15 @@ communications pertaining to community business.
 
 ## Contact info
 
-Our arbitration team currently consists of the following people
-* Daniel Pono Takamori <pono@sfconservancy.org> (USA)
+Our arbitration team consists of the following people
+* Stefan Reinauer <stefan.reinauer@coreboot.org> (USA)
+* Patrick Georgi <patrick@coreboot.org> (Germany)
 * Ronald Minnich <rminnich@coreboot.org> (USA)
 * Martin Roth <martin@coreboot.org> (USA)
 
-If you have an issue with someone on the arbitration team, please reach
-out to the coreboot leadership board directly.
-
-The leadership board's information can be found on the
-[coreboot Leadership and Admin Boards](https://coreboot.org/leadership.html)
-page on the website.
-
 ## License and attribution
 
 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/cross_project_collaboration.md

@@ -1,56 +0,0 @@
-# Cross-Project Collaboration
-
-Open source firmware has become popular and important over the last several
-decades and is currently anchored in multiple key applications like industry,
-automotive, infrastructure and commodity PC systems. coreboot has a
-long-reaching history in all these applications and has become a vital
-alternative to proprietary firmware solutions. Since coreboot itself is
-minimalistic, other open source projects like SeaBIOS and flashrom help complete
-the overall user experience by providing a well established way to boot into an
-OS and easily reprogram the firmware on demand.
-
-Open source projects often lack funds and are heavily dependent on volunteer
-work by enthusiasts. coreboot has made its way over the many years it’s been
-running and is now able to operate its own paid infrastructure for various
-services like git, Gerrit and Jenkins, all of them are key factors for a
-worldwide collaboration and project success. Other small but still important
-projects do not have such resources and face infrastructure issues more often.
-
-Furthermore, often the same people do work for different open source projects.
-Therefore, it is important to support such projects where feasible.
-For instance, sharing the IT infrastructure can leverage quite some synergies
-as the tasks for different projects are quite similar, e.g. push code to public,
-review it in Gerrit, let Jenkins do a build and report back to Gerrit or provide
-a bug tracker platform where users and developers can report bugs and issues.
-The coreboot project already has servers providing such services and these have
-a huge amount of headroom to execute such tasks for other projects.
-Additionally, the developers working on multiple projects are supported as they
-can do their work with the same mindset while interfacing with common services
-among different projects. This not only improves cross-project collaboration but
-also does improve code quality because the developers do not have to switch
-between different project setups.
-
-Therefore, the coreboot project explicitly encourages collaboration with other
-open source projects in the firmware domain. Especially the already well
-established partnership with flashrom, SeaBIOS, and EM100 should continue to be
-maintained further on. This includes:
-
-* Sharing of the IT infrastructure
-* Sharing the critical services like git, Gerrit, Jenkins and the bugtracker
-* Sharing of the established communication methods via mailing list, Slack, IRC
-  or Discord
-* Sharing web services for web page or wikis and blog posts
-
-If there is interest in a collaboration, please reach out to
-coreboot@coreboot.org.
-
-The coreboot project is still responsible and in charge of its offered services
-to partner projects. The technical details of the collaboration will be
-discussed on a case-by-case basis with affected parties where coreboot project
-infrastructure maintainers have the lead.
-
-Note that it is expected that everyone using the coreboot services is expected
-to follow coreboot code-of-conduct policies at all times. In cases where the
-coreboot CoC is broken by someone working only on other projects in the coreboot
-infrastructure, the coreboot leadership will work with the leadership of the
-other project on the issue.

Documentation/community/forums.md

@@ -14,7 +14,7 @@ read its
 ## Real time chat
 
 We also have a real time chat room on [IRC](ircs://irc.libera.chat/#coreboot),
-also bridged to [Matrix](https://matrix.to/#/#coreboot:matrix.org) and a
+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
@@ -31,7 +31,7 @@ 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),
+best with [Google Meet](https://meet.google.com/syn-toap-agu),
 using [Google Docs](https://docs.google.com/document/d/1NRXqXcLBp5pFkHiJbrLdv3Spqh1Hu086HYkKrgKjeDQ/edit)
 for the agenda and meeting minutes. Neither the video conference nor
 the document require a Google account to participate, although editing

Documentation/community/index.md

@@ -1,11 +0,0 @@
-# Community
-
-```{toctree}
-:maxdepth: 1
-
-Code of Conduct <code_of_conduct.md>
-Language style <language_style.md>
-Community forums <forums.md>
-coreboot at conferences <conferences.md>
-Cross-Project Collaboration <cross_project_collaboration.md>
-```

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

@@ -1,48 +1,223 @@
-# Configuration file for the Sphinx documentation builder.
-#
-# For the full list of built-in configuration values, see the documentation:
-# https://www.sphinx-doc.org/en/master/usage/configuration.html
-
-# -- Project information -----------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
-
+# -*- coding: utf-8 -*-
 import subprocess
+from recommonmark.parser import CommonMarkParser
+import sphinx
 
-project = 'coreboot'
-copyright = 'CC-by 4.0 the coreboot project'
-author = 'the coreboot project'
+# Get Sphinx version
+major = 0
+minor = 0
+patchlevel = 0
+version = sphinx.__version__.split(".")
+if len(version) > 1:
+	major = int(version[0])
+	minor = int(version[1])
+	if len(version) > 2:
+		patchlevel = int(version[2])
 
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix(es) of source filenames.
+source_suffix = ['.md']
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'coreboot'
+copyright = u'CC-by 4.0 the coreboot project'
+author = u'the coreboot project'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The full version, including alpha/beta/rc tags.
 release = subprocess.check_output(('git', 'describe')).decode("utf-8")
 # The short X.Y version.
 version = release.split("-")[0]
 
+extensions = []
+# Load recommonmark, supported since 1.8+
+if major >= 2 or (major == 1 and minor >= 8):
+    extensions += ['recommonmark']
 
-# -- General configuration ---------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
-
-extensions = ["myst_parser"]
-
-myst_heading_anchors = 5
-myst_url_schemes = ["http", "https", "mailto", "ftp", "ircs"]
-
-templates_path = ['_templates']
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
-
-# The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+# Try to load DITAA
+try:
+    import sphinxcontrib.ditaa
+except ImportError:
+    print("Error: Please install sphinxcontrib.ditaa for ASCII art conversion\n")
+else:
+    extensions += ['sphinxcontrib.ditaa']
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = 'en'
+language = None
 
-# -- Options for HTML output -------------------------------------------------
-# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+# modindex_common_prefix = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+# keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- Options for HTML output ----------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
 html_theme = 'sphinx_rtd_theme'
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
-html_css_files = [
-    'theme_overrides.css',  # override wide tables in RTD theme
+
+html_context = {
+      'css_files': [
+        '_static/theme_overrides.css',  # override wide tables in RTD theme
+      ],
+}
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'corebootdoc'
+
+# -- Options for LaTeX output ---------------------------------------------
+
+latex_elements = {
+     # The paper size ('letterpaper' or 'a4paper').
+     #
+     # 'papersize': 'letterpaper',
+
+     # The font size ('10pt', '11pt' or '12pt').
+     #
+     # 'pointsize': '10pt',
+
+     # Additional stuff for the LaTeX preamble.
+     #
+     # 'preamble': '',
+
+     # Latex figure (float) alignment
+     #
+     # 'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+latex_documents = [
+    (master_doc, 'coreboot.tex', u'coreboot Documentation',
+     u'the coreboot project', 'manual'),
 ]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#
+# latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#
+# latex_use_parts = False
+
+# If true, show page references after internal links.
+#
+# latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#
+# latex_show_urls = False
+
+# Documents to append as an appendix to all manuals.
+#
+# latex_appendices = []
+
+# If false, will not define \strong, \code,	itleref, \crossref ... but only
+# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
+# packages.
+#
+# latex_keep_old_macro_names = True
+
+# If false, no module index is generated.
+#
+# latex_domain_indices = True
+
+
+# -- Options for manual page output ---------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+    (master_doc, 'coreboot', u'coreboot Documentation',
+     [author], 1)
+]
+
+# If true, show URL addresses after external links.
+#
+# man_show_urls = False
+
+
+# -- Options for Texinfo output -------------------------------------------
+
+# Grouping the document tree into Texinfo files. List of tuples
+# (source start file, target name, title, author,
+#  dir menu entry, description, category)
+texinfo_documents = [
+    (master_doc, 'coreboot', u'coreboot Documentation',
+     author, 'coreboot', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+enable_auto_toc_tree = True
+
+class MyCommonMarkParser(CommonMarkParser):
+    # remove this hack once upstream RecommonMark supports inline code
+    def visit_code(self, mdnode):
+        from docutils import nodes
+        n = nodes.literal(mdnode.literal, mdnode.literal)
+        self.current_node.append(n)
+
+# Documents to append as an appendix to all manuals.
+#
+# texinfo_appendices = []
+
+# If false, no module index is generated.
+#
+# texinfo_domain_indices = True
+
+# How to display URL addresses: 'footnote', 'no', or 'inline'.
+#
+# texinfo_show_urls = 'footnote'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#
+# texinfo_no_detailmenu = False
+
+
+def setup(app):
+    from recommonmark.transform import AutoStructify
+    # Load recommonmark on old Sphinx
+    if major == 1 and minor < 8:
+        app.add_source_parser('.md', MyCommonMarkParser)
+
+    app.add_config_value('recommonmark_config', {
+        'enable_auto_toc_tree': True,
+        'enable_auto_doc_ref': False, # broken in Sphinx 1.6+
+        'enable_eval_rst': True,
+        'url_resolver': lambda url: '/' + url
+    }, True)
+    app.add_transform(AutoStructify)

Documentation/contributing/coding_style.md

@@ -3,17 +3,17 @@
 This document describes the preferred C 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. They may be ignored in individual
-instances when there are good practical reasons to do so, and reviewers
-are in agreement.
+should overrule personal preference. But they may be ignored in
+individual instances when there are good practical reasons to do so, and
+reviewers are in agreement.
 
 Any style questions that are not mentioned in here should be decided
 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 generally match similar existing files in
+file -- otherwise, they should try to match similar existing files in
 coreboot.
 
 Bulk style changes to existing code ("cleanup patches") should avoid
@@ -24,8 +24,7 @@ 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
-except in cases where they directly match the style guide.)
+positives. They should not be bulk-applied to change existing code.)
 
 ## Indentation
 
@@ -43,8 +42,7 @@ Now, some people will claim that having 8-character indentations makes
 the code move too far to the right, and makes it hard to read on a
 80-character terminal screen. The answer to that is that if you need
 more than 3 levels of indentation, you're screwed anyway, and should
-fix your program.  Note that coreboot has expanded the 80 character
-limit to 96 characters to allow for modern wider screens.
+fix your program.
 
 In short, 8-char indents make things easier to read, and have the added
 benefit of warning you when you're nesting your functions too deep.
@@ -68,7 +66,7 @@ case 'm':
 case 'K':
 case 'k':
 	mem <<= 10;
-	__fallthrough;
+	/* fall through */
 default:
 	break;
 }
@@ -89,9 +87,7 @@ Outside of comments, documentation and except in Kconfig, spaces are
 never used for indentation, and the above example is deliberately
 broken.
 
-Get a decent editor and don't leave whitespace at the end of lines. This
-will actually keep the patch from being tested in the CI, so patches
-with ending whitespace cannot be merged.
+Get a decent editor and don't leave whitespace at the end of lines.
 
 ## Breaking long lines and strings
 
@@ -507,14 +503,18 @@ comments to note or warn about something particularly clever (or ugly),
 but try to avoid excess. Instead, put the comments at the head of the
 function, telling people what it does, and possibly WHY it does it.
 
-coreboot style for comments is the C89 "/* ... */" style. You may also
-use C99-style "// ..." comments for single-line comments.
+When commenting the kernel API functions, please use the kernel-doc
+format. See the files Documentation/kernel-doc-nano-HOWTO.txt and
+scripts/kernel-doc for details.
+
+coreboot style for comments is the C89 "/* ... */" style. You may
+use C99-style "// ..." comments.
 
 The preferred style for *short* (multi-line) comments is:
 
 ```c
 /* This is the preferred style for short multi-line
-   comments in the coreboot source code.
+   comments in the Linux kernel source code.
    Please use it consistently. */
 ```
 
@@ -522,8 +522,8 @@ The preferred style for *long* (multi-line) comments is:
 
 ```c
 /*
- * This is the preferred style for long multi-line
- * comments in the coreboot source code.
+ * This is the preferred style for multi-line
+ * comments in the Linux kernel source code.
  * Please use it consistently.
  *
  * Description:  A column of asterisks on the left side,
@@ -578,8 +578,7 @@ To do the latter, you can stick the following in your .emacs file:
 ```
 
 This will make emacs go better with the kernel coding style for C files
-below ~/src/linux-trees.  Obviously, this should be updated to match
-your own paths for coreboot.
+below ~/src/linux-trees.
 
 But even if you fail in getting emacs to do sane formatting, not
 everything is lost: use "indent".
@@ -627,6 +626,38 @@ config ADFS_FS_RW
 For full documentation on the configuration files, see the file
 Documentation/kbuild/kconfig-language.txt.
 
+Data structures
+---------------
+
+Data structures that have visibility outside the single-threaded
+environment they are created and destroyed in should always have
+reference counts. In the kernel, garbage collection doesn't exist (and
+outside the kernel garbage collection is slow and inefficient), which
+means that you absolutely _have_ to reference count all your uses.
+
+Reference counting means that you can avoid locking, and allows multiple
+users to have access to the data structure in parallel - and not having
+to worry about the structure suddenly going away from under them just
+because they slept or did something else for a while.
+
+Note that locking is _not_ a replacement for reference counting.
+Locking is used to keep data structures coherent, while reference
+counting is a memory management technique. Usually both are needed, and
+they are not to be confused with each other.
+
+Many data structures can indeed have two levels of reference counting,
+when there are users of different "classes". The subclass count counts
+the number of subclass users, and decrements the global count just once
+when the subclass count goes to zero.
+
+Examples of this kind of "multi-level-reference-counting" can be found
+in memory management ("struct mm_struct": mm_users and mm_count),
+and in filesystem code ("struct super_block": s_count and
+s_active).
+
+Remember: if another thread can find your data structure, and you don't
+have a reference count on it, you almost certainly have a bug.
+
 Macros, Enums and RTL
 ---------------------
 
@@ -696,19 +727,35 @@ The cpp manual deals with macros exhaustively. The gcc internals manual
 also covers RTL which is used frequently with assembly language in the
 kernel.
 
-Printing coreboot messages
+Printing kernel messages
 ------------------------
 
-coreboot developers like to be seen as literate. Do mind the spelling of
-coreboot messages to make a good impression. Do not use crippled words
+Kernel developers like to be seen as literate. Do mind the spelling of
+kernel messages to make a good impression. Do not use crippled words
 like "dont"; use "do not" or "don't" instead. Make the messages
 concise, clear, and unambiguous.
 
-coreboot messages do not have to be terminated with a period.
+Kernel messages do not have to be terminated with a period.
 
 Printing numbers in parentheses (%d) adds no value and should be
 avoided.
 
+There are a number of driver model diagnostic macros in
+<linux/device.h> which you should use to make sure messages are
+matched to the right device and driver, and are tagged with the right
+level: dev_err(), dev_warn(), dev_info(), and so forth. For messages
+that aren't associated with a particular device, <linux/printk.h>
+defines pr_debug() and pr_info().
+
+Coming up with good debugging messages can be quite a challenge; and
+once you have them, they can be a huge help for remote troubleshooting.
+Such messages should be compiled out when the DEBUG symbol is not
+defined (that is, by default they are not included). When you use
+dev_dbg() or pr_debug(), that's automatic. Many subsystems have
+Kconfig options to turn on -DDEBUG. A related convention uses
+VERBOSE_DEBUG to add dev_vdbg() messages to the ones already enabled
+by DEBUG.
+
 Allocating memory
 -----------------
 
@@ -745,7 +792,12 @@ The inline disease
 There appears to be a common misperception that gcc has a magic "make
 me faster" speedup option called "inline". While the use of inlines
 can be appropriate (for example as a means of replacing macros, see
-Chapter 12), it very often is not.
+Chapter 12), it very often is not. Abundant use of the inline keyword
+leads to a much bigger kernel, which in turn slows the system as a whole
+down, due to a bigger icache footprint for the CPU and simply because
+there is less memory available for the pagecache. Just think about it; a
+pagecache miss causes a disk seek, which easily takes 5 milliseconds.
+There are a LOT of cpu cycles that can go into these 5 milliseconds.
 
 A reasonable rule of thumb is to not put inline at functions that have
 more than 3 lines of code in them. An exception to this rule are the
@@ -766,9 +818,9 @@ Function return values and names
 
 Functions can return values of many different kinds, and one of the most
 common is a value indicating whether the function succeeded or failed.
-Such a value can be represented as an error-code integer (`CB_ERR_xxx`
-(negative number) = failure, `CB_SUCCESS` (0) = success) or a "succeeded"
-boolean (0 = failure, non-zero = success).
+Such a value can be represented as an error-code integer (-Exxx =
+failure, 0 = success) or a "succeeded" boolean (0 = failure, non-zero
+= success).
 
 Mixing up these two sorts of representations is a fertile source of
 difficult-to-find bugs. If the C language included a strong distinction
@@ -780,84 +832,21 @@ If the name of a function is an action or an imperative command,
 the function should return an error-code integer.  If the name
 is a predicate, the function should return a "succeeded" boolean.
 
-For example, "add work" is a command, and the `add_work()` function
-returns 0 for success or `CB_ERR` for failure. In the same way, "PCI
-device present" is a predicate, and the `pci_dev_present()` function
+For example, "add work" is a command, and the add_work() function
+returns 0 for success or -EBUSY for failure. In the same way, "PCI
+device present" is a predicate, and the pci_dev_present() function
 returns 1 if it succeeds in finding a matching device or 0 if it
 doesn't.
 
+All EXPORTed functions must respect this convention, and so should all
+public functions. Private (static) functions need not, but it is
+recommended that they do.
+
 Functions whose return value is the actual result of a computation,
 rather than an indication of whether the computation succeeded, are not
 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 to report failure.
-
-Error handling, assertions and die()
------------------------------
-
-As firmware, coreboot has no means to let the user interactively fix things when
-something goes wrong. We either succeed to boot or the device becomes a brick
-that must be recovered through complicated external means (e.g. a flash
-programmer). Therefore, coreboot code should strive to continue booting
-wherever possible.
-
-In most cases, errors should be handled by logging a message of at least
-`BIOS_ERR` level, returning out of the function stack for the failed feature,
-and then continuing execution. For example, if a function reading the EDID of an
-eDP display panel encounters an I2C error, it should print a "cannot read EDID"
-message and return an error code. The calling display initialization function
-knows that without the EDID there is no way to initialize the display correctly,
-so it will also immediately return with an error code without running its
-remaining code that would initialize the SoC's display controller. Execution
-returns further up the function stack to the mainboard initialization code
-which continues booting despite the failed display initialization, since
-display functionality is non-essential to the system. (Code is encouraged but
-not required to use `enum cb_err` error codes to return these errors.)
-
-coreboot also has the `die()` function that completely halts execution. `die()`
-should only be used as a last resort, since it results in the worst user
-experience (bricked system). It is generally preferrable to continue executing
-even after a problem was encountered that might be fatal (e.g. SPI clock
-couldn't be configured correctly), because a slight chance of successfully
-booting is still better than not booting at all. The only cases where `die()`
-should be used are:
-
-1. There is no (simple) way to continue executing. For example, when loading the
-   next stage from SPI flash fails, we don't have any more code to execute. When
-   memory initialization fails, we have no space to load the ramstage into.
-
-2. Continuing execution would pose a security risk. All security features in
-   coreboot are optional, but when they are configured in the user must be able
-   to rely on them. For example, if CBFS verification is enabled and the file
-   hash when loading the romstage doesn't match what it should be, it is better
-   to stop execution than to jump to potentially malicious code.
-
-In addition to normal error logging with `printk()`, coreboot also offers the
-`assert()` macro. `assert()` should be used judiciously to confirm that
-conditions are true which the programmer _knows_ to be true, in order to catch
-programming errors and incorrect assumptions. It is therefore different from a
-normal `if ()`-check that is used to actually test for things which may turn
-out to be true or false based on external conditions. For example, anything
-that involves communicating with hardware, such as whether an attempt to read
-from SPI flash succeeded, should _not_ use `assert()` and should instead just
-be checked with a normal `if ()` and subsequent manual error handling. Hardware
-can always fail for various reasons and the programmer can never 100% assume in
-advance that it will work as expected. On the other hand, if a function takes a
-pointer parameter `ctx` and the contract for that function (as documented in a
-comment above its declaration) specifies that this parameter should point to a
-valid context structure, then adding an `assert(ctx)` line to that function may
-be a good idea. The programmer knows that this function should never be called
-with a NULL pointer (because that's how it is specified), and if it was actually
-called with a NULL pointer that would indicate a programming error on account of
-the caller.
-
-`assert()` can be configured to either just print an error message and continue
-execution (default), or call `die()` (when `CONFIG_FATAL_ASSERTS` is set).
-Developers are encouraged to always test their code with this option enabled to
-make assertion errors (and therefore bugs) more easy to notice. Since assertions
-thus do not always stop execution, they should never be relied upon to be the
-sole guard against conditions that really _need_ to stop execution (e.g.
-security guarantees should never be enforced only by `assert()`).
+pointers; they use NULL or the ERR_PTR mechanism to report failure.
 
 Headers and includes
 ---------------
@@ -871,7 +860,7 @@ in the same directory that is not part of a normal include path gets included
 .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. This should not be the norm.
+documented with comments.
 
 Files should generally include every header they need a definition from
 directly (and not include any unnecessary extra headers). Excepted from
@@ -971,78 +960,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.
-
-Refactoring
------------
-Because refactoring existing code can add bugs to tested code, any
-refactors should be done only with serious consideration. Refactoring
-for style differences should only be done if the existing style
-conflicts with a documented coreboot guideline. If you believe that the
-style should be modified, the pros and cons can be discussed on the
-mailing list and in the coreboot leadership meeting.
-
-Similarly, the original author should be respected. Changing working
-code simply because of a stylistic disagreement is *prohibited*. This is
-not saying that refactors that are objectively better (simpler, faster,
-easier to understand) are not allowed, but there has to be a definite
-improvement, not simply stylistic changes.
-
-Basically, when refactoring code, there should be a clear benefit to
-the project and codebase. The reviewers and submitters get to make the
-call on how to interpret this.
-
-When refactoring, adding unit tests to verify that the post-change
-functionality matches or improves upon pre-change functionality is
-encouraged.
-
 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/contributing/git_commit_messages.md

@@ -1,79 +0,0 @@
-# Git Commit messages
-
-There are a number of different recommendations for git commit
-messages, so this is another one.
-
-It's expected that coreboot contributors already generally understand
-the idea of writing good git commit messages, so this is not trying
-to go over everything again. There are other tutorials that cover that.
-
-- [Linux Kernel tip tree Handbook](https://www.kernel.org/doc/html/latest/process/maintainer-tip.html#patch-subject)
-- [How to write a Git Commit Message](https://cbea.ms/git-commit/)
-
-## Line length
-
-- The subject line should be <= 65 characters, with an absolute maximum
-  of 72 characters
-- Prose in the commit message should be <= 72 characters
-- If reflowing prose to 72 characters can reduce the length of the
-  commit message by 2 or more lines, please reflow it. Using the entire
-  72 characters on a line when reasonable is recommended, but not
-  required.
-- Non-prose text in the body in the commit message does not need to be
-  wrapped at 72 characters. Examples: URLs, compiler output, or poetry.
-
-## Both Subject & body
-
-- Use the present tense. (The for loop exits too early, so ...", not
- "The for loop exited too early, so ...").
-- When using acronyms, make sure they're explained in the commit
-  message itself or in the [acronyms list](https://doc.coreboot.org/acronyms.html).
-
-## Commit message Subject Line
-
-- Start the subject line with a prefix denoting the area of the change.
-  Often part of the path can be used by that. Looking through existing
-  commit messages summaries with `git log --oneline ...` gives a good
-  idea. Because this prefix takes space used by the rest of the subject,
-  it should be kept short while still uniquely describing the area.
-  - Don't include `src/`
-  - Use abbreviations where possible:
-    - mb: mainboard
-    - vc: vendorcode
-- Don't end the subject line with a period.
-- Use the imperative mood. ("Fix whitespace", not "whitespace fixes").
-
-## Commit Message Body
-
-- Make sure the problem being solved by the commit is described. While
-  it may be obvious to the committer, it may not be obvious to others.
-- When referencing other commits use a 12 character hash and the subject
-  (e.g. `commit XXXXXXXXXXXX ("some commit")`). However, use `CB:XXXXX`
-  when referring to an open or abandoned change on Gerrit.
-- When using a URL in a commit message, use archive.org when possible.
-  URLs often get changed or go stale, so this keeps them stable.
-- Make sure that all changes in a patch are addressed in the commit
-  message.
-- A TEST= tag is highly recommended, but not required. This lets people
-  know whether you tested it by booting the board or just by compiling.
-- All but the most trivial of patches should generally have a body.
-- A BUG= tag can be added when the author wants to indicate that the
-  patch is or is not related to a bug. This can be either in coreboot's
-  issue tracker, or a private issue tracker.
-    - `BUG=b:####` is used by the Google internal issue tracker.
-    - `BUG=chromium:####` indicates the Chromium public tracker at
-      https://issues.chromium.org/
-    - `BUG=CID ####` can be used to indicate coverity error fixes.
-    - `BUG=https://...` can be used to link directly to a public
-      tracker.
-- The BRANCH= tag is used in cases where a patch needs to be added to a
-  specific downstream branch. This is never required by the coreboot
-  project.
-
-## Footers
-
-- The Signed-off-by line is required (Jenkins forces this).
-- The Change ID is required (Gerrit forces this.)
-- When adding a patch that has already gone through another git or
-  gerrit, the footers from those previous commits may be added, but
-  keep the list reasonable.

Documentation/contributing/gsoc.md

@@ -1,286 +0,0 @@
-# Google Summer of Code
-
-## Organization admins
-
-The *organization admins* are managing the GSoC program for the coreboot
-organization.
-
-The organization admins are:
-
-  * Felix Singer (primary)
-  * Martin Roth
-  * David Hendricks
-
-
-## 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.
-
-
-## 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]
-
-  * [Organization Admin Tips][GSoC Organization Admin Tips]
-
-
-## 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 [small 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
-[GSoC Organization Admin Tips]: https://developers.google.com/open-source/gsoc/help/oa-tips

Documentation/contributing/index.md

@@ -1,29 +0,0 @@
-# Contributing
-
-```{toctree}
-:maxdepth: 1
-
-Coding Style <coding_style.md>
-Gerrit Guidelines <gerrit_guidelines.md>
-Commit Message Guidelines <git_commit_messages.md>
-Project Ideas <project_ideas.md>
-Documentation Ideas <documentation_ideas.md>
-Google Summer of Code <gsoc.md>
-```
-
-The coreboot project uses the Developer Certificate of Origin as its
-policy of accepting contributions. As such, a submitter bears the burden
-that they have all necessary rights to submit their contribution to the
-project under the project's licenses as appropriate. Violations of third
-party rights will lead to the code's removal or replacement as suitable
-to bring the project back into compliance.
-
-This applies no matter under which circumstances a contribution has been
-created: legal frameworks, work contracts, Generative Artificial
-Intelligence ("AI") tooling, or other aspects that may affect the
-ownership and copyright status of a contribution are outside the
-project's control.
-
-See the [Sign-off procedure] for more information.
-
-[Sign-off procedure]: gerrit_guidelines.md#sign-off-procedure

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.
 
-## Small 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 small 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/coreboot-untested-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,
@@ -63,6 +45,7 @@ non-Linux builds or Docker for different Linux distributions.
 * hardware requirements: Nothing special
 
 ### Mentors
+* Patrick Georgi <patrick@georgi.software>
 
 ## Support Power9/Power8 in coreboot
 There are some basic PPC64 stubs in coreboot, and there's open hardware
@@ -86,8 +69,8 @@ across architectures.
 ## 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,
-FILO, or Linux-as-Payload.
+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
 combination of payload and architecture to support.
@@ -129,6 +112,7 @@ their bug reports.
   going on from the resulting logs.
 
 ### Mentors
+* Patrick Georgi <patrick@georgi.software>
 
 ## Extend Ghidra to support analysis of firmware images
 [Ghidra](https://ghidra-sre.org) is a recently released cross-platform

Documentation/corebootBuildingGuide.tex

@@ -386,7 +386,7 @@ want to submit all commits in the currently checked-out branch for
 review on gerrit:
 { \small
 \begin{verbatim}
-$ git config remote.origin.push HEAD:refs/for/main
+$ git config remote.origin.push HEAD:refs/for/master
 \end{verbatim}
 }
 
@@ -399,10 +399,10 @@ $ make gitconfig
 
 \subsection{Work flow}
 
-It is recommended that you make a new branch when you start to work, not pushing changes to main.
+It is recommended that you make a new branch when you start to work, not pushing changes to master.
 { \small
 \begin{verbatim}
-$ git checkout main -b mybranch
+$ git checkout master -b mybranch
 \end{verbatim}
 }
 After you have done your changes, run:
@@ -452,7 +452,7 @@ make a new local commit that fixes the issues reported by the
 reviewers, then rebase the change by preserving the same Change-ID. We
 recommend you to use the git rebase command in interactive mode,
 
-Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/main.
+Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/master.
 
 %
 % Working with Gerrit
@@ -474,9 +474,9 @@ click \url{https://review.coreboot.org}
 |Search for status:open                                     |
 +-----------------------------------------------------------+
 |Subject      Status   Owner  Project  Branch Updated CR V  |
-|cpu: Rename..      Alexandru coreboot main   1:20 PM +1    |
-|cpu: Only a..      Alexandru coreboot main   1:17 PM    X  |
-|arch/x86: D..      Alexandru coreboot main   1:09 PM       |
+|cpu: Rename..      Alexandru coreboot master 1:20 PM +1    |
+|cpu: Only a..      Alexandru coreboot master 1:17 PM    X  |
+|arch/x86: D..      Alexandru coreboot master 1:09 PM       |
 |                                                           |
 |                                                  Next ->  |
 |Press '?' to view keyboard shortcuts | Powered by Gerrit   |
@@ -637,7 +637,7 @@ Gerrit makes reviews easier by showing changes in a side-by-side
 display, and allowing inline comments to be added by any reviewer.
 
 Gerrit simplifies Git based project maintainership by permitting any
-authorized user to submit changes to the upstream Git repository, rather
+authorized user to submit changes to the master Git repository, rather
 than requiring all approved changes to be merged in by hand by the
 project maintainer. This functionality enables a more centralized
 usage of Git.

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

@@ -17,25 +17,6 @@ running on the Embedded Controller (EC) – a small microcontroller which provid
 functions like battery management, keyboard support, and sensor interfacing –
 is open source as well.
 
-### Nitrokey
-
-[Nitrokey](https://nitrokey.com) is a german IT security hardware vendor which
-offers a range of laptops, PCs, HSMs, and networking devices with coreboot and
-[Dasharo](https://dasharo.com/). The devices come with neutralized Intel
-Management Engine (ME) and with pre-installed [Heads](http://osresearch.net) or
-EDK2 payload providing measured boot and verified boot protection. For
-additional security the systems can be physically sealed and pictures of those
-sealings are sent via encrypted email.
-
-### NovaCustom laptops
-
-[NovaCustom](https://novacustom.com) 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.
-
 ### PC Engines APUs
 
 [PC Engines](https://pcengines.ch) designs and sells embedded PC hardware that
@@ -43,15 +24,12 @@ 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).
 
-### Protectli
+### System76
 
-[Protectli](https://protectli.com) is dedicated to providing reliable,
-cost-effective, and secure computer equipment with coreboot-based firmware
-tailored for their hardware. It comes with the [Dasharo](#dasharo)
-firmware, maintained by [3mdeb](https://3mdeb.com/). Protectli hardware has
-verified support for many popular operating systems, such as Linux distributions,
-FreeBSD, and Windows. Support includes Debian, Ubuntu, OPNsense, pfSense,
-ProxMox VE, VMware ESXi, Windows 10 and 11, and many more.
+[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
 
@@ -60,31 +38,26 @@ 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.
 
-### 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.
-
 ## After-market firmware
 
-### Dasharo
+### Libreboot
 
-[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.
+[Libreboot](https://libreboot.org) is a downstream coreboot distribution that
+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.
 
-Contributions are welcome,
-[this document](https://docs.dasharo.com/ways-you-can-help-us/).
+### MrChromebox
+
+[MrChromebox](https://mrchromebox.tech/) provides upstream coreboot firmware
+images for the vast majority of x86-based Chromebooks and Chromeboxes, using
+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
+(i.e., they run Windows as well as Linux). They also offer updated CPU
+microcode, as well as firmware updates for the device's embedded controller
+(EC). This firmware "takes the training wheels off" your ChromeOS device :)
 
 ### Heads
 
@@ -99,25 +72,6 @@ Heads is not just another Linux distribution – it combines physical hardening
 of specific hardware platforms and flash security features with custom coreboot
 firmware and a Linux boot loader in ROM.
 
-### Libreboot
-
-[Libreboot](https://libreboot.org) is a downstream coreboot distribution that
-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.
-
-### 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
-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
-(i.e., they run Windows as well as Linux). They also offer updated CPU
-microcode, as well as firmware updates for the device's embedded controller
-(EC). This firmware "takes the training wheels off" your ChromeOS device :)
-
 ### Skulls
 
 [Skulls](https://github.com/merge/skulls) provides firmware images for

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/acpi_fan_control.md

@@ -1,387 +0,0 @@
-# ACPI Active Cooling with Five-Level Fan Control
-
-## Overview
-
-This document describes an ACPI-based thermal management pattern used across multiple coreboot mainboards. The implementation uses ACPI thermal zones with active cooling policies to control fan speed based on CPU temperature through a five-level power resource state machine.
-
-This pattern is particularly prevalent on Intel-based mainboards using SuperIO environmental controllers for fan PWM control.
-
-## Mainboards Using This Pattern
-
-The following mainboards implement this five-level ACPI fan control pattern:
-
-### Google Chromebooks
-- **google/beltino** - Haswell Chromebox
-  - All variants (mccloud, monroe, panther, tricky, zako) use a single implementation
-- **google/jecht** - Broadwell Chromebox
-  - Each variant (jecht, rikku, guado, tidus) has a unique implementation
-
-### Samsung
-- **samsung/stumpy** - Sandy Bridge Chromebox
-
-### Intel Reference Boards
-- **intel/wtm2** - Haswell ULT reference board
-- **intel/baskingridge** - Haswell desktop reference board
-- **intel/emeraldlake2** - Ivy Bridge reference board
-
-## Architecture
-
-### Hardware Components
-
-Common hardware elements across implementations:
-
-- **Temperature Sensor**: SuperIO TMPIN3 reads CPU temperature via PECI (Platform Environment Control Interface)
-- **Fan Controller**: SuperIO Environmental Controller (ENVC) with PWM output
-  - Fan2 (F2PS) on Google Chromebooks
-  - Fan3 (F3PS) on Intel/Samsung boards
-- **CPU**: Provides temperature data as an offset from Tj_max (maximum junction temperature)
-
-### ACPI Components
-
-- **Thermal Zone**: `\_TZ.THRM` - Main thermal management zone
-- **Fan Devices**: `FAN0` through `FAN4` - Five fan speed levels
-- **Power Resources**: `FNP0` through `FNP4` - Control fan state transitions
-- **Active Cooling Levels**: `_AC0` through `_AC4` - Temperature thresholds for each fan level
-
-## Fan Speed Levels
-
-The system implements **5 fan speed levels** (0-4), where:
-
-- **Level 0**: Maximum fan speed (highest cooling, activated at highest temperature)
-- **Level 1**: High fan speed
-- **Level 2**: Medium fan speed
-- **Level 3**: Low fan speed
-- **Level 4**: Minimum fan speed (idle/baseline cooling, default state)
-
-The system starts at **Level 4** (minimum speed) and increases to lower-numbered levels as temperature rises.
-
-## Temperature Management
-
-### Temperature Reading Process
-
-1. **Raw PECI Reading**: Read from `\_SB.PCI0.LPCB.SIO.ENVC.TIN3`
-   - Returns a value representing offset from Tj_max
-   - Value 0x80 indicates "no reading available"
-   - Values 0 or 255 are invalid
-
-2. **Temperature Calculation**:
-   ```
-   actual_temperature = Tj_max - (255 - raw_value)
-   ```
-
-3. **Conversion to ACPI Format**: Convert from Celsius to deci-Kelvin:
-   ```
-   deci_kelvin = (celsius * 10) + 2732
-   ```
-
-### Critical Temperature Handling
-
-Most implementations include safety logic in the `_TMP` method:
-- If temperature reaches `\TMAX` (Tj_max), logs a critical event
-- Waits 1 second for sensor re-poll
-- Re-reads temperature to confirm
-- Reports the current temperature to the OS
-
-### Temperature Thresholds
-
-Thresholds are defined in board-specific headers (typically `thermal.h`):
-
-- `FAN0_THRESHOLD_ON/OFF` - Trigger points for maximum fan speed
-- `FAN1_THRESHOLD_ON/OFF` - Trigger points for high fan speed
-- `FAN2_THRESHOLD_ON/OFF` - Trigger points for medium fan speed
-- `FAN3_THRESHOLD_ON/OFF` - Trigger points for low fan speed
-- `FAN4_PWM` - PWM value for minimum fan speed
-
-Each level has hysteresis (different ON/OFF thresholds) to prevent rapid cycling.
-
-## Active Cooling Implementation
-
-### Active Cooling Methods (`_ACx`)
-
-Each `_ACx` method returns a temperature threshold:
-- When system temperature **exceeds** the threshold, the OS activates the corresponding fan level
-- When temperature **falls below** the threshold, the OS may deactivate that level
-
-**Hysteresis Logic**:
-```
-Method (_AC0) {
-    If (\FLVL <= 0) {
-        Return (CTOK (FAN0_THRESHOLD_OFF))  // Higher temp to turn off
-    } Else {
-        Return (CTOK (FAN0_THRESHOLD_ON))   // Lower temp to turn on
-    }
-}
-```
-
-This prevents oscillation by requiring different temperatures to activate vs. deactivate a fan level.
-
-### Active Cooling Lists (`_ALx`)
-
-Each `_ALx` associates a cooling threshold with a fan device:
-```
-Name (_AL0, Package () { FAN0 })  // FAN0 activated at _AC0 threshold
-Name (_AL1, Package () { FAN1 })  // FAN1 activated at _AC1 threshold
-Name (_AL2, Package () { FAN2 })  // FAN2 activated at _AC2 threshold
-Name (_AL3, Package () { FAN3 })  // FAN3 activated at _AC3 threshold
-Name (_AL4, Package () { FAN4 })  // FAN4 activated at _AC4 threshold
-```
-
-## Power Resource State Machine
-
-Each fan level has an associated power resource (`FNP0` through `FNP4`) that manages state transitions.
-
-### State Transitions
-
-**FNP0-FNP3** (Levels 0-3):
-- `_STA`: Returns 1 (ON) if `\FLVL <= level`, else 0 (OFF)
-- `_ON`: Transitions **to** this level from a higher-numbered level
-- `_OFF`: Transitions **away** from this level to the next higher-numbered level
-
-Example for FNP0 (maximum cooling):
-```
-PowerResource (FNP0, 0, 0) {
-    Method (_STA) {
-        If (\FLVL <= 0) { Return (1) }  // Active if at max cooling
-        Else { Return (0) }
-    }
-    Method (_ON) {
-        If (!_STA ()) {                  // If not already active
-            \FLVL = 0                     // Set to max cooling
-            \_SB.PCI0.LPCB.SIO.ENVC.F2PS = FAN0_PWM  // Set fan PWM
-            Notify (\_TZ.THRM, 0x81)       // Notify thermal zone
-        }
-    }
-    Method (_OFF) {
-        If (_STA ()) {                   // If currently active
-            \FLVL = 1                     // Transition to level 1
-            \_SB.PCI0.LPCB.SIO.ENVC.F2PS = FAN1_PWM  // Set corresponding PWM
-            Notify (\_TZ.THRM, 0x81)       // Notify thermal zone
-        }
-    }
-}
-```
-
-**FNP4** (Minimum cooling - Level 4):
-- `_STA`: Returns 1 if `\FLVL <= 4` (always true in normal operation)
-- `_ON`: Transitions to minimum cooling state
-- `_OFF`: **No-op** - This is the minimum state, cannot transition lower
-
-### Critical: FNP4._OFF Must Be a No-Op
-
-This is **essential for Windows compatibility**:
-
-**Problem**: Early implementations had `_OFF` setting `\FLVL = 4` and PWM values, identical to `_ON`. This violated ACPI power resource requirements:
-- After `_ON` is called, `_STA` must eventually return 1 (ON)
-- After `_OFF` is called, `_STA` must eventually return 0 (OFF)
-
-Since both methods resulted in `\FLVL = 4`, and `_STA` returns 1 when `\FLVL <= 4`, the power resource could never properly transition to OFF state.
-
-**Solution**: Make `_OFF` a no-op since FAN4 is the minimum cooling state:
-```
-PowerResource (FNP4, 0, 0) {
-    Method (_STA) {
-        If (\FLVL <= 4) { Return (1) }
-        Else { Return (0) }
-    }
-    Method (_ON) {
-        If (!_STA ()) {
-            \FLVL = 4
-            \_SB.PCI0.LPCB.SIO.ENVC.F2PS = FAN4_PWM
-            Notify (\_TZ.THRM, 0x81)
-        }
-    }
-    Method (_OFF) {
-        // FAN4 is the minimum cooling state (idle/lowest fan speed)
-        // There is no lower state to transition to, so _OFF is a no-op
-        // to maintain proper ACPI power resource state machine semantics
-    }
-}
-```
-
-This maintains proper ACPI state machine semantics and ensures Windows compatibility while maintaining Linux compatibility.
-
-## Passive Cooling
-
-In addition to active (fan-based) cooling, most implementations support passive cooling:
-
-- `_PSV`: Returns passive cooling threshold temperature
-- `_PSL`: Returns list of processors to throttle
-- `_TC1`, `_TC2`: Thermal constants for passive cooling algorithm
-- `_TSP`: Thermal sampling period (typically 20 deciseconds = 2 seconds)
-
-When temperature exceeds `_PSV` threshold, the OS throttles CPUs listed in `_PSL` to reduce heat generation.
-
-## Polling and Notification
-
-- `_TZP`: Thermal zone polling period (typically 100 deciseconds = 10 seconds)
-  - OS polls `_TMP` at this interval to check temperature
-
-- `Notify (\_TZ.THRM, 0x81)`: Thermal zone change notification
-  - Sent whenever fan level changes
-  - Tells OS to re-evaluate thermal zone immediately
-
-## Initialization
-
-The `_INI` method runs when the thermal zone is initialized:
-
-```
-Method (_INI) {
-    \FLVL = 4                             // Start at minimum cooling
-    \_SB.PCI0.LPCB.SIO.ENVC.F2PS = FAN4_PWM  // Set initial fan PWM
-    Notify (\_TZ.THRM, 0x81)               // Initial notification
-}
-```
-
-## Operating System Interaction
-
-### Thermal Policy Flow
-
-1. **OS boots** → Executes `_INI` → Fan starts at Level 4
-2. **OS polls `_TMP`** periodically → Gets current temperature
-3. **Temperature rises** → Exceeds `_AC3` threshold
-4. **OS calls `FAN3._ON`** → Power resource FNP3 activated → `\FLVL = 3`
-5. **Temperature continues rising** → Exceeds `_AC2` threshold
-6. **OS calls `FAN2._ON`** → Power resource FNP2 activated → `\FLVL = 2`
-7. **Temperature drops** → Falls below `_AC2` threshold
-8. **OS calls `FAN2._OFF`** → `\FLVL = 3` → Returns to Level 3
-9. **Cycle continues** based on temperature changes
-
-### Critical Temperature
-
-If temperature reaches `_CRT` threshold:
-- OS initiates emergency shutdown
-- Prevents hardware damage from overheating
-
-## Global Variables
-
-Standard variables used across implementations:
-
-- `\FLVL`: Current fan level (0-4)
-- `\TMAX`: Maximum junction temperature (Tj_max)
-- `\TCRT`: Critical shutdown temperature
-- `\TPSV`: Passive cooling threshold temperature
-
-## Configuration
-
-Fan thresholds and PWM values are defined in board-specific headers, typically:
-```
-src/mainboard/<vendor>/<board>/include/thermal.h
-```
-or
-```
-src/mainboard/<vendor>/<board>/variants/<variant>/include/variant/thermal.h
-```
-
-Example configuration:
-```c
-#define FAN0_THRESHOLD_ON   75  // Temperature to activate max fan (°C)
-#define FAN0_THRESHOLD_OFF  65  // Temperature to deactivate max fan (°C)
-#define FAN0_PWM            0xFF // PWM duty cycle value (max)
-
-#define FAN1_THRESHOLD_ON   65
-#define FAN1_THRESHOLD_OFF  55
-#define FAN1_PWM            0xC0
-
-#define FAN2_THRESHOLD_ON   55
-#define FAN2_THRESHOLD_OFF  45
-#define FAN2_PWM            0x80
-
-#define FAN3_THRESHOLD_ON   45
-#define FAN3_THRESHOLD_OFF  35
-#define FAN3_PWM            0x40
-
-#define FAN4_PWM            0x20  // Idle fan speed
-```
-
-## Implementation Variations
-
-While the core pattern is consistent, there are some variations:
-
-### PWM Output Selection
-- **Google boards**: Use Fan2 PWM (`F2PS`)
-- **Intel/Samsung boards**: Use Fan3 PWM (`F3PS`)
-
-### Guard Checks
-Some implementations wrap state changes with `_STA()` checks:
-```
-Method (_ON) {
-    If (!_STA ()) {  // Only change state if not already active
-        // ... state change
-    }
-}
-```
-
-Others omit the guard and always perform the state change.
-
-### Temperature Reading
-- Most implementations read from SuperIO TMPIN3 via PECI
-- Some (like intel/wtm2) use simplified stub implementations for reference
-
-### Dynamic Thermal Tables
-The google/jecht/tidus variant includes multiple thermal tables that can be switched based on system temperature sensors, allowing more sophisticated thermal management.
-
-## Compatibility Notes
-
-### Linux
-- More lenient ACPI parser
-- Tolerates minor state machine violations
-- Worked with buggy FNP4._OFF implementations
-
-### Windows
-- Stricter ACPI compliance checking
-- Requires proper power resource state machine behavior
-- **Requires the FNP4._OFF no-op fix** to function correctly
-- May disable thermal zone entirely if ACPI violations detected
-
-## Debugging
-
-To debug fan control issues:
-
-1. **Check ACPI errors**: Look for thermal zone errors in OS logs
-   - Linux: `dmesg | grep -i acpi` or check `/sys/class/thermal/`
-   - Windows: Event Viewer → System → ACPI errors
-
-2. **Monitor temperature**: Use OS tools to check `_TMP` readings
-   - Linux: `/sys/class/thermal/thermal_zone*/temp`
-   - Windows: HWiNFO64, HWMonitor
-
-3. **Check fan level**: Monitor `\FLVL` value (ACPI debugger or custom logging)
-
-4. **Verify thresholds**: Ensure threshold values are appropriate for the hardware
-
-5. **Test state transitions**: Verify each fan level activates at correct temperature
-
-6. **ACPI table inspection**: Decompile DSDT/SSDT tables with `acpidump` and `iasl` to verify implementation
-
-## Implementation Checklist
-
-When implementing this pattern on a new board:
-
-- [ ] Define all 5 fan threshold pairs (ON/OFF) with appropriate hysteresis
-- [ ] Define PWM values for all 5 fan levels
-- [ ] Implement temperature sensor reading (typically PECI via SuperIO)
-- [ ] Implement CTOK conversion method (°C to deci-Kelvin)
-- [ ] Create all 5 PowerResource objects (FNP0-FNP4)
-- [ ] **Critical**: Ensure FNP4._OFF is a no-op (not setting state)
-- [ ] Create all 5 Fan Device objects (FAN0-FAN4) with correct `_PR0` references
-- [ ] Implement _ACx methods with hysteresis logic
-- [ ] Define _ALx packages linking to fan devices
-- [ ] Implement _INI to set initial state
-- [ ] Implement _TMP with error handling
-- [ ] Define _CRT, _PSV, _PSL for critical/passive cooling
-- [ ] Set appropriate _TZP polling interval
-- [ ] Test on both Linux and Windows
-
-## References
-
-- [ACPI Specification 6.5 - Thermal Management](https://uefi.org/specs/ACPI/6.5/)
-- [ACPI Specification - ThermalZone Objects](https://uefi.org/specs/ACPI/6.5/11_Thermal_Management.html)
-- [ACPI Specification - PowerResource Objects](https://uefi.org/specs/ACPI/6.5/07_Power_and_Performance_Mgmt.html#power-resources)
-- Intel PECI Specification
-- SuperIO vendor datasheets (ITE, Nuvoton, Winbond, etc.)
-
-## See Also
-
-- [Intel DPTF](dptf.md) - More sophisticated Intel Dynamic Platform and Thermal Framework
-- [ACPI GPIO Documentation](../acpi/gpio.md)
-

Documentation/drivers/cbfs_smbios.md

@@ -1,143 +0,0 @@
-# CBFS SMBIOS hooks
-
-The document describes the coreboot options how to make CBFS files populate
-platform-unique SMBIOS data.
-
-## SMBIOS Serial Number
-
-The [DMTF SMBIOS specification] defines a field in the type 1 System
-Information and type 2 Baseboard Information called Serial Number. It
-is a null-terminated string field assumed to be unique per platform. Certain
-mainboard ports have SMBIOS hooks to generate the Serial Numbers from external
-data, e.g. Lenovo Thinkpads (see DRIVER_LENOVO_SERIALS). This driver aims to
-provide an option to populate the Serial Numbers from CBFS for boards that
-can't generate the it from any source.
-
-### Usage
-
-In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers`
-and select an option `Serial number in CBFS`. The Kconfig system will enable
-`DRIVERS_GENERIC_CBFS_SERIAL` 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 serial number:
-
-```shell
-./build/cbfstool build/coreboot.rom add -n serial_number -t raw -f /path/to/serial_file.txt
-```
-
-Where `serial_file.txt` is the unterminated string representation of the SMBIOS
-type 1 or type 2 Serial Number, e.g. `5Q4Q7Y1`. 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 serial_number -t raw \
-	-f /path/to/serial_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 serial_number -t raw \
-	-f /path/to/serial_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 Serial Number from running system (if it exists) using one
-of the following commands:
-
-```shell
-# Type 1
-echo -n `sudo dmidecode -s system-serial-number` > serial_file.txt
-# OR Type 2
-echo -n `sudo dmidecode -s baseboard-serial-number` > serial_file.txt
-```
-
-Ensure the file does not end with whitespaces like LF and/or CR. The above
-commands will not add any whitespaces. The driver automatically terminates the
-Serial Number with the NULL character. If the CBFS file is not present, the
-driver will fall back to the string defined in `MAINBOARD_SERIAL_NUMBER` build
-option.
-
-Please note that this driver provides `smbios_mainboard_serial_number` hook
-overriding the default implementation which returns `MAINBOARD_SERIAL_NUMBER`
-build option. If you wish to populate only type 2 Serial Number field your
-board code needs to implement `smbios_system_serial_number`, otherwise the weak
-implementation of `smbios_system_serial_number` will call
-`smbios_mainboard_serial_number` from the `DRIVERS_GENERIC_CBFS_SERIAL`
-implementation overriding it. So selecting the `DRIVERS_GENERIC_CBFS_SERIAL`
-has a side-effect of populating both SMBIOS type 1 and type 2 Serial Numbers
-if the board does not implement its own `smbios_system_serial_number`.
-
-There is also SMBIOS type 3 Chassis Information Serial Number, but it is not
-populated by `DRIVERS_GENERIC_CBFS_SERIAL` nor by the default weak
-implementation (returns empty string). If you wish to populate type 3 Serial
-Number, your board code should override the default
-`smbios_chassis_serial_number` weak implementation.
-
-## 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/cfr.md

@@ -1,297 +0,0 @@
-# CFR - coreboot form representation
-
-This documents the API exposed by coreboot to be consumed by
-loaded OS image or payload.
-
-## Problem Statement
-
-As per coreboot design there's no UI present to change firmware
-related options like "Hyper-Theading Enable". There's no way of
-knowing what options are supported, if they are supported in the
-current configuration and what they do.
-
-The `USE_OPTION_TABLE` Kconfig allows to integrate a list of
-mainboard specific options into coreboot tables when the option
-API is using the *CMOS NVRAM*. It has no meaning if another option
-API is being used.
-
-## Design Proposal
-
-Propose a new coreboot table that is independent from the option
-backend. The coreboot table is generated from coreboot ramstage
-code.
-
-Every possible boot option is described by its name, the user
-visible name, a help text, a default value and status flags.
-All strings are in ASCII.
-
-The boot options are grouped into forms, where each form hold
-one or more options. Boot options that are not used in the current
-boot flow, and are never reachable should be marked as hidden.
-Dependecies between options can be defined in the code and should
-be evaluated by the CFR parser/UI.
-
-A boot option can be one of the following types:
-- boolean
-- number
-- enum
-- string
-
-All of the information is *Position Independent Data*. That is, it is
-safe to relocate any of the information without its meaning/correctness
-changing.
-
-CFR records form a tree structure. Every record starts with a `tag`
-and a `size` field as generic header:
-
-```C
-struct __packed lb_cfr_header {
-  uint32_t tag;
-  uint32_t size;
-};
-```
-
-The size of a record includes the size of its own fields plus the size of all
-child records. A record can have none or multiple child records.
-The record `tag` must be known by the parser to parse the record and its
-sub records. If it is not known to the parser it can simply skip it by
-jumping `size` bytes forward.
-
-The coreboot table containing the CFR tree has the tag `LB_TAG_CFR`.
-
-The public API can be found in
-`src/commonlib/include/commonlib/cfr.h` and
-`src/commonlib/include/commonlib/coreboot_tables.h`.
-
-## Implementation design
-### Tags
-Tags identify the structure defined in `src/commonlib/include/commonlib/cfr.h`.
-Every struct might be immediately followed by additional structs (so called
-sub nodes), having their own tag and size field. The sum of all sub nodes size
-fields plus the size of the struct itself equals the size field.
-
-* CFR_TAG_OPTION_FORM
-
-   Used in `struct lb_cfr_option_form` to describe a group of options. Every
-   sub node is one option that should be displayed in the order found in
-   memory.
-
-   Allowed sub nodes:
-    - `CFR_TAG_OPTION_ENUM`
-    - `CFR_TAG_OPTION_NUMBER`
-    - `CFR_TAG_OPTION_BOOL`
-    - `CFR_TAG_OPTION_VARCHAR`
-    - `CFR_TAG_OPTION_FORM`
-    - `CFR_TAG_OPTION_COMMENT`
-    - `CFR_TAG_VARCHAR_UI_NAME`
-
-   Required sub nodes:
-    - `CFR_TAG_VARCHAR_UI_NAME`
-
-* CFR_TAG_ENUM_VALUE
-
-   Used in `struct lb_cfr_enum_value` to describe a numeric value to be
-   used in a parent `CFR_TAG_OPTION_ENUM`.
-
-   Allowed sub nodes:
-     - `CFR_TAG_VARCHAR_UI_NAME`
-
-   Required sub nodes:
-     - `CFR_TAG_VARCHAR_UI_NAME`
-
-* CFR_TAG_OPTION_ENUM
-
-   Used in `struct lb_cfr_numeric_option` to describe a numeric variable with
-   a predefined selection of possible values in the referenced variable.
-
-   Allowed sub nodes:
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-     - `CFR_TAG_ENUM_VALUE`
-     - `CFR_TAG_VARCHAR_UI_HELPTEXT`
-
-   Required sub nodes:
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-     - `CFR_TAG_ENUM_VALUE`
-
-* CFR_TAG_OPTION_NUMBER
-
-   Used in `struct lb_cfr_numeric_option` to describe a numeric variable with
-   any possible value in the referenced variable.
-
-   Allowed sub nodes:
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-     - `CFR_TAG_VARCHAR_UI_HELPTEXT`
-
-   Required sub nodes:
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-
-* CFR_TAG_OPTION_BOOL
-
-   Used in `struct lb_cfr_numeric_option` to describe a numeric variable with
-   the possible values [0, 1] in the referenced variable.
-
-   Allowed sub nodes:
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-     - `CFR_TAG_VARCHAR_UI_HELPTEXT`
-
-   Required sub nodes:
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-
-* CFR_TAG_OPTION_VARCHAR
-
-   Used in `struct lb_cfr_varchar_option` to describe an ASCII string
-   stored in the referenced variable.
-
-   *Example:* Linux kernel cmdline.
-
-   Allowed sub nodes:
-     - `CFR_TAG_VARCHAR_DEF_VALUE`
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-     - `CFR_TAG_VARCHAR_UI_HELPTEXT`
-
-   Required sub nodes:
-     - `CFR_TAG_VARCHAR_DEF_VALUE`
-     - `CFR_TAG_VARCHAR_OPT_NAME`
-     - `CFR_TAG_VARCHAR_UI_NAME`
-
-* CFR_TAG_OPTION_COMMENT
-
-   Used in `struct lb_cfr_option_comment` to describe an ASCII string visible
-   to the user, but doesn't reference a variable. Informal use only.
-
-   Allowed sub nodes:
-     - `CFR_TAG_VARCHAR_UI_NAME`
-     - `CFR_TAG_VARCHAR_UI_HELPTEXT`
-
-   Required sub nodes:
-     - `CFR_TAG_VARCHAR_UI_NAME`
-
-* CFR_TAG_VARCHAR_OPT_NAME
-
-   Used in `struct lb_cfr_varbinary` to describe the option name used by
-   coreboot's code. It thus must match what is used in code by
-   `get_uint_option()`.
-
-   Is not user visible.
-
-* CFR_TAG_VARCHAR_UI_NAME
-
-   Used in `struct lb_cfr_varbinary`
-
-   User visible name of the option.
-
-* CFR_TAG_VARCHAR_UI_HELPTEXT
-
-   Used in `struct lb_cfr_varbinary`
-
-   Optional user visible description what is changed by this option.
-
-* CFR_TAG_VARCHAR_DEF_VALUE
-
-   Used in `struct lb_cfr_varbinary`
-
-   Default value in case the variable is not present.
-
-### Flags
-
-The optional flags describe the visibilty of the option and the
-effect on the non-volatile variable.
-
-* `CFR_OPTFLAG_READONLY`
-
-   Prevents writes to the variable.
-
-* `CFR_OPTFLAG_INACTIVE`
-
-   Implies `READONLY`. The option is visible, but cannot be modified
-   because one of the dependencies are not given. However there's a
-   possibility to enable the option by changing runtime configuration.
-
-   *For example:* Setting SATA mode, but SATA is globally disabled.
-
-* `CFR_OPTFLAG_SUPPRESS`
-
-   Runtime code sets this flag to indicate that the option has no effect
-   and is never reachable, not even by changing runtime configuration.
-   This option is never shown in the UI.
-
-* `CFR_OPTFLAG_VOLATILE`
-
-   Implies `READONLY`.
-   The option is not backed by a non-volatile variable. This is useful
-   to display the current state of a specific component, a dependency or
-   a serial number. This information could be passed in a new coreboot
-   table, but it not useful other than to be shown at this spot in the
-   UI.
-
-* `CFR_OPTFLAG_RUNTIME`
-
-   The option is allowed to be changed by a post payload entity. On UEFI
-   this sets the `EFI_VARIABLE_RUNTIME_ACCESS` attribute.
-   It is out of scope of this specification how non runtime variables
-   are protected after the payload has hand over control.
-
-### Example
-
-To display a boolean option with the label `Boolean`, that default value
-is `true`, on a form called `test`, that modifies the variable `First`
-the following structure will be generated:
-
-```
-struct lb_cfr_option_form {
-  uint32_t tag;                  = CFR_TAG_OPTION_FORM
-  uint32_t size;                 = sizeof(struct lb_cfr_option_form) +
-                                   sizeof(struct lb_cfr_varbinary) +
-                                   strlen(name) + 1 + 3 +
-                                   sizeof(struct lb_cfr_numeric_option) +
-                                   sizeof(struct lb_cfr_varbinary) +
-                                   strlen(optname) + 1 + 2 +
-                                   sizeof(struct lb_cfr_varbinary) +
-                                   strlen(uiname) + 1 = 120
-  uint64_t object_id;            = 1
-  uint64_t dependency_id;        = 0
-  uint32_t flags;                = 0
-}
-  struct lb_cfr_varbinary {
-    uint32_t tag;                = CFR_TAG_VARCHAR_UI_NAME
-    uint32_t size;               = sizeof(struct lb_cfr_varbinary) +
-                                   strlen(name) + 1 + 3 = 20
-    uint32_t data_length;        = strlen(name) + 1
-  };
-    char name[5];                = "test"
-    char padding[3];
-  struct lb_cfr_numeric_option {
-    uint32_t tag;                = CFR_TAG_OPTION_BOOL
-    uint32_t size;               = sizeof(struct lb_cfr_numeric_option) +
-                                   sizeof(struct lb_cfr_varbinary) +
-                                   strlen(optname) + 1 + 2 +
-                                   sizeof(struct lb_cfr_varbinary) +
-                                   strlen(uiname) + 1 = 72
-    uint64_t object_id;          = 2
-    uint64_t dependency_id;      = 0
-    uint32_t flags;              = 0
-    uint32_t default_value;      = true
-  };
-    struct lb_cfr_varbinary {
-      uint32_t tag;              = CFR_TAG_VARCHAR_OPT_NAME
-      uint32_t size;             = sizeof(struct lb_cfr_varbinary) +
-                                   strlen(optname) + 1 + 2 = 20
-      uint32_t data_length;      = strlen(optname) + 1 = 6
-    };
-      char optname[6];           = "First"
-      char padding[2];
-    struct lb_cfr_varbinary {
-      uint32_t tag;              = CFR_TAG_VARCHAR_UI_NAME
-      uint32_t size;             = sizeof(struct lb_cfr_varbinary) +
-                                   strlen(uiname) + 1 = 20
-      uint32_t data_length;      = strlen(uiname) + 1 = 8
-    };
-      char uiname[8];            = "Boolean"
-```

Documentation/drivers/cfr_internal.md

@@ -1,190 +0,0 @@
-# CFR - coreboot form representation - Internals
-
-This documents the API internally used by coreboot to be used
-by ramstage code.
-
-Please read [CFR](cfr.md) first.
-
-## Enabling CFR support
-
-Users should select `DRIVERS_OPTION_CFR` in Kconfig to enable CFR
-support. Mainboards should select `DRIVERS_OPTION_CFR_ENABLED` to
-enable `DRIVERS_OPTION_CFR` by default.
-
-## Using CFR
-
-When CFR support is enabled there are two possibilites to generate
-the records:
-
-- mainboard specific code
-- automatic collection
-
-In both cases you have to add `C` structs in ramstage to describe the
-option and group them together into a form. CFR objects should reside
-on the heap as they can be modified to match the current boot flow.
-
-### Overriding default values
-
-Mainboards often want to reuse CFR objects defined in SoC or common code
-but with different default values. Rather than duplicating the entire object
-definition, mainboards can declare an override table that maps option names
-to new default values.
-
-**Example:** Override defaults for several SoC-defined options:
-
-```
-#include <drivers/option/cfr_frontend.h>
-#include <intelblocks/pcie_rp.h>
-
-const struct cfr_default_override mb_cfr_overrides[] = {
-	CFR_OVERRIDE_BOOL("s0ix_enable", false),
-	CFR_OVERRIDE_ENUM("pciexp_aspm", ASPM_DISABLE),
-	CFR_OVERRIDE_NUMBER("igd_dvmt", 64),
-	CFR_OVERRIDE_END
-};
-
-void mb_cfr_setup_menu(struct lb_cfr *cfr_root)
-{
-	/* Register overrides before writing menu */
-	cfr_register_overrides(mb_cfr_overrides);
-	cfr_write_setup_menu(cfr_root, sm_root);
-}
-```
-
-When the CFR system writes the setup menu, it will check the override table
-for each option and use the override value if one exists. All other object
-metadata (name, help text, enum values, flags) comes from the original object.
-
-The following helper macros are available to populate the table:
-
-- `CFR_OVERRIDE_BOOL(name, value)`
-- `CFR_OVERRIDE_ENUM(name, value)`
-- `CFR_OVERRIDE_NUMBER(name, value)`
-- `CFR_OVERRIDE_VARCHAR(name, value)`
-- `CFR_OVERRIDE_END`
-
-Each macro encodes the override type, and the CFR backend validates that the
-override type matches the original object's type. If the types do not match,
-the override is ignored and a warning is printed.
-
-### Updating CFR options
-
-The CFR options should be updated before tables are written.
-You can use a callback, using the `WITH_CALLBACK()` macro, to update
-single or multiple options when the CFR table is written into the
-coreboot table.
-
-**Example:** Updates the option serial_number with the contents from the
-EMI eeprom.
-
-```
-static void update_serial(struct sm_object *new)
-{
-	new->sm_varchar.default_value = get_emi_eeprom_vpd()->serial_number;
-}
-
-static const struct sm_object serial_number = SM_DECLARE_VARCHAR({
-	.flags		= CFR_OPTFLAG_READONLY | CFR_OPTFLAG_VOLATILE,
-	.opt_name	= "serial_number",
-	.ui_name	= "Serial Number",
-}, WITH_CALLBACK(update_serial));
-```
-
-### Dependencies in CFR options
-
-The CFR options can have a dependency that must be evaluated at runtime by
-the OS/payload that parses the CFR record and displays the UI.
-By using the `WITH_DEP()` macro you can specify another numeric option that
-is checked to hide the current option. The `WITH_DEP_VALUES()` macro allows
-specifying one or more values that cause the dependent option to be displayed.
-
-**Example:** Declares a dependency from `sata_disable_port0` to `sata_enable`.
-The option `sata_disable_port0` will be hidden as long as "sata_enable" is 0.
-When the user changes "sata_enable" to 1 or it was 1 then the option
-`sata_disable_port0` should be visible.
-
-```
-static struct sm_object sata_enable = SM_DECLARE_BOOL({
-	.flags		= CFR_OPTFLAG_RUNTIME,
-	.opt_name	= "sata_enable",
-	.ui_name	= "Enable SATA controller",
-	.ui_helptext	= NULL,
-	.default_value	= true,
-});
-
-static struct sm_object sata_disable_port0 = SM_DECLARE_BOOL({
-	.flags		= CFR_OPTFLAG_RUNTIME,
-	.opt_name	= "sata_disable_port0",
-	.ui_name	= "Disable SATA port #0",
-	.ui_helptext	= NULL,
-	.default_value	= false,
-}, WITH_DEP(&sata_enable));
-```
-
-**Example:** Declares a dependency from `com1_termination` to `com1_mode`.
-The option `com1_termination` will only be shown if `com1_mode` is set to RS-485.
-
-```
-#define COM_MODE_DISABLED 3
-#define COM_MODE_RS232    0
-#define COM_MODE_RS485    1
-
-static struct sm_object com1_mode = SM_DECLARE_ENUM({
-	.flags		= CFR_OPTFLAG_RUNTIME,
-	.opt_name	= "com1_mode",
-	.ui_name	= "COM1 Mode",
-	.ui_helptext	= NULL,
-	.default_value	= 1,
-	.values		= (const struct sm_enum_value[]) {
-				{ "Disabled", COM_MODE_DISABLED },
-				{ "RS-232",   COM_MODE_RS232    },
-				{ "RS-485",   COM_MODE_RS485    },
-				SM_ENUM_VALUE_END },
-});
-
-static struct sm_object com1_termination = SM_DECLARE_BOOL({
-	.flags		= CFR_OPTFLAG_RUNTIME,
-	.opt_name	= "com1_termination",
-	.ui_name	= "Enable COM1 termination resistors",
-	.ui_helptext	= NULL,
-	.default_value	= false,
-}, WITH_DEP_VALUES(&com1_mode, COM_MODE_RS485));
-
-```
-
-### Providing mainboard custom options
-
-A mainboard that uses CFR can provide a list of custom options
-be overwriting the weak `void mb_cfr_setup_menu(struct lb_cfr *cfr_root);`
-function in ramstage.
-
-### Automatic CFR collection
-
-CFR forms that have the `__cfr_form` attribute are automatically collected
-and inserted into the coreboot table.
-
-## Example
-
-The following CFR form `southbridge` will be automatically added to the
-coreboot table and it will have a single option called `Enable NMI` that
-allows the variable `nmi` to be changed to *0* or *1*.
-
-**Example:**
-```C
-static struct sm_object nmi = SM_DECLARE_BOOL({
-	.flags		= CFR_OPTFLAG_RUNTIME,
-	.opt_name	= "nmi",
-	.ui_name	= "Enable NMI",
-	.ui_helptext	= NULL,
-	.default_value	= false,
-});
-
-static const  __cfr_form struct sm_obj_form southbridge = {
-	.flags		= 0,
-	.ui_name	= "Southbridge",
-	.obj_list	= (const struct sm_object *[]) {
-		&nmi,
-		NULL
-	},
-};
-```

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,21 +298,21 @@ 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
+## 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

Documentation/drivers/dt_entries.md

@@ -1,309 +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_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, Exclusive, ,, )
-            {
-                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, Exclusive, ,, )
-    {
-        0x0000002D,
-    }
-```
-
-which comes from:
-
-```
-    register "irq" = "ACPI_IRQ_LEVEL_LOW(GPP_A21_IRQ)"
-```
-
-The IRQ settings control the "Trigger" and "Polarity" 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).
-
-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``.
-
-AMD platforms don't have the ability to route GPIOs to the IO-APIC. Instead the
-GPIO controller needs to be used directly. You can do this by setting the
-`irq_gpio` register and using the `ACPI_GPIO_IRQ_X_X` macros.
-
-i.e.,
-```
-register "irq_gpio" = "ACPI_GPIO_IRQ_EDGE_LOW(GPIO_40)"
-```
-
-### 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. The first
-mainboards in the tree to implement this are google/skyrim and google/guybrush.
-This feature has also been used in downstream forks without issue for some time
-now on several other boards.
-
-### 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.
-
-### device
-
-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".
-
-## Wake sources
-
-The ACPI spec defines two methods to describe how a device can wake the system.
-Only one of these methods should be used, otherwise duplicate wake events will
-be generated.
-
-### Using GPEs as a wake source
-
-The `wake` property specified above is used to tell the ACPI subsystem that the
-device can use a GPE to wake the system. The OS can control whether to enable
-or disable the wake source by unmasking/masking off the GPE.
-
-The `GPIO` -> `GPE` mapping must be configured in firmware. On AMD platforms this is
-generally done by a mainboard specific `gpio.c` file that defines the GPIO
-using `PAD_SCI`. The `GPIO` -> `GPE` mapping is returned by the
-`soc_get_gpio_event_table` method that is defined in the SoC specific `gpio.c`
-file. On Intel platforms, you fill in the `pmc_gpe0_dw0`, `pmc_gpe0_dw1`, and
-`pmc_gpe0_dw2` fields in the devicetree to map 3 GPIO communities to `tier-1`
-GPEs (the rest are available as `tier-2` GPEs).
-
-Windows has a large caveat when using this method. If you use the `gpio_irq`
-property to define a `GpioInt` in the `_CRS`, and then use the `wake` property
-to define a `GPE`, Windows will
-[BSOD](https://github.com/MicrosoftDocs/windows-driver-docs/blob/staging/windows-driver-docs-pr/debugger/bug-check-0xa5--acpi-bios-error.md)
-complaining about an invalid ACPI configuration.
-> 0x1000D - A device used both GPE and GPIO interrupts, which is not supported.
-
-In order to avoid this error, you should use the `irq` property instead. AMD
-platforms don't support routing GPIOs to the IO-APIC, so this workaround isn't
-feasible. The other option is to use a wake capable GPIO as described below.
-
-### Using GPIO interrupts as a wake source
-
-The `ACPI_IRQ_WAKE_{EDGE,LEVEL}_{LOW,HIGH}` macros can be used when setting the
-`irq` or `gpio_irq` properties. This ends up setting `ExclusiveAndWake` or
-`SharedAndWake` on the `Interrupt` or `GpioInt` ACPI resource.
-
-This method has a few caveats:
-* On Intel and AMD platforms the IO-APIC can't wake the system. This means using
-  the `ACPI_IRQ_WAKE_*` macros with the `irq` property won't actually wake the
-  system. Instead you need to use the `gpio_irq` property, or a `GPE` as
-  described above.
-* The OS needs to know how to enable the `wake` bit on the GPIO. For linux this
-  means the platform specific GPIO controller driver must implement the
-  `irq_set_wake` callback. For AMD systems this wasn't
-  [implemented](https://github.com/torvalds/linux/commit/d62bd5ce12d79bcd6a6c3e4381daa7375dc21158)
-  until linux v5.15. If the controller doesn't define this callback, it's
-  possible for the firmware to manually set the `wake` bit on the GPIO. This is
-  often done in a mainboard-specific file named `gpio.c`. This is not
-  recommended because then it's not possible for the OS to disable the wake
-  source.
-* As of
-  [linux v6.0-rc5](https://github.com/torvalds/linux/releases/tag/v6.0-rc5),
-  the ACPI subsystem doesn't take the interrupt `wake` bit into account when
-  deciding on which power state to put the device in before suspending the
-  system. This means that if you define a power resource for a device via
-  `has_power_resource`, `enable_gpio`, etc, then the linux kernel will place the
-  device into D3Cold. i.e., power off the device.
-
-## 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_.
-D3Hot means the `PR3` power resources are still on and the device is still
-responsive on the bus. For i2c devices this is generally the same state as `D0`.
-
-### \_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/efi_capsule_generation.md

@@ -1,77 +0,0 @@
-# Generating signed UEFI capsules with EDK2
-
-coreboot can cooperate with an EDK2 payload to support firmware updates via the UEFI
-ESRT/FMP capsule mechanism.
-
-This document covers generating a *signed* capsule during the coreboot build.
-
-At present, capsule generation requires a compatible EDK2 tree with the
-corresponding payload-side changes. Upstream support is being tracked in:
-
-https://github.com/tianocore/edk2/pull/12053
-
-Older EDK2 trees may be missing pieces required by this integration.
-
-## Build-time capsule generation
-
-Enable capsule support and use an EDK2 payload:
-
-- `CONFIG_DRIVERS_EFI_UPDATE_CAPSULES`: enable coreboot capsule update support.
-- `CONFIG_DRIVERS_EFI_GENERATE_CAPSULE`: generate `build/coreboot.cap` after the ROM is finalised.
-- `CONFIG_PAYLOAD_EDK2`: build an EDK2 payload.
-
-When enabled, the coreboot build generates `build/coreboot.cap` after the ROM image is
-finalised. The capsule can also be generated explicitly with `make capsule`.
-
-Configure the FMAP allowlist embedded into the ROM as a manifest:
-
-- `CONFIG_DRIVERS_EFI_CAPSULE_REGIONS`: whitespace-separated FMAP region allowlist embedded into
-  the ROM as a manifest (e.g. `COREBOOT EC`).
-
-Configure the ESRT/FMP firmware identity used by the capsule:
-
-- `CONFIG_DRIVERS_EFI_MAIN_FW_GUID`: GUID of the firmware
-- `CONFIG_DRIVERS_EFI_MAIN_FW_VERSION`: firmware version encoded in the capsule header;
-  if set to `0`, derive a value from the leading `<major>.<minor>` in
-  `CONFIG_LOCALVERSION` when possible
-- `CONFIG_DRIVERS_EFI_MAIN_FW_LSV`: lowest supported firmware version; if set to `0`,
-  use the resolved firmware version
-
-Reset behavior during capsule application:
-
-- `CONFIG_DRIVERS_EFI_CAPSULE_INITIATE_RESET`: add the capsule `InitiateReset` flag.
-  This is disabled by default because Linux rejects capsules with `InitiateReset` when using
-  `/dev/efi_capsule_loader`.
-
-## Embedded drivers (FmpDxe in capsule)
-
-Some EDK2 capsule update flows use an embedded `FmpDxe.efi` driver inside the capsule.
-
-To generate capsules with an embedded `FmpDxe.efi`, enable:
-
-- `CONFIG_DRIVERS_EFI_CAPSULE_EMBED_FMP_DXE`: embed `FmpDxe.efi` into generated capsules.
-- `CONFIG_DRIVERS_EFI_CAPSULE_ACCEPT_EMBEDDED_DRIVERS`: configure the EDK2 payload to accept
-  capsules with embedded drivers (sets `PcdCapsuleEmbeddedDriverSupport=TRUE`).
-
-Note: if Secure Boot is enabled, the embedded driver must be signed by a key trusted by the
-running firmware, otherwise capsule processing may fail when loading the embedded driver.
-
-## Capsule signing certificates
-
-`GenerateCapsule` can sign the FMP payload (PKCS#7). Many platforms require signed capsules.
-
-coreboot exposes three Kconfig options for the certificate chain:
-
-- `CONFIG_DRIVERS_EFI_CAPSULE_SIGNER_PRIVATE_CERT`: PEM containing the signing private key and
-  leaf certificate
-- `CONFIG_DRIVERS_EFI_CAPSULE_OTHER_PUBLIC_CERT`: PEM intermediate certificate
-- `CONFIG_DRIVERS_EFI_CAPSULE_TRUSTED_PUBLIC_CERT`: PEM trusted root certificate
-
-If a configured path is relative, it is interpreted relative to the configured EDK2 repository
-inside `payloads/external/edk2/workspace`.
-
-The defaults use the EDK2 BaseTools test certificate chain. Do not use the test keys for
-production firmware updates.
-
-To generate your own certificate chain and convert it into the required PEM files, see:
-`BaseTools/Source/Python/Pkcs7Sign/Readme.md` in the EDK2 tree.

Documentation/drivers/index.md

@@ -4,30 +4,9 @@ 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.
 
-For details on how to connect device drivers to a mainboard, see [Driver Devicetree Entries](dt_entries.md).
-
-```{toctree}
-:maxdepth: 1
-:hidden:
-
-Driver Devicetree Entries <dt_entries.md>
-```
-
-Some of the drivers currently available include:
-
-```{toctree}
-:maxdepth: 1
-
-ACPI Five-Level Fan Control <acpi_fan_control.md>
-CFR <cfr.md>
-CFR use within coreboot <cfr_internal.md>
-Intel DPTF <dptf.md>
-IPMI BT (Block Transfer) <ipmi_bt.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>
-EDK2 capsule generation <efi_capsule_generation.md>
-```
+* [Intel DPTF](dptf.md)
+* [IPMI KCS](ipmi_kcs.md)
+* [SMMSTORE](smmstore.md)
+* [SoundWire](soundwire.md)
+* [SMMSTOREv2](smmstorev2.md)
+* [USB4 Retimer](retimer.md)

Documentation/drivers/ipmi_bt.md

@@ -1,79 +0,0 @@
-# IPMI Block Transfer (BT) driver
-
-The driver can be found in `src/drivers/ipmi/` (same as KCS). It works with BMC
-that provides a BT I/O interface as specified in the [IPMI] standard.  See
-"Intelligent Platform Management Interface Specification", v2.0, Rev. 1.1 for
-more details on the interface and IPMI in general.
-
-The driver detects the IPMI version and reserves the I/O space in coreboot's
-resource allocator.
-
-## For developers
-
-To use the driver, select the `IPMI_BT` Kconfig and add the following PNP
-device (in example for the BT at 0xe4):
-
-```
-chip drivers/ipmi
-    device pnp e4.0 on end        # IPMI BT
-end
-```
-
-**Note:** The I/O base address must be aligned to 4.
-
-The following settings can be set in a device tree:
-
-```{eval-rst}
-+------------------+--------------+-------------------------------------------+
-|  Setting         | Type/Default | Description/Purpose                       |
-+==================+==============+===========================================+
-| wait_for_bmc     | | Boolean    | Wait for BMC to boot. This can be used if |
-|                  | | false      | the BMC takes a long time to boot after   |
-|                  |              | PoR.                                      |
-+------------------+--------------+-------------------------------------------+
-| bmc_boot_timeout | | Integer    | The timeout in seconds to wait for the    |
-|                  | | 0          | IPMI service to be loaded.  Will be used  |
-|                  |              | if wait_for_bmc is true.                  |
-+------------------+--------------+-------------------------------------------+
-```
-
-## Debugging/testing the driver
-
-`ipmi_sim` from [OpenIPMI] project can be used by running `ipmi_sim -d` in one
-console to watch what's being sent/received and starting QEMU like this in
-another console:
-
-```
-qemu-system-x86_64 \
-    -M q35,smm=on \
-    -bios build/coreboot.rom \
-    -chardev socket,id=ipmichr0,host=localhost,port=9002,reconnect=10 \
-    -device ipmi-bmc-extern,chardev=ipmichr0,id=bmc0 \
-    -device isa-ipmi-bt,bmc=bmc0,irq=0 \
-    -serial stdio
-```
-
-A simpler alternative is to use QEMU's builtin BMC simulator:
-
-```
-qemu-system-x86_64 \
-    -M q35,smm=on \
-    -bios build/coreboot.rom \
-    -device ipmi-bmc-sim,id=bmc0 \
-    -device isa-ipmi-bt,bmc=bmc0,irq=0 \
-    -serial stdio
-```
-
-## References
-
-Useful links on the subject:
- * README of `ipmi_sim`:
-   <https://github.com/wrouesnel/openipmi/blob/master/lanserv/README.ipmi_sim>
- * slides about OpenIPMI:
-   <https://www.linux-kvm.org/images/7/76/03x08-Juniper-Corey_Minyard-UsingIPMIinQEMU.ods.pdf>
- * a usage example: <https://github.com/dhilst/qemu-ipmi>
- * old docs (the options are still there, but no longer have a dedicated page in
-   modern documentation): <https://hskinnemoen.github.io/qemu/specs/ipmi.html>
-
-[IPMI]: https://www.intel.com/content/dam/www/public/us/en/documents/specification-updates/ipmi-intelligent-platform-mgt-interface-spec-2nd-gen-v2-0-spec-update.pdf
-[OpenIPMI]: https://github.com/wrouesnel/openipmi

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,6 +1,6 @@
 # USB4 Retimers
 
-## Introduction
+# 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
@@ -17,7 +17,7 @@ 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
+# 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

Documentation/drivers/smmstore.md

@@ -128,8 +128,7 @@ data or modify the currently running kernel.*
 
 ## External links
 
-* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDK II](https://github.com/tianocore-docs/Docs/raw/master/White_Papers/A_Tour_Beyond_BIOS_Implementing_UEFI_Authenticated_Variables_in_SMM_with_EDKII_V2.pdf)
-
+* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDKI](https://software.intel.com/sites/default/files/managed/cf/ea/a_tour_beyond_bios_implementing_uefi_authenticated_variables_in_smm_with_edkii.pdf)
 Note, this differs significantly from coreboot's implementation.
 
 [SMM]: ../security/smm.md

Documentation/drivers/smmstorev2.md

@@ -21,7 +21,7 @@ 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:
+EDK2 uses three different regions in the store:
 
 - The variable store
 - The FTW spare block
@@ -35,7 +35,7 @@ With 64 KiB as block size, the minimum size of the FTW-enabled store is:
 - 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.
+Therefore, the minimum size for EDK2 FTW is 4 blocks, or 256 KiB.
 
 ## API
 
@@ -74,30 +74,19 @@ has to read the coreboot table with tag `0x0039`, containing:
 struct lb_smmstorev2 {
 	uint32_t tag;
 	uint32_t size;
-	uint32_t num_blocks;		/* Number of writable blocks in SMM */
-	uint32_t block_size;		/* Size of a block in byte. Default: 64 KiB */
-	uint32_t mmap_addr_deprecated;	/* 32-bit MMIO address of the store for read only access.
-					   Prefer 'mmap_addr' for new software.
-					   Zero when the address won't fit into 32-bits. */
-	uint32_t com_buffer;		/* Physical address of the communication buffer */
-	uint32_t com_buffer_size;	/* Size of the communication buffer in bytes */
-	uint8_t apm_cmd;		/* The command byte to write to the APM I/O port */
-	uint8_t unused[3];		/* Set to zero */
-	uint64_t mmap_addr;		/* 64-bit MMIO address of the store for read only access.
-					   Introduced after the initial implementation. Users of
-					   this table must check the 'size' field to detect if its
-					   written out by coreboot. */
+	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.
 
-`mmap_addr` is an optional field added after the initial implementation.
-Users of this table must check the size field to know if it's written by coreboot.
-In case it's not present 'mmap_addr_deprecated' is to be used as the SPI ROM MMIO
-address and it must be below 4 GiB.
-
 ### Blocks
 
 The SMMSTOREv2 splits the SMMSTORE FMAP partition into smaller chunks
@@ -135,9 +124,25 @@ 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_DEPRECATED = 4
+#### - SMMSTORE_CMD_INIT = 4
 
-Unused, returns SMMSTORE_REG_UNSUPPORTED.
+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
 
@@ -208,49 +213,9 @@ coreboot tables, there's no risk that a malicious application capable
 of issuing SMIs could extract arbitrary data or modify the currently
 running kernel.
 
-## Capsule update API
-
-Availability of this command is tied to `CONFIG_DRIVERS_EFI_UPDATE_CAPSULES`.
-
-To allow updating full flash content (except if locked at hardware
-level), few new calls were added. They reuse communication buffer, SMI
-command, return values and calling arguments of SMMSTORE commands listed
-above, with the exception of subcommand passed via `%ah`. If the
-subcommand is to operate on full flash size, it has the highest bit set,
-e.g. it is `0x85` for `SMMSTORE_CMD_RAW_READ` and `0x86` for
-`SMMSTORE_CMD_RAW_WRITE`. Every `block_id` describes block relative to
-the beginning of a flash, maximum value depends on its size.
-
-Attempts to write the protected memory regions can lead to undesired
-consequences ranging from system instability to bricking and security
-vulnerabilities. When this feature is used, care must be taken to temporarily
-lift protections for the duration of an update when the whole flash is
-rewritten or the update must be constrained to affect only writable portions of
-the flash (e.g., "BIOS" region).
-
-There is one new subcommand that must be called before any other subcommands
-with highest bit set can be used.
-
-### - SMMSTORE_CMD_USE_FULL_FLASH = 0x80
-
-This command can only be executed once and is done by the firmware.
-Calling this function at runtime has no effect. It takes one additional
-parameter that, contrary to other commands, isn't a pointer. Instead,
-`%ebx` indicates requested state of full flash access. If it equals 0,
-commands for accessing full flash are permanently disabled, otherwise
-they are permanently enabled until the next boot.
-
-The assumption is that if capsule updates are enabled at build time and
-whole flash access is enabled at runtime, a UEFI payload (highly likely
-EDK2 or its derivative) won't allow a regular OS to boot if the handler is
-enabled without rebooting first. There could be a way of deactivating the
-handler, but coreboot, having no way of enforcing its usage, might as well
-permit access until a reboot and rely on the payload to do the right thing.
-
 ## External links
 
-* [A Tour Beyond BIOS Implementing UEFI Authenticated Variables in SMM with EDK II](https://github.com/tianocore-docs/Docs/raw/master/White_Papers/A_Tour_Beyond_BIOS_Implementing_UEFI_Authenticated_Variables_in_SMM_with_EDKII_V2.pdf)
-
+* [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/external_docs.md

@@ -1,137 +0,0 @@
-# External Resources
-
-This is a list of resources that could be useful to coreboot developers.
-These are not endorsed or officially recommended by the coreboot project,
-but simply listed here in the hopes that someone will find something
-useful.
-
-Please add any helpful or informational links and sections as you see fit.
-
-## Articles
-
-* External Interrupts in the x86 system.
-  * [Part 1: Interrupt controller evolution](https://habr.com/en/post/446312/)
-  * [Part 2: Linux kernel boot options](https://habr.com/en/post/501660/)
-  * [Part 3: Interrupt routing setup in a chipset](https://habr.com/en/post/501912/)
-* System address map initialization in x86/x64 architecture.
-  * [Part 1: PCI-based systems](https://resources.infosecinstitute.com/topic/system-address-map-initialization-in-x86x64-architecture-part-1-pci-based-systems/)
-  * [Part 2: PCI express-based systems](https://resources.infosecinstitute.com/topic/system-address-map-initialization-x86x64-architecture-part-2-pci-express-based-systems/)
-  * [PCIe elastic buffer](https://www.mindshare.com/files/resources/mindshare_pcie_elastic_buffer.pdf)
-* [Boot Guard and PSB have user-hostile defaults](https://mjg59.dreamwidth.org/58424.html)
-
-
-## General Information
-
-* [OS Dev](https://wiki.osdev.org/Categorized_Main_Page)
-* [Interface BUS](http://www.interfacebus.com/)
-
-## OpenSecurityTraining2
-
-OpenSecurityTraining2 is dedicated to sharing training material for any topic
-related to computer security, including coreboot.
-
-There are various ways to learn firmware, some are more efficient than others,
-depending on the people. Before going straight to practice and experimenting
-with hardware, it can be beneficial to learn the basics of computing. OST2
-focuses on conveying computer architecture and security information in the form
-of structured instructor-led classes, available to everyone for free.
-
-All material is licensed [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/),
-allowing anyone to use the material however they see fit, so long as they share
-modified works back to the community.
-
-Below is a list of currently available courses that can help understand the
-inner workings of coreboot and other firmware-related topics:
-
-* [coreboot design principles and boot process](https://ost2.fyi/Arch4031)
-* [x86-64 Assembly](https://ost2.fyi/Arch1001)
-* [x86-64 OS Internals](https://ost2.fyi/Arch2001)
-* [x86-64 Intel Firmware Attack & Defense](https://ost2.fyi/Arch4001)
-
-There are [additional security courses](https://p.ost2.fyi/courses) at the site
-as well (such as
-[how to avoid writing exploitable code in C/C++](https://ost2.fyi/Vulns1001).)
-
-## Firmware Specifications & Information
-
-* [System Management BIOS - SMBIOS](https://www.dmtf.org/standards/smbios)
-* [Desktop and Mobile Architecture for System Hardware - DASH](https://www.dmtf.org/standards/dash)
-* [PNP BIOS](https://www.intel.com/content/dam/support/us/en/documents/motherboards/desktop/sb/pnpbiosspecificationv10a.pdf)
-
-
-### ACPI
-
-* [ACPI Specs](https://uefi.org/acpi/specs)
-* [ACPI in Linux](https://www.kernel.org/doc/ols/2005/ols2005v1-pages-59-76.pdf)
-* [ACPI 5 Linux](https://blog.linuxplumbersconf.org/2012/wp-content/uploads/2012/09/LPC2012-ACPI5.pdf)
-* [ACPI 6 Linux](https://events.static.linuxfound.org/sites/events/files/slides/ACPI_6_and_Linux_0.pdf)
-
-
-### Security
-
-* [Intel Boot Guard](https://edk2-docs.gitbook.io/understanding-the-uefi-secure-boot-chain/secure_boot_chain_in_uefi/intel_boot_guard)
-
-
-## Hardware information
-
-* [WikiChip](https://en.wikichip.org/wiki/WikiChip)
-* [Sandpile](https://www.sandpile.org/)
-* [CPU-World](https://www.cpu-world.com/index.html)
-* [CPU-Upgrade](https://www.cpu-upgrade.com/index.html)
-
-
-### Hardware Specifications & Standards
-
-* [Bluetooth](https://www.bluetooth.com/specifications/specs/) - Bluetooth SIG
-* [eMMC](https://www.jedec.org/)  - JEDEC - (LOGIN REQUIRED)
-* [eSPI](https://cdrdv2.intel.com/v1/dl/getContent/645987) - Intel
-* [I2c Spec](https://web.archive.org/web/20170704151406/https://www.nxp.com/docs/en/user-guide/UM10204.pdf),
-  [Appnote](https://www.nxp.com/docs/en/application-note/AN10216.pdf) - NXP
-* [I2S](https://www.nxp.com/docs/en/user-manual/UM11732.pdf) - NXP
-* [I3C](https://www.mipi.org/specifications/i3c-sensor-specification) - MIPI Alliance (LOGIN REQUIRED)
-* [Memory](https://www.jedec.org/)  - JEDEC - (LOGIN REQUIRED)
-* [NVMe](https://nvmexpress.org/developers/) - NVMe Specifications
-* [LPC](https://www.intel.com/content/dam/www/program/design/us/en/documents/low-pin-count-interface-specification.pdf) - Intel
-* [PCI / PCIe / M.2](https://pcisig.com/specifications) -  PCI-SIG - (LOGIN REQUIRED)
-* [Power Delivery](https://www.usb.org/documents) - USB Implementers Forum
-* [SATA](https://sata-io.org/developers/purchase-specification) - SATA-IO (LOGIN REQUIRED)
-* [SMBus](http://www.smbus.org/specs/) - System Management Interface Forum
-* [Smart Battery](http://smartbattery.org/specs/) - Smart Battery System Implementers Forum
-* [USB](https://www.usb.org/documents) - USB Implementers Forum
-* [WI-FI](https://www.wi-fi.org/discover-wi-fi/specifications) - Wi-Fi Alliance
-
-
-### Chip Vendor Documentation
-
-* AMD
-  * [Developer Guides, Manuals & ISA Documents](https://developer.amd.com/resources/developer-guides-manuals/)
-  * [AMD Tech Docs - Official Documentation Page](https://www.amd.com/en/support/tech-docs)
-* ARM
-  * [Tools and Software - Specifications](https://developer.arm.com/tools-and-software/software-development-tools/specifications)
-* Intel
-  * [Developer Zone](https://www.intel.com/content/www/us/en/developer/overview.html)
-  * [Resource & Documentation Center](https://www.intel.com/content/www/us/en/resources-documentation/developer.html)
-  * [Architecture Software Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html)
-  * [Intel specific ACPI](https://www.intel.com/content/www/us/en/standards/processor-vendor-specific-acpi-specification.html)
-  * [coreboot on Eagle Stream](https://www.intel.com/content/www/us/en/content-details/778593/coreboot-practice-on-eagle-stream.html)
-
-* Rockchip
-  * [Open Source Wiki](https://opensource.rock-chips.com/wiki_Main_Page)
-
-
-## Software
-
- * [Fiedka](https://github.com/fiedka/fiedka) - A graphical Firmware Editor
- * [IOTools](https://github.com/adurbin/iotools) - Command line tools to access hardware registers
- * [UEFITool](https://github.com/LongSoft/UEFITool) - Editor for UEFI PI compliant firmware images
- * [CHIPSEC](https://chipsec.github.io) - Framework for analyzing platform level security & configuration
- * [SPDEditor](https://github.com/integralfx/SPDEditor) - GUI to edit DDR3 SPD files
- * [DDR4XMPEditor](https://github.com/integralfx/DDR4XMPEditor) - Editor for DDR4 SPD and XMP
-* [overclockSPD](https://github.com/baboomerang/overclockSPD) - Fast and easy way to read and write data to RAM SPDs.
-* [VBiosFinder](https://github.com/coderobe/VBiosFinder) - This tool attempts to extract a VBIOS from a BIOS update.
-
-
-## Infrastructure software
-
-* [Kconfig](https://www.kernel.org/doc/html/latest/kbuild/kconfig-language.html)
-* [GNU Make](https://www.gnu.org/software/make/manual/)

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 internally](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/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 particularly useful for high level
+CPU cache like regular SRAM. This is particullary useful for high level
 languages like `C`, which need RAM for heap and stack.
 
 The CAR needs to be activated using vendor specific CPU instructions.

Documentation/getting_started/build_system.md

@@ -7,10 +7,10 @@ to the point of providing its own custom language.
 The overhead of learning this new syntax is (hopefully) offset by its lower
 complexity.
 
-The build system is defined in the toplevel `Makefile` and `toolchain.mk`
+The build system is defined in the toplevel `Makefile` and `toolchain.inc`
 and is supposed to be generic (and is in fact used with a number of other
 projects).  Project specific configuration should reside in files called
-`Makefile.mk`.
+`Makefile.inc`.
 
 In general, the build system provides a number of "classes" that describe
 various parts of the build. These cover the various build targets in coreboot
@@ -36,7 +36,7 @@ TODO: explain how to create new classes and how to evaluate them.
 ### subdirs
 `subdirs` contains subdirectories (relative to the current directory) that
 should also be handled by the build system. The build system expects these
-directories to contain a file called `Makefile.mk`.
+directories to contain a file called `Makefile.inc`.
 
 Subdirectories are not read at the point where the `subdirs` statement
 resides but later, after the current directory is handled (and potentially
@@ -62,21 +62,6 @@ supported options are:
 
 `position` and `align` are mutually exclusive.
 
-### Adding Makefile fragments
-
-You can use the `add_intermediate` helper to add new post-processing steps for
-the final `coreboot.rom` image. For example you can add new files to CBFS by
-adding something like this to `site-local/Makefile.mk`
-
-```
-$(call add_intermediate, add_mrc_data)
-	$(CBFSTOOL) $< write -r RW_MRC_CACHE -f site-local/my-mrc-recording.bin
-```
-
-Note that the second line must start with a tab, not spaces.
-
-See also <project:../tutorial/managing_local_additions.md>.
-
 #### FMAP region support
 With the addition of FMAP flash partitioning support to coreboot, there was a
 need to extend the specification of files to provide more precise control
@@ -98,4 +83,4 @@ The default implementation just returns `COREBOOT` (the default region) for
 all files.
 
 vboot provides its own implementation of `regions-for-file` that can be used
-as reference in `src/vboot/Makefile.mk`.
+as reference in `src/vboot/Makefile.inc`.

Documentation/getting_started/cbmem.md

@@ -1,361 +0,0 @@
-# CBMEM high table memory manager
-
-## Introduction
-
-CBMEM (coreboot memory) is a dynamic memory infrastructure used in
-coreboot to store runtime data structures, logs, and other information
-that needs to persist across different boot stages, and even across warm
-boots. CBMEM is crucial for maintaining state and information through
-the coreboot boot process.
-
-Its key responsibilities include:
-- Providing a stable storage area for critical boot data
-- Managing console logging
-- Storing configuration tables for hand off to payloads
-- Maintaining timestamps for performance analysis
-- Preserving boot state during S3 suspend/resume cycles
-- Storing data such as ACPI tables, SMBIOS tables and coreboot tables
-  which are used at runtime
-
-
-## Creation and Placement
-
-CBMEM is initialized by coreboot during romstage, but is used mainly in
-ramstage for storing any data that needs to be saved for more than a
-short period of time.
-
-For 32-bit builds, CBMEM is typically located at the highest usable DRAM
-address below the 4GiB boundary. For 64-bit builds, while there is no
-strict upper limit, it is advisable to follow the same guidelines to
-prevent access or addressing issues. Regardless of the build type, the
-CBMEM address must remain consistent between romstage and ramstage.
-
-Each platform may need to implement its own method for determining the
-`cbmem_top` address, as this can depend on specific hardware
-configurations and memory layouts.
-
-
-## Architecture Overview
-
-Each CBMEM region is identified by a unique ID, allowing different
-components to store and retrieve their data during runtime.
-
-Upon creating an entry, a block of memory of the requested size is
-allocated from the reserved CBMEM region. This region typically persists
-across warm reboots, making it useful for debugging and passing
-information to payloads.
-
-CBMEM is implemented as a specialized in-memory database (IMD) system
-that grows downward from a defined upper memory limit. This means that
-only the latest added entry may be removed.
-
-```text
-High Memory
-+----------------------+ <- cbmem_top
-|  Root Pointer        |
-|----------------------|
-|  Root Structure      |
-|----------------------|
-|  Entry 1             |
-|----------------------|
-|  Entry 2             |
-|----------------------|
-|  ...                 |
-|  (grows downward)    |
-+----------------------+
-```
-
-
-### Core Components
-
-The CBMEM system consists of several key components:
-
-1. **Root Pointer**: Located at the very top of CBMEM memory space,
-   contains a magic number and offset to the Root Structure
-
-2. **Root Structure**: Contains metadata about the CBMEM region,
-   including:
-   - Entry alignment requirements
-   - Maximum number of entries
-   - Current number of entries
-   - Address of the lowest allocated memory
-
-3. **Entries**: Individual allocations within CBMEM, identified by:
-   - 32-bit ID (often encoding ASCII characters for readability)
-   - Size information
-   - Magic validation value
-
-4. **IMD Implementation**: The underlying memory management system
-   that handles allocation, deallocation, and entry management
-
-
-## Memory Layout and Initialization
-
-CBMEM is positioned at the top of available system RAM, typically
-just below the 4GiB boundary for 32-bit builds. This placement
-ensures compatibility with legacy code while allowing CBMEM to
-retain its contents across warm resets.
-
-
-### CBMEM Location Determination
-
-Each platform must implement a `cbmem_top_chipset()` function
-that returns the physical address where CBMEM should be located.
-This address must be consistent across coreboot stages and is
-determined based on:
-
-- Available physical memory
-- Architecture-specific constraints
-- BIOS/chipset requirements
-
-
-### Initialization Process
-
-CBMEM is initialized in a multi-step process:
-
-1. **Early Initialization**: A small console buffer is created in during
-   bootblock and romstage
-
-2. **RAM Initialization**: The full CBMEM area is established in
-   ramstage
-
-3. **Normal Operation**:
-   - In a normal boot, CBMEM is created fresh
-   - Size and alignment values are specified
-   - Initial entries are allocated
-
-4. **Recovery Operation**:
-   - During S3 resume, CBMEM structure is recovered from memory
-   - Content is validated using magic numbers and checksums
-   - All existing entries remain accessible
-
-
-## Entry Management
-
-CBMEM entries are identified by a 32-bit ID, often encoding ASCII
-characters to indicate their purpose (for example, "CNSL" for console).
-
-### Entry Creation
-
-```c
-void *cbmem_add(u32 id, u64 size);
-```
-
-This function:
-- Searches for an existing entry with the given ID
-- If found, returns the existing entry (size is ignored)
-- If not found, allocates a new entry of the requested size
-- Returns a pointer to the entry's data area
-
-
-### Entry Access
-
-```c
-void *cbmem_find(u32 id);
-```
-
-This function:
-- Searches for an entry with the specified ID
-- Returns a pointer to the entry's data area if found
-- Returns NULL if the entry does not exist
-
-
-### Entry Removal
-
-```c
-int cbmem_entry_remove(const struct cbmem_entry *entry);
-```
-
-This function:
-- Removes the specified entry if it was the last one added
-- Returns 0 on success, negative value on failure
-- Note: Due to the downward-growing design, only the most recently
-  added entry can be removed
-
-
-## CBMEM Console Implementation
-
-The CBMEM console is a circular buffer used for capturing log messages
-across all boot stages. It is one of the most widely used CBMEM
-features. The size of this buffer is determined by the
-`CONFIG_CBMEM_CONSOLE_SIZE` Kconfig option.
-
-
-### Console Structure
-
-```c
-struct cbmem_console {
-    u32 size;            // Size of the buffer
-    u32 cursor;          // Current write position and flags
-    u8  body[];          // Actual data buffer
-};
-```
-
-Key features:
-- The high bit of `cursor` indicates overflow condition
-- Only the lower 28 bits of `cursor` are used as position
-- Supports ring-buffer operation when full
-
-
-### Console Operation
-
-1. **Initialization**: A console entry is created in CBMEM with ID
-   `CBMEM_ID_CONSOLE` (0x434f4e53 - 'CONS')
-
-2. **Writing**: Log messages are written byte-by-byte using
-   `cbmemc_tx_byte()` which:
-   - Adds data to the current cursor position
-   - Advances the cursor
-   - Sets the overflow flag when wrapping around
-
-3. **Stage Transition**: When transitioning between boot stages:
-   - Pre-RAM console contents are copied to the main CBMEM console
-   - Any overflow condition is preserved and noted
-   - The process ensures no log messages are lost
-
-
-## Common CBMEM Entry Types
-
-CBMEM contains various data structures used by different coreboot
-components:
-
-- **Console**: Log messages from all boot stages (`CBMEM_ID_CONSOLE`)
-- **Timestamps**: Performance metrics (`CBMEM_ID_TIMESTAMP`)
-- **ACPI Tables**: ACPI data for OS handoff (`CBMEM_ID_ACPI`)
-- **coreboot Tables**: System information (`CBMEM_ID_CBTABLE`)
-- **Memory Information**: RAM configuration (`CBMEM_ID_MEMINFO`)
-- **Stage Cache**: Code/data for faster S3 resume
-- **ROM/CBFS Cache**: Cached ROM content
-- **Vendor-specific**: Platform-dependent structures
-
-A complete list of IDs is defined in
-`src/commonlib/bsd/include/commonlib/bsd/cbmem_id.h`.
-
-
-## Integration with Boot Stages
-
-CBMEM interacts differently with each coreboot boot stage.
-
-
-### Bootblock/Romstage
-
-- Uses cache-as-RAM for temporary console storage
-- Limited CBMEM functionality before RAM initialization
-- Sets up initial timestamp entries
-
-
-### Ramstage
-
-- Full CBMEM initialization or recovery
-- All entries become accessible
-- Most coreboot subsystems interact with CBMEM
-- Console logging is fully operational
-
-
-### Payload Handoff
-
-- CBMEM contents are preserved when transferring to the payload
-- Entries are made available via coreboot tables
-- Common payloads (SeaBIOS, GRUB, etc.) can access CBMEM data
-
-
-## Platform-Specific Considerations
-
-Different platforms have unique requirements for CBMEM implementation.
-
-
-### x86 Platforms
-
-- CBMEM typically located just below 4GiB
-- Often integrates with ACPI resume and SMM operations
-- May need to accommodate memory reserved by legacy components
-
-
-### ARM/RISC-V Platforms
-
-- More flexibility in CBMEM placement
-- Must coordinate with platform-specific memory controllers
-- Memory topology can vary significantly between implementations
-
-
-## CBMEM Hooks
-
-CBMEM provides a hook mechanism to allow subsystems to perform
-initialization or recovery operations when CBMEM becomes available:
-
-```c
-CBMEM_CREATION_HOOK(hook_function);    // First-time creation only
-CBMEM_READY_HOOK(hook_function);       // Any CBMEM initialization
-CBMEM_READY_HOOK_EARLY(hook_function); // Early CBMEM initialization
-```
-
-These macros register functions to be called when CBMEM is initialized,
-allowing components to set up their CBMEM entries at the appropriate time.
-
-
-## Debugging and Utilities
-
-### CBMEM Utility
-
-The `cbmem` utility provides direct access to CBMEM contents on a
-running system. It needs to be built from the coreboot source tree using
-`make -C util/cbmem`. Common uses include:
-
-- Listing all CBMEM entries (`cbmem -l`)
-- Viewing console logs (`cbmem -c`)
-- Analyzing timestamps (`cbmem -t`)
-- Extracting specific entries by ID (`cbmem -e <ID>`)
-
-
-### Debugging Techniques
-
-- CBMEM console contents can be dumped to UART for debugging if serial
-  output is enabled.
-- The console overflow flag (`cbmem -c` output) helps identify if logs
-  were truncated.
-- Size validation within CBMEM helps detect potential memory corruption.
-- Magic numbers provide integrity validation for CBMEM structures.
-- Enabling `CONFIG_CBMEM_CHECKS` in Kconfig adds extra sanity checks
-  that can help catch issues during development.
-
-
-## Limitations
-
-While CBMEM is a powerful tool, it has some inherent limitations:
-
-- **Downward Growth**: The stack-like allocation (growing downwards)
-  means that only the most recently added entry can be removed. This
-  prevents fragmentation but limits flexibility in freeing memory.
-- **Fixed Size**: Once CBMEM is initialized in ramstage, its total size
-  and top address (`cbmem_top`) are fixed. Entries cannot be resized
-  after allocation.
-- **Platform Complexity**: Determining the correct `cbmem_top` can be
-  complex on some platforms due to varying memory maps and reserved
-  regions.
-
-
-## Best Practices for Developers
-
-When working with the CBMEM subsystem:
-
-1. **Alignment**: Always respect the alignment requirements of the
-   CBMEM tier (`IMD_ROOT` vs `IMD_SMALL`) you are using.
-
-2. **ID Selection**: Use unique, meaningful IDs for new entries,
-   preferably encoding ASCII characters for readability (see
-   `cbmem_id.h`).
-
-3. **Size Estimation**: Allocate sufficient space initially, as
-   entries cannot be resized.
-
-4. **Memory Conservation**: Be mindful of limited memory resources,
-   especially on constrained platforms. Avoid storing excessively large
-   data structures in CBMEM unless necessary.
-
-5. **Persistence**: Remember that CBMEM contents persist across
-   warm reboots (like S3 resume) but not across full system resets
-   (cold boots).
-
-6. **Entry Ordering**: Consider that only the most recently added
-   entry can be removed, which might influence your allocation strategy
-   if you anticipate needing to free space.

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/faq.md

@@ -1,312 +0,0 @@
-# coreboot FAQ
-
-## General coreboot questions
-
-
-### What is coreboot?
-
-coreboot is a free and open software project designed to initialize
-computers and embedded systems in a fast, secure, and auditable fashion.
-The focus is on minimal hardware initialization: to do only what is
-absolutely needed, then pass control to other software (a payload, in
-coreboot parlance) in order to boot the operating system securely.
-
-
-### What is a coreboot payload?
-
-coreboot itself does not deal with boot media such as hard-drives,
-SSDs, or USB flash-drives, beyond initializing the underlying hardware.
-So in order to actually boot an operating system, another piece of
-software which does do those things must be used. coreboot supports
-a large number of diverse payloads; see below for more details.
-
-
-### Is coreboot the same as UEFI?
-
-No. coreboot and UEFI are both system firmware that handle the
-initialization of the hardware, but are otherwise not similar.
-coreboot’s goal is to **just** initialize the hardware and exit.
-This makes coreboot smaller and simpler, leading to faster boot times,
-and making it easier to find and fix bugs. The result is a higher
-overall security.
-
-
-### What's the difference between coreboot and UEFI?
-
-UEFI is actually a firmware specification, not a specific software
-implementation. Intel, along with the rest of the Tianocore project,
-has released an open-source implementation of the overall framework,
-EDK2, but it does not come with hardware support. Most hardware running
-UEFI uses a proprietary implementation built on top of EDK2.
-
-coreboot does not implement the UEFI specification, but it can be used to
-initialize the system, then launch a UEFI payload such as EDK2 in order
-to provide UEFI boot services.
-
-The UEFI specification also defines and allows for many things that are
-outside of coreboot’s scope, including (but not limited to):
-
-* Boot device selection
-* Updating the firmware
-* A CLI shell
-* Network communication
-* An integrated setup menu
-
-
-### Can coreboot boot operating systems that require UEFI?
-
-Yes, but... again, coreboot **just** initializes the hardware. coreboot
-itself doesn’t load operating systems from storage media other than the
-flash chip. Unlike UEFI, coreboot does not, and will not contain a Wi-Fi
-driver or communicate directly with any sort of network. That sort of
-functionality is not related to hardware initialization.
-
-To boot operating systems that require UEFI, coreboot can be compiled with
-EDK2 as the payload. This allows coreboot to perform the hardware init,
-with EDK2 supplying the UEFI boot interface and runtime services to
-the operating system.
-
-
-### What non-UEFI payloads does coreboot support?
-
-* SeaBIOS, behaves like a classic BIOS, allowing you to boot operating
-  systems that rely on the legacy interrupts.
-
-* GRUB can be used as a coreboot payload, and is currently the most
-  common approach to full disk encryption (FDE).
-
-* A Linux kernel and initramfs stored alongside coreboot in the boot
-  ROM can also be used as a payload. In this scenario coreboot
-  initializes hardware, loads Linux from boot ROM into RAM, and
-  executes it. The embedded Linux environment can look for a target OS
-  kernel to load from local storage or over a network and execute it
-  using kexec. This is sometimes called LinuxBoot.
-
-* U-boot, depthcharge, FILO, etc.
-
-There’s [https://doc.coreboot.org/payloads.html](https://doc.coreboot.org/payloads.html)
-with a list, although it’s not complete.
-
-
-### What does coreboot leave in memory after it's done initializing the hardware?
-
-While coreboot tries to remove itself completely from memory after
-finishing, some tables and data need to remain for the OS. coreboot
-reserves an area in memory known as CBMEM, to save this data after it
-has finished booting. This contains things such as the boot log, tables
-that get passed to the payload, SMBIOS, and ACPI tables for the OS.
-
-In addition to CBMEM, on X86 systems, coreboot will typically set up
-SMM, which will remain resident after coreboot exits.
-
-
-## Platforms
-
-### What’s the best coreboot platform for a user?
-
-The choice of the best coreboot platform for a user can vary depending
-on their specific needs, preferences, and use cases.
-
-Typically, people who want a system with a minimum of proprietary
-firmware are restricted to older systems like the Lenovo X220, or more
-expensive, non-x86 solutions like TALOS, from Raptor Engineering.
-
-There are a number of companies selling modern systems, but those all
-require more proprietary binaries in addition to coreboot (e.g., Intel
-FSP). However, unlike the older ThinkPads, many of these newer devices
-use open-source embedded controller (EC) firmware, so there are
-tradeoffs with either option.
-
-The coreboot project mantains a list of companies selling machines
-which use coreboot on the [website](https://coreboot.org/users.html).
-
-
-### What’s the best platform for coreboot development?
-
-Similar to the best platform for users, the best platform for
-developers very much depends on what a developer is trying to do.
-
-* QEMU is generally the easiest platform for coreboot development, just
-  because it’s easy to run anywhere. However, it’s possible for things
-  to work properly in QEMU but fail miserably on actual hardware.
-
-While laptops tend to be harder to develop than desktop platforms, a
-majority of newer platforms on coreboot tend to be laptops. The
-development difficulty is due to a few different factors:
-
-1. The EC (Embedded Controller) is a specialized microcontroller that
-   typically handles keyboard and sometimes mouse input for a laptop.
-   It also controls many power management functions such as fans, USB-C
-   power delivery, etc. ECs run mainboard-specific firmware, which is
-   typically undocumented.
-2. ThinkPads (X230, 30-series, 20-series, T430, T540, T520). Sandy
-   Bridge and Ivy Bridge are well-supported. Some may have
-   difficult-to-reach SPI flash chips. Boards with two flash chips (e.g.
-   30-series ThinkPads) are harder to externally reflash as one needs to
-   make sure the non-targeted flash chip remains disabled at all times.
-   The X230 is notoriously sensitive to external reflashing issues.
-3. Laptops often lack a convenient method to obtain firmware boot logs.
-   One can use EHCI debug on older systems and Chromebook-specific
-   solutions for Chromebooks, but one often has to resort to flashconsole
-   (writing coreboot logs to the flash chip where coreboot resides). On
-   the other hand, several desktop mainboards still have a RS-232 serial
-   port.
-
-Some of the easiest physical systems to use for coreboot development
-are Chromebooks. Newer Chromebooks allow for debug without opening the
-case. Look for SuzyQ Cables or SuzyQables or instructions on how to
-build one. These cables only work on a specific port in a specific
-orientation. Google [supplies
-specifications](https://chromium.googlesource.com/chromiumos/third_party/hdctools/+/master/docs/ccd.md#SuzyQ-SuzyQable)
-for these cables.
-
-
-### What platforms does coreboot support?
-
-The most accurate way to determine what systems coreboot supports is by
-browsing the src/mainboard tree or running “make menuconfig” and going
-through the “Mainboard” submenu. You can also search Gerrit to see if
-there are any unmerged ports for your board.
-
-There is also the board status page
-([https://coreboot.org/status/board-status.html](https://coreboot.org/status/board-status.html)),
-however this does not currently show supported board variants.
-
-
-## coreboot Development
-
-### Can coreboot be ported to [this board]?
-
-The best way to determine if coreboot can be ported to a system is to
-see if the processor and chipset is supported. The next step is to see
-whether the system is locked to the proprietary firmware which comes
-with the board.
-
-Intel Platforms:
-
-* coreboot only supports a few northbridges (back when northbridges
-  were on a separate package), and there's next to no support for
-  "server" platforms (multi-socket and similar things). Here's a list
-  of more recent supported Intel processors:
-    * Alder Lake (2021 - Core Gen 12)
-    * Apollo Lake (2016 - Atom)
-    * Baytrail (2014 - Atom)
-    * Braswell (2016 - Atom)
-    * Broadwell (2014 - Core Gen 5)
-    * Comet Lake (2019 - Core Gen 10)
-    * Cannon Lake (2018 - Core Gen 8/9)
-    * Denverton (2017)
-    * Elkhart lake (2021 - Atom)
-    * Haswell (2013 - Core Gen 4)
-    * Ivy Bridge (2012 - Core Gen 3)
-    * Jasper Lake (2021 - Atom)
-    * Kaby Lake (2016 - Core Gen 7/8)
-    * Meteor Lake (2023 - Gen 1 Ultra-mobile)
-    * Sandy Bridge (2011 - Core Gen 2)
-    * Sky Lake (2015 - Core Gen 6)
-    * Tiger Lake (2020 - Core Gen 11)
-    * Whiskey Lake (2018 - Core Gen 8)
-
-* Intel Boot Guard is a security feature which tries to prevent loading
-  unauthorized firmware by the mainboard. If supported by the platform,
-  and the platform is supported by intelmetool, you should check if Boot
-  Guard is enabled. If it is, then getting coreboot to run will be
-  difficult or impossible even if it is ported. You can run
-  `intelmetool -b` on supported platforms to see if Boot Guard is
-  enabled (although it can fail because it wants to probe the ME
-  beforehand).
-
-AMD Ryzen-based platforms:
-
-* The AMD platforms Ryzen-based platforms unfortunately are currently
-  not well supported outside of the Chromebooks (and AMD reference
-  boards) currently in the tree.
-  The responsible teams are trying to fix this, but currently it's
-  **very** difficult to do a new port. Recent supported SoCs:
-    * Stoney Ridge
-    * Picasso
-    * Cezanne
-    * Mendocino
-    * Phoenix
-
-General notes:
-
-* Check the output of `lspci` to determine what processor/chipset
-  family your system has. Processor/chipset support is the most
-  important to determine if a board can be ported.
-* Check the output of `superiotool` to see if it detects the Super I/O
-  on the system. You can also check board schematics and/or boardviews
-  if you can find them, or physically look at the mainboard for a chip
-  from one of the common superio vendors.
-* Check what EC your system has (mostly applicable to laptops, but some
-  desktops have EC-like chips). You will likely need to refer to the
-  actual board or schematics/boardviews for this. Physical observation
-  is the most accurate identification procedure; software detection can
-  then be used to double-check if the chip is correct, but one should
-  not rely on software detection alone to identify an EC.
-
-
-### How do I port coreboot to [this board]?
-
-A critical piece for anyone attempting to do a board port is to make
-sure that you have a method to recover your system from a failed flash.
-
-We need an updated motherboard porting guide, but currently the guide
-on the [wiki](https://www.coreboot.org/Motherboard_Porting_Guide) looks
-to be the best reference.
-
-At the moment, the best answer to this question is to ask for help on
-one of the [various community
-forums](https://doc.coreboot.org/community/forums.html).
-
-
-### What about the Intel ME?
-
-There seems to be a lot of FUD about what the ME can and can’t do.
-coreboot currently does not have a clear recommendation on how to
-handle the ME. We understand that there are serious concerns about the
-ME, and would like to flatly recommend removing as much as possible,
-however modifying the ME can cause serious stability issues.
-
-Additionally, coreboot and the Intel ME are completely separate entites
-which in many cases simply happen to occupy the same flash chip. It is
-not necessary to run coreboot to modify the ME, and running coreboot
-does not imply anything about the ME's operational state.
-
-
-#### A word of caution about the modifying ME
-
-Messing with the ME firmware can cause issues, and this is outside the
-scope of the coreboot project.
-
-If you do decide to modify the ME firmware, please make sure coreboot
-works **before** messing with it. Even if the vendor boot firmware
-works when the ME isn't operating normally, it's possible that coreboot
-doesn't handle it the same way and something breaks. If someone asks
-for help with coreboot and we think the ME state may be a factor, we'll
-ask them to try reproducing the issue with the ME running normally to
-reduce the number of variables involved. This is especially important
-when flashing coreboot for the first time, as it's best for newbies to
-start with small steps: start by flashing coreboot to the BIOS region
-and leaving the remaining regions untouched, then tinker around with
-coreboot options (e.g. other payloads, bootsplash, RAM overclock...),
-or try messing with the ME firmware **without changing coreboot**.
-
-Most people don't understand the implications of messing with the ME
-firmware, especially the use of `me_cleaner`. We admit that we don't
-know everything about the ME, but we try to understand it as much as
-possible. The ME is designed to operate correctly with the HAP (or
-AltMeDisable) bit set, and it will gracefully enter a debug state (not
-normal, but not an error). However, when using `me_cleaner` to remove
-parts of the ME firmware, the ME will often end up in an error state
-because parts of its FW are missing. It is known that removing some of
-these parts ([`EFFS` and `FCRS` on Cougar Point,
-c.f.](https://review.coreboot.org/c/coreboot/+/27798/6/src/mainboard/asus/p8h61-m_lx/Kconfig#63))
-can cause problems. We do not know whether the state the ME ends up in
-after applying `me_cleaner` is as secure as the state the ME goes to
-when only the HAP bit is set: the removed FW modules could contain
-steps to lock down important settings for security reasons.
-
-To sum up, **we do not recommend messing with the ME firmware**. But if
-you have to, please use `ifdtool` to set the HAP bit initially before
-progressing to `me_cleaner` if necessary.

Documentation/getting_started/gerrit_guidelines.md

@@ -9,7 +9,7 @@ friction in the community.
 
 Note that as with many rules, there are exceptions. Some have been noted
 in the 'More Detail' section. If you feel there is an exception not listed
-here, please discuss it in the mailing list to get this document updated.
+here, please discuss it in the mailing list to get this document  updated.
 Don't just assume that it's okay, even if someone on IRC says it is.
 
 
@@ -41,7 +41,7 @@ project you're submitting the changes to. If you’re submitting code that
 you wrote that might be owned by your employer, make sure that your
 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](#sign-off-procedure).
+[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
@@ -53,10 +53,7 @@ it's implemented, should restart the wait period.
 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
+the problem so that the emergency need becomes apparent. The change
 itself should be as limited in scope and impact as possible to make it
 simple to assess the impact. Such a change can be merged early with 3
 Code-Review+2. For emergency fixes that affect a single project (SoC,
@@ -127,54 +124,6 @@ those platforms. While it would be nice to update any other platforms, you
 must at least provide a path that will allow other platforms to continue
 working.
 
-Sign-off Procedure
-------------------
-The coreboot project employs a sign-off procedure similar to what is
-used by the Linux kernel. Each gerrit commit requires a sign-off line
-saying that the contributed code abides by the Developer's certificate
-of origin, below.
-```text
-Signed-off-by: Random J Developer <random@developer.example.org>
-```
-
-Using '-s' with 'git commit' will automatically add a Signed-off-by line
-to your commit message.  Patches without a Signed-off-by should not be
-pushed to gerrit, and will be rejected by coreboot's CI system.
-
-You must use a known identity in the Signed-off-by line. Anonymous
-contributions cannot be committed! This can be anything sufficient to
-identify and contact the source of a contribution, such as your name or
-an established alias/nickname. Refer to [this LKML thread] and the
-[SCO-Linux disputes] for the rationale behind the DCO.
-
-Developer's Certificate of Origin 1.1
-
-> By making a contribution to this project, I certify that:
->
-> (a) The contribution was created in whole or in part by me and I have
-> the right to submit it under the open source license indicated in the
-> file; or
->
-> (b) The contribution is based upon previous work that, to the best of
-> my knowledge, is covered under an appropriate open source license and
-> I have the right under that license to submit that work with
-> modifications, whether created in whole or in part by me, under the
-> same open source license (unless I am permitted to submit under a
-> different license), as indicated in the file; or
->
-> (c) The contribution was provided directly to me by some other person
-> who certified (a), (b) or (c) and I have not modified it; and
->
-> (d) In the case of each of (a), (b), or (c), I understand and agree
-> that this project and the contribution are public and that a record of
-> the contribution (including all personal information I submit with it,
-> including my sign-off) is maintained indefinitely and may be
-> redistributed consistent with this project or the open source license
-> indicated in the file.
-
-Note: The [Developer's Certificate of Origin 1.1] is licensed under the
-terms of the [Creative Commons Attribution-ShareAlike 2.5 License].
-
 
 Recommendations for gerrit activity
 -----------------------------------
@@ -221,10 +170,7 @@ This helps verify that the patch train won’t tie up the jenkins builders
 for no reason if there are failing patches in the train. For running
 parallel builds, you can specify the number of cores to use by setting the
 the CPUS environment variable. Example:
-
-```Bash
-make what-jenkins-does CPUS=8
-```
+        make what-jenkins-does CPUS=8
 
 * Use a topic when pushing a train of patches. This groups the commits
 together so people can easily see the connection at the top level of
@@ -232,10 +178,7 @@ gerrit. Topics can be set for individual patches in gerrit by going into
 the patch and clicking on the icon next to the topic line. Topics can also
 be set when you push the patches into gerrit. For example, to push a set of
 commits with the i915-kernel-x60 set, use the command:
-
-```Bash
-git push origin HEAD:refs/for/main%topic=i915-kernel-x60
-```
+        git push origin HEAD:refs/for/master%topic=i915-kernel-x60
 
 * If one of your patches isn't ready to be merged, make sure it's obvious
 that you don't feel it's ready for merge yet. The preferred way to show
@@ -245,28 +188,17 @@ Examples of this are "WIP: title" or "[NEEDS_TEST]: title".  Another way to
 mark the patch as not ready would be to give it a -1 or -2 review, but
 isn't as obvious as the commit message. These patches can also be pushed with
 the wip flag:
-
-```Bash
-git push origin HEAD:refs/for/main%wip
-```
+	git push origin HEAD:refs/for/master%wip
 
 * 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:
-
-```Bash
-git push origin HEAD:refs/for/main%private
-```
+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:
-
-```Bash
-git push origin HEAD:refs/for/main%private,wip,topic=experiment
-```
+        git push origin HEAD:refs/for/master%private,wip,topic=experiment
 
 * Respond to anyone who has taken the time to review your patches, even if
 it's just to say that you disagree. While it may seem annoying to address a
@@ -292,7 +224,7 @@ changed.
 helps others and shows that these mainboards are currently being
 maintained. At some point, boards that are not up to date in the
 board-status repo will probably end up getting removed from the coreboot
-main branch.
+master branch.
 
 * Abandon patches that are no longer useful, or that you don’t intend to
 keep working on to get submitted.
@@ -304,7 +236,7 @@ would be a good reviewer, look in the MAINTAINERS file or git history of
 the files that you’ve changed, and add those people.
 
 * Familiarize yourself with the coreboot [commit message
-guidelines](#commit-message-guidelines), before pushing
+guidelines](https://www.coreboot.org/Git#Commit_messages), before pushing
 patches. This will help to keep annoying requests to fix your commit
 message to a minimum.
 
@@ -340,16 +272,14 @@ git/gerrit tags by prepending the lines with 'Original-'.  Marking
 the original text this way makes it much easier to tell what changes
 happened in which repository. This applies to these lines, not the actual
 commit message itself:
-
-	* Commit-Id:
-	* Change-Id:
-	* Signed-off-by:
-	* Reviewed-on:
-	* Tested-by:
-	* Reviewed-by:
-
-The script `util/scripts/cross-repo-cherrypick` can be used to help
-automate this. Other tags such as 'Commit-Queue' can simply be removed.
+        Commit-Id:
+        Change-Id:
+        Signed-off-by:
+        Reviewed-on:
+        Tested-by:
+        Reviewed-by:
+The script 'util/gitconfig/rebase.sh' can be used to help automate this.
+Other tags such as 'Commit-Queue' can simply be removed.
 
 * Check if there's documentation that needs to be updated to remain current
 after your change. If there's no documentation for the part of coreboot
@@ -395,8 +325,8 @@ 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" code reviews.
-- A reviewer can give "-1" and "+2" code reviews.
+- 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.
 
@@ -433,55 +363,4 @@ 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>.
 
-Commit message guidelines
--------------------------
-Git does not enforce a certain style for commit messages. For all aspects of
-Git to work best with, it's important to follow these simple guidelines for
-commit messages:
-
-* The first line of the commit message consists of a short
-  (less than 65 characters, absolute maximum is 75) summary
-* The second line is empty (no whitespace at all)
-* The third and any following number of lines contains a longer description
-  of the commit as is necessary, including relevant background information
-  and quite possibly rationale for why the issue was solved in this particular
-  way. These lines should never be longer than 75 characters.
-* The next line is empty (no whitespace at all)
-* An optional TEST= line which describes the test that was done in order to
-  validate the patch
-* An optional BUG= line to reference to a bug (of [coreboot's bug tracker] or any
-  other) this patch resolves
-* The next line is empty if the optional lines are used
-* A Change-Id: line to let Gerrit track this logical change
-* A Signed-off-by: line according to [Signed-off-by policy](#sign-off-procedure)
-
-Please do not create the Change-Id: and Signed-off-by: entries manually because
-it is boring and error-prone. Instead, please install the commit-msg hook, e.g.
-by running
-```Bash
-make gitconfig
-```
-in coreboot's top-level directory, and let the hook script do it for you.
-And remember to always use
-```Bash
-git commit -s
-```
-to have git add your Signed-off-by: automatically.
-
-When you write your commit message, please keep the following two hints in mind:
-
-* If anyone involved in coreboot reads your comment in a year or so, they
-  shall still be able to understand what your commit is about, without the need
-  to analyze the code.
-* Double-check that you are really committing what you think you are, e.g. by
-  typing the following in the top-level coreboot directory:
-```Bash
-git show
-```
-
 [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
-[Developer's Certificate of Origin 1.1]: https://developercertificate.org/
-[Creative Commons Attribution-ShareAlike 2.5 License]: https://creativecommons.org/licenses/by-sa/2.5/
-[this LKML thread]: https://lkml.org/lkml/2004/5/23/10
-[SCO-Linux disputes]: https://en.wikipedia.org/wiki/SCO%E2%80%93Linux_disputes
-[coreboot's bug tracker]: https://ticket.coreboot.org/

Documentation/getting_started/gpio.md

@@ -162,82 +162,6 @@ 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

Documentation/getting_started/index.md

@@ -1,15 +1,10 @@
 # Getting Started
 
-```{toctree}
-:maxdepth: 1
-
-coreboot architecture <architecture.md>
-Build System <build_system.md>
-Submodules <submodules.md>
-Kconfig <kconfig.md>
-Writing Documentation <writing_documentation.md>
-Setting up GPIOs <gpio.md>
-Adding devices to a device tree <devicetree.md>
-CBMEM <cbmem.md>
-Frequently Asked Questions <faq.md>
-```
+* [coreboot architecture](architecture.md)
+* [Build System](build_system.md)
+* [Submodules](submodules.md)
+* [Kconfig](kconfig.md)
+* [Gerrit Guidelines](gerrit_guidelines.md)
+* [Documentation License](license.md)
+* [Writing Documentation](writing_documentation.md)
+* [Setting up GPIOs](gpio.md)

Documentation/getting_started/kconfig.md

@@ -69,6 +69,9 @@ These variables are typically set in the makefiles or on the make command line.
 These variables were added to Kconfig specifically for coreboot and are not
 included in the Linux version.
 
+- KCONFIG_STRICT=value. Define to enable warnings as errors.   This is enabled
+  in coreboot, and should not be changed.
+
 - KCONFIG_NEGATIVES=value. Define to show negative values in the autoconf.h file
   (build/config.h). This is enabled in coreboot, and should not be changed.
 
@@ -99,9 +102,6 @@ included in the Linux version.
 - KCONFIG_SPLITCONFIG=”directory name for individual SYMBOL.h files”.
   coreboot sets this to $(obj)/config.
 
-- KCONFIG_WERROR=value. Define to enable warnings as errors. This is enabled
-  in coreboot, and should not be changed.
-
 #### Used only for ‘make menuconfig’
 - MENUCONFIG_MODE=single_menu.  Set to "single_menu" to enable.  All other
   values disable the option.  This makes submenus appear below the menu option
@@ -196,9 +196,9 @@ values to be set based on other values.
   visible in the front end.
 
 
-### Keywords
+## Keywords
 
-#### bool
+### bool
 
 The 'bool' keyword assigns a boolean type to a symbol. The allowable values for
 a boolean type are 'n' or 'y'. The keyword can be followed by an optional prompt
@@ -234,7 +234,7 @@ bool \[prompt\] \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### choice
+### choice
 
 This creates a selection list of one or more boolean symbols. For bools, only
 one of the symbols can be selected, and one will be be forced to be selected,
@@ -297,7 +297,7 @@ choice \[symbol\]
 
 --------------------------------------------------------------------------------
 
-#### comment
+### comment
 
 This keyword defines a line of text that is displayed to the user in the
 configuration frontend and is additionally written to the output files.
@@ -322,7 +322,7 @@ comment <prompt>
 
 --------------------------------------------------------------------------------
 
-#### config
+### config
 
 This is the keyword that starts a block defining a Kconfig symbol. The symbol
 modifiers follow the 'config' statement.
@@ -359,7 +359,7 @@ config <symbol>
 
 --------------------------------------------------------------------------------
 
-#### default
+### default
 
 The ‘default’ keyword assigns a value to a symbol in the case where no preset
 value exists, i.e. the symbol is not present and assigned in .config.  If there
@@ -399,7 +399,7 @@ default <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### def_bool
+### def_bool
 
 ‘def_bool’ is similar to the 'bool' keyword in that it sets a symbol’s type to
 boolean. It lets you set the type and default value at the same time, instead
@@ -433,7 +433,7 @@ def_bool <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### depends on
+### depends on
 
 This defines a dependency for a menu entry, including symbols and comments.  It
 behaves the same as surrounding the menu entry with an if/endif block.  If the
@@ -462,28 +462,28 @@ depends on <expr>
 
 --------------------------------------------------------------------------------
 
-#### endchoice
+### endchoice
 
 This ends a choice block. See the 'choice' keyword for more information and an
 example.
 
 --------------------------------------------------------------------------------
 
-#### endif
+### endif
 
 This ends a block started by the 'if' keyword. See the 'if' keyword for more
 information and an example.
 
 --------------------------------------------------------------------------------
 
-#### endmenu
+### endmenu
 
 This ends a menu block. See the 'menu' keyword for more information and an
 example.
 
 --------------------------------------------------------------------------------
 
-#### help
+### help
 
 The 'help' keyword defines the subsequent block of text as help for a config or
 choice block. The help block is started by the 'help' keyword on a line by
@@ -515,7 +515,7 @@ help <help text>
 
 --------------------------------------------------------------------------------
 
-#### hex
+### hex
 
 This is another symbol type specifier, specifying an unsigned integer value
 formatted as hexadecimal.
@@ -551,7 +551,7 @@ hex <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### if
+### if
 
 The 'if' keyword is overloaded, used in two different ways. The first definition
 enables and disables various other keywords, and follows the other keyword
@@ -592,7 +592,7 @@ endif
 
 --------------------------------------------------------------------------------
 
-#### int
+### int
 
 A type setting keyword, defines a symbol as an integer, accepting only signed
 numeric values.  The values can be further restricted with the ‘range’ keyword.
@@ -628,7 +628,7 @@ int <expr> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### mainmenu
+### mainmenu
 
 The 'mainmenu' keyword sets the title or title bar of the configuration front
   end, depending on how the configuration program decides to use it. It can only
@@ -648,7 +648,7 @@ mainmenu "coreboot configuration"
 
 --------------------------------------------------------------------------------
 
-#### menu
+### menu
 
 The 'menu' and 'endmenu' keywords tell the configuration front end that the
 enclosed statements are part of a group of related pieces.
@@ -695,7 +695,7 @@ endmenu
 
 --------------------------------------------------------------------------------
 
-#### prompt
+### prompt
 
 The 'prompt' keyword sets the text displayed for a config symbol or choice in
 configuration front end.
@@ -748,7 +748,7 @@ prompt <prompt> \[if <expr>\]
             prompt "Prompt value 2"
 --------------------------------------------------------------------------------
 
-#### range
+### range
 
 This sets the allowable minimum and maximum entries for hex or int type config
 symbols.
@@ -770,7 +770,7 @@ range <symbol> <symbol> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### select
+### select
 
 The ‘select’ keyword is used within a bool type config block.  In coreboot (and
 other projects that don't use modules), the 'select' keyword can force an
@@ -786,7 +786,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
@@ -814,7 +814,7 @@ select <symbol> \[if <expr>\]
 
 --------------------------------------------------------------------------------
 
-#### source
+### source
 
 The 'source' keyword functions much the same as an 'include' statement in c.
 This pulls one or more files into Kconfig at the location of the 'source'
@@ -873,7 +873,7 @@ statements that generate a list of all the platform names:
 
 --------------------------------------------------------------------------------
 
-#### string
+### string
 
 The last of the symbol type assignment keywords. 'string' allows a text value to
 be entered.
@@ -919,7 +919,7 @@ keyword later. See the prompt keyword for more notes.
 
 
 
-### Keywords not used in coreboot at the time of writing:
+## Keywords not used in coreboot at the time of writing:
 
 - allnoconfig_y:
 - defconfig_list
@@ -944,7 +944,7 @@ statements:
     #define SYMBOL NAME XXX
 
 
-#### Symbol types:
+##### Symbol types:
 - bool, int, and hex types -  Every symbol of one of these types created in the
   Kconfig tree is defined.  It doesn’t matter whether they’re in an if/endif
   block, or have a ‘depends on’ statement - they ALL end up being defined in
@@ -963,7 +963,7 @@ variable.  This is not set in coreboot, which uses the default CONFIG_ prefix
 for all of its symbols.
 
 The coreboot makefile forces the config.h file to be included into all coreboot
-C files. This is done in Makefile.mk on the compiler command line using the
+C files. This is done in Makefile.inc on the compiler command line using the
 “-include $(obj)/config.h” command line option.
 
 Example of various symbol types in the config.h file:
@@ -1160,25 +1160,29 @@ saved .config file. As always, a 'select' statement overrides any specified
 - coreboot has added the glob operator '*' for the 'source' keyword.
 - coreboot’s Kconfig always defines variables except for strings. In other
   Kconfig implementations, bools set to false/0/no are not defined.
+- coreboot’s version of Kconfig adds the KCONFIG_STRICT environment variable to
+  error out if there are any issues in the Kconfig files.  In the Linux kernel,
+  Kconfig will generate a warning, but will still output an updated .config or
+  config.h file.
 
 
 ## Kconfig Editor Highlighting
 
-### vim:
+#### vim:
 
 vim has syntax highlighting for Kconfig built in (or at least as a part of
 vim-common), but most editors do not.
 
 
-### ultraedit:
+#### ultraedit:
 
-<https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew>
+https://github.com/martinlroth/wordfiles/blob/master/kconfig.uew
 
 
 
-### atom:
+#### atom:
 
-<https://github.com/martinlroth/language-kconfig>
+https://github.com/martinlroth/language-kconfig
 
 
 ## Syntax Checking:
@@ -1217,7 +1221,7 @@ in.
 ## License:
 This work is licensed under the Creative Commons Attribution 4.0 International
 License. To view a copy of this license, visit
-<https://creativecommons.org/licenses/by/4.0/> or send a letter to Creative
+https://creativecommons.org/licenses/by/4.0/ or send a letter to Creative
 Commons, PO Box 1866, Mountain View, CA 94042, USA.
 
 Code examples snippets are licensed under GPLv2, and are used here under fair

Documentation/getting_started/writing_documentation.md

@@ -14,13 +14,18 @@ coreboot uses [Sphinx] documentation tool. We prefer the markdown format
 over reStructuredText so only embedded ReST is supported. Checkout the
 [Markdown Guide] for more information.
 
-### Option 1: Use the docker image
+### option 1: Use the docker image
 
 The easiest way to build the documentation is using a docker image.
 To build the image run the following in the base directory:
 
 	make -C util/docker/ doc.coreboot.org
 
+Before building the documentation make sure the output directory is given
+the correct permissions before running docker.
+
+	mkdir -p Documentation/_build
+
 To build the documentation:
 
 	make -C util/docker docker-build-docs
@@ -31,29 +36,31 @@ To have the documentation build and served over a web server live run:
 
 On the host machine, open a browser to the address <http://0.0.0.0:8000>.
 
-### Option 2: Install Sphinx
+### option 2: Install Sphinx
 
-Please follow this official [guide] to install sphinx. You will also need
-myst-parser for sphinx to be able to handle markdown documentation.
+Please follow this official [guide] to install sphinx.
+You will also need python-recommonmark for sphinx to be able to handle
+markdown documentation.
 
 Since some Linux distributions don't package every needed sphinx extension,
 the installation via pip in a venv is recommended. You'll need these python3
 modules:
 
 * sphinx
-* myst-parser
-* sphinx-rtd-theme
+* recommonmark
+* sphinx_rtd_theme
+* sphinxcontrib-ditaa
 
-The following combination of versions has been tested: sphinx 8.1.3,
-myst-parser 4.0.0, and sphinx-rtd-theme 2.0.0.
+The following combination of versions has been tested: sphinx 2.3.1,
+recommonmark 0.6.0, sphinx_rtd_theme 0.4.3 and sphinxcontrib-ditaa 0.7.
 
 Now change into the `Documentation` folder in the coreboot directory and run
 this command in there
 
-	make
+	make sphinx
 
 If no error occurs, you can find the generated HTML documentation in
-`Documentation/_build/html` now.
+`Documentation/_build` now.
 
 ### Optional
 
@@ -82,19 +89,17 @@ Documentation:
 12.  Shouldn't cover implementation details; for details, the code is the
      reference.
 
+## Referencing markdown documents
+
+Starting with Sphinx 1.6 recommonmark's *auto_doc_ref* feature is broken.
+To reference documents use the TOC tree or inline RST code.
+
 ## Markdown and Tables
 
-Markdown tables are supported:
+Under Sphinx markdown tables are not supported. Therefore you can use following
+code block to write tables in reStructuredText and embed them into the markdown:
 
-    | Header 1   | Header 2  | Header 3  |
-    |------------|-----------|-----------|
-    | body row 1 | column 2  | column 3  |
-    | body row 2 | column 2  | column 3  |
-
-Tables can also be written using embedded reStructured Text, which provides
-additional features like the ability to merge cells:
-
-    ```{eval-rst}
+    ```eval_rst
     +------------+------------+-----------+
     | Header 1   | Header 2   | Header 3  |
     +============+============+===========+
@@ -113,20 +118,22 @@ additional features like the ability to merge cells:
 To make sure that all documents are included into the final documentation, you
 must reference each document from at least one *toctree*. The *toctree* must
 only reference files in the same folder or in subfolders !
-To create a toctree, you must use the following syntax to invoke the
-Sphinx toctree directive:
+To create a toctree, simply use a bullet list or numbered list with a single
+reference. References in regular text aren't considered as *toctree* .
+This feature is enabled by recommonmark's *enable_auto_toc_tree* .
 
 **Example toctree:**
 
-    ```{toctree}
-    :maxdepth: 1
+```
+* [Chapter 1](chapter1.md)
+* [Chapter 2](chapter2.md)
+* [Subchapter](sub/index.md)
+```
 
-    Chapter 1 <chapter1.md>
-    Chapter 2 <chapter2.md>
-    Subchapter <sub/index.md>
-    ```
-
-References in regular text aren't considered as *toctree* .
+```
+1. [Chapter 1](chapter1.md)
+2. [Chapter 2](chapter2.md)
+```
 
 If you do only reference the document, but do not include it in any toctree,
 you'll see the following warning:
@@ -137,7 +144,7 @@ you'll see the following warning:
 You can import CSV files and let sphinx automatically convert them to human
 readable tables, using the following reStructuredText snipped:
 
-    ```{eval-rst}
+    ```eval_rst
     .. csv-table::
        :header: "Key", "Value"
        :file: keyvalues.csv
@@ -146,9 +153,11 @@ readable tables, using the following reStructuredText snipped:
 Of course this can only be done from a markdown file that is included in the
 TOC tree.
 
-[sphinx-autobuild]: https://github.com/sphinx-doc/sphinx-autobuild
-[guide]: https://www.sphinx-doc.org/en/master/usage/installation.html
-[Sphinx]: https://www.sphinx-doc.org/en/master/
+[coreboot]: https://coreboot.org
+[Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
+[sphinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
+[guide]: http://www.sphinx-doc.org/en/stable/install.html
+[Sphinx]: http://www.sphinx-doc.org/en/master/
 [Markdown Guide]: https://www.markdownguide.org/
-[Gerrit Guidelines]: ../contributing/gerrit_guidelines.md
+[Gerrit Guidelines]: gerrit_guidelines.md
 [review.coreboot.org]: https://review.coreboot.org

Documentation/gfx/display-panel.md

@@ -22,7 +22,7 @@ the power sequence timing parameters, which are usually named T[N] and also
 referenced in Intel's respective registers listing. You need the values for
 `PP_ON_DELAYS`, `PP_OFF_DELAYS` and `PP_DIVISOR` for your `devicetree.cb`:
 
-```{eval-rst}
+```eval_rst
 +-----------------------------+---------------------------------------+-----+
 | Intel docs                  | devicetree.cb                         | eDP |
 +-----------------------------+---------------------------------------+-----+

Documentation/gfx/libgfxinit.md

@@ -22,14 +22,14 @@ GMA: Framebuffer Configuration
 *coreboot* supports two different framebuffer setups. The default
 enables the legacy VGA plane in textmode. Due to legacy hardware
 constraints, only the first found display is enabled in this mode.
-(cf. `src/drivers/intel/gma/text_fb/gma-gfx_init.adb`).
+(cf. `src/drivers/intel/gma/text_fb/gma.adb`).
 
 The second option sets up a high-resolution framebuffer with the
 native resolution of the display if only one is detected, or the
 smallest of all resolutions (per dimension) if multiple displays
 are detected. This option is selected by
 `CONFIG_FRAMEBUFFER_KEEP_VESA_MODE`.
-(cf. `src/drivers/intel/gma/hires_fb/gma-gfx_init.adb`).
+(cf. `src/drivers/intel/gma/hires_fb/gma.adb`).
 
 In any case, a smaller framebuffer is up-scaled to each display's
 native resolution while keeping aspect ratio.

Documentation/ifdtool/binary_extraction.md

@@ -9,9 +9,9 @@ Now, execute the following commands to extract the binaries from a ROM image.
 **Note:** Make sure you are in the root coreboot directory.
 
     cd /path/to/coreboot/util/ifdtool
-    make
-    ./ifdtool -d COREBOOT_IMAGE # dump flash descriptor to stdout
-    ./ifdtool -x COREBOOT_IMAGE # extract IFD binaries into files (e.g. ME, IFD, GBE...)
+    ./ifdtool COREBOOT_IMAGE
+    ./ifdtool -d COREBOOT_IMAGE
+    ./ifdtool -x COREBOOT_IMAGE
 
 In the above steps, COREBOOT_IMAGE is the name of the ROM image to extract the
 binaries from, including the file path (ex. /build/coreboot.rom).

Documentation/ifdtool/index.md

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

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
@@ -14,7 +14,7 @@ The names of the IFD regions in the FMAP should follow the convention of
 starting with the prefix `SI_` which stands for `silicon initialization` as a
 way to categorize anything required by the SoC but not provided by coreboot.
 
-```{eval-rst}
+```eval_rst
 +------------+------------------+-----------+-------------------------------------------+
 | IFD Region | IFD Region name  | FMAP Name | Notes                                     |
 | index      |                  |           |                                           |
@@ -29,7 +29,7 @@ way to categorize anything required by the SoC but not provided by coreboot.
 +------------+------------------+-----------+-------------------------------------------+
 | 4          | Platform Data    | SI_PDR    |                                           |
 +------------+------------------+-----------+-------------------------------------------+
-| 8          | EC Firmware      | SI_EC     | Most ChromeOS devices do not use this     |
+| 8          | EC Firmware      | SI_EC     | Most Chrome OS devices do not use this    |
 |            |                  |           | region; EC firmware is stored in BIOS     |
 |            |                  |           | region of flash                           |
 +------------+------------------+-----------+-------------------------------------------+

Documentation/index.md

@@ -1,13 +1,9 @@
 # Welcome to the coreboot documentation
 
 This is the developer documentation for [coreboot](https://coreboot.org).
-It is built from Markdown files in the [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.
+It is built from Markdown files in the
+[Documentation](https://review.coreboot.org/cgit/coreboot.git/tree/Documentation)
+directory in the source code.
 
 ## Purpose of coreboot
 
@@ -25,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.
 
@@ -139,55 +135,16 @@ Every now and then, coreboot is present in one way or another at
 [conferences](community/conferences.md). If you're around, come and
 say hello!
 
-## Blob policy in the coreboot project
-
-The goal of the coreboot project is to provide a FOSS firmware solution across
-multiple CPU architectures, such as ARM, x86, and RISC-V. While fully open
-source implementations for these architectures are encouraged and preferred,
-we understand that a fully open implementation whereby every firmware component
-is available as source code for modern platforms is not always feasible.
-Different reasons inhibit the availability of fully open implementations,
-including limited development resources, 3rd party license constraints of
-IP blocks, or a legacy mindset of the silicon vendors.
-
-It is important for the coreboot project to have support for modern CPU
-platforms in order to provide a viable alternative for proprietary firmware
-implementations. We do not have direct control over how hardware vendors design
-their products, however we can provide an attractive alternative to the
-expensive and complicated proprietary firmware model that exists today.
-For modern platforms, we are largely dependent on the silicon
-vendor to provide additional information on how to properly initialize the
-hardware, as the required datasheets are often only available with an NDA.
-Therefore, one possible way to have coreboot support for the latest platforms
-is binary code (aka, a blob) provided by the silicon vendor. While we do
-discourage this solution, it can be a door opener for coreboot’s support of a
-given platform and thus keep coreboot functional on modern platforms. It is
-clearly not the goal of the project to accept every blob a silicon vendor wishes
-to use without question. On the contrary, each new blob needs to be examined
-critically by the community, evaluating the need, risk, and alternative options.
-
-Wherever possible, introducing new blobs should be avoided. That said, there
-can be situations where a piece of code provided as a blob will enable the rest
-of the fully open source firmware stack on a brand new platform. If blocking
-this blob would lead to no support at all for the platform in question in
-coreboot, this situation needs to be examined carefully. While these kinds
-of discussion will be coordinated closely with the community (e.g. on the
-mailing list or dedicated meetings), ultimately it is up to the leadership to
-decide if there is no agreement between the community and the vendor pushing for
-the new blob. This decision will be communicated on the mailing list.
-Please see additionally
-[coreboot binary policy](https://github.com/coreboot/blobs/blob/master/README.md).
-
 ## Getting the source code
 
 coreboot is primarily developed in the
-[git](https://review.coreboot.org/plugins/gitiles/coreboot) version control
+[git](https://review.coreboot.org/cgit/coreboot.git) version control
 system, using [Gerrit](https://review.coreboot.org) to manage
 contributions and code review.
 
-In general we try to keep the `main` branch in the repository functional
+In general we try to keep the `master` branch in the repository functional
 for all hardware we support. So far, the only guarantee we can make is
-that the main branch will (nearly) always build for all boards in a
+that the master branch will (nearly) always build for all boards in a
 standard configuration.
 
 However, we're continually working on improvements to our infrastructure to
@@ -209,39 +166,34 @@ for example OpenBSD, is probably the closest cousin of our approach.
 
 Contents:
 
-```{toctree}
-:maxdepth: 1
-
-Getting Started <getting_started/index.md>
-Tutorial <tutorial/index.md>
-Contributing <contributing/index.md>
-Community <community/index.md>
-Payloads <payloads.md>
-Distributions <distributions.md>
-Technotes <technotes/index.md>
-Internal APIs & Configuration <internals/index.md>
-ACPI <acpi/index.md>
-Native Graphics Initialization with libgfxinit <gfx/libgfxinit.md>
-Display panel <gfx/display-panel.md>
-CPU Architecture <arch/index.md>
-Platform independent drivers <drivers/index.md>
-Northbridge <northbridge/index.md>
-System on Chip <soc/index.md>
-Mainboard <mainboard/index.md>
-Payloads <lib/payloads/index.md>
-Libraries <lib/index.md>
-Options <lib/option.md>
-Security <security/index.md>
-SuperIO <superio/index.md>
-Vendorcode <vendorcode/index.md>
-Utilities <util.md>
-Software Bill of Materials <sbom/sbom.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>
-External Resources <external_docs.md>
-Documentation License <documentation_license.md>
-```
-
-[Documentation]: https://review.coreboot.org/plugins/gitiles/coreboot/+/refs/heads/main/Documentation/
+* [Getting Started](getting_started/index.md)
+* [Tutorial](tutorial/index.md)
+* [Coding Style](contributing/coding_style.md)
+* [Project Ideas](contributing/project_ideas.md)
+* [Documentation Ideas](contributing/documentation_ideas.md)
+* [Code of Conduct](community/code_of_conduct.md)
+* [Language style](community/language_style.md)
+* [Community forums](community/forums.md)
+* [Project services](community/services.md)
+* [coreboot at conferences](community/conferences.md)
+* [Payloads](payloads.md)
+* [Distributions](distributions.md)
+* [Technotes](technotes/index.md)
+* [ACPI](acpi/index.md)
+* [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md)
+* [Display panel](gfx/display-panel.md)
+* [CPU Architecture](arch/index.md)
+* [Platform independent drivers](drivers/index.md)
+* [Northbridge](northbridge/index.md)
+* [System on Chip](soc/index.md)
+* [Mainboard](mainboard/index.md)
+* [Payloads](lib/payloads/index.md)
+* [Libraries](lib/index.md)
+* [Options](lib/option.md)
+* [Security](security/index.md)
+* [SuperIO](superio/index.md)
+* [Vendorcode](vendorcode/index.md)
+* [Utilities](util.md)
+* [coreboot infrastructure](infrastructure/index.md)
+* [Release notes for past releases](releases/index.md)
+* [Flashing firmware tutorial](flash_tutorial/index.md)

Documentation/infrastructure/admin.md

@@ -1,52 +0,0 @@
-# Operating our services
-
-## Mailing list moderation
-
-Our [mailing lists] experience the same barrage of spam mails than any
-other email address. We do have a spam filter in front of it, and
-since the lists require registration, spam ends up in the moderation
-queue. But not only spam ends up there, sometimes users send inquiries
-without registering first. It's a custom of the project to let these
-through, so that such emails can be discussed. This requires manual
-intervention.
-
-This section describes the tasks related to mailing list management.
-
-### Registration
-
-To participate in mailing list moderation, you need to become a list
-moderator or owner. This is up for the existing owners to handle and
-if you want to contribute in that area, it might be best to bring it
-up at the leadership meeting.
-
-After gaining leadership approval, list admins can add you to the
-appropriate group in the [mailing list backend] by selecting the list,
-then User / group-name, and add your email address there.
-
-### Regular tasks
-
-Most of our lists are auto-subscribing, so users can register
-themselves and finish the process by responding to the double-opt-in
-email. Some lists are manually managed though. The [mailing list
-backend] shows the number of open subscription requests for these
-lists on the mailing list's main page.
-
-It also provides a list of held messages, where they can be accepted,
-rejected or dropped. Spam should be dropped, that's clear. Emails with
-huge attachments (e.g. screenshots) should be rejected, which gives
-you an opportunity to explain the reason (in case of large
-attachments, something like "Please re-send without attachments, offer
-the files through some other mechanism please: Our emails are
-distributed to hundreds of readers, and sending the files to everybody
-is inconsiderate of traffic and storage constraints.")
-
-Legit emails (often simple requests of the form "is this or that
-supported") can be accepted, which means they'll be sent out.
-
-If you notice recurring spam sources (e.g. marketers) you can put them
-on the [global ban list] to filter them out across all lists. It takes
-entries in regular expression format.
-
-[mailing lists]: https://mail.coreboot.org/hyperkitty/
-[mailing list backend]: https://mail.coreboot.org/postorius/
-[global ban list]: https://mail.coreboot.org/postorius/bans/

Documentation/infrastructure/builders.md

@@ -8,8 +8,8 @@ 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.
+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
@@ -23,79 +23,57 @@ as the system can just be disabled until someone is available to fix any
 issues.
 
 Currently active Jenkins admins:
-*   Martin Roth:
-    *   Email: [gaumless@gmail.com](mailto:gaumless@gmail.com)
-    *   IRC: martinr
+*   Patrick Georgi:
+    *   Email: [patrick@georgi-clan.de](mailto:patrick@georgi-clan.de)
+    *   IRC: pgeorgi
+
 
 ### 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.
+For a builder, we need a fast system with lots of threads and plenty of
+RAM.  The builder builds and stores the git repos and output in tmpfs
+along with the ccache save area, so if there isn't enough memory, the
+builds will slow down because of smaller ccache areas and can run into
+"out of storage space" errors.
 
 #### Current Build Machines
 
 To give an idea of what a suitable build machine might be, currently the
-coreboot project has 6 active jenkins build machines.
-
-These times are taken from the week of Feb 21 - Feb 28, 2022
+coreboot project has 3 active jenkins build machines.
 
 * 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
+  *  Fastest Passing coreboot gerrit build: 4 min, 30 sec
+  *  Slowest Passing coreboot gerrit build: 9 min, 56 sec
 
-* 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)
+* Gleeful builder - 64 thread, 64GiB RAM
+  *  Fastest Passing coreboot gerrit build: 6 min, 6 sec
+  *  Slowest Passing coreboot gerrit build, 34 min
+
 
 * Ultron (9elements) - 48 threads, 128GiB RAM
-  * Fastest Passing coreboot gerrit build: 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
+  *  Fastest Passing coreboot gerrit build: 6 min, 32 sec
+  *  Slowest Passing coreboot gerrit build: 44 min
 
 
 ### Jenkins Builds
 
 There are a number of builds handled by the coreboot jenkins builders,
 for a number of different projects - coreboot, flashrom, memtest86+,
-em100, etc.  Many of these have builders for their current main branch
-as well as Gerrit and [Coverity](coverity.md) builds.
+em100, etc.  Many of these have builders for their current master branch
+as well as gerrit and coverity 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:
+You can see all the builds here:
 [https://qa.coreboot.org/](https://qa.coreboot.org/)
 
-Most of the time on the builders is taken up by the coreboot main and
-coreboot gerrit builds.
+Most of the time on the builders is taken up by the coreboot master and
+gerrit builds.
 
 * [coreboot gerrit build](https://qa.coreboot.org/job/coreboot-gerrit/)
 ([Time trend](https://qa.coreboot.org/job/coreboot-gerrit/buildTimeTrend))
 
 
-* [coreboot main build](https://qa.coreboot.org/job/coreboot/)
+* [coreboot master build](https://qa.coreboot.org/job/coreboot/)
  ([Time trend](https://qa.coreboot.org/job/coreboot/buildTimeTrend))
 
 
@@ -107,8 +85,8 @@ 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
+```
+$ 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’
@@ -118,8 +96,8 @@ 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
+```
+$ 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
@@ -149,23 +127,10 @@ 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}
-```
+Install docker by following the
+[directions](https://docs.docker.com/engine/install/) on the docker
+site.  These instructions keep changing, so just check the latest
+information.
 
 
 #### Set up environment variables
@@ -174,12 +139,12 @@ 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 revision of the container from docker hub
+export DOCKER_COMMIT=65718760fa
 
 # Set the location of where the jenkins cache directory will be.
 export COREBOOT_JENKINS_CACHE_DIR="/srv/docker/coreboot-builder/cache"
@@ -196,13 +161,13 @@ continuing to the next step.
 
 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
@@ -234,10 +199,22 @@ Variables:
   DOCKER_COMMIT=65718760fa
 ```
 
+### Set up the system for the jenkins builder
+
+As a regular user - *Not root*, run:
+
+```
+sudo mkdir -p ${COREBOOT_JENKINS_CACHE_DIR}
+sudo mkdir -p ${COREBOOT_JENKINS_CCACHE_DIR}
+sudo chown $(whoami):$(whoami) ${COREBOOT_JENKINS_CCACHE_DIR}
+sudo chown $(whoami):$(whoami) ${COREBOOT_JENKINS_CACHE_DIR}
+wget http://www.dediprog.com/save/78.rar/to/EM100Pro.rar
+mv EM100Pro.rar ${COREBOOT_JENKINS_CACHE_DIR}
+```
 
 ### Install the coreboot jenkins builder
 
-```sh
+```
 make -C util/docker docker-jenkins-server
 ```
 
@@ -249,17 +226,17 @@ 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.
+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`
+`$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.
+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
+20-25 minutes to do the entire what-jenkins-does build while the ccache
 is getting filled up and the entire coreboot repo gets downloaded.  As
 the ccache gets populated, the build time will drop.
 
@@ -268,40 +245,39 @@ the ccache gets populated, the build time will drop.
 
 
 ### 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
+```
+    $ 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
+but just to debug issues. Changes to the build system are highly
 discouraged as it leads to situations where patches can pass the build
 testing on one builder and fail on another builder. Any changes that are
 made in the image will be lost on the next update, so if you
-accidentally change something, you can remove the containers and images,
-then update to get a fresh installation.
+accidentally change something, you can remove the containers and images
+and update to get a fresh installation.
 
 
 ### How to download containers/images for a fresh installation and remove old containers
 
 To delete the old containers & images:
 
-```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.
+```
+$ 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
+```
+$ make -C util/docker docker-jenkins-server
 ```
 
 #### Getting ready to push the docker images
@@ -315,15 +291,15 @@ Get an admin to add the account to the coreboot team on hub.docker.com
 Make sure your credentials are configured on your host machine by
 running
 
-```sh
-docker login
+```
+$ 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
+#### Updating the Dockerfiles:
 
 The coreboot-sdk Dockerfile will need to be updated when any additional
 dependencies are added.  Both the coreboot-sdk and the
@@ -334,15 +310,15 @@ 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
+#### Rebuilding the coreboot-sdk docker image to update the toolchain:
 
-```sh
-make -C util/docker coreboot-sdk
+```
+$ make -C util/docker coreboot-sdk
 ```
 
 This takes a relatively long time.
 
-#### Test the coreboot-sdk docker image
+#### 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
@@ -350,44 +326,44 @@ 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
+#### Running the docker image interactively:
 
 Run:
 
-```sh
-make -C util/docker docker-jenkins-server
-make -C util/docker docker-jenkins-attach
+```
+$ make -C util/docker docker-jenkins-server
+$ make -C util/docker docker-jenkins-attach
 ```
 
-#### Running the build directly
+#### Running the build directly:
 
 From the coreboot directory:
 
-```sh
-make -C util/docker docker-build-coreboot
+```
+$ 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
+#### 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
+```
+$ make -C util/docker upload-coreboot-sdk
 ```
 
-#### Building and pushing the coreboot-jenkins-node docker image
+#### 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
+```
+$ make -C util/docker coreboot-jenkins-node
+$ make -C util/docker upload-coreboot-jenkins-node
 ```
 
 ### Coverity Setup
@@ -400,7 +376,6 @@ to be marked as a coverity builder.
 
 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)
 
@@ -408,7 +383,7 @@ 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
 ```
 

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,martin}@coreboot.org.

Documentation/infrastructure/index.md

@@ -1,20 +1,6 @@
-# Project infrastructure & services
+# coreboot infrastructure
 
-This section contains documentation about our infrastructure
-
-## Services
-
-```{toctree}
-:maxdepth: 1
-
-Project services <services.md>
-Administrator's handbook <admin.md>
-```
+This section contains documentation about coreboot infrastructure
 
 ## Jenkins builders and builds
-```{toctree}
-:maxdepth: 1
-
-Setting up Jenkins build machines <builders.md>
-Coverity Scan integration <coverity.md>
-```
+* [Setting up Jenkins build machines](builders.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