.checkpatch.conf

@@ -0,0 +1,41 @@
+# 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 SPLIT_STRING
+--ignore BLOCK_COMMENT_STYLE
+--ignore AVOID_EXTERNS
+--ignore VOLATILE
+--ignore CONFIG_DESCRIPTION
+--ignore MISSING_SPACE
+--ignore CORRUPTED_PATCH
+--ignore SPDX_LICENSE_TAG
+--ignore UNDOCUMENTED_DT_STRING
+--ignore PRINTK_WITHOUT_KERN_LEVEL
+--ignore ASSIGN_IN_IF
+--ignore UNNECESSARY_ELSE
+--ignore GERRIT_CHANGE_ID
+
+# FILE_PATH_CHANGES seems to not be working correctly. It will
+# choke on added / deleted files even if the MAINTAINERS file
+# is touched.
+--ignore FILE_PATH_CHANGES
+
+# This one has a linux path hard coded, so it would choke on
+# some commits unnecessarily.
+--ignore EXECUTE_PERMISSIONS
+
+# Exclude vendorcode directories that don't follow coreboot's coding style.
+--exclude src/vendorcode/amd
+--exclude src/vendorcode/cavium
+--exclude src/vendorcode/intel
+--exclude src/vendorcode/mediatek

.clang-format

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

.editorconfig

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

.gitignore

@@ -0,0 +1,47 @@
+junit.xml
+abuild*.xml
+.config
+.config.old
+defconfig
+.coreboot-version
+.xcompile
+.ccwrap
+build/
+coreboot-builds/
+coreboot-builds*/
+generated/
+
+site-local
+
+*.\#
+*.a
+*.bin
+*.debug
+!Kconfig.debug
+*.elf
+*.fd
+*.o
+*.o.d
+*.out
+*.pyc
+*.sw[po]
+/*.rom
+.test
+.dependencies
+
+# Development friendly files
+tags
+.clang_complete
+.cache
+compile_commands.json
+.vscode/
+.clangd
+
+# Cross-compile toolkits
+xgcc/
+tarballs/
+
+# editor backup files, temporary files, IDE project files
+*~
+*.kate-swp
+*.kdev4

.gitmodules

@@ -0,0 +1,81 @@
+[submodule "3rdparty/blobs"]
+	path = 3rdparty/blobs
+	url = https://review.coreboot.org/blobs.git
+	update = none
+	ignore = dirty
+[submodule "util/nvidia-cbootimage"]
+	path = util/nvidia/cbootimage
+	url = https://review.coreboot.org/nvidia-cbootimage.git
+[submodule "vboot"]
+	path = 3rdparty/vboot
+	url = https://review.coreboot.org/vboot.git
+	branch = main
+[submodule "arm-trusted-firmware"]
+	path = 3rdparty/arm-trusted-firmware
+	url = https://review.coreboot.org/arm-trusted-firmware.git
+[submodule "libhwbase"]
+	path = 3rdparty/libhwbase
+	url = https://review.coreboot.org/libhwbase.git
+[submodule "libgfxinit"]
+	path = 3rdparty/libgfxinit
+	url = https://review.coreboot.org/libgfxinit.git
+[submodule "3rdparty/fsp"]
+	path = 3rdparty/fsp
+	url = https://review.coreboot.org/fsp.git
+	update = none
+	ignore = dirty
+[submodule "opensbi"]
+	path = 3rdparty/opensbi
+	url = https://review.coreboot.org/opensbi.git
+[submodule "intel-microcode"]
+	path = 3rdparty/intel-microcode
+	url = https://review.coreboot.org/intel-microcode.git
+	update = none
+	ignore = dirty
+	branch = main
+[submodule "3rdparty/ffs"]
+	path = 3rdparty/ffs
+	url = https://review.coreboot.org/ffs.git
+[submodule "3rdparty/amd_blobs"]
+	path = 3rdparty/amd_blobs
+	url = https://review.coreboot.org/amd_blobs
+	update = none
+	ignore = dirty
+[submodule "3rdparty/cmocka"]
+	path = 3rdparty/cmocka
+	url = https://review.coreboot.org/cmocka.git
+	update = none
+	branch = stable-1.1
+[submodule "3rdparty/qc_blobs"]
+	path = 3rdparty/qc_blobs
+	url = https://review.coreboot.org/qc_blobs.git
+	update = none
+	ignore = dirty
+[submodule "3rdparty/intel-sec-tools"]
+	path = 3rdparty/intel-sec-tools
+	url = https://review.coreboot.org/9esec-security-tooling.git
+	ignore = dirty
+[submodule "3rdparty/stm"]
+	path = 3rdparty/stm
+	url = https://review.coreboot.org/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

@@ -0,0 +1,5 @@
+[gerrit]
+host=review.coreboot.org
+port=29418
+project=coreboot
+defaultbranch=main

.mailmap

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

@@ -0,0 +1 @@
+Subproject commit aa9288a33c6d7a67e55b8757390029207593fa9f

3rdparty/arm-trusted-firmware

@@ -0,0 +1 @@
+Subproject commit 9109143417b24337d39a2a9583828a44996f8aac

3rdparty/blobs

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

3rdparty/cmocka

@@ -0,0 +1 @@
+Subproject commit 8be37372097d1aa5e03b565936db7891b6180e73

3rdparty/ffs

@@ -0,0 +1 @@
+Subproject commit 3ec70fbc458e32eef0d0b1de79688b4dc48cbd57

3rdparty/fsp

@@ -0,0 +1 @@
+Subproject commit 81399b3b61479abc379c2d01362d4b6dc6f515c9

3rdparty/intel-microcode

@@ -0,0 +1 @@
+Subproject commit 250941fb670645d7d91f761cc63656ad3a1ec367

3rdparty/intel-sec-tools

@@ -0,0 +1 @@
+Subproject commit 0031ac73447baeb197fb2d80e5fba2470716e76d

3rdparty/libgfxinit

@@ -0,0 +1 @@
+Subproject commit 3c3828add50024e90e57d6fbe0e660d1b66302d9

3rdparty/libhwbase

@@ -0,0 +1 @@
+Subproject commit 584629b9f4771b7618951cec57df2ca3af9c6981

3rdparty/open-power-signing-utils

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

3rdparty/opensbi

@@ -0,0 +1 @@
+Subproject commit 5019fd124b4c46e1581129c5154fc2cdd3b777ed

3rdparty/qc_blobs

@@ -0,0 +1 @@
+Subproject commit 6379308814bd00a8b6e36a4715bdb86ba019a3a7

3rdparty/stm

@@ -0,0 +1 @@
+Subproject commit 1f3258261a4f4d6c60ec4447c7a03acf2509b984

3rdparty/vboot

@@ -0,0 +1 @@
+Subproject commit 5c360ef458b0a013d8a6d47724bb0fffb5accbcf

AUTHORS

@@ -0,0 +1,910 @@
+# This is the list of coreboot authors for copyright purposes.
+#
+# This does not necessarily list everyone who has contributed code, since in
+# some cases, their employer may be the copyright holder.  To see the full list
+# of contributors, and their email addresses, see the revision history in source
+# control.
+# Run the below commands in the coreboot repo for additional information.
+# To see a list of contributors: git log --pretty=format:%an | sort | uniq
+# For patches adding or removing a name: git log -i -S "NAME" --source --all
+
+3mdeb Embedded Systems Consulting
+9elements Agency GmbH
+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.
+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
+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.
+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
+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
+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
+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
+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/.gitignore

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

Documentation/.mdl_style.rb

@@ -0,0 +1,9 @@
+# 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/AMD-S3.txt

@@ -0,0 +1,153 @@
+   _____ ____  _____  ______ ____   ____   ____ _______
+  / ____/ __ \|  __ \|  ____|  _ \ / __ \ / __ \__   __|
+ | |   | |  | | |__) | |__  | |_) | |  | | |  | | | |
+ | |   | |  | |  _  /|  __| |  _ <| |  | | |  | | | |
+ | |___| |__| | | \ \| |____| |_) | |__| | |__| | | |
+  \_____\____/|_|  \_\______|____/ \____/ \____/  |_|
+
+           __  __ _____     _____   ____
+     /\   |  \/  |  __ \   / ____| |___ \
+    /  \  | \  / | |  | | | (___     __) |
+   / /\ \ | |\/| | |  | |  \___ \   |__ <
+  / ____ \| |  | | |__| |  ____) |  ___) |
+ /_/    \_\_|  |_|_____/  |_____/  |____/
+
+
+               S3 in coreboot (V 1.2)
+----------------------------------------
+                Zheng Bao
+            <zheng.bao@amd.com>
+            <fishbaozi@gmail.com>
+
+Introduction
+============
+This document is about how the feature S3 is implemented on coreboot,
+specifically on AMD platform. This topic deals with ACPI spec, hardware,
+BIOS, OS. We try to help coreboot users to realize their own S3.
+
+S3 in a nutshell
+================
+The S3 sleeping state is a low wake latency sleeping state where all
+system context is lost except system memory. [1]. S3 is a ACPI
+definition.
+To enter S3, write 3 in SLP_TYPx and set the SLP_EN bit (See ACPI
+registers). But if you do that, board can not resume at where it
+sleeps, because you don't save the context. More often than not, we
+make the board go into S3 by the tools which OSes provide. For
+windows, click Start->sleep. For linux, some distribution provide a
+tools called pm-suspend, which can make the system goto S3. If
+pm-suspend is not available, we can run "echo mem > /sys/power/state",
+but this way may not save all the needed context.
+In S3 state, the power is off. So when the power button is pressed,
+BIOS runs as it does in cold boot. If BIOS didn't detect whether
+board boots or resumes, it would go the same way as boot. It is not
+what we expect. BIOS detects the SLP_TYPx. If it is 3, it means BIOS
+are waking up.
+BIOS is responsible for restore the machine state as it is before
+sleep. It needs restore the memory controller, not overwriting memory
+which is not marked as reserved. For the peripheral which loses its
+registers, BIOS needs to write the original value.
+When everything is done, BIOS needs to find out the wakeup vector
+provided by OSes and jump there. OSes also have work to do. We can go
+to linux kernel or some other open source projects to find out how they
+handle S3 resume.
+
+ACPI registers
+==============
+ACPI specification defines a group of registers. OSes handle all these
+registers to read and write status to all the platform.
+On AMD platform, these registers are provided by southbridge. For
+example, Hudson uses PMIO 60:6F to define ACPI registers.
+OSes don't have any specific driver to know where these registers
+are. BIOS has the responsibility to allocated the IO resources and
+write all these address to FADT, a ACPI defined table.
+
+Memory Layout
+=============
+Restoring memory is the most important job done by BIOS. When the
+power is off, the memory is maintained by standby power. BIOS need to
+make sure that when flow goes to OS, everything in memory should be
+the same as it was.
+
+The chip vendor will provide a way, or code, to wake up the memory
+from sleeping. In AGESA 2008 arch, it is called AmdInitResume.
+
+The BIOS itself needs some memory to run. Either, BIOS marks the erea
+as reserved in e820, or BIOS saves the content into reserved space.
+
+Here is the address Map for S3 Resume. Assumingly the total memory is 1GB.
+00000000 --- 00100000      BIOS Reserved area.
+00100000 --- 00200000      Free
+00200000 --- 01000000      coreboot ramstage area.
+01000000 --- 2e160000      Free
+2e160000 --- 2e170000      ACPI table
+2e170000 --- 2ef70000      OSRAM
+2ef70000 --- 2efe0000      Stack in highmem
+2efe0000 --- 2f000000      heap in highmem
+2f000000                   TOM
+
+AMD requirements in S3
+======================
+Chip vendor like AMD will provide bunch of routines to restore the
+board.[2]
+ * AmdS3Save: It is called in cold boot, save required register into
+ non-volatile storage. Currently, we use SPI flash to store the data.
+ * AmdInitResume: Restore the memory controller.
+ * AmdS3LateRestore: Called after AmdInitResume, restore other
+ register that memory.
+ * (SouthBridge)InitS3EarlyRestore, (SouthBridge)InitS3LateRestore:
+ Provided by Southbridge vendor code. Early is called before PCI
+ enumeration, and Late is called after that.
+
+Lifecycle of booting, sleeping and waking coreboot and Ubuntu
+=============================================================
+1. Cold boot.
+For a system with S3 feature, the BIOS needs to save some data to
+non-volatile storage at cold boot stage. What data need to be save are
+provided by AmdS3Save. After the wrapper calls the AmdS3Save, it gets
+the VolatileStorage and NvStorage, which are where the data are
+located. It is the wrappers's responsibility to save the data.[3][4]
+Currently, the wrappers allocate a CBFS modules in BIOS image. To do
+that, the wrapper needs to have the ability to write flash chips. It
+is not as comprehensive as flashrom. But for the SST chip on Parmer,
+MX chip on Thather, coreboot works well.[5]
+
+2. OS goes in S3.
+For Linux, besides the kernel needs to do some saving, most distributions
+run some scripts. For Ubuntu, scripts are located at /usr/lib/pm-utils/sleep.d.
+  # ls /usr/lib/pm-utils/sleep.d
+   000kernel-change  49bluetooth        90clock       95led
+   00logging         55NetworkManager   94cpufreq     98video-quirk-db-handler
+   00powersave       60_wpa_supplicant  95anacron     99video
+   01PulseAudio      75modules          95hdparm-apm
+The script with lower prefix runs before the one with higher prefix.
+99video is the last one.
+Those scripts have hooks called hibernate, suspend, thaw, resume. For
+each script, suspend is called when system sleeps and wakeup is called
+when system wakeups.
+
+3. Firmware detects S3 wakeup
+As we mentioned, Firmware detects the SLP_TYPx to find out if the board
+wakes up. In romstage.c, AmdInitReset and AmdInitEarly are called
+as they are during cold boot. AmdInitResume and AmdS3LateRestore are
+called only during resume. For whole ramstage, coreboot goes through
+almost the same way as cold boot, other than not calling the AmdInitMid,
+AmdInitLate and AmdS3Save, and restoring all the MTRRs.
+At last step of coreboot stage, coreboot finds out the wakeup vector in FADT,
+written by OS, and jump.
+
+4. OS resumes.
+When Linux resumes, all the sleeping scripts call their resume
+hooks. If we are more lucky, all the scripts can go through. More
+chances that the 99video hangs or fails to get the display
+back. Sometimes it can fixed if CONFIG_S3_VGA_ROM_RUN is unset in
+coreboot/Kconfig. That needs more troubleshooting.
+
+
+Reference
+=========
+[1]   ACPI40a, http://www.acpi.info/spec40a.htm
+[2]   coreboot Vendorcode, {top}/src/vendorcode/amd/agesa/{family}/Proc/Common/
+[3]   coreboot AGESA wrapper, {top}/src/mainboard/amd/parmer/agesawrapper.c
+[4]   coreboot AGESA wrapper, {top}/src/cpu/amd/agesa/s3_resume.c
+[5]   coreboot Southbridge, {top}/src/southbridge/amd/agesa/hudson/spi.c

Documentation/COPYING

@@ -0,0 +1,401 @@
+Files under Documentation/ are licensed under CC-BY 4.0 terms, printed below.
+As an exception, files under Documentation/ with a history older than 2017-05-24
+might be under different licenses (but should be cleared up ASAP).
+
+------
+Attribution 4.0 International
+
+=======================================================================
+
+Creative Commons Corporation ("Creative Commons") is not a law firm and
+does not provide legal services or legal advice. Distribution of
+Creative Commons public licenses does not create a lawyer-client or
+other relationship. Creative Commons makes its licenses and related
+information available on an "as-is" basis. Creative Commons gives no
+warranties regarding its licenses, any material licensed under their
+terms and conditions, or any related information. Creative Commons
+disclaims all liability for damages resulting from their use to the
+fullest extent possible.
+
+Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and
+conditions that creators and other rights holders may use to share
+original works of authorship and other material subject to copyright
+and certain other rights specified in the public license below. The
+following considerations are for informational purposes only, are not
+exhaustive, and do not form part of our licenses.
+
+     Considerations for licensors: Our public licenses are
+     intended for use by those authorized to give the public
+     permission to use material in ways otherwise restricted by
+     copyright and certain other rights. Our licenses are
+     irrevocable. Licensors should read and understand the terms
+     and conditions of the license they choose before applying it.
+     Licensors should also secure all rights necessary before
+     applying our licenses so that the public can reuse the
+     material as expected. Licensors should clearly mark any
+     material not subject to the license. This includes other CC-
+     licensed material, or material used under an exception or
+     limitation to copyright. More considerations for licensors:
+	wiki.creativecommons.org/Considerations_for_licensors
+
+     Considerations for the public: By using one of our public
+     licenses, a licensor grants the public permission to use the
+     licensed material under specified terms and conditions. If
+     the licensor's permission is not necessary for any reason--for
+     example, because of any applicable exception or limitation to
+     copyright--then that use is not regulated by the license. Our
+     licenses grant only permissions under copyright and certain
+     other rights that a licensor has authority to grant. Use of
+     the licensed material may still be restricted for other
+     reasons, including because others have copyright or other
+     rights in the material. A licensor may make special requests,
+     such as asking that all changes be marked or described.
+     Although not required by our licenses, you are encouraged to
+     respect those requests where reasonable. More_considerations
+     for the public:
+	wiki.creativecommons.org/Considerations_for_licensees
+
+=======================================================================
+
+Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree
+to be bound by the terms and conditions of this Creative Commons
+Attribution 4.0 International Public License ("Public License"). To the
+extent this Public License may be interpreted as a contract, You are
+granted the Licensed Rights in consideration of Your acceptance of
+these terms and conditions, and the Licensor grants You such rights in
+consideration of benefits the Licensor receives from making the
+Licensed Material available under these terms and conditions.
+
+
+Section 1 -- Definitions.
+
+  a. Adapted Material means material subject to Copyright and Similar
+     Rights that is derived from or based upon the Licensed Material
+     and in which the Licensed Material is translated, altered,
+     arranged, transformed, or otherwise modified in a manner requiring
+     permission under the Copyright and Similar Rights held by the
+     Licensor. For purposes of this Public License, where the Licensed
+     Material is a musical work, performance, or sound recording,
+     Adapted Material is always produced where the Licensed Material is
+     synched in timed relation with a moving image.
+
+  b. Adapter's License means the license You apply to Your Copyright
+     and Similar Rights in Your contributions to Adapted Material in
+     accordance with the terms and conditions of this Public License.
+
+  c. Copyright and Similar Rights means copyright and/or similar rights
+     closely related to copyright including, without limitation,
+     performance, broadcast, sound recording, and Sui Generis Database
+     Rights, without regard to how the rights are labeled or
+     categorized. For purposes of this Public License, the rights
+     specified in Section 2(b)(1)-(2) are not Copyright and Similar
+     Rights.
+
+  d. Effective Technological Measures means those measures that, in the
+     absence of proper authority, may not be circumvented under laws
+     fulfilling obligations under Article 11 of the WIPO Copyright
+     Treaty adopted on December 20, 1996, and/or similar international
+     agreements.
+
+  e. Exceptions and Limitations means fair use, fair dealing, and/or
+     any other exception or limitation to Copyright and Similar Rights
+     that applies to Your use of the Licensed Material.
+
+  f. Licensed Material means the artistic or literary work, database,
+     or other material to which the Licensor applied this Public
+     License.
+
+  g. Licensed Rights means the rights granted to You subject to the
+     terms and conditions of this Public License, which are limited to
+     all Copyright and Similar Rights that apply to Your use of the
+     Licensed Material and that the Licensor has authority to license.
+
+  h. Licensor means the individual(s) or entity(ies) granting rights
+     under this Public License.
+
+  i. Share means to provide material to the public by any means or
+     process that requires permission under the Licensed Rights, such
+     as reproduction, public display, public performance, distribution,
+     dissemination, communication, or importation, and to make material
+     available to the public including in ways that members of the
+     public may access the material from a place and at a time
+     individually chosen by them.
+
+  j. Sui Generis Database Rights means rights other than copyright
+     resulting from Directive 96/9/EC of the European Parliament and of
+     the Council of 11 March 1996 on the legal protection of databases,
+     as amended and/or succeeded, as well as other essentially
+     equivalent rights anywhere in the world.
+
+  k. You means the individual or entity exercising the Licensed Rights
+     under this Public License. Your has a corresponding meaning.
+
+
+Section 2 -- Scope.
+
+  a. License grant.
+
+       1. Subject to the terms and conditions of this Public License,
+          the Licensor hereby grants You a worldwide, royalty-free,
+          non-sublicensable, non-exclusive, irrevocable license to
+          exercise the Licensed Rights in the Licensed Material to:
+
+            a. reproduce and Share the Licensed Material, in whole or
+               in part; and
+
+            b. produce, reproduce, and Share Adapted Material.
+
+       2. Exceptions and Limitations. For the avoidance of doubt, where
+          Exceptions and Limitations apply to Your use, this Public
+          License does not apply, and You do not need to comply with
+          its terms and conditions.
+
+       3. Term. The term of this Public License is specified in Section
+          6(a).
+
+       4. Media and formats; technical modifications allowed. The
+          Licensor authorizes You to exercise the Licensed Rights in
+          all media and formats whether now known or hereafter created,
+          and to make technical modifications necessary to do so. The
+          Licensor waives and/or agrees not to assert any right or
+          authority to forbid You from making technical modifications
+          necessary to exercise the Licensed Rights, including
+          technical modifications necessary to circumvent Effective
+          Technological Measures. For purposes of this Public License,
+          simply making modifications authorized by this Section 2(a)
+          (4) never produces Adapted Material.
+
+       5. Downstream recipients.
+
+            a. Offer from the Licensor -- Licensed Material. Every
+               recipient of the Licensed Material automatically
+               receives an offer from the Licensor to exercise the
+               Licensed Rights under the terms and conditions of this
+               Public License.
+
+            b. No downstream restrictions. You may not offer or impose
+               any additional or different terms or conditions on, or
+               apply any Effective Technological Measures to, the
+               Licensed Material if doing so restricts exercise of the
+               Licensed Rights by any recipient of the Licensed
+               Material.
+
+       6. No endorsement. Nothing in this Public License constitutes or
+          may be construed as permission to assert or imply that You
+          are, or that Your use of the Licensed Material is, connected
+          with, or sponsored, endorsed, or granted official status by,
+          the Licensor or others designated to receive attribution as
+          provided in Section 3(a)(1)(A)(i).
+
+  b. Other rights.
+
+       1. Moral rights, such as the right of integrity, are not
+          licensed under this Public License, nor are publicity,
+          privacy, and/or other similar personality rights; however, to
+          the extent possible, the Licensor waives and/or agrees not to
+          assert any such rights held by the Licensor to the limited
+          extent necessary to allow You to exercise the Licensed
+          Rights, but not otherwise.
+
+       2. Patent and trademark rights are not licensed under this
+          Public License.
+
+       3. To the extent possible, the Licensor waives any right to
+          collect royalties from You for the exercise of the Licensed
+          Rights, whether directly or through a collecting society
+          under any voluntary or waivable statutory or compulsory
+          licensing scheme. In all other cases the Licensor expressly
+          reserves any right to collect such royalties.
+
+
+Section 3 -- License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the
+following conditions.
+
+  a. Attribution.
+
+       1. If You Share the Licensed Material (including in modified
+          form), You must:
+
+            a. retain the following if it is supplied by the Licensor
+               with the Licensed Material:
+
+                 i. identification of the creator(s) of the Licensed
+                    Material and any others designated to receive
+                    attribution, in any reasonable manner requested by
+                    the Licensor (including by pseudonym if
+                    designated);
+
+                ii. a copyright notice;
+
+               iii. a notice that refers to this Public License;
+
+                iv. a notice that refers to the disclaimer of
+                    warranties;
+
+                 v. a URI or hyperlink to the Licensed Material to the
+                    extent reasonably practicable;
+
+            b. indicate if You modified the Licensed Material and
+               retain an indication of any previous modifications; and
+
+            c. indicate the Licensed Material is licensed under this
+               Public License, and include the text of, or the URI or
+               hyperlink to, this Public License.
+
+       2. You may satisfy the conditions in Section 3(a)(1) in any
+          reasonable manner based on the medium, means, and context in
+          which You Share the Licensed Material. For example, it may be
+          reasonable to satisfy the conditions by providing a URI or
+          hyperlink to a resource that includes the required
+          information.
+
+       3. If requested by the Licensor, You must remove any of the
+          information required by Section 3(a)(1)(A) to the extent
+          reasonably practicable.
+
+       4. If You Share Adapted Material You produce, the Adapter's
+          License You apply must not prevent recipients of the Adapted
+          Material from complying with this Public License.
+
+
+Section 4 -- Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that
+apply to Your use of the Licensed Material:
+
+  a. for the avoidance of doubt, Section 2(a)(1) grants You the right
+     to extract, reuse, reproduce, and Share all or a substantial
+     portion of the contents of the database;
+
+  b. if You include all or a substantial portion of the database
+     contents in a database in which You have Sui Generis Database
+     Rights, then the database in which You have Sui Generis Database
+     Rights (but not its individual contents) is Adapted Material; and
+
+  c. You must comply with the conditions in Section 3(a) if You Share
+     all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not
+replace Your obligations under this Public License where the Licensed
+Rights include other Copyright and Similar Rights.
+
+
+Section 5 -- Disclaimer of Warranties and Limitation of Liability.
+
+  a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE
+     EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS
+     AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF
+     ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS,
+     IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION,
+     WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR
+     PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS,
+     ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT
+     KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT
+     ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU.
+
+  b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE
+     TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION,
+     NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT,
+     INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES,
+     COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR
+     USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN
+     ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR
+     DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR
+     IN PART, THIS LIMITATION MAY NOT APPLY TO YOU.
+
+  c. The disclaimer of warranties and limitation of liability provided
+     above shall be interpreted in a manner that, to the extent
+     possible, most closely approximates an absolute disclaimer and
+     waiver of all liability.
+
+
+Section 6 -- Term and Termination.
+
+  a. This Public License applies for the term of the Copyright and
+     Similar Rights licensed here. However, if You fail to comply with
+     this Public License, then Your rights under this Public License
+     terminate automatically.
+
+  b. Where Your right to use the Licensed Material has terminated under
+     Section 6(a), it reinstates:
+
+       1. automatically as of the date the violation is cured, provided
+          it is cured within 30 days of Your discovery of the
+          violation; or
+
+       2. upon express reinstatement by the Licensor.
+
+     For the avoidance of doubt, this Section 6(b) does not affect any
+     right the Licensor may have to seek remedies for Your violations
+     of this Public License.
+
+  c. For the avoidance of doubt, the Licensor may also offer the
+     Licensed Material under separate terms or conditions or stop
+     distributing the Licensed Material at any time; however, doing so
+     will not terminate this Public License.
+
+  d. Sections 1, 5, 6, 7, and 8 survive termination of this Public
+     License.
+
+
+Section 7 -- Other Terms and Conditions.
+
+  a. The Licensor shall not be bound by any additional or different
+     terms or conditions communicated by You unless expressly agreed.
+
+  b. Any arrangements, understandings, or agreements regarding the
+     Licensed Material not stated herein are separate from and
+     independent of the terms and conditions of this Public License.
+
+
+Section 8 -- Interpretation.
+
+  a. For the avoidance of doubt, this Public License does not, and
+     shall not be interpreted to, reduce, limit, restrict, or impose
+     conditions on any use of the Licensed Material that could lawfully
+     be made without permission under this Public License.
+
+  b. To the extent possible, if any provision of this Public License is
+     deemed unenforceable, it shall be automatically reformed to the
+     minimum extent necessary to make it enforceable. If the provision
+     cannot be reformed, it shall be severed from this Public License
+     without affecting the enforceability of the remaining terms and
+     conditions.
+
+  c. No term or condition of this Public License will be waived and no
+     failure to comply consented to unless expressly agreed to by the
+     Licensor.
+
+  d. Nothing in this Public License constitutes or may be interpreted
+     as a limitation upon, or waiver of, any privileges and immunities
+     that apply to the Licensor or You, including from the legal
+     processes of any jurisdiction or authority.
+
+
+=======================================================================
+
+Creative Commons is not a party to its public
+licenses. Notwithstanding, Creative Commons may elect to apply one of
+its public licenses to material it publishes and in those instances
+will be considered the “Licensor.” The text of the Creative Commons
+public licenses is dedicated to the public domain under the CC0 Public
+Domain Dedication. Except for the limited purpose of indicating that
+material is shared under a Creative Commons public license or as
+otherwise permitted by the Creative Commons policies published at
+creativecommons.org/policies, Creative Commons does not authorize the
+use of the trademark "Creative Commons" or any other trademark or logo
+of Creative Commons without its prior written consent including,
+without limitation, in connection with any unauthorized modifications
+to any of its public licenses or any other arrangements,
+understandings, or agreements concerning use of licensed material. For
+the avoidance of doubt, this paragraph does not form part of the
+public licenses.
+
+Creative Commons may be contacted at creativecommons.org.
+

Documentation/Makefile

@@ -0,0 +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
+
+export SPHINXOPTS
+
+all: sphinx
+
+$(BUILDDIR):
+	mkdir -p $(BUILDDIR)
+
+sphinx: $(BUILDDIR)
+	$(MAKE) -f Makefile.sphinx html BUILDDIR="$(BUILDDIR)"
+
+clean-sphinx:
+	$(MAKE) -f Makefile.sphinx clean BUILDDIR="$(BUILDDIR)"
+
+clean: clean-sphinx
+	rm -f *.aux *.idx *.log *.toc *.out $(FIGS)
+
+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

Documentation/Makefile.sphinx

@@ -0,0 +1,29 @@
+## SPDX-License-Identifier: GPL-2.0-only
+# Minimal 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
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile.sphinx
+
+.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)
+
+# 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)

Documentation/POSTCODES

@@ -0,0 +1,31 @@
+-------------------------------------------------------------------------------
+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
+0x11 Start copying coreboot to RAM with decompression if compressed
+0x12 Copy/decompression finished jumping to RAM
+0x80 Entry into coreboot in RAM
+0x13 Entry into c_start
+0xfe Pre call to hardwaremain()
+0x39 Console is initialized
+0x40 Console boot message succeeded
+0x66 Devices have been enumerated
+0x88 Devices have been configured
+0x89 Devices have been enabled
+0xe0 Boot media (e.g. SPI ROM) is corrupt
+0xe1 Resource stored within CBFS is corrupt
+0xe2 Vendor binary (e.g. FSP) generated a fatal error
+0xe3 RAM could not be initialized
+0xe4 Critical hardware component could not initialize
+0xe5 Video subsystem failed to initialize
+0xf8 Entry into elf boot
+0xf3 Jumping to payload
+
+Errors (used in several places):
+
+0xee Not supposed to get here
+0xff Elfload fail or die() called

Documentation/RFC/chip.tex

@@ -0,0 +1,266 @@
+		RFC for the chip specification architecture
+
+\begin{abstract}
+At the end of this document is the original message that motivated the
+change.
+\end{abstract}
+
+\section{Scope}
+This document defines how LinuxBIOS programmers can specify chips that
+are used, specified, and initialized. The current scope is for superio
+chips, but the architecture should allow for specification of other chips such
+as southbridges. Multiple chips of same or different type are supported.
+
+\section{Goals}
+The goals of the new chip architecture are these:
+\begin{itemize}
+\item separate implementation details from specification in the Config file
+(translation: no more C code in Config files)
+\item make the specification easier for people to use and understand
+\item remove private details of a given chip to the chip file as much
+as possible
+\item allow unique register-set-specifiers for each chip
+\end{itemize}
+
+\section{Specification in the Config file}
+The specification looks like this:
+\begin{verbatim}
+chip <name> [path=<path>] ["<configuration>"]
+\end{verbatim}
+The name is in the standard LinuxBIOS form of type/vendor/name, e.g.
+"southbridge/intel/piix4e" or "superio/ite/it8671f". The class of the
+chip is derived from the first pathname component of the name, and the chip
+configuration is derived from the following components.
+
+The path defines the access mechanism to the chip.
+It is optional. If present, it overrides the default path to the chip.
+
+The configuration defines chip-specific configuration details, and is also
+optional. Note that an empty configuration will leave the chip with
+no enabled resources. This may be desirable in some cases.
+
+\section{Results of specifying a chip}
+
+When one or more chips are specified, the data about the chips
+is saved until the entire file is parsed. At this point, the config tool
+creates a file in the build directory called chip.c This file contains
+a common struct containing information about
+each individual chip and an array of pointers to these structures.
+
+For each chip, there are two structures. The structures contain control
+information for the chip, and register initialization information. The
+names of the structures are derived by ``flattening'' the chip name,
+as in the current linuxbios. For example, superio/ite/xyz uses
+two structs, one called superio_ite_xyz_control and one called
+superio_ite_xyz_init. The control struct is initialized from the
+chip name and path information, and has a pointer to the
+config struct. The config struct is initialized from the quote string
+
+\begin{verbatim}
+From rminnich@lanl.gov Fri May 16 10:34:13 2003
+Date: Tue, 13 May 2003 08:11:46 -0600 (MDT)
+From: ron minnich <rminnich@lanl.gov>
+To: linuxbios@clustermatic.org
+Subject: RFC:new superio proposal
+
+Abstract:
+	The superio architecture for linuxbios has worked for the last 2
+years but is being stretched to the limit by the changes in superio chips.
+The architecture depended on superio resources being relatively constant
+between chips, but this assumption no longer holds. In this document we
+propose several alternatives and solicit comments.
+
+Overview:
+The superio architecture in linuxbios was developed over time, and
+modified as circumstances required. In the beginning it was relatively
+simple and assumed only one superio per mainboard. The latest version
+allows an arbitrary number of superios per mainboard, and allows complete
+specification of the superio base I/O address along with the specification
+of reasonable default valures for both the base I/O address and the
+superio parameters such as serial enable, baud rate, and so on.
+
+Specification of superio control parameters is done by a configuration
+line such as:
+
+nsuperio sis/950 com1={1} floppy=1  lpt=1
+
+This fragment sets the superio type to sis/950; sets com1, floppy, and lpt
+to enabled; and leaves the defaults to com1 (baud rate, etc.) to the
+default values.
+
+While it is not obvious, these configuration parameters are fragments of a
+C initializer. The initializers are used to build a statically initialized
+structure of this type:
+
+struct superio {
+        struct superio_control *super; // the ops for the device.
+        unsigned int port; // if non-zero, overrides the default port
+        // com ports. This is not done as an array (yet).
+        // We think it's easier to set up from python if it is not an
+	// array.
+        struct com_ports com1, com2, com3, com4;
+        // DMA, if it exists.
+        struct lpt_ports lpt1, lpt2;
+        /* flags for each device type. Unsigned int. */
+        // low order bit ALWAYS means enable. Next bit means to enable
+        // LPT is in transition, so we leave this here for the moment.
+        // The winbond chips really stretched the way this works.
+        // so many functions!
+        unsigned int ide, floppy, lpt;
+        unsigned int keyboard, cir, game;
+        unsigned int gpio1, gpio2, gpio3;
+        unsigned int acpi,hwmonitor;
+};
+
+These structures are, in turn, created and statically initialized by a
+config-tool-generated structure that defines all the superios. This file
+is called nsuperio.c, is created for each mainboard you build, only
+appears in the build directory, and looks like this:
+
+===
+extern struct superio_control superio_winbond_w83627hf_control;
+
+struct superio superio_winbond_w83627hf= {
+  &superio_winbond_w83627hf_control,
+  .com1={1}, .com2={1}, .floppy=1, .lpt=1, .keyboard=1, .hwmonitor=1};
+
+struct superio *all_superio[] = {&superio_winbond_w83627hf,
+};
+
+unsigned long nsuperio = 1;
+===
+
+This example shows a board with one superio (nsuperio). The superio
+consists of a winbond w83627hf, with com1, com2, floppy, lpt, keyboard,
+and hwmonitor enabled. Note that this structure also allows for
+over-riding the default superio base, although that capability is rarely
+used.
+
+The control structure is used to define how to access the superio for
+purposes of control. It looks like this:
+===
+struct superio_control {
+  void (*pre_pci_init)(struct superio *s);
+  void (*init)(struct superio *s);
+  void (*finishup)(struct superio *s);
+  unsigned int defaultport;     /* the defaultport. Can be overridden
+                                 * by commands in config
+                                 */
+  // This is the print name for debugging
+  char *name;
+};
+===
+
+There are three methods for stages of hardwaremain. First is pre_pci_init
+(for chips like the acer southbridge that require you to enable some
+resources BEFORE pci scan); init, called during the 'middle' phase of
+hardwaremain; and finishup, called before the payload is loaded.
+
+This approach was inspired by and borrows heavily on the Plan 9 kernel
+configuration tools.
+
+The problem:
+
+When the first version of the superio structure came out it was much
+smaller. It has grown and in the limit this structure is the union of all
+possibly superio chips. Obviously, in the long term, this is not
+practical: we can not anticipate all possible superio chips for all time.
+
+The common PC BIOS solution to this type of problem is to continue with
+binary structures but add version numbers to them, so that all code that
+uses a given structure has to check the version number. Personally, I find
+this grotesque and would rather not work this way.
+
+Using textual strings for configuration is something I find far more
+attractive. Plan 9 has shown that this approach has no real limits and
+suffices for configuration tasks. The Linux kernel does more limited use
+of strings for configuration, but still depends on them. Strings are
+easier to read and work with than binary structures, and more important, a
+lot easier to deal with when things start going wrong.
+
+The proposed solution:
+
+What follows are three possible ideas for specifying superio resources and
+their settings.
+
+A common part of the new idea is to eliminate the common superio
+structure, due to the many variations in chips, and make it invisible
+outside a given superio source file -- the superio structure is now
+private to a given superio. Thus, sis/950/superio.c would contain its own
+superio structure definitions, and also might contain more than once
+instance of these structures (consider a board with 2 sis 950 chips).
+
+The control structure would change as follows:
+struct superio_control {
+  int (*create)(struct superio *s);
+  void (*pre_pci_init)(struct superio *s);
+  void (*init)(struct superio *s);
+  void (*finishup)(struct superio *s);
+  unsigned int defaultport;     /* the defaultport. Can be overridden
+                                 * by commands in config
+                                 */
+  // This is the print name for debugging
+  char *name;
+};
+
+I.e. we add a new function for creating the superio.
+
+Communication of superio settings from linuxbios to the superio would be
+via textual strings. The superio structure becomes this:
+
+struct superio {
+        struct superio_control *super; // the ops for the device.
+        unsigned int port; // if non-zero, overrides the default port
+	struct configuration *config;
+};
+
+
+So now the question becomes, what is the configuration structure?
+There are several choices. The simplest, from my point of view, are
+keyword-value pairs:
+struct configuration {
+	const char *keyword;
+	const char *value;
+};
+
+These get filled in by the config tool as before. The linuxbios library can
+then provide a generic parsing function for the superios to use.
+
+The remaining question is how should the superio command look in
+freebios2?
+
+superio sis/950 "com1=115200,8n1 lpt=1 com2=9600"
+
+or
+
+superio sis/950 "com1baud=115200 lpt=1 com1chars=8n1"
+
+or
+
+superio sis/950 ((com1 115200 8n1) (lpt 1))
+
+So,  my questions:
+
+1. Does this new scheme look workable. If not, what needs to change?
+2. What should the 'struct configuration' be? does keyword/value work?
+3. what should the superio command look like?
+
+Comments welcome.
+
+I'd like to adopt this "RFC" approach for freebios2 as much as we can.
+There was a lot of give-and-take in the early days of linuxbios about
+structure and it proved useful. There's a lot that will start happening in
+freebios2 now, and we need to try to make sure it will work for everyone.
+
+Those of you who are doing mainboards, please look at freebios2 and see
+how it looks for you. There's a lot of good work that has been done (not
+by me so far, thanks Eric and Stefan), and more that needs to be done.
+Consider trying out romcc as an "assembly code killer". See how it fits
+together and if you can work with it or need changes. Bring comments back
+to this list.
+
+thanks
+
+ron
+
+\end{verbatim}

Documentation/RFC/intel-gpio-cleanup.md

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

Documentation/_static/theme_overrides.css

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2018 Patrick Rudolph <siro@das-labor.org>
+ *
+ * licensed under CC-by 4.0
+ */
+
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+

Documentation/acpi/gpio.md

@@ -0,0 +1,180 @@
+# GPIO toggling in ACPI AML for coreboot
+
+## Table of contents
+- Introduction
+- Platform Interface
+- Helper routines
+- Implementation details
+- Arguments and Local Variables Management
+
+## Introduction
+
+ACPI provides platform-independent interfaces enabling the operating
+system to perform power management for devices as well as the entire
+system. An operating system can simply call into Method()s implemented
+by the interface to request different power management operations. In
+order to be able to perform these operations, an interface might
+require toggling of GPIOs. e.g. a touchscreen device interface might
+require toggling of reset-gpio in order to take the device out of
+reset or to put it back into reset.
+
+Thus, any coreboot driver that implements such an ACPI interface might
+require the ability to toggle GPIOs. However, toggling of GPIO is not
+the same across different platforms and it will require the driver to
+depend upon platform to do the required work. This document presents a
+simple interface that can be used by any coreboot driver to generate
+ACPI AML code for reading or toggling platform GPIOs.
+
+## Platform Interface
+
+All platforms that use drivers requiring ACPI AML code for GPIO
+interactions need to be implement the following functions:
+1. Return GPIO Rx value if it is acting as input
+   int acpigen_soc_read_rx_gpio(unsigned int gpio_num)
+2. Return GPIO Tx value if it is acting as output
+   int acpigen_soc_get_tx_gpio(unsigned int gpio_num)
+3. Set GPIO Tx value to 1 if it is acting as output
+   int acpigen_soc_set_tx_gpio(unsigned int gpio_num)
+4. Set GPIO Tx value to 0 if it is acting as output
+   int acpigen_soc_clear_tx_gpio(unsigned int gpio_num)
+
+Each of the above functions takes as input gpio_num which is the gpio
+number that needs to be read or toggled and returns an integer which
+is:
+1. Error = -1
+2. Success = 0
+
+Above callback functions are chosen to be implemented in C rather than
+adding them as AML code callbacks for the following reasons:
+1. It is easier to add error prints in C which will inform the
+   developer that these callbacks are missing. It restricts debugging
+   to coreboot logs.
+2. GPIO conversion from number to register offset can be easily done
+   in C by reusing implemented functions rather than adding all the
+   logic to AML code or depending upon complicated macros to be added
+   to device-tree.
+3. Allows GPIO AML methods to be present under any device scope and
+   gives SoC the flexibility to call them without any restrictions.
+
+## Helper routines
+
+In order to relieve drivers of the task of implementing the same code
+for enabling/disabling Tx GPIOs based on the GPIO polarity, helper
+routines are provided which implement this common code and can be used
+directly in the driver routines:
+1. Enable Tx GPIO
+   int acpigen_enable_tx_gpio(struct acpi_gpio gpio)
+2. Disable Tx GPIO
+   int acpigen_disable_tx_gpio(struct acpi_gpio gpio)
+
+Both the above functions take as input struct acpi_gpio type and
+return -1 on error and 0 on success. These helper routines end up
+calling the platform specific acpigen_soc_{set,clear}_tx_gpio
+functions internally. Thus, all the ACPI AML calling conventions for
+the platform functions apply to these helper functions as well.
+
+3. Get Rx GPIO
+   int acpigen_get_rx_gpio(struct acpi_gpio gpio)
+
+This function takes as input, an struct acpi_gpio type and outputs
+AML code to read the *logical* value of a gpio (after taking its
+polarity into consideration), into the Local0 variable. It calls
+the platform specific acpigen_soc_read_rx_gpio() to actually read
+the raw Rx gpio value.
+
+## Implementation Details
+
+Platforms are restricted to using Local5, Local6 and Local7 variables
+only in implementations of the above functions. Any AML methods called
+by the above functions do not have any such restrictions on use of
+Local variables in AML code. Local0 is to be used for all get/read
+functions to return values. This means that the driver code should not
+make any assumptions about the values in Local5, Local6 and Local7
+variables.
+
+```
+ **Function**                   **Operation**                **Return**
+ acpigen_soc_read_rx_gpio     Generate ACPI AML code to      Error = -1
+                              read value of Rx in Local0.    Success = 0
+ acpigen_soc_get_tx_gpio      Generate ACPI AML code to      Error = -1
+                              get value of Tx in Local0.     Success = 0
+ acpigen_soc_set_tx_gpio      Generate ACPI AML code to      Error = -1
+                              set Tx to 1.                   Success = 0
+ acpigen_soc_clear_tx_gpio    Generate ACPI AML code to      Error = -1
+                              set Tx to 0.                   Success = 0
+```
+
+Ideally, the operation column in the above table should use one or
+more functions implemented by the platform in AML code library (like
+gpiolib.asl). In the example below SPC0 and GPC0 need to be
+implemented by the SoC in AML code library and they can be used by
+acpi_soc_set_tx_gpio to read and set bit in the appropriate register
+for the GPIO.
+
+**acpigen_soc_set_tx_gpio**
+
+	uint64_t gpio_reg_offset = gpio_get_reg_offset(gpio_num);
+
+	/* Store (\_SB.GPC0(gpio_reg_offset, Local5) */
+	acpigen_write_store();
+	acpigen_emit_namestring(“\\_SB.GPC0”);
+	acpigen_write_integer(gpio_reg_offset);
+	acpigen_emit_byte(LOCAL5_OP);
+
+
+	/* Or (Local5, TX_BIT, Local5) */
+	acpigen_write_or(LOCAL5_OP, TX_BIT, LOCAL5_OP);
+
+	/* \_SB.SPC0(gpio_reg_offset, LOCAL5) */
+	acpigen_emit_namestring(“\\_SB.SPC0”);
+	acpigen_write_integer(gpio_reg_offset);
+	acpigen_emit_byte(LOCAL5_OP);
+
+	return 0;
+
+**acpigen_soc_get_tx_gpio**
+
+	uint64_t gpio_reg_offset = gpio_get_reg_offset(gpio_num);
+
+
+	/* Store (\_SB.GPC0(gpio_reg_offset, Local5) */
+	acpigen_write_store();
+	acpigen_emit_namestring(“\\_SB.GPC0”);
+	acpigen_write_integer(gpio_reg_offset);
+	acpigen_emit_byte(LOCAL5_OP);
+
+
+	/*
+	 * If (And (Local5, TX_BIT)) Store (One, Local0) Else Store (Zero,
+	 * Local0)
+	 */
+	acpigen_write_if_and(Local5, TX_BIT);
+	acpigen_write_store_args(ONE_OP, LOCAL0_OP);
+	acpigen_write_else();
+	acpigen_write_store_args(ZERO_OP, LOCAL0_OP);
+	acpigen_pop_len();
+
+	return 0;
+
+
+These are reference implementations and the platforms are free to
+implement these functions in any way they like. coreboot driver can
+then simply call into these functions to generate ACPI AML code to
+get/set/clear any GPIO. In order to decide whether GPIO operations are
+required, driver code can rely either on some config option or read
+device-tree to use any user-provided GPIOs.
+
+## Arguments and Local Variables Management
+
+Platform-defined functions can call methods using the same calling
+conventions provided by AML code. However, use of Local Variables is
+restricted to Local5, Local6 and Local7 unless they call into some
+other method. Called method can use any Local variables, Local0 -
+Local7. In case of functions expected to return back value to the
+caller, this value is expected to be returned in Local0.
+
+Driver code should not make any assumptions about the contents of
+Local5, Local6 and Local7 across callbacks to SoC code. If it makes a
+read or get call to SoC, the return value should be used from Local0
+on return. However, if it makes a set or clear call to SoC, the value
+in Local0 is undefined.

Documentation/acpi/index.md

@@ -0,0 +1,34 @@
+# ACPI-specific documentation
+
+This section contains documentation about coreboot on ACPI. coreboot dropped
+backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
+upwards.
+
+
+```{toctree}
+:maxdepth: 1
+
+SSDT UID generation <uid.md>
+```
+
+## GPIO
+
+```{toctree}
+:maxdepth: 1
+
+GPIO toggling in ACPI AML <gpio.md>
+```
+
+## 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)

Documentation/acpi/uid.md

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

Documentation/acpi/windows.md

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

@@ -0,0 +1,19 @@
+# Architecture-specific documentation
+
+This section contains documentation about coreboot on specific CPU
+architectures.
+
+## RISC-V
+
+```{toctree}
+:maxdepth: 1
+
+RISC-V documentation <riscv/index.md>
+```
+
+## x86
+```{toctree}
+:maxdepth: 1
+
+x86 documentation <x86/index.md>
+```

Documentation/arch/riscv/index.md

@@ -0,0 +1,64 @@
+# RISC-V architecture documentation
+
+This section contains documentation about coreboot on RISC-V architecture.
+
+## Mode usage
+All stages run in M mode.
+
+Payloads have a choice of managing M mode activity: they can control
+everything or nothing.
+
+Payloads run from the romstage (i.e. rampayloads) are started in M mode.
+The payload must, for example, prepare and install its own SBI.
+
+Payloads run from the ramstage are started in S mode, and trap delegation
+will have been done. These payloads rely on the SBI and can not replace it.
+
+## Stage handoff protocol
+On entry to a stage or payload (including SELF payloads),
+* all harts are running.
+* A0 is the hart ID.
+* A1 is the pointer to the Flattened Device Tree (FDT).
+* A2 contains the additional program calling argument:
+  - cbmem_top for ramstage
+  - the address of the payload for opensbi
+
+## Additional payload handoff requirements
+The location of cbmem should be placed in a node in the FDT.
+
+## OpenSBI
+In case the payload doesn't install it's own SBI, like the [RISCV-PK] does,
+[OpenSBI] can be used instead.
+It's loaded into RAM after coreboot has finished loading the payload.
+coreboot then will jump to OpenSBI providing a pointer to the real payload,
+which OpenSBI will jump to once the SBI is installed.
+
+Besides providing SBI it also sets protected memory regions and provides
+a platform independent console.
+
+The OpenSBI code is always run in M mode.
+
+## Trap delegation
+Traps are delegated to the payload.
+
+## SMP within a stage
+At the beginning of each stage, all harts save 0 are spinning in a loop on
+a semaphore.  At the end of the stage harts 1..max are released by changing
+the semaphore.
+
+A possible way to do this is to have a pointer to a struct containing
+variables, e.g.
+
+```c
+struct blocker {
+	void (*fn)(); // never returns
+}
+```
+
+The hart blocks until fn is non-null, and then calls it.  If fn returns, we
+will panic if possible, but behavior is largely undefined.
+
+Only hart 0 runs through most of the code in each stage.
+
+[RISCV-PK]: https://github.com/riscv/riscv-pk
+[OpenSBI]: https://github.com/riscv/opensbi

Documentation/arch/x86/index.md

@@ -0,0 +1,10 @@
+# x86 architecture documentation
+
+This section contains documentation about coreboot on x86 architecture.
+
+```{toctree}
+:maxdepth: 1
+
+x86 PAE support <pae.md>
+x86_64 support <x86_64.md>
+```

Documentation/arch/x86/pae.md

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

Documentation/arch/x86/x86_64.md

@@ -0,0 +1,109 @@
+# 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/beginverbatim.tex

@@ -0,0 +1 @@
+\begin{verbatim}

Documentation/cbfs.txt

@@ -0,0 +1,421 @@
+
+Received: from www.crouse-house.com ([199.45.160.146]
+	for coreboot@coreboot.org; Fri, 19 Dec 2008 23:11:59 +0100
+From: Jordan Crouse <jordan@cosmicpenguin.net>
+
+
+Greetings.  I apologize for the incompleteness of what I am about to
+discuss.  I was planning on working on it leisurely, but my employment
+circumstances changed and I've been trying to get it completed in a
+hurry before I had to leave it behind.
+
+I've been thinking a lot about LAR lately, and ways to make it more
+extensible and robust.  Marc and I have been trading ideas back and
+forth for a number of months, and over time a clear idea of what I
+wanted to do started to take shape.
+
+My goal was to add small things to LAR while retaining the overall
+scheme.  Over time, the scheme evolved slightly, but I think you'll find
+that it remains true to the original idea.  Below is the beginnings of
+an architecture document - I did it in text form, but if met with
+aclaim, it should be wikified.  This presents what I call CBFS - the
+next generation LAR for next generation coreboot.  Its easier to
+describe what it is by describing what changed:
+
+A header has been added somewhere in the bootblock similar to Carl
+Daniel's scheme.  In addition to the coreboot information, the header
+reports the size of the ROM, the alignment of the blocks, and the offset
+of the first component in the CBFS.   The master header provides all
+the information LAR needs plus the magic number information flashrom needs.
+
+Each "file" (or component, as I style them) now has a type associated
+with it. The type is used by coreboot to identify the type of file that
+it is loading, and it can also be used by payloads to group items in the
+CBFS by type (i.e - bayou can ask for all components that are payloads).
+
+The header on each "file" (or component, as I like to style them) has
+been simplified - We now only store the length, the type, the checksum,
+and the offset to the data.  The name scheme remains the same.  The
+additional information, which is component specific, has been moved to
+the component itself (see below).
+
+The components are arranged in the ROM aligned along the specified
+alignment from the master header - this is to facilitate partial re-write.
+
+Other then that, the LAR ideas remain pretty much the same.
+
+The plan for moving the metadata to the components is to allow many
+different kinds of components, not all of which are groked by coreboot.
+  However, there are three essential component types that are groked by
+coreboot, and they are defined:
+
+stage - the stage is being parsed from the original ELF, and stored in
+the ROM as a single blob of binary data.  The load address, start
+address, compression type and length are stored in the component sub-header.
+
+payload - this is essentially SELF in different clothing - same idea as
+SELF, with the sub-header as above.
+
+optionrom - This is in flux - right now, the optionrom is stored
+unadulterated and uncompressed, but that is likely to be changed.
+
+Following this email are two replies containing the v3 code and a new
+ROM tool to implement this respectively.  I told you that I was trying
+to get this out before I disappear, and I'm not kidding - the code is
+compile tested and not run-tested.  I hope that somebody will embrace
+this code and take it the rest of the way, otherwise it will die a
+pretty short death.
+
+I realize that this will start an awesome flamewar, and I'm looking
+forward to it.  Thanks for listening to me over the years - and good
+luck with coreboot.  When you all make a million dollars, send me a few
+bucks, will you?
+
+Jordan
+
+coreboot CBFS Specification
+Jordan Crouse <jordan@cosmicpenguin.net>
+
+= Introduction =
+
+This document describes the coreboot CBFS specification (from here
+referred to as CBFS).  CBFS is a scheme for managing independent chunks
+of data in a system ROM.  Though not a true filesystem, the style and
+concepts are similar.
+
+
+= Architecture =
+
+The CBFS architecture looks like the following:
+
+/---------------\ <-- Start of ROM
+| /-----------\ | --|
+| | Header    | |   |
+| |-----------| |   |
+| | Name      | |   |-- Component
+| |-----------| |   |
+| |Data       | |   |
+| |..         | |   |
+| \-----------/ | --|
+|               |
+| /-----------\ |
+| | Header    | |
+| |-----------| |
+| | Name      | |
+| |-----------| |
+| |Data       | |
+| |..         | |
+| \-----------/ |
+|               |
+| ...           |
+| /-----------\ |
+| |           | |
+| | Bootblock | |
+| | --------- | |
+| | Reset     | | <- 0xFFFFFFF0
+| \-----------/ |
+\---------------/
+
+
+The CBFS architecture consists of a binary associated with a physical
+ROM disk referred hereafter as the ROM. A number of independent of
+components, each with a  header prepended on to data are located within
+the ROM.  The components are nominally arranged sequentially, though they
+are aligned along a pre-defined boundary.
+
+The bootblock occupies the last 20k of the ROM.  Within
+the bootblock is a master header containing information about the ROM
+including the size, alignment of the components, and the offset of the
+start of the first CBFS component within the ROM.
+
+= Master Header =
+
+The master header contains essential information about the ROM that is
+used by both the CBFS implementation within coreboot at runtime as well
+as host based utilities to create and manage the ROM.  The master header
+will be located somewhere within the bootblock (last 20k of the ROM).  A
+pointer to the location of the header will be located at offset
+-4 from the end of the ROM.  This translates to address 0xFFFFFFFC on a
+normal x86 system.  The pointer will be to physical memory somewhere
+between - 0xFFFFB000 and 0xFFFFFFF0.  This makes it easier for coreboot
+to locate the header at run time.  Build time utilities will
+need to read the pointer and do the appropriate math to locate the header.
+
+The following is the structure of the master header:
+
+struct cbfs_header {
+        u32 magic;
+        u32 version;
+        u32 romsize;
+        u32 bootblocksize;
+        u32 align;
+        u32 offset;
+        u32 architecture;
+        u32 pad[1];
+} __packed;
+
+The meaning of each member is as follows:
+
+'magic' is a 32 bit number that identifies the ROM as a CBFS type.  The
+magic
+number is 0x4F524243, which is 'ORBC' in ASCII.
+
+'version' is a version number for CBFS header. cbfs_header structure may be
+different if version is not matched.
+
+'romsize' is the size of the ROM in bytes.  coreboot will subtract 'size' from
+0xFFFFFFFF to locate the beginning of the ROM in memory.
+
+'bootblocksize' is the size of bootblock reserved in firmware image.
+
+'align' is the number of bytes that each component is aligned to within the
+ROM.  This is used to make sure that each component is aligned correctly
+with
+regards to the erase block sizes on the ROM - allowing one to replace a
+component at runtime without disturbing the others.
+
+'offset' is the offset of the first CBFS component (from the start of
+the ROM).  This is to allow for arbitrary space to be left at the beginning
+of the ROM for things like embedded controller firmware.
+
+'architecture' describes which architecture (x86, arm, ...) this CBFS is created
+for.
+
+= Bootblock =
+The bootblock is a mandatory component in the ROM.  It is located in the
+last
+20k of the ROM space, and contains, among other things, the location of the
+master header and the entry point for the loader firmware.  The bootblock
+does not have a component header attached to it.
+
+= Components =
+
+CBFS components are placed in the ROM starting at 'offset' specified in
+the master header and ending at the bootblock.  Thus the total size
+available
+for components in the ROM is (ROM size - 20k - 'offset').  Each CBFS
+component is to be aligned according to the 'align' value in the header.
+Thus, if a component of size 1052 is located at offset 0 with an 'align'
+value
+of 1024, the next component will be located at offset 2048.
+
+Each CBFS component will be indexed with a unique ASCII string name of
+unlimited size.
+
+Each CBFS component starts with a header:
+
+struct cbfs_file {
+         char magic[8];
+         unsigned int len;
+         unsigned int type;
+         unsigned int checksum;
+         unsigned int offset;
+};
+
+'magic' is a magic value used to identify the header.  During runtime,
+coreboot will scan the ROM looking for this value.  The default magic is
+the string 'LARCHIVE'.
+
+'len' is the length of the data, not including the size of the header and
+the size of the name.
+
+'type' is a 32 bit number indicating the type of data that is attached.
+The data type is used in a number of ways, as detailed in the section
+below.
+
+'checksum' is a 32bit checksum of the entire component, including the
+header and name.
+
+'offset' is the start of the component data, based off the start of the
+header.
+The difference between the size of the header and offset is the size of the
+component name.
+
+Immediately following the header will be the name of the component,
+which will
+null terminated and 16 byte aligned.   The following picture shows the
+structure of the header:
+
+/--------\  <- start
+| Header |
+|--------|  <- sizeof(struct cbfs_file)
+| Name   |
+|--------|  <- 'offset'
+| Data   |
+| ...    |
+\--------/  <- start + 'offset' + 'len'
+
+== Searching Algorithm ==
+
+To locate a specific component in the ROM, one starts at the 'offset'
+specified in the CBFS master header.  For this example, the offset will
+be 0.
+
+ From that offset, the code should search for the magic string on the
+component, jumping 'align' bytes each time.  So, assuming that 'align' is
+16, the code will search for the string 'LARCHIVE' at offset 0, 16, 32, etc.
+If the offset ever exceeds the allowable range for CBFS components, then no
+component was found.
+
+Upon recognizing a component, the software then has to search for the
+specific name of the component.  This is accomplished by comparing the
+desired name with the string on the component located at
+offset + sizeof(struct cbfs_file).  If the string matches, then the
+component
+has been located, otherwise the software should add 'offset' + 'len' to
+the offset and resume the search for the magic value.
+
+== Data Types ==
+
+The 'type' member of struct cbfs_file is used to identify the content
+of the component data, and is used by coreboot and other
+run-time entities to make decisions about how to handle the data.
+
+There are three component types that are essential to coreboot, and so
+are defined here.
+
+=== Stages ===
+
+Stages are code loaded by coreboot during the boot process.  They are
+essential to a successful boot.   Stages are comprised of a single blob
+of binary data that is to be loaded into a particular location in memory
+and executed.   The uncompressed header contains information about how
+large the data is, and where it should be placed, and what additional memory
+needs to be cleared.
+
+Stages are assigned a component value of 0x10.  When coreboot sees this
+component type, it knows that it should pass the data to a sub-function
+that will process the stage.
+
+The following is the format of a stage component:
+
+/--------\
+| Header |
+|--------|
+| Binary |
+| ..     |
+\--------/
+
+The header is defined as:
+
+struct cbfs_stage {
+         unsigned int compression;
+         unsigned long long entry;
+         unsigned long long load;
+         unsigned int len;
+         unsigned int memlen;
+};
+
+'compression' is an integer defining how the data is compressed.  There
+are three compression types defined by this version of the standard:
+none (0x0), lzma (0x1), and nrv2b (0x02, deprecated), though additional
+types may be added assuming that coreboot understands how to handle the scheme.
+
+'entry' is a 64 bit value indicating the location where  the program
+counter should jump following the loading of the stage.  This should be
+an absolute physical memory address.
+
+'load' is a 64 bit value indicating where the subsequent data should be
+loaded.  This should be an absolute physical memory address.
+
+'len' is the length of the compressed data in the component.
+
+'memlen' is the amount of memory that will be used by the component when
+it is loaded.
+
+The component data will start immediately following the header.
+
+When coreboot loads a stage, it will first zero the memory from 'load' to
+'memlen'.  It will then decompress the component data according to the
+specified scheme and place it in memory starting at 'load'.  Following that,
+it will jump execution to the address specified by 'entry'.
+Some components are designed to execute directly from the ROM - coreboot
+knows which components must do that and will act accordingly.
+
+=== Payloads ===
+
+Payloads are loaded by coreboot following the boot process.
+
+Stages are assigned a component value of 0x20.  When coreboot sees this
+component type, it knows that it should pass the data to a sub-function
+that will process the payload.  Furthermore, other run time
+applications such as 'bayou' may easily index all available payloads
+on the system by searching for the payload type.
+
+
+The following is the format of a stage component:
+
+/-----------\
+| Header    |
+| Segment 1 |
+| Segment 2 |
+| ...       |
+|-----------|
+| Binary    |
+| ..        |
+\-----------/
+
+The header is as follows:
+
+struct cbfs_payload {
+         struct cbfs_payload_segment segments;
+}
+
+The header contains a number of segments corresponding to the segments
+that need to be loaded for the payload.
+
+The following is the structure of each segment header:
+
+struct cbfs_payload_segment {
+         unsigned int type;
+         unsigned int compression;
+         unsigned int offset;
+         unsigned long long load_addr;
+         unsigned int len;
+         unsigned int mem_len;
+};
+
+'type' is the type of segment, one of the following:
+
+PAYLOAD_SEGMENT_CODE   0x45444F43   The segment contains executable code
+PAYLOAD_SEGMENT_DATA   0x41544144   The segment contains data
+PAYLOAD_SEGMENT_BSS    0x20535342   The memory specified by the segment
+                                     should be zeroed
+PAYLOAD_SEGMENT_PARAMS 0x41524150   The segment contains information for
+                                     the payload
+PAYLOAD_SEGMENT_ENTRY  0x52544E45   The segment contains the entry point
+		  		    for the payload
+
+'compression' is the compression scheme for the segment.  Each segment can
+be independently compressed. There are three compression types defined by
+this version of the standard: none (0x0), lzma (0x1), and nrv2b
+(0x02, deprecated), though additional types may be added assuming that
+coreboot understands how to handle the scheme.
+
+'offset' is the address of the data within the component, starting from
+the component header.
+
+'load_addr' is a 64 bit value indicating where the segment should be placed
+in memory.
+
+'len' is a 32 bit value indicating the size of the segment within the
+component.
+
+'mem_len' is the size of the data when it is placed into memory.
+
+The data will located immediately following the last segment.
+
+=== Option ROMS ===
+
+The third specified component type will be Option ROMs.  Option ROMS will
+have component type '0x30'.  They will have no additional header, the
+uncompressed binary data will be located in the data portion of the
+component.
+
+=== NULL ===
+
+There is a 4th component type ,defined as NULL (0xFFFFFFFF).  This is
+the "don't care" component type.  This can be used when the component
+type is not necessary (such as when the name of the component is unique.
+i.e. option_table).  It is recommended that all components be assigned a
+unique type, but NULL can be used when the type does not matter.

Documentation/codeflow.svg

@@ -0,0 +1,234 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="256px" height="640px" viewBox="0 0 256 640" enable-background="new 0 0 256 640" xml:space="preserve">
+<font horiz-adv-x="1000">
+<font-face font-family="MyriadPro-Regular" units-per-em="1000" underline-position="-100" underline-thickness="50"/>
+<missing-glyph horiz-adv-x="500" d="M0,0l500,0l0,700l-500,0M250,395l-170,255l340,0M280,350l170,255l0,-510M80,50l170,255l170,-255M50,605l170,-255l-170,-255z"/>
+<glyph unicode="A" horiz-adv-x="612" d="M424,212l72,-212l93,0l-230,674l-104,0l-230,-674l90,0l70,212M203,280l66,195C283,516 293,558 303,597l2,0C315,558 325,518 340,474l67,-194z"/>
+<glyph unicode="B" horiz-adv-x="542" d="M76,2C105,-2 151,-6 211,-6C321,-6 397,14 443,57C478,89 501,134 501,192C501,292 426,345 362,360l0,3C432,388 476,445 476,511C476,564 454,604 419,630C378,664 322,679 235,679C175,679 114,673 76,664M163,606C177,609 200,612 240,612C328,612 387,580 387,502C387,437 333,388 242,388l-79,0M163,323l72,0C330,323 409,284 409,193C409,95 326,62 236,62C205,62 181,63 163,66z"/>
+<glyph unicode="C" horiz-adv-x="580" d="M529,91C494,74 440,63 386,63C223,63 128,168 128,334C128,511 233,612 391,612C447,612 494,600 526,584l22,71C525,667 471,685 388,685C179,685 36,543 36,331C36,109 178,-11 368,-11C450,-11 515,5 546,21z"/>
+<glyph unicode="D" horiz-adv-x="666" d="M76,2C120,-3 171,-6 234,-6C365,-6 469,28 533,91C595,153 630,243 630,353C630,462 595,540 534,595C475,649 386,679 261,679C192,679 129,673 76,664M163,601C186,606 220,610 265,610C449,610 539,509 538,350C538,168 438,64 251,64C217,64 185,65 163,68z"/>
+<glyph unicode="E" horiz-adv-x="492" d="M424,388l-261,0l0,213l277,0l0,73l-365,0l0,-674l380,0l0,73l-292,0l0,243l261,0z"/>
+<glyph unicode="F" horiz-adv-x="487" d="M75,0l88,0l0,305l254,0l0,72l-254,0l0,224l275,0l0,73l-363,0z"/>
+<glyph unicode="H" horiz-adv-x="652" d="M75,674l0,-674l88,0l0,316l326,0l0,-316l88,0l0,674l-88,0l0,-282l-326,0l0,282z"/>
+<glyph unicode="I" horiz-adv-x="239" d="M75,674l0,-674l88,0l0,674z"/>
+<glyph unicode="L" horiz-adv-x="472" d="M75,0l376,0l0,73l-288,0l0,601l-88,0z"/>
+<glyph unicode="M" horiz-adv-x="804" d="M660,0l86,0l-42,674l-111,0l-120,-326C443,263 419,189 401,121l-2,0C381,191 359,265 331,348l-115,326l-111,0l-47,-674l83,0l18,289C165,391 170,503 172,587l2,0C193,507 219,421 251,325l110,-321l66,0l119,327C580,424 607,509 631,587l2,0C633,504 639,390 644,296z"/>
+<glyph unicode="N" horiz-adv-x="658" d="M158,0l0,288C158,400 157,481 152,566l3,1C188,494 233,417 280,342l214,-342l88,0l0,674l-82,0l0,-282C500,287 502,205 510,115l-3,-1C476,183 436,254 387,333l-215,341l-96,0l0,-674z"/>
+<glyph unicode="O" horiz-adv-x="689" d="M348,686C168,686 36,546 36,332C36,128 160,-11 339,-11C511,-11 652,113 652,344C652,545 533,686 348,686M345,615C490,615 560,475 560,340C560,187 482,60 344,60C206,60 128,189 128,334C128,481 200,615 345,615z"/>
+<glyph unicode="P" horiz-adv-x="532" d="M76,0l87,0l0,270C183,265 207,264 233,264C318,264 392,289 439,338C473,373 491,421 491,482C491,542 468,591 432,623C392,659 329,679 243,679C173,679 118,673 76,666M163,603C178,607 207,610 245,610C340,610 404,567 404,477C404,386 340,334 235,334C206,334 182,336 163,341z"/>
+<glyph unicode="Q" horiz-adv-x="689" d="M657,-26C600,-16 527,0 460,17l0,4C572,61 652,171 652,345C652,544 533,686 349,686C167,686 36,547 36,331C36,113 172,-5 333,-11C346,-11 359,-16 374,-21C452,-48 541,-75 632,-99M344,60C206,60 128,189 128,333C128,479 200,615 347,615C490,615 560,476 560,340C560,187 482,60 344,60z"/>
+<glyph unicode="R" horiz-adv-x="538" d="M76,0l87,0l0,292l82,0C324,289 361,254 381,161C399,77 414,20 425,0l90,0C501,26 485,91 463,185C447,255 416,303 365,321l0,3C435,348 491,407 491,495C491,548 471,594 438,624C397,661 336,679 243,679C184,679 120,673 76,665M163,604C178,608 207,611 249,611C341,611 404,573 404,486C404,409 345,358 252,358l-89,0z"/>
+<glyph unicode="S" horiz-adv-x="493" d="M42,33C78,9 149,-11 214,-11C373,-11 449,80 449,184C449,283 392,338 278,382C185,418 144,449 144,512C144,558 179,613 271,613C332,613 377,594 398,581l24,71C393,669 342,685 274,685C143,685 56,607 56,502C56,408 124,350 234,310C325,276 361,239 361,177C361,109 309,62 220,62C160,62 104,81 65,106z"/>
+<glyph unicode="T" horiz-adv-x="497" d="M204,0l88,0l0,600l206,0l0,74l-499,0l0,-74l205,0z"/>
+<glyph unicode="U" horiz-adv-x="647" d="M75,674l0,-397C75,67 179,-11 317,-11C463,-11 572,73 572,280l0,394l-88,0l0,-400C484,126 419,60 320,60C230,60 163,124 163,274l0,400z"/>
+<glyph unicode="a" horiz-adv-x="482" d="M413,297C413,393 377,494 229,494C168,494 109,477 69,452l20,-59C123,416 170,429 216,429C315,430 326,357 326,318l0,-10C139,309 35,245 35,128C35,58 85,-11 183,-11C252,-11 304,23 331,61l3,0l7,-61l79,0C415,33 413,74 413,116M328,163C328,155 327,145 324,135C310,94 269,54 205,54C161,54 123,80 123,138C123,232 232,249 328,247z"/>
+<glyph unicode="b" horiz-adv-x="569" d="M73,125C73,82 71,33 69,0l75,0l5,79l2,0C188,16 244,-11 314,-11C422,-11 532,75 532,248C532,394 448,494 327,494C249,494 193,460 162,406l-2,0l0,304l-87,0M160,280C160,294 162,306 165,317C183,383 239,425 298,425C393,425 443,342 443,245C443,134 389,59 296,59C232,59 180,101 164,162C161,172 160,183 160,194z"/>
+<glyph unicode="c" horiz-adv-x="448" d="M403,83C378,72 345,60 295,60C199,60 127,129 127,241C127,341 187,424 298,424C346,424 379,412 400,401l20,67C396,481 350,494 298,494C140,494 38,385 38,236C38,88 133,-11 279,-11C344,-11 395,6 418,17z"/>
+<glyph unicode="," horiz-adv-x="207" d="M78,-117C106,-70 150,41 174,126l-98,-10C65,43 38,-64 16,-124z"/>
+<glyph unicode="d" horiz-adv-x="564" d="M403,710l0,-289l-2,0C379,459 330,494 255,494C138,494 37,396 38,235C38,88 129,-11 246,-11C325,-11 383,30 409,84l3,0l4,-84l78,0C492,33 490,82 490,125l0,585M403,203C403,189 402,177 399,165C383,100 329,60 270,60C176,60 127,141 127,239C127,345 181,425 272,425C338,425 386,379 399,324C402,313 403,298 403,287z"/>
+<glyph unicode="e" horiz-adv-x="501" d="M462,226C464,236 465,249 465,267C465,356 424,494 265,494C124,494 38,380 38,234C38,88 127,-11 276,-11C353,-11 407,6 438,20l-16,63C390,69 351,58 288,58C199,58 124,107 122,226M123,289C130,350 168,431 258,431C357,431 381,344 380,289z"/>
+<glyph unicode="h" horiz-adv-x="555" d="M73,0l88,0l0,292C161,308 162,321 167,334C184,381 228,421 285,421C368,421 397,356 397,278l0,-278l88,0l0,288C485,454 381,494 316,494C283,494 252,485 226,470C199,455 177,432 163,407l-2,0l0,303l-88,0z"/>
+<glyph unicode="-" horiz-adv-x="307" d="M30,302l0,-64l247,0l0,64z"/>
+<glyph unicode="i" horiz-adv-x="234" d="M161,0l0,484l-88,0l0,-484M117,675C84,675 62,650 62,620C62,590 83,566 115,566C150,566 171,590 171,620C171,651 149,675 117,675z"/>
+<glyph unicode="k" horiz-adv-x="469" d="M160,710l-87,0l0,-710l87,0l0,182l45,50l166,-232l108,0l-213,285l186,199l-105,0l-143,-167C190,300 174,279 162,262l-2,0z"/>
+<glyph unicode="l" horiz-adv-x="236" d="M73,0l88,0l0,710l-88,0z"/>
+<glyph unicode="m" horiz-adv-x="834" d="M73,0l86,0l0,291C159,306 161,322 166,334C180,378 221,422 275,422C342,422 376,367 376,290l0,-290l86,0l0,299C462,315 465,330 469,343C485,385 523,422 574,422C644,422 679,367 679,273l0,-273l86,0l0,284C765,452 670,494 605,494C559,494 528,482 499,460C479,445 459,425 444,397l-2,0C421,454 371,494 306,494C225,494 180,451 153,405l-3,0l-4,79l-77,0C71,444 73,404 73,353z"/>
+<glyph unicode="n" horiz-adv-x="555" d="M73,0l88,0l0,291C161,306 163,321 167,332C183,381 228,422 285,422C368,422 397,357 397,279l0,-279l88,0l0,288C485,454 381,494 314,494C234,494 178,449 154,404l-2,0l-5,80l-78,0C72,444 73,404 73,353z"/>
+<glyph unicode="o" horiz-adv-x="549" d="M278,494C145,494 38,399 38,238C38,85 140,-11 270,-11C386,-11 511,67 511,246C511,393 417,494 278,494M276,428C380,428 421,325 421,243C421,134 358,55 274,55C188,55 128,135 128,241C128,332 173,428 276,428z"/>
+<glyph unicode="p" horiz-adv-x="569" d="M73,-198l87,0l0,263l2,0C191,17 247,-11 311,-11C425,-11 532,75 532,249C532,395 444,494 326,494C247,494 189,460 154,401l-2,0l-5,83l-78,0C71,438 73,388 73,326M160,281C160,292 163,305 166,316C182,382 239,424 299,424C392,424 443,341 443,245C443,134 389,58 296,58C233,58 180,100 164,161C161,172 160,184 160,197z"/>
+<glyph unicode="(" horiz-adv-x="284" d="M195,694C132,610 65,481 64,285C64,90 132,-38 195,-121l68,0C193,-21 138,106 138,284C138,466 190,595 263,694z"/>
+<glyph unicode=")" horiz-adv-x="284" d="M88,-121C151,-37 218,91 219,287C219,483 151,612 88,694l-68,0C91,594 145,467 145,287C145,107 90,-22 20,-121z"/>
+<glyph unicode="." horiz-adv-x="207" d="M110,-11C147,-11 171,16 171,52C171,89 147,115 112,115C77,115 52,88 52,52C52,16 76,-11 110,-11z"/>
+<glyph unicode="?" horiz-adv-x="406" d="M220,192l-2,25C215,268 231,313 275,365C323,422 361,471 361,539C361,615 309,686 194,686C141,686 85,670 51,646l24,-63C100,602 140,614 176,614C239,613 271,579 271,528C271,483 246,444 201,391C151,331 133,271 139,218l2,-26M178,-11C215,-11 238,16 238,51C238,88 215,114 179,114C145,114 120,88 120,51C120,16 144,-11 178,-11z"/>
+<glyph unicode="r" horiz-adv-x="327" d="M73,0l88,0l0,258C161,272 162,287 164,299C176,365 220,411 282,411C294,411 303,411 312,409l0,83C304,493 297,494 288,494C229,494 175,453 153,388l-3,0l-4,96l-77,0C72,439 73,390 73,333z"/>
+<glyph unicode="s" horiz-adv-x="396" d="M40,23C74,3 123,-11 176,-11C289,-11 356,49 356,135C356,207 312,249 229,280C166,305 138,323 138,363C138,399 166,429 218,429C263,429 298,412 317,400l21,64C312,481 269,494 220,494C117,494 53,430 53,352C53,294 94,247 182,215C246,191 271,169 271,127C271,86 241,55 178,55C134,55 88,73 61,89z"/>
+<glyph unicode="/" horiz-adv-x="343" d="M66,-39l280,725l-69,0l-278,-725z"/>
+<glyph unicode=" " horiz-adv-x="212"/>
+<glyph unicode="t" horiz-adv-x="331" d="M93,574l0,-90l-75,0l0,-67l75,0l0,-264C93,96 103,53 127,26C148,3 181,-11 222,-11C256,-11 283,-5 300,1l-4,67C283,64 269,62 245,62C196,62 179,96 179,156l0,261l126,0l0,67l-126,0l0,116z"/>
+<glyph unicode="2" horiz-adv-x="513" d="M460,0l0,73l-291,0l0,2l51,48C357,255 444,352 444,472C444,565 385,661 245,661C171,661 106,632 62,595l28,-62C120,558 169,588 228,588C325,588 356,527 356,461C356,363 280,279 114,121l-69,-67l0,-54z"/>
+<glyph unicode="u" horiz-adv-x="551" d="M478,484l-88,0l0,-296C390,171 387,155 382,143C366,103 325,62 266,62C187,62 158,125 158,217l0,267l-88,0l0,-283C70,32 161,-11 237,-11C323,-11 375,40 397,79l2,0l5,-79l78,0C479,38 478,82 478,133z"/>
+<glyph unicode="v" horiz-adv-x="481" d="M13,484l184,-484l84,0l190,484l-92,0l-94,-271C269,168 255,128 244,88l-3,0C231,128 218,168 202,213l-95,271z"/>
+<glyph unicode="x" horiz-adv-x="463" d="M16,484l164,-237l-172,-247l97,0l70,109C194,138 210,164 226,193l2,0C245,164 261,137 280,109l72,-109l99,0l-169,250l165,234l-96,0l-67,-103C267,355 251,330 235,302l-2,0C217,329 202,353 183,380l-69,104z"/>
+<glyph unicode="y" horiz-adv-x="471" d="M9,484l178,-446C192,27 194,20 194,15C194,10 191,3 187,-6C166,-51 137,-85 113,-104C87,-126 58,-140 36,-147l22,-73C80,-216 122,-201 166,-164C226,-111 269,-27 332,139l132,345l-93,0l-96,-284C263,165 253,128 244,99l-2,0C234,128 222,166 210,198l-105,286z"/>
+<glyph unicode="z" horiz-adv-x="428" d="M18,0l392,0l0,70l-282,0l0,2C150,96 169,121 190,148l216,281l0,55l-368,0l0,-70l262,0l0,-2C278,386 258,363 236,336l-218,-285z"/>
+</font>
+
+	<g>
+	<rect y="1.152" fill="#AAAAAA" stroke="#000000" width="256" height="36.887"/>
+	<text transform="matrix(1 0 0 1 27.7441 23.7046)" font-family="'MyriadPro-Regular'" font-size="14">Enter protected mode</text>
+</g>
+<g>
+	<rect y="45.642" fill="#AAAAAA" stroke="#000000" width="256" height="43.62"/>
+	<text transform="matrix(1 0 0 1 27.7441 71.5605)" font-family="'MyriadPro-Regular'" font-size="14">non-coherent HT enumeration</text>
+</g>
+<g>
+	<rect y="98.359" fill="#AAAAAA" stroke="#000000" width="256" height="60.15"/>
+	<text transform="matrix(1 0 0 1 27.7441 132.5435)" font-family="'MyriadPro-Regular'" font-size="14">coherent HT initialization</text>
+</g>
+<g>
+	<rect y="165.983" fill="#AAAAAA" stroke="#000000" width="256" height="68.421"/>
+	<text transform="matrix(1 0 0 1 27.7441 204.3022)" font-family="'MyriadPro-Regular'" font-size="14">Fallback / Normal?</text>
+</g>
+<g>
+	<rect y="243.893" fill="#AAAAAA" stroke="#000000" width="256" height="69.173"/>
+	<text transform="matrix(1 0 0 1 27.7441 282.5879)" font-family="'MyriadPro-Regular'" font-size="14">RAM initialization</text>
+</g>
+<g>
+	<rect y="410.747" fill="#AAAAAA" stroke="#000000" width="256" height="52.632"/>
+	<text transform="matrix(1 0 0 1 27.7441 432.7725)"><tspan x="0" y="0" font-family="'MyriadPro-Regular'" font-size="14">Create external tables (coreboot table,</tspan><tspan x="0" y="16.8" font-family="'MyriadPro-Regular'" font-size="14">ACPI, MP, PIRQ, DMI)</tspan></text>
+</g>
+<g>
+	<rect y="323.526" fill="#AAAAAA" stroke="#000000" width="256" height="77.443"/>
+	<text transform="matrix(1 0 0 1 27.7441 339.3154)"><tspan x="0" y="0" font-family="'MyriadPro-Regular'" font-size="14">Resource Allocation (PCI, PCIe, I2C, SIO, </tspan><tspan x="0" y="16.8" font-family="'MyriadPro-Regular'" font-size="14">CPU, mainboard...)</tspan></text>
+	<rect x="27.744" y="362.248" fill="#BCBCBC" width="228.256" height="38.722"/>
+</g>
+<g>
+	<rect y="473.781" fill="#AAAAAA" stroke="#000000" width="256" height="80.076"/>
+	<text transform="matrix(1 0 0 1 27.7441 497.4658)" font-family="'MyriadPro-Regular'" font-size="14">ELF / Payload Loader</text>
+	<rect x="27.744" y="507.993" fill="#BCBCBC" width="228.256" height="45.864"/>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,31.246 130.359,46.62 132.854,44.7
+									132.027,51.206 131.201,57.711 124.701,56.845 118.201,55.98 120.608,54.127 110.178,33.439								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,57.636 132.228,59.101 133.828,45.178 133.062,44.181							"/>
+							<polygon fill="#231F20" points="131.152,57.643 132.28,59.108 118.41,57.093 117.644,56.096							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,81.246 130.359,96.62 132.854,94.7
+									132.027,101.206 131.201,107.711 124.701,106.845 118.201,105.98 120.608,104.127 110.178,83.439								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,107.636 132.228,109.101 133.828,95.178 133.062,94.181							"/>
+							<polygon fill="#231F20" points="131.152,107.643 132.28,109.108 118.41,107.093 117.644,106.096							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,151.586 130.359,166.961 132.854,165.041
+									132.027,171.546 131.201,178.052 124.701,177.186 118.201,176.321 120.608,174.468 110.178,153.78								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,177.977 132.228,179.442 133.828,165.519 133.062,164.522							"/>
+							<polygon fill="#231F20" points="131.152,177.983 132.28,179.449 118.41,177.434 117.644,176.437							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,227.013 130.359,242.387 132.854,240.467
+									132.027,246.973 131.201,253.478 124.701,252.612 118.201,251.747 120.608,249.894 110.178,229.207								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,253.403 132.228,254.868 133.828,240.945 133.062,239.948							"/>
+							<polygon fill="#231F20" points="131.152,253.41 132.28,254.875 118.41,252.86 117.644,251.863							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,303.013 130.359,318.388 132.854,316.468
+									132.027,322.973 131.201,329.479 124.701,328.612 118.201,327.747 120.607,325.895 110.178,305.207								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,329.404 132.228,330.868 133.829,316.945 133.062,315.948							"/>
+							<polygon fill="#231F20" points="131.152,329.41 132.28,330.876 118.41,328.86 117.643,327.864							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,395.872 130.359,411.247 132.854,409.327
+									132.027,415.833 131.201,422.338 124.701,421.473 118.201,420.606 120.608,418.754 110.178,398.066								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,422.264 132.228,423.728 133.828,409.805 133.062,408.808							"/>
+							<polygon fill="#231F20" points="131.152,422.27 132.28,423.735 118.41,421.72 117.644,420.724							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<g>
+	<g>
+		<g>
+			<g>
+				<g>
+					<g>
+						<g>
+							<g>
+								<polygon fill="#FFFFFF" stroke="#231F20" stroke-width="0.3876" points="113.028,452.152 130.359,467.528 132.854,465.608
+									132.027,472.113 131.201,478.619 124.701,477.753 118.201,476.888 120.607,475.035 110.178,454.347								"/>
+							</g>
+							<polygon fill="#231F20" points="131.101,478.545 132.228,480.009 133.829,466.085 133.062,465.089							"/>
+							<polygon fill="#231F20" points="131.152,478.551 132.28,480.017 118.41,478.001 117.643,477.004							"/>
+						</g>
+					</g>
+				</g>
+			</g>
+		</g>
+	</g>
+</g>
+<text transform="matrix(1 0 0 1 59.3232 385.7627)" font-family="'MyriadPro-Regular'" font-size="14">Drivers</text>
+<text transform="matrix(1 0 0 1 55.564 535.3789)" font-family="'MyriadPro-Regular'" font-size="14">Linux, FILO, SeaBIOS, ...</text>
+</svg>

Documentation/community/code_of_conduct.md

@@ -0,0 +1,145 @@
+# Code of Conduct
+
+This code of conduct outlines our rules and expectations for everybody
+participating in the coreboot community.
+
+## coreboot community etiquette
+
+We have a friendly and productive atmosphere on our mailing lists,
+development / code review tools, IRC chat rooms and when we meet in
+person.  Our principles evolve around the following:
+
+* It's not the user's fault if something goes wrong.
+* Attempt collaboration before conflict.
+* People who intentionally insult others (users, developers, corporations,
+  other projects, or the coreboot project itself) will be dealt with. See
+  policy below.
+* We are dealing with hardware with lots of undocumented pitfalls. It is quite
+  possible that you did everything right, but coreboot or its tools still
+  won't work for you.
+
+Refrain from insulting anyone or the group they belong to. Remember that
+people might be sensitive to other things than you are.
+
+Most of our community members are not native English speakers, thus
+misunderstandings can (and do) happen. Assume that others are friendly
+and may have picked less-than-stellar wording by accident as long as
+you possibly can.
+
+## Reporting Issues
+
+If you have a grievance due to conduct in this community, we're sorry
+that you have had a bad experience, and we want to hear about it so
+we can resolve the situation.
+
+Please contact members of our arbitration team (listed below) promptly
+and directly, in person (if available) or by email: They will listen
+to you and react in a timely fashion.
+
+If you feel uncomfortable, please don't wait it out, ask for help,
+so we can work on setting things right.
+
+For transparency there is no alias or private mailing list address for
+you to reach out to, since we want to make sure that you know who will
+and who won't read your message.
+
+However since people might be on travel or otherwise be unavailable
+at times, please reach out to multiple persons at once, especially
+when using email.
+
+The team will treat your messages confidential as far as the law permits.
+For the purpose of knowing what law applies, the list provides the usual
+country of residence of each team member.
+
+## Unacceptable Behavior
+
+Unacceptable behaviors include: intimidating, harassing, abusive,
+discriminatory, derogatory or demeaning speech or actions by any
+participant in our community online, at all related events and in
+one-on-one communications carried out in the context of community
+business. Community event venues may be shared with members of the public;
+please be respectful to all patrons of these locations.
+
+Examples of behaviors we do not accept in our community:
+
+* harmful or prejudicial verbal or written comments related to gender,
+  sexual orientation, race, religion, disability;
+* inappropriate physical contact, and unwelcome sexual advances;
+* deliberate intimidation, stalking or following;
+* harassing photography or recording;
+* sustained disruption of talks or other events.
+
+Using this code of conduct aggressively against other people in the
+community might also be harassment. Be considerate when enforcing the code
+of conduct and always try to listen to both sides before passing judgment.
+
+## Consequences of Unacceptable Behavior
+
+Unacceptable behavior from any community member, including sponsors and
+those with decision-making authority, will not be tolerated.
+
+Anyone asked to stop unacceptable behavior is expected to comply
+immediately.
+
+If a community member engages in unacceptable behavior, the community
+organizers may take any action they deem appropriate, up to and including
+a temporary ban or permanent expulsion from the community without warning
+(and without refund in the case of a paid event).
+
+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.
+
+## Addressing Grievances
+
+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;
+sponsors; and other guests) to abide by this Code of Conduct in all
+community venues, online and in-person, as well as in all one-on-one
+communications pertaining to community business.
+
+## Contact info
+
+Our arbitration team currently consists of the following people
+* Daniel Pono Takamori <pono@sfconservancy.org> (USA)
+* 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/)

Documentation/community/conferences.md

@@ -0,0 +1,70 @@
+# Conferences
+The coreboot community is present at a number of conferences over the year,
+usually at [FOSDEM](https://fosdem.org), [OSFC](https://osfc.io), and the
+[Chaos Communication Congress](https://events.ccc.de/congress/).
+
+The kind of presence differs, but there's usually a booth or other kind of
+gathering where everybody is welcome to say hello and to learn more about
+coreboot.
+
+Depending on the nature of the conference, coreboot developers might bring
+their development kit with them and conduct development sessions.
+
+## Talks
+
+[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)
+([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
+
+[A tale of reusability in coreboot](https://www.youtube.com/watch?v=p2bnEYKBDpI) by Furquan Shaikh at OSFC 2018
+
+[How to enable AMD IOMMU in coreboot](https://www.youtube.com/watch?v=5JoEuh9qXx0) by Piotr Król at OSFC 2018
+
+[ARM Trusted Firmware for coreboot developers](https://www.youtube.com/watch?v=UC35q4OJg3k) by Julius Werner at OSFC 2018
+
+[Google Secure Microcontroller and Case Closed Debugging](https://www.youtube.com/watch?v=gC-lbMNmIsg) by Vadim Bendebury at OSFC 2018
+
+[coreboot rompayload](https://www.youtube.com/watch?v=ukSh1n7wjSA) by Ron Minnich at OSFC 2018
+
+[Run upstream coreboot on an ARM Chromebook](https://www.youtube.com/watch?v=N7_9okzPeHo) by Paul Menzel at ECC 2017
+
+[DDR3 memory initialization basics on Intel Sandybrige platforms](https://www.youtube.com/watch?v=h-Lkkg03Erk) by Patrick Rudolph at ECC 2017
+
+[Let's move SMM out of firmware and into the kernel](https://www.youtube.com/watch?v=6GEaw4msq6g) by Ron Minnich at ECC 2017
+
+[SINUMERIK – step ahead with coreboot](https://www.youtube.com/watch?v=tq4xSipCWEU) by Werner Zeh at ECC 2017
+
+[Booting UEFI-aware OS on coreboot enabled platform](https://www.youtube.com/watch?v=nt0BkqVUu3w) by Piotr Król and Kamil Wcisło at ECC 2017
+
+[Reverse engineering MT8173 PCM firmwares and ISA for a fully free bootchain](https://www.youtube.com/watch?v=9rKxfo7Gkqo) by Paul Kocialkowski at ECC 2017
+
+[A Tale of six motherboards, two BSDs and coreboot](https://www.youtube.com/watch?v=jlCGzML6zF8) by Piotr Kubaj at ECC 2017
+
+[Enabling TPM 2.0 on coreboot based devices](https://www.youtube.com/watch?v=Yjb9n5p3giI) by Piotr Król and Kamil Wcisło at ECC 2017
+
+[Porting coreboot to the HP ProLiant MicroServer Gen8](https://www.youtube.com/watch?v=BcmUSW2J53k) by Alexander Couzens and Felix Held at ECC 2017
+
+[Implementing coreboot in a ground breaking secure system: ORWL](https://www.youtube.com/watch?v=D4oQjcP6AVI) by Wim Vervoorn and Gerard Duynisveld at ECC 2017
+
+[Buying trustworthy hardware for federal agencies: How open source firmware saves the day](https://www.youtube.com/watch?v=DG_wfaw4zl0) by Carl-Daniel Hailfinger at ECC 2017
+
+[Verified Boot: Surviving in the Internet of Insecure Things: Randall Spangler](https://www.youtube.com/watch?v=4EvTcfcYfMY) by Randall Spangler at coreboot conference 2016
+
+[coreboot on RISC-V](https://www.youtube.com/watch?v=CDNIWuf1jAk) by Ron Minnich at coreboot conference 2016
+
+[An Open Source Embedded Controller](https://www.youtube.com/watch?v=hQb8waUBVSQ) by Bill Richardson at coreboot conference 2016
+
+[KB9012 EC Firmware Reverse Engineering](https://www.youtube.com/watch?v=B708jdCiW7o) by Paul Kocialkowski at coreboot conference 2016
+
+[coreboot on ARM](https://www.youtube.com/watch?v=z-KpAA4_afs) by Julius Werner at coreboot conference 2016
+
+[Intel FSP 2.0 overview](https://www.youtube.com/watch?v=uzfiTiP9dEM) by Giri Mudusuru and Vincent Zimmer at coreboot conference 2016
+
+[coreboot Internals](https://www.youtube.com/watch?v=7YUXr1MH9d4) by Aaron Durbin at coreboot conference 2016
+
+[Skylake FSP to coreboot integration overview](https://www.youtube.com/watch?v=SpL8LbquSVs) by Robbie Zhang at coreboot conference 2016
+
+[S3 implementation on Braswell](https://www.youtube.com/watch?v=GfwTijFnFl0) by Hannah Williams at coreboot conference 2016

Documentation/community/cross_project_collaboration.md

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

@@ -0,0 +1,39 @@
+# Our forums
+
+The coreboot community has various venues to help each other and discuss the
+direction of our project.
+
+## Mailing list
+
+The first address for coreboot related discussion is our mailing list.
+You can subscribe on its
+[information page](https://mail.coreboot.org/postorius/lists/coreboot.coreboot.org/) and
+read its
+[archives](https://mail.coreboot.org/hyperkitty/list/coreboot@coreboot.org/).
+
+## 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
+[Discord](https://discord.gg/JqT8NM5Zbg) presence. You can also find us on
+[OSF Slack](https://osfw.slack.com/), which has channels on many open source
+firmware related topics. Slack requires that people come from specific domains
+or are explicitly invited. To work around that, there's an
+[invite bot](https://slack.osfw.dev/) to let people in.
+
+## Fortnightly coreboot leadership meeting
+
+There's a leadership meeting held every 14 days (currently every other
+Wednesday at 10am Pacific Time, usually 18:00 UTC with some deviation
+possible due to daylight saving time related shifts). The meeting
+is open to everyone and provides a forum to discuss general coreboot
+topics, including community and technical matters that benefit from
+an official decision.
+
+We tried a whole lot of different tools, but so far the meetings worked
+best with [Google Meet](https://meet.google.com/pyt-newq-rbb),
+using [Google Docs](https://docs.google.com/document/d/1NRXqXcLBp5pFkHiJbrLdv3Spqh1Hu086HYkKrgKjeDQ/edit)
+for the agenda and meeting minutes. Neither the video conference nor
+the document require a Google account to participate, although editing
+access to the document is limited to adding comments - any desired
+agenda item added that way will be approved in time before the meeting.

Documentation/community/index.md

@@ -0,0 +1,11 @@
+# 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/language_style.md

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

Documentation/conf.py

@@ -0,0 +1,48 @@
+# 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
+
+import subprocess
+
+project = 'coreboot'
+copyright = 'CC-by 4.0 the coreboot project'
+author = 'the coreboot project'
+
+release = subprocess.check_output(('git', 'describe')).decode("utf-8")
+# The short X.Y version.
+version = release.split("-")[0]
+
+
+# -- 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'
+
+# 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'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+html_css_files = [
+    'theme_overrides.css',  # override wide tables in RTD theme
+]

Documentation/contributing/documentation_ideas.md

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

Documentation/contributing/gerrit_guidelines.md

@@ -0,0 +1,487 @@
+coreboot Gerrit Etiquette and Guidelines
+========================================
+
+The following rules are the requirements for behavior in the coreboot
+codebase in gerrit. These have mainly been unwritten rules up to this
+point, and should be familiar to most users who have been active in
+coreboot for a period of time. Following these rules will help reduce
+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.
+Don't just assume that it's okay, even if someone on IRC says it is.
+
+
+Summary
+-------
+These are the expectations for committing, reviewing, and submitting code
+into coreboot git and gerrit. While breaking individual rules may not have
+immediate consequences, the coreboot leadership may act on repeated or
+flagrant violations with or without notice.
+
+* Don't violate the licenses.
+* Let non-trivial patches sit in a review state for at least 24 hours
+before submission.
+* Try to coordinate with platform maintainers when making changes to
+platforms.
+* If you give a patch a -2, you are responsible for giving concrete
+recommendations for what could be changed to resolve the issue the patch
+addresses.
+* Don't modify other people's patches without their consent.
+* Be respectful to others when commenting.
+* Don’t submit patches that you know will break other platforms.
+
+
+More detail
+-----------
+* Don't violate the licenses. If you're submitting code that you didn't
+write yourself, make sure the license is compatible with the license of the
+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).
+
+* In general, patches should remain open for review for at least 24 hours
+since the last significant modification to the change. The purpose is to
+let coreboot developers around the world have a chance to review. Complex
+reworks, even if they don't change the purpose of the patch but the way
+it's implemented, should restart the wait period.
+
+* A change can go in without the wait period if its purpose is to fix
+a recently-introduced issue (build, boot or OS-level compatibility, not
+necessarily identified by coreboot.org facilities). Its commit message
+has to explain what change introduced the problem and the nature of
+the problem so that the emergency need becomes apparent. Avoid stating
+something like "fix build error" in the commit summary, describe what
+the commit does instead, just like any other commit. In addition, it is
+recommended to reference the commit that introduced the issue. The change
+itself should be as limited in scope and impact as possible to make it
+simple to assess the impact. Such a change can be merged early with 3
+Code-Review+2. For emergency fixes that affect a single project (SoC,
+mainboard, ...) it's _strongly_ recommended to get a review by somebody
+not involved with that project to ensure that the documentation of the
+issue is clear enough.
+
+* Trivial changes that deal with minor issues like inconsistencies in
+whitespace or spelling fixes that don't impact the final binary output
+also don't need to wait. Such changes should point out in their commit
+messages how the the author verified that the binary output is identical
+(e.g. a TIMELESS build for a given configuration). When submitting
+such changes early, the submitter must be different from the author
+and must document the intent in the Gerrit discussion, e.g. "landed the
+change early because it's trivial". Note that trivial fixes shouldn't
+necessarily be expedited: Just like they're not critical enough for
+things to go wrong because of them, they're not critical enough to
+require quick handling. This exception merely serves to acknowledge that
+a round-the-world review just isn't necessary for some types of changes.
+
+* As explained in our Code of Conduct, we try to assume the best of each
+other in this community. It's okay to discuss mistakes (e.g. isolated
+instances of non-trivial and non-critical changes submitted early) but
+try to keep such inquiries blameless. If a change leads to problems with
+our code, the focus should be on fixing the issue, not on assigning blame.
+
+* Do not +2 patches that you authored or own, even for something as trivial
+as whitespace fixes. When working on your own patches, it’s easy to
+overlook something like accidentally updating file permissions or git
+submodule commit IDs. Let someone else review the patch. An exception to
+this would be if two people worked in the patch together. If both +2 the
+patch, that is acceptable, as each is giving a +2 to the other's work.
+
+* Try to coordinate with platform maintainers and other significant
+contributors to the code when making changes to platforms. The platform
+maintainers are the users who initially pushed the code for that platform,
+as well as users who have made significant changes to a platform. To find
+out who maintains a piece of code, please use util/scripts/maintainers.go
+or refer to the original author of the code in git log.
+
+* If you give a patch a -2, you are responsible for giving concrete
+recommendations for what could be changed to resolve the issue the patch
+addresses. If you feel strongly that a patch should NEVER be merged, you
+are responsible for defending your position and listening to other points
+of view. Giving a -2 and walking away is not acceptable, and may cause your
+ -2 to be removed by the coreboot leadership after no less than a week. A
+ notification that the -2 will be removed unless there is a response will
+ be sent out at least 2 days before it is removed.
+
+* Don't modify other people's patches unless you have coordinated this with
+the owner of that patch. Not only is this considered rude, but your changes
+could be unintentionally lost. An exception to this would be for patches
+that have not been updated for more than 90 days. In that case, the patch
+can be taken over if the original author does not respond to requests for
+updates. Alternatively, a new patch can be pushed with the original
+content, and both patches should be updated to reference the other.
+
+* Be respectful to others when commenting on patches. Comments should
+be kept to the code, and should be kept in a polite tone. We are a
+worldwide community and English is a difficult language. Assume your
+colleagues are intelligent and do not intend disrespect. Resist the urge to
+retaliate against perceived verbal misconduct, such behavior is not
+conducive to getting patches merged.
+
+* Don’t submit code that you know will break other platforms. If your patch
+affects code that is used by other platforms, it should be compatible with
+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
+-----------------------------------
+These guidelines are less strict than the ones listed above. These are more
+of the “good idea” variety. You are requested to follow the below
+guidelines, but there will probably be no actual consequences if they’re
+not followed. That said, following the recommendations below will speed up
+review of your patches, and make the members of the community do less work.
+
+* Each patch should be kept to one logical change, which should be
+described in the title of the patch. Unrelated changes should be split out
+into separate patches. Fixing whitespace on a line you’re editing is
+reasonable. Fixing whitespace around the code you’re working on should be a
+separate ‘cleanup’ patch. Larger patches that touch several areas are fine,
+so long as they are one logical change. Adding new chips and doing code
+cleanup over wide areas are two examples of this.
+
+* Test your patches before submitting them to gerrit. It's also appreciated
+if you add a line to the commit message describing how the patch was
+tested. This prevents people from having to ask whether and how the patch
+was tested. Examples of this sort of comment would be ‘TEST=Built
+platform’ or ‘Tested by building and booting platform’.  Stating that the
+patch was not tested is also fine, although you might be asked to do some
+testing in cases where that would be reasonable.
+
+* Take advantage of the lint tools to make sure your patches don’t contain
+trivial mistakes. By running ‘make gitconfig’, the lint-stable tools are
+automatically put in place and will test your patches before they are
+committed. As a violation of these tools will cause the jenkins build test
+to fail, it’s to your advantage to test this before pushing to gerrit.
+
+* Don't submit patch trains longer than around 20 patches unless you
+understand how to manage long patch trains. Long patch trains can become
+difficult to handle and tie up the build servers for long periods of time
+if not managed well. Rebasing a patch train over and over as you fix
+earlier patches in the train can hide comments, and make people review the
+code multiple times to see if anything has changed between revisions. When
+pushing long patch trains, it is recommended to only push the full patch
+train once - the initial time, and only to rebase three or four patches at
+a time.
+
+* Run 'make what-jenkins-does' locally on patch trains before submitting.
+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
+```
+
+* 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
+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
+```
+
+* 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
+this is by marking in the commit message that it’s not ready until X. The
+commit message can be updated easily when it’s ready to be pushed.
+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
+```
+
+* 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
+```
+
+* Multiple push options can be combined:
+
+```Bash
+git push origin HEAD:refs/for/main%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
+request to fix spelling or 'trivial' issues, it’s generally easy to handle
+in gerrit’s built-in editor. If you do use the built-in editor, remember to
+get that change to your local copy before re-pushing. It's also acceptable
+to add fixes for these sorts of comments to another patch, but it's
+recommended that that patch be pushed to gerrit before the initial patch
+gets submitted.
+
+* Consider breaking up large individual patches into smaller patches
+grouped by areas. This makes the patches easier to review, but increases
+the number of patches. The way you want to handle this is a personal
+decision, as long as each patch is still one logical change.
+
+* If you have an interest in a particular area or mainboard, set yourself
+up as a ‘maintainer’ of that area by adding yourself to the MAINTAINERS
+file in the coreboot root directory. Eventually, this should automatically
+add you as a reviewer when an area that you’re listed as a maintainer is
+changed.
+
+* Submit mainboards that you’re working on to the board-status repo. This
+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.
+
+* Abandon patches that are no longer useful, or that you don’t intend to
+keep working on to get submitted.
+
+* Bring attention to patches that you would like reviewed. Add reviewers,
+ask for reviewers on IRC or even just rebase it against the current
+codebase to bring it to the top of the gerrit list. If you’re not sure who
+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
+patches. This will help to keep annoying requests to fix your commit
+message to a minimum.
+
+* If there have been comments or discussion on a patch, verify that the
+comments have been addressed before giving a +2. If you feel that a comment
+is invalid, please respond to that comment instead of just ignoring it.
+
+* Be conscientious when reviewing patches. As a reviewer who approves (+2)
+a patch, you are responsible for the patch and the effect it has on the
+codebase. In the event that the patch breaks things, you are expected to
+be actively involved in the cleanup effort. This means you shouldn’t +2 a
+patch just because you trust the author of a patch - Make sure you
+understand what the implications of a patch might be, or leave the review
+to others. Partial reviews, reviewing code style, for example, can be given
+a +1 instead of a +2. This also applies if you think the patch looks good,
+but may not have the experience to know if there may be unintended
+consequences.
+
+* If there is still ongoing discussion to a patch, try to wait for a
+conclusion to the discussion before submitting it to the tree. If you feel
+that someone is just bikeshedding, maybe just state that and give a time
+that the patch will be submitted if no new objections are raised.
+
+* When working with patch trains, for minor requests it’s acceptable to
+create a fix addressing a comment in another patch at the end of the patch
+train. This minimizes rebases of the patch train while still addressing the
+request. For major problems where the change doesn’t work as intended or
+breaks other platforms, the change really needs to go into the original
+patch.
+
+* When bringing in a patch from another git repo, update the original
+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.
+
+* Check if there's documentation that needs to be updated to remain current
+after your change. If there's no documentation for the part of coreboot
+you're working on, consider adding some.
+
+* When contributing a significant change to core parts of the code base (such
+as the boot state machine or the resource allocator), or when introducing
+a new way of doing something that you think is worthwhile to apply across
+the tree (e.g. board variants), please bring up your design on the [mailing
+list](../community/forums.md). When changing behavior substantially, an
+explanation of what changes and why may be useful to have, either in the
+commit message or, if the discussion of the subject matter needs way more
+space, in the documentation. Since "what we did in the past and why it isn't
+appropriate anymore" isn't the most useful reading several years down the road,
+such a description could be put into the release notes for the next version
+(that you can find in Documentation/releases/) where it will inform people
+now without cluttering up the regular documentation, and also gives a nice
+shout-out to your contribution by the next release.
+
+Expectations contributors should have
+-------------------------------------
+* Don't expect that people will review your patch unless you ask them to.
+Adding other people as reviewers is the easiest way. Asking for reviews for
+individual patches in the IRC channel, or by sending a direct request to an
+individual through your favorite messenger is usually the best way to get a
+patch reviewed quickly.
+
+* Don't expect that your patch will be submitted immediately after getting
+a +2. As stated previously, non-trivial patches should wait at least 24
+hours before being submitted. That said, if you feel that your patch or
+series of patches has been sitting longer than needed, you can ask for it
+to be submitted on IRC, or comment that it's ready for submission in the
+patch. This will move it to the top of the list where it's more likely to
+be noticed and acted upon.
+
+* Reviews are about the code. It's easy to take it personally when someone
+is criticising your code, but the whole idea is to get better code into our
+codebase. Again, this also applies in the other direction: review code,
+criticize code, but don’t make it personal.
+
+Gerrit user roles
+-----------------
+There are a few relevant roles a user can have on Gerrit:
+
+- The anonymous user can check out source code.
+- A registered user can also comment and give "+1" code reviews.
+- A reviewer can give "-1" and "+2" code reviews.
+- A core developer can also give "-2" (that is, blocking) code reviews
+  and submit changes.
+
+Anybody can register an account on our instance, using either an
+OpenID provider or OAuth through GitHub or Google.
+
+The reviewer group is still quite open: Any core developer can add
+registered users to that group and should do so once some activity
+(commits, code reviews, and so on) has demonstrated rough knowledge
+of how we handle things.
+
+A core developer should be sufficiently well established in the
+community so that they feel comfortable when submitting good patches,
+when asking for improvements to less good patches and reasonably
+uncomfortable when -2'ing patches. They're typically the go-to
+person for _some_ part of the coreboot tree and ideally listed as its
+maintainer in our MAINTAINERS registry. To become part of this group,
+a candidate developer who already demonstrated proficiency with the
+code base as a reviewer should be nominated, by themselves or others,
+at the regular [coreboot leadership meetings](../community/forums.md)
+where a decision is made.
+
+Core developers are expected to use their privileges for the good of the
+project, which includes any of their own coreboot development but also beyond
+that. They should make sure that [ready changes] don't linger around needlessly
+just because their authors aren't well-connected with core developers but
+submit them if they went through review and generally look reasonable. They're
+also expected to help clean-up breakage as a result of their submissions.
+
+Since the project expects some activity by core developers, long-term absence
+(as in "years") can lead to removal from the group, which can easily be
+reversed after they come back.
+
+Requests for clarification and suggestions for updates to these guidelines
+should be sent to the coreboot mailing list at <coreboot@coreboot.org>.
+
+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/contributing/git_commit_messages.md

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

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

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

@@ -0,0 +1,246 @@
+# Project Ideas
+
+This section collects ideas to improve coreboot and related projects and
+should serve as a pool of ideas for people who want to enter the field
+of firmware development but need some guidance what to work on.
+
+These tasks can be adopted as part of programs like Google Summer of
+Code or by motivated individuals outside such programs.
+
+Each entry should outline what would be done, the benefit it brings
+to the project, the pre-requisites, both in knowledge and parts. They
+should also list people interested in supporting people who want to work
+on them - since we started building this list for Google Summer of Code,
+we'll adopt its term for those people and call them mentors.
+
+The requirements for each project aim for productive work on the project,
+but it's always possible to learn them "on the job". If you have any
+doubt if you can bring yourself up to speed in a required time frame
+(e.g. for GSoC), feel free to ask in the community or the mentors listed
+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,
+which is a bad experience when trying to build coreboot the first time.
+
+Provide packages/installers of our compiler toolchain for Linux distros,
+Windows, Mac OS. For Windows, this should also include the environment
+(shell, make, ...). A student doesn't have to cover _all_ platforms, but
+pick a set of systems that match their interest and knowledge and lay
+out a plan on how to do this.
+
+The scripts to generate these packages should be usable on a Linux
+host, as that's what we're using for our automated build testing system
+that we could extend to provide current packages going forward. This
+might include automating some virtualization system (eg. QEMU or CrosVM) for
+non-Linux builds or Docker for different Linux distributions.
+
+### Requirements
+* coreboot knowledge: Should know how to build coreboot images and where
+  the compiler comes into play in our build system.
+* other knowledge: Should know how packages or installers for their
+  target OS work. Knowledge of the GCC build system is a big plus
+* hardware requirements: Nothing special
+
+### Mentors
+
+## Support Power9/Power8 in coreboot
+There are some basic PPC64 stubs in coreboot, and there's open hardware
+in TALOS2 and its family. While they already have fully open source
+firmware, coreboot support adds a unified story for minimal firmware
+across architectures.
+
+### Requirements
+* coreboot knowledge: Should be familiar with making chipset level
+  changes to the code.
+* other knowledge: A general idea of the Power architecture, the more,
+  the better
+* hardware requirements: QEMU Power bring-up exists, and even if it
+  probably needs to be fixed up, that shouldn't be an exceedingly large
+  task. For everything else, access to real Power8/9 hardware and recovery
+  tools (e.g. for external flashing) is required.
+
+### Mentors
+* Timothy Pearson <tpearson@raptorengineering.com>
+
+## 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.
+
+Since this is a bit of a catch-all idea, an application to GSoC should pick a
+combination of payload and architecture to support.
+
+### Requirements
+* coreboot knowledge: Should know the general boot flow in coreboot
+* other knowledge: It helps to be familiar with the architecture you want to
+  work on.
+* hardware requirements: Much of this can be done in QEMU or other emulators,
+  but the ability to test on real hardware is a plus.
+
+### Mentors
+* Simon Glass <sjg@chromium.org> for U-Boot payload projects
+
+## Fully support building coreboot with the Clang compiler
+Most coreboot code is written in C, and it would be useful to support
+a second compiler suite in addition to gcc. Clang is another popular
+compiler suite and the build system generally supports building coreboot
+with it, but firmware is a rather special situation and we need to
+adjust coreboot and Clang some more to get usable binaries out of that
+combination.
+
+The goal would be to get the emulation targets to boot reliably first,
+but also to support real hardware. If you don't have hardware around,
+you likely will find willing testers for devices they own and work from
+their bug reports.
+
+### Requirements
+* coreboot knowledge: Have a general concept of the build system
+* Clang knowledge: It may be necessary to apply minor modifications to Clang
+  itself, but at least there will be Clang-specific compiler options etc to
+  adapt, so some idea how compilers work and how to modify their behavior is
+  helpful.
+* hardware requirements: If you have your own hardware that is already
+  supported by coreboot that can be a good test target, but you will debug
+  other people's hardware, too.
+* debugging experience: It helps if you know how to get the most out of a bug
+  report, generate theories, build patches to test them and figure out what's
+  going on from the resulting logs.
+
+### Mentors
+
+## Extend Ghidra to support analysis of firmware images
+[Ghidra](https://ghidra-sre.org) is a recently released cross-platform
+disassembler and decompiler that is extensible through plugins. Make it
+useful for firmware related work: Automatically parse formats (eg. by
+integrating UEFITool, cbfstool, decompressors), automatically identify
+16/32/64bit code on x86/amd64, etc.
+
+This has been done in 2019 with [some neat
+features](https://github.com/al3xtjames/ghidra-firmware-utils) being
+developed, but it may be possible to expand support for all kinds of firmware
+analyses.
+
+## Learn hardware behavior from I/O and memory access logs
+[SerialICE](https://www.serialice.com) is a tool to trace the behavior of
+executable code like firmware images. One result of that is a long log file
+containing the accesses to hardware resources.
+
+It would be useful to have a tool that assists a developer-analyst in deriving
+knowledge about hardware from such logs. This likely can't be entirely
+automatic, but a tool that finds patterns and can propagate them across the
+log (incrementially raising the log from plain I/O accesses to a high-level
+description of driver behavior) would be of great use.
+
+This is a research-heavy project.
+
+### Requirements
+* Driver knowledge: Somebody working on this should be familiar with
+  how hardware works (eg. MMIO based register access, index/data port
+  accesses) and how to read data sheets.
+* Machine Learning: ML techniques may be useful to find structure in traces.
+
+### Mentors
+* Ron Minnich <rminnich@google.com>
+
+## Libpayload based memtest payload
+[Memtest86+](https://www.memtest.org/) has some limitations: first and
+foremost it only works on x86, while it can print to serial console the
+GUI only works in legacy VGA mode.
+
+This project would involve porting the memtest suite to libpayload and
+build a payload around it.
+
+### Requirements
+* coreboot knowledge: Should know how to build coreboot images and
+  include payloads.
+* other knowledge: Knowledge on how dram works is a plus.
+* hardware requirements: Initial work can happen on qemu targets,
+  being able to test on coreboot supported hardware is a plus.
+
+### Mentors
+* TODO
+
+## Fix POST code handling
+coreboot supports writing POST codes to I/O port 80.
+There are various Kconfigs that deal with POST codes, which don't have
+effect on most platforms.
+The code to send POST codes is scattered in C and Assembly, some use
+functions, some use macros and others simply use the `outb` instruction.
+The POST codes are duplicated between stages and aren't documented properly.
+
+
+Tasks:
+* Guard Kconfigs with a *depends on* to only show on supported platforms
+* Remove duplicated Kconfigs
+* Replace `outb(0x80, ...)` with calls to `post_code(...)`
+* Update Documentation/POSTCODES
+* Use defines from console/post_codes.h where possible
+* Drop duplicated POST codes
+* Make use of all possible 255 values
+
+### Requirements
+* knowledge in the coreboot build system and the concept of stages
+* other knowledge: Little experience with C and x86 Assembly
+* hardware requirements: Nothing special
+
+### Mentors
+* Patrick Rudolph <patrick.rudolph@9elements.com>
+* Christian Walter <christian.walter@9elements.com>
+
+## Board status replacement
+The [Board status page](https://coreboot.org/status/board-status.html) allows
+to see last working commit of a board. The page is generated by a cron job
+that runs on a huge git repository.
+
+Build an open source replacement written in Golang using existing tools
+and libraries, consisting of a backend, a frontend and client side
+scripts. The backend should connect to an SQL database with can be
+controlled using a RESTful API. The RESTful API should have basic authentication
+for management tasks and new board status uploads.
+
+At least one older test result should be kept in the database.
+
+The frontend should use established UI libraries or frameworks (for example
+Angular) to display the current board status, that is if it's working or not
+and some details provided with the last test. If a board isn't working the last
+working commit (if any) should be shown in addition to the broken one.
+
+Provide a script/tool that allows to:
+1. Push mainboard details from coreboot master CI
+2. Push mainboard test results from authenticated users containing
+   * working
+   * commit hash
+   * bootlog (if any)
+   * dmesg (if it's booting)
+   * timestamps (if it's booting)
+   * coreboot config
+
+### Requirements
+* coreboot knowledge: Non-technical, needed to perform requirements analysis
+* software knowledge: Golang, SQL for the backend, JS for the frontend
+
+### Mentors
+* Patrick Rudolph <patrick.rudolph@9elements.com>
+* Christian Walter <christian.walter@9elements.com>

Documentation/corebootBuildingGuide.tex

@@ -0,0 +1,671 @@
+%
+% This document is released under the GPL
+% Initially written by Stefan Reinauer, <stepan@coresystems.de>
+%
+
+\documentclass[titlepage,12pt]{article}
+\usepackage{a4}
+\usepackage{graphicx}
+\usepackage{epsfig}
+\usepackage{epstopdf}
+\usepackage{url}
+\usepackage{color}
+% \usepackage{geometry}
+\usepackage[pdftex]{hyperref}
+% \usepackage{makeidx}
+% \makeindex
+% \geometry{left=2cm,right=2cm,top=2cm,bottom=2cm}
+
+\hypersetup{
+    urlbordercolor={1 1 1},
+    menubordercolor={1 1 1},
+    linkbordercolor={1 1 1},
+    colorlinks=false,
+    % pdfpagemode=None,  % PDF-Viewer starts without TOC
+    % pdfstartview=FitH,
+    pdftitle={coreboot Porting Guide},
+    pdfauthor={Zheng Bao},
+    pdfsubject={coreboot configuration and build process},
+    pdfkeywords={coreboot, AMD, configuration, Build}
+}
+
+\setlength{\parindent}{0pt}
+\setlength{\hoffset}{0pt}
+
+\title{coreboot from Scratch}
+\author{Stefan Reinauer $<$stepan@coresystems.de$>$\and Zheng Bao $<$zheng.bao@amd.com$>$}
+\date{Dec 4th, 2013}
+
+\begin{document}
+
+\maketitle
+
+\thispagestyle{empty}
+
+\tableofcontents
+
+\newpage
+
+\section{What is coreboot}
+coreboot aims to replace the normal BIOS found on x86, AMD64, PPC,
+Alpha, and other machines with a Linux kernel that can boot Linux from a cold
+start. The startup code of an average coreboot port is about 500 lines of
+assembly and 5000 lines of C. It executes 16 instructions to get into 32bit
+protected mode and then performs DRAM and other hardware initializations
+required before Linux can take over.
+
+The projects primary motivation initially was maintenance of large
+clusters. Not surprisingly interest and contributions have come from
+people with varying backgrounds.  Nowadays a large and growing number of
+Systems can be booted with coreboot, including embedded systems,
+Desktop PCs and Servers.
+
+This document is used to build, modify, and port the coreboot code
+base on the AMD platform.
+
+
+\section{Changes}
+
+ \begin{itemize}
+ \item 2013/12/20 Add Git, Gerrit, toolchains building.
+ \item 2009/04/19 replace LinuxBIOS with coreboot
+ \item 2004/06/02 url and language fixes from Ken Fuchs $<$kfuchs@winternet.com$>$
+ \item 2004/02/10 ACPI and option ROM updates
+ \item 2003/11/18 initial release
+ \end{itemize}
+
+%
+% Build Requirements
+%
+
+\section{Build Requirements}
+To build coreboot for AMD64 from the sources you need a recent Linux.
+SUSE Linux 11.2, CentOS release 6.3, Fedora Core 16, Cygwin, FreeBSD,
+NetBSD are known to work fine.
+
+To build the toolchain, you need following host compilers:
+
+ \begin{itemize}
+ \item GNUtar
+ \item GNUpatch
+ \item GNUmake
+ \item GCC
+ \item binutils
+ \item bison
+ \item flex
+ \item m4
+ \item wget
+ \end{itemize}
+
+Besides the tools above, after the toolchains are built, you also need the following
+tools to build the source.
+
+ \begin{itemize}
+ \item git: Get the source code from repository
+ \item libncurses-dev (or ncursesw, ncurses, curses, pdcursesw, pdcurses): for menuconfig
+ \item python: Optional for gdb.
+ \item perl: Optional for gdb.
+ \end{itemize}
+
+%
+% Getting coreboot
+%
+
+\section{Getting coreboot}
+The latest coreboot sources are available via GIT.
+For users who doesn't need to change and commit the code:
+{ \small
+\begin{verbatim}
+$ git clone https://review.coreboot.org/coreboot
+\end{verbatim}
+}
+For developers, you need to get a gerrit account which you can register
+at \url{https://review.coreboot.org}. Please refer section ~\ref{sec:gerrit}
+{ \small
+\begin{verbatim}
+$ git clone ssh://<username>@review.coreboot.org:29418/coreboot
+$ git clone https://[<username>:<password>@]review.coreboot.org/coreboot.git
+\end{verbatim}
+}
+
+Checks out a sub-repository in the 3rdparty directory.
+{ \small
+\begin{verbatim}
+$ git submodule update --init --checkout
+\end{verbatim}
+}
+
+%
+% Building the toolchain
+%
+
+\section{Building the toolchain}
+coreboot recommends and guarantees the toolchain integrated with coreboot.
+Linux distributions usually modify their compilers in ways incompatible with coreboot.
+
+{ \small
+\begin{verbatim}
+$ cd coreboot
+$ make crossgcc
+\end{verbatim}
+}
+
+or
+
+{ \small
+\begin{verbatim}
+$ cd util/crossgcc
+$ buildgcc
+\end{verbatim}
+}
+
+The buildgcc will try to get packages from website. You need to make sure you can
+get access the internet. Or you can get the source.tar.gz and put it in util/crossgcc/tarballs.
+
+{ \small
+\textcolor{blue} {Welcome to the} \textcolor{red} {coreboot} \textcolor{blue} {cross toolchain builder v1.23 (September 20th, 2013)}
+
+Target arch is now i386-elf
+
+Will skip GDB ... ok
+
+Downloading tar balls ...
+
+ * gmp-5.1.2.tar.bz2 (cached)
+
+ * mpfr-3.1.2.tar.bz2 (cached)
+
+ * mpc-1.0.1.tar.gz (cached)
+
+ * libelf-0.8.13.tar.gz (cached)
+
+ * gcc-4.7.3.tar.bz2 (cached)
+
+ * binutils-2.23.2.tar.bz2 (cached)
+
+ * acpica-unix-20130626.tar.gz (cached)
+
+Downloaded tar balls ... \textcolor {green}{ok}
+
+Unpacking and patching ...
+
+ * gmp-5.1.2.tar.bz2
+
+ * mpfr-3.1.2.tar.bz2
+
+ * mpc-1.0.1.tar.gz
+
+ * libelf-0.8.13.tar.gz
+
+ * gcc-4.7.3.tar.bz2
+
+ * binutils-2.23.2.tar.bz2
+
+   o binutils-2.23.2\_arv7a.patch
+
+   o binutils-2.23.2\_no-bfd-doc.patch
+
+ * acpica-unix-20130626.tar.gz
+
+Unpacked and patched ... \textcolor {green}{ok}
+
+Building GMP 5.1.2 ... \textcolor {green}{ok}
+
+Building MPFR 3.1.2 ... \textcolor {green}{ok}
+
+Building MPC 1.0.1 ... \textcolor {green}{ok}
+
+Building libelf 0.8.13 ... \textcolor {green}{ok}
+
+Building binutils 2.23.2 ... \textcolor {green}{ok}
+
+Building GCC 4.7.3 ...  ok
+
+Skipping Expat (Python scripting not enabled)
+
+Skipping Python (Python scripting not enabled)
+
+Skipping GDB (GDB support not enabled)
+
+Building IASL 20130626 ... \textcolor {green}{ok}
+
+Cleaning up... \textcolor {green}{ok}
+
+\textcolor {green}{You can now run your i386-elf cross toolchain from /home/baozheng/x86/coreboot-gerrit/util/crossgcc/xgcc.}
+}
+If you are lucky, you can get toolchains located in util/crossgcc/xgcc.
+
+%
+% Build coreboot
+%
+
+\section{Building coreboot}
+\subsection{Build main module of coreboot}
+{ \small
+\begin{verbatim}
+$ cd coreboot
+$ make menuconfig
+.config - coreboot v4.0-4895-gc5025a4-dirty Configuration
++------------------------ coreboot Configuration -------------------------+
+|  Arrow keys navigate the menu.  <Enter> selects submenus --->.          |
+|  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes, |
+|  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </> |
+|  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < >       |
+| +---------------------------------------------------------------------+ |
+| |        General setup  --->                                          | |
+| |        Mainboard  --->                                              | |
+| |        Architecture (x86)  --->                                     | |
+| |        Chipset  --->                                                | |
+| |        Devices  --->                                                | |
+| |        VGA BIOS  --->                                               | |
+| |        Display  --->                                                | |
+| |        PXE ROM  --->                                                | |
+| |        Generic Drivers  --->                                        | |
+| |        Console  --->                                                | |
+| |    [ ] Relocatable Modules                                          | |
+| |        System tables  --->                                          | |
+| |        Payload  --->                                                | |
+| |        Debugging  --->                                              | |
+| |    ---                                                              | |
+| +----v(+)-------------------------------------------------------------+ |
++-------------------------------------------------------------------------+
+|                    <Select>    < Exit >    < Help >                     |
++-------------------------------------------------------------------------
+\end{verbatim}
+}
+Select Mainboard -$>$ Mainboard Vendor -$>$ AMD
+                 -$>$ Mainboard Model  -$>$ Olive Hill
+
+Then save, exit and run make.
+
+{ \small
+\begin{verbatim}
+$ make
+\end{verbatim}
+}
+The built image, coreboot.rom, is located at folder build.
+
+\section{Programming coreboot to flash memory}
+The image resulting from a coreboot build can be directly programmed to
+a flash device, either using an external flash programmers, e.g., Dediprog SF100, or by using the
+Linux flash utility, flashrom.
+
+
+\subsection{Add modules and payload}
+
+\subsubsection{VGA BIOS}
+There is a big Chance that you need to get a VGA BIOS.
+{ \small
+\begin{verbatim}
+.config - coreboot v4.0 Configuration
+------------------------------------------------------------------------------
++-------------------------------- VGA BIOS --------------------------------+
+|  Arrow keys navigate the menu.  <Enter> selects submenus --->.           |
+|  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes,  |
+|  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </>  |
+|  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < > module |
+| +----------------------------------------------------------------------+ |
+| |    [*] Add a VGA BIOS image                                          | |
+| |    (vgabios.bin) VGA BIOS path and filename                          | |
+| |    (1002,1306) VGA device PCI IDs                                    | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| +----------------------------------------------------------------------+ |
++--------------------------------------------------------------------------+
+|                     <Select>    < Exit >    < Help >                     |
++--------------------------------------------------------------------------+
+\end{verbatim}
+}
+Select VGA BIOS. ``The VGA device PCI IDs'' should be the same as your device. Get the
+Option ROM from Vendor's website.
+
+\subsubsection{Payload}
+coreboot in itself is "only" minimal code for initializing a mainboard
+with peripherals. After the initialization, it jumps to a payload.
+
+Currently, SeaBIOS is the most widely used payload. The best way to integrate SeaBIOS
+is setting it in menuconfig.
+{ \small
+\begin{verbatim}
++------------------------------- Payload ---------------------------------+
+|  Arrow keys navigate the menu.  <Enter> selects submenus --->.           |
+|  Highlighted letters are hotkeys.  Pressing <Y> includes, <N> excludes,  |
+|  <M> modularizes features.  Press <Esc><Esc> to exit, <?> for Help, </>  |
+|  for Search.  Legend: [*] built-in  [ ] excluded  <M> module  < > module |
+| +----------------------------------------------------------------------+ |
+| |        Add a payload (SeaBIOS)  --->                                 | |
+| |        SeaBIOS version (1.7.2.1)  --->                               | |
+| |    [*] Use LZMA compression for payloads (NEW)                       | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| |                                                                      | |
+| +----------------------------------------------------------------------+ |
++--------------------------------------------------------------------------+
+|                     <Select>    < Exit >    < Help >                     |
++--------------------------------------------------------------------------+
+\end{verbatim}
+The script in Makefile will automatically checkout, config, build the SeaBIOS source,
+and integrat the binary into the final image.
+
+%
+% Working with Git
+%
+
+\section{Working with Git}
+\subsection{Configuration of Git}
+Inside the checkout you should install a commit-msg hook that adds a
+Change-Id into commit messages, which uniquely identifies the logical
+change in Gerrit even across multiple iterations of the commit. The
+hook only needs to be installed once per clone, and installation can
+be done with:
+{ \small
+\begin{verbatim}
+$ cd coreboot
+$ cp ./util/gitconfig/* .git/hooks
+\end{verbatim}
+}
+configure your name and email in git.
+{ \small
+\begin{verbatim}
+$ git config --global user.name "Your Name Comes Here"
+$ git config --global user.email your.email@example.com'
+\end{verbatim}
+}
+The name~\ref{user name} and email~\ref{Contact Information} should be the same the settings in gerrit.
+Otherwise you can not push you code to community.
+
+Then run the following command once, to tell git that by default you
+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
+\end{verbatim}
+}
+
+The above configurations for git has been integrated into Makefile. You can run
+{ \small
+\begin{verbatim}
+$ make gitconfig
+\end{verbatim}
+}
+
+\subsection{Work flow}
+
+It is recommended that you make a new branch when you start to work, not pushing changes to main.
+{ \small
+\begin{verbatim}
+$ git checkout main -b mybranch
+\end{verbatim}
+}
+After you have done your changes, run:
+{ \small
+\begin{verbatim}
+$ git add file_need_to_submit.c
+$ git commit -m "my first change."
+\end{verbatim}
+}
+
+% Does anyone have a better word to describe the philosophy of splitting changes to patches?
+You need to realize that the changes you have made should be well divided into
+several commits. Each of them has one and only one meaning. You could use git rebase -i to
+split, squash, remove, rewrite you comment.
+
+Here is an example of a well-formatted commit message:
+
+{ \small
+\begin{verbatim}
+examplecomponent: Refactor duplicated setup into a function
+
+Setting up the demo device correctly requires the exact same register
+values to be written into each of the PCI device functions. Moving the
+writes into a function allows also otherexamplecomponent to use them.
+
+Signed-off-by: Joe Hacker <joe@hacker.email>
+\end{verbatim}
+}
+
+Then you can push the code.
+{ \small
+\begin{verbatim}
+$ git push
+\end{verbatim}
+}
+
+You can go to the ~\ref{sec:gerrit} gerrit to see if your changes is successfully pushed.
+
+Often it might happen that the patch you sent for approval is not good
+enough from the first attempt. Gerrit and git make it easy to track
+patch evolution during the review process until patches meet our
+quality standards and are ready for approval.
+
+You can easily modify a patch sent to gerrit by you or even by someone
+else. Just apply it locally using one of the possible ways to do it,
+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.
+
+%
+% Working with Gerrit
+%
+
+\section{Working with Gerrit}
+\label{sec:gerrit}
+If you are a coreboot user, not planning to contribute, you can skip this section.
+\subsection{Get gerrit account}
+You need to get an OpenID first. Currently Google account give you an OpenID. It means, if you have a gmail account, you have an OpenID. You can try to signed in.
+click \url{https://review.coreboot.org}
+
+%\includegraphics[width=6.00in,height=1.00in]{gerrit_signin.png}
+{ \small
+\begin{verbatim}
++-----------------------------------------------------------+
+|All    Projects  Documentation           Register  Sign In |
+|Open Merged   Abandoned                                    |
+|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       |
+|                                                           |
+|                                                  Next ->  |
+|Press '?' to view keyboard shortcuts | Powered by Gerrit   |
++-----------------------------------------------------------+
+\end{verbatim}
+}
+Click ``Sign In'', You will get
+
+%\includegraphics[width=6.00in,height=4.00in]{openid.png}
+
+You will be redirected to Google to get logging in.
+
+% \includegraphics[width=6.00in,height=1.50in]{login.png}
+{ \small
+\begin{verbatim}
+Sign In to Gerrit Code Review at review.coreboot.org
++--------------------------------------------------+
++--------------------------------------------------+
+[] Remember me
+Sign In Cancel
+Sign in with a Google Account
+Sign in with a Yahoo! ID
+What is OpenID?
+
+OpenID provides secure single-sign-on, without revealing your passwords to this website.
+
+There are many OpenID providers available. You may already be member of one!
+
+Get OpenID
+\end{verbatim}
+}
+
+\subsection{Configure account}
+Click the dropdown button near the user name and click ``Settings''
+
+% \includegraphics[width=6.00in,height=4.00in]{settings}
+% \epsfig{figure=keystroke_left}
+% \epstopdf {file=settings.eps}
+% \epsfig{file=settings.eps}
+
+\label{user name} In ``profile'' section, type the user name for git. This probably can be changed only once.
+{ \small
+\begin{verbatim}
+Profile               Username      zbao
+Preferences           Full Name     Zheng Bao
+Watched Projects      Email Address zheng.bao@amd.com
+Contact Information   Registered    Jun 28, 2011 4:33 PM
+SSH Public Keys       Account ID    1000034
+HTTP Password
+Identities
+Groups
+\end{verbatim}
+}
+
+\label{Contact Information} In ``Contact Information'', enter you full name and your Email, which should be configured in your .gitconfig
+{ \small
+\begin{verbatim}
+      Full Name  __________________________________
+Preferred Email  ______________   Registered Email
+
+Save Changes
+\end{verbatim}
+}
+
+In ``SSH Public Keys'' section, upload your public key.
+{ \small
+\begin{verbatim}
+Status  Algorithm   Key Comment
+
+Delete
+Add SSH Public Key
+ > How to Generate an SSH Key
++--------------------------+
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
+|                          |
++--------------------------+
+clear       Add  Close
+\end{verbatim}
+}
+
+Click ``Add Key ...''
+Go back to you linux command line and type:
+{ \small
+\begin{verbatim}
+$ ssh-keygen
+Generating public/private rsa key pair.
+Enter file in which to save the key (/home/zhengbao/.ssh/id_rsa):
+Enter passphrase (empty for no passphrase):
+Enter same passphrase again:
+Your identification has been saved in /home/zhengbao/.ssh/id_rsa.
+Your public key has been saved in /home/zhengbao/.ssh/id_rsa.pub.
+The key fingerprint is:
+xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx:xx zhengb@host.domain
+The key's randomart image is:
++--[ RSA 2048]----+
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
+|                 |
++-----------------+
+\end{verbatim}
+}
+The data in ~/.ssh/id\_rsa.pub is your public key. Copy them to the box in the page of ``SSH Public Keys'' and click add.
+
+In ``HTTP Password'' section, click button ``Generate Password''. You will get the password for http checkout.
+{ \small
+\begin{verbatim}
+Username    XXX
+Password    XXXXXXXXXXXX
+
+Generate Password   Clear Password
+
+\end{verbatim}
+}
+
+\subsection{Reviewing Changes}
+For each listed changes in Gerrit, you can review, comment, evaluate,
+cherry-pick, and even re-submit them. For you own patches, only you can
+abandon them. Click in the file and commit message, you can add in-line comment.
+
+%
+% 14 Glossary
+%
+
+\section{Glossary}
+\begin{itemize}
+\item payload
+
+coreboot only cares about low level machine initialization, but also has
+very simple mechanisms to boot a file either from FLASHROM or IDE. That
+file, possibly a Linux Kernel, a boot loader or Etherboot, are called
+payload, since it is the first software executed that does not cope with
+pure initialization.
+
+\item flash device
+
+Flash devices are commonly used in all different computers since unlike
+ROMs they can be electronically erased and reprogrammed.
+
+\item Gerrit
+
+Gerrit is a web based code review system, facilitating online code
+reviews for projects using the Git version control system.
+
+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
+than requiring all approved changes to be merged in by hand by the
+project maintainer. This functionality enables a more centralized
+usage of Git.
+
+\end{itemize}
+
+\newpage
+
+%
+% 14 Bibliography
+%
+
+\section{Bibliography}
+\subsection{Additional Papers on coreboot}
+
+\begin{itemize}
+ \item
+ \textit{\url{https://www.coreboot.org/Documentation}}
+\end{itemize}
+
+\subsection {Links}
+
+\begin{itemize}
+ \item Etherboot: \textit{\url{http://www.etherboot.org/}}
+ \item OpenBIOS: \textit{\url{http://www.openbios.org/}}
+ \item Flashrom: \textit{\url{http://www.flashrom.org/}}
+ \item Seabios: \textit{\url{http://www.seabios.org/}}
+\end{itemize}
+
+
+\end{document}

Documentation/coreboot_logo.svg

@@ -0,0 +1,40 @@
+<?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

@@ -0,0 +1,128 @@
+# Distributions
+
+coreboot doesn't provide binaries but provides a toolbox that others can use
+to build boot firmware for all kinds of purposes. These third-parties can be
+broadly separated in two groups: Those shipping coreboot on their hardware,
+and those providing after-market firmware to extend the usefulness of devices.
+
+
+## Hardware shipping with coreboot
+
+### ChromeOS Devices
+
+All ChromeOS devices ([Chromebooks](https://chromebookdb.com/), Chromeboxes,
+Chromebit, etc) released from 2012 onward use coreboot for their main system
+firmware. Additionally, starting with the 2013 Chromebook Pixel, the firmware
+running on the Embedded Controller (EC) – a small microcontroller which provides
+functions like battery management, keyboard support, and sensor interfacing –
+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
+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
+
+[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.
+
+### Purism
+
+[Purism](https://www.puri.sm) sells laptops with a focus on user privacy and
+security; part of that effort is to minimize the amount of proprietary and/or
+binary code. Their laptops ship with a blob-free OS and coreboot firmware
+with a neutralized Intel Management Engine (ME) and SeaBIOS as the payload.
+
+### 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
+
+[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.
+
+Contributions are welcome,
+[this document](https://docs.dasharo.com/ways-you-can-help-us/).
+
+### Heads
+
+[Heads](http://osresearch.net) is an open source custom firmware and OS
+configuration for laptops and servers that aims to provide slightly better
+physical security and protection for data on the system. Unlike
+[Tails](https://tails.boum.org/), which aims to be a stateless OS that leaves
+no trace on the computer of its presence, Heads is intended for the case where
+you need to store data and state on the computer.
+
+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
+laptops like the Lenovo Thinkpad X230. It uses upstream coreboot, an easy
+to use payload like SeaBIOS and Intel's latest microcode update.
+
+It simplifies installation and includes compact documentation. Skulls also
+enables easy switching to [Heads](#heads) and back.

Documentation/documentation_license.md

@@ -0,0 +1,164 @@
+# coreboot documentation license
+
+Files under Documentation/ are licensed under CC-BY 4.0 terms, printed below.
+As an exception, files under Documentation/ with a history older than 2017-05-24
+might be under different licenses (but should be cleared up ASAP).
+
+## Attribution 4.0 International
+
+Creative Commons Corporation (“Creative Commons”) is not a law firm and does not provide legal services or legal advice. Distribution of Creative Commons public licenses does not create a lawyer-client or other relationship. Creative Commons makes its licenses and related information available on an “as-is” basis. Creative Commons gives no warranties regarding its licenses, any material licensed under their terms and conditions, or any related information. Creative Commons disclaims all liability for damages resulting from their use to the fullest extent possible.
+
+### Using Creative Commons Public Licenses
+
+Creative Commons public licenses provide a standard set of terms and conditions that creators and other rights holders may use to share original works of authorship and other material subject to copyright and certain other rights specified in the public license below. The following considerations are for informational purposes only, are not exhaustive, and do not form part of our licenses.
+
+* __Considerations for licensors:__ Our public licenses are intended for use by those authorized to give the public permission to use material in ways otherwise restricted by copyright and certain other rights. Our licenses are irrevocable. Licensors should read and understand the terms and conditions of the license they choose before applying it. Licensors should also secure all rights necessary before applying our licenses so that the public can reuse the material as expected. Licensors should clearly mark any material not subject to the license. This includes other CC-licensed material, or material used under an exception or limitation to copyright. [More considerations for licensors](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensors).
+
+* __Considerations for the public:__ By using one of our public licenses, a licensor grants the public permission to use the licensed material under specified terms and conditions. If the licensor’s permission is not necessary for any reason–for example, because of any applicable exception or limitation to copyright–then that use is not regulated by the license. Our licenses grant only permissions under copyright and certain other rights that a licensor has authority to grant. Use of the licensed material may still be restricted for other reasons, including because others have copyright or other rights in the material. A licensor may make special requests, such as asking that all changes be marked or described. Although not required by our licenses, you are encouraged to respect those requests where reasonable. [More considerations for the public](http://wiki.creativecommons.org/Considerations_for_licensors_and_licensees#Considerations_for_licensees).
+
+## Creative Commons Attribution 4.0 International Public License
+
+By exercising the Licensed Rights (defined below), You accept and agree to be bound by the terms and conditions of this Creative Commons Attribution 4.0 International Public License ("Public License"). To the extent this Public License may be interpreted as a contract, You are granted the Licensed Rights in consideration of Your acceptance of these terms and conditions, and the Licensor grants You such rights in consideration of benefits the Licensor receives from making the Licensed Material available under these terms and conditions.
+
+### Section 1 – Definitions.
+
+a. __Adapted Material__ means material subject to Copyright and Similar Rights that is derived from or based upon the Licensed Material and in which the Licensed Material is translated, altered, arranged, transformed, or otherwise modified in a manner requiring permission under the Copyright and Similar Rights held by the Licensor. For purposes of this Public License, where the Licensed Material is a musical work, performance, or sound recording, Adapted Material is always produced where the Licensed Material is synched in timed relation with a moving image.
+
+b. __Adapter's License__ means the license You apply to Your Copyright and Similar Rights in Your contributions to Adapted Material in accordance with the terms and conditions of this Public License.
+
+c. __Copyright and Similar Rights__ means copyright and/or similar rights closely related to copyright including, without limitation, performance, broadcast, sound recording, and Sui Generis Database Rights, without regard to how the rights are labeled or categorized. For purposes of this Public License, the rights specified in Section 2(b)(1)-(2) are not Copyright and Similar Rights.
+
+d. __Effective Technological Measures__ means those measures that, in the absence of proper authority, may not be circumvented under laws fulfilling obligations under Article 11 of the WIPO Copyright Treaty adopted on December 20, 1996, and/or similar international agreements.
+
+e. __Exceptions and Limitations__ means fair use, fair dealing, and/or any other exception or limitation to Copyright and Similar Rights that applies to Your use of the Licensed Material.
+
+f. __Licensed Material__ means the artistic or literary work, database, or other material to which the Licensor applied this Public License.
+
+g. __Licensed Rights__ means the rights granted to You subject to the terms and conditions of this Public License, which are limited to all Copyright and Similar Rights that apply to Your use of the Licensed Material and that the Licensor has authority to license.
+
+h. __Licensor__ means the individual(s) or entity(ies) granting rights under this Public License.
+
+i. __Share__ means to provide material to the public by any means or process that requires permission under the Licensed Rights, such as reproduction, public display, public performance, distribution, dissemination, communication, or importation, and to make material available to the public including in ways that members of the public may access the material from a place and at a time individually chosen by them.
+
+j. __Sui Generis Database Rights__ means rights other than copyright resulting from Directive 96/9/EC of the European Parliament and of the Council of 11 March 1996 on the legal protection of databases, as amended and/or succeeded, as well as other essentially equivalent rights anywhere in the world.
+
+k. __You__ means the individual or entity exercising the Licensed Rights under this Public License. Your has a corresponding meaning.
+
+### Section 2 – Scope.
+
+a. ___License grant.___
+
+   1. Subject to the terms and conditions of this Public License, the Licensor hereby grants You a worldwide, royalty-free, non-sublicensable, non-exclusive, irrevocable license to exercise the Licensed Rights in the Licensed Material to:
+
+       A. reproduce and Share the Licensed Material, in whole or in part; and
+
+       B. produce, reproduce, and Share Adapted Material.
+
+   2. __Exceptions and Limitations.__ For the avoidance of doubt, where Exceptions and Limitations apply to Your use, this Public License does not apply, and You do not need to comply with its terms and conditions.
+
+   3. __Term.__ The term of this Public License is specified in Section 6(a).
+
+   4. __Media and formats; technical modifications allowed.__ The Licensor authorizes You to exercise the Licensed Rights in all media and formats whether now known or hereafter created, and to make technical modifications necessary to do so. The Licensor waives and/or agrees not to assert any right or authority to forbid You from making technical modifications necessary to exercise the Licensed Rights, including technical modifications necessary to circumvent Effective Technological Measures. For purposes of this Public License, simply making modifications authorized by this Section 2(a)(4) never produces Adapted Material.
+
+   5. __Downstream recipients.__
+
+       A. __Offer from the Licensor – Licensed Material.__ Every recipient of the Licensed Material automatically receives an offer from the Licensor to exercise the Licensed Rights under the terms and conditions of this Public License.
+
+       B. __No downstream restrictions.__ You may not offer or impose any additional or different terms or conditions on, or apply any Effective Technological Measures to, the Licensed Material if doing so restricts exercise of the Licensed Rights by any recipient of the Licensed Material.
+
+   6. __No endorsement.__ Nothing in this Public License constitutes or may be construed as permission to assert or imply that You are, or that Your use of the Licensed Material is, connected with, or sponsored, endorsed, or granted official status by, the Licensor or others designated to receive attribution as provided in Section 3(a)(1)(A)(i).
+
+b. ___Other rights.___
+
+   1. Moral rights, such as the right of integrity, are not licensed under this Public License, nor are publicity, privacy, and/or other similar personality rights; however, to the extent possible, the Licensor waives and/or agrees not to assert any such rights held by the Licensor to the limited extent necessary to allow You to exercise the Licensed Rights, but not otherwise.
+
+   2. Patent and trademark rights are not licensed under this Public License.
+
+   3. To the extent possible, the Licensor waives any right to collect royalties from You for the exercise of the Licensed Rights, whether directly or through a collecting society under any voluntary or waivable statutory or compulsory licensing scheme. In all other cases the Licensor expressly reserves any right to collect such royalties.
+
+### Section 3 – License Conditions.
+
+Your exercise of the Licensed Rights is expressly made subject to the following conditions.
+
+a. ___Attribution.___
+
+   1. If You Share the Licensed Material (including in modified form), You must:
+
+       A. retain the following if it is supplied by the Licensor with the Licensed Material:
+
+         i. identification of the creator(s) of the Licensed Material and any others designated to receive attribution, in any reasonable manner requested by the Licensor (including by pseudonym if designated);
+
+         ii. a copyright notice;
+
+         iii. a notice that refers to this Public License;
+
+         iv. a notice that refers to the disclaimer of warranties;
+
+         v. a URI or hyperlink to the Licensed Material to the extent reasonably practicable;
+
+       B. indicate if You modified the Licensed Material and retain an indication of any previous modifications; and
+
+       C. indicate the Licensed Material is licensed under this Public License, and include the text of, or the URI or hyperlink to, this Public License.
+
+   2. You may satisfy the conditions in Section 3(a)(1) in any reasonable manner based on the medium, means, and context in which You Share the Licensed Material. For example, it may be reasonable to satisfy the conditions by providing a URI or hyperlink to a resource that includes the required information.
+
+   3. If requested by the Licensor, You must remove any of the information required by Section 3(a)(1)(A) to the extent reasonably practicable.
+
+   4. If You Share Adapted Material You produce, the Adapter's License You apply must not prevent recipients of the Adapted Material from complying with this Public License.
+
+### Section 4 – Sui Generis Database Rights.
+
+Where the Licensed Rights include Sui Generis Database Rights that apply to Your use of the Licensed Material:
+
+a. for the avoidance of doubt, Section 2(a)(1) grants You the right to extract, reuse, reproduce, and Share all or a substantial portion of the contents of the database;
+
+b. if You include all or a substantial portion of the database contents in a database in which You have Sui Generis Database Rights, then the database in which You have Sui Generis Database Rights (but not its individual contents) is Adapted Material; and
+
+c. You must comply with the conditions in Section 3(a) if You Share all or a substantial portion of the contents of the database.
+
+For the avoidance of doubt, this Section 4 supplements and does not replace Your obligations under this Public License where the Licensed Rights include other Copyright and Similar Rights.
+
+### Section 5 – Disclaimer of Warranties and Limitation of Liability.
+
+a. __Unless otherwise separately undertaken by the Licensor, to the extent possible, the Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable. Where disclaimers of warranties are not allowed in full or in part, this disclaimer may not apply to You.__
+
+b. __To the extent possible, in no event will the Licensor be liable to You on any legal theory (including, without limitation, negligence) or otherwise for any direct, special, indirect, incidental, consequential, punitive, exemplary, or other losses, costs, expenses, or damages arising out of this Public License or use of the Licensed Material, even if the Licensor has been advised of the possibility of such losses, costs, expenses, or damages. Where a limitation of liability is not allowed in full or in part, this limitation may not apply to You.__
+
+c. The disclaimer of warranties and limitation of liability provided above shall be interpreted in a manner that, to the extent possible, most closely approximates an absolute disclaimer and waiver of all liability.
+
+### Section 6 – Term and Termination.
+
+a. This Public License applies for the term of the Copyright and Similar Rights licensed here. However, if You fail to comply with this Public License, then Your rights under this Public License terminate automatically.
+
+b. Where Your right to use the Licensed Material has terminated under Section 6(a), it reinstates:
+
+   1. automatically as of the date the violation is cured, provided it is cured within 30 days of Your discovery of the violation; or
+
+   2. upon express reinstatement by the Licensor.
+
+   For the avoidance of doubt, this Section 6(b) does not affect any right the Licensor may have to seek remedies for Your violations of this Public License.
+
+c. For the avoidance of doubt, the Licensor may also offer the Licensed Material under separate terms or conditions or stop distributing the Licensed Material at any time; however, doing so will not terminate this Public License.
+
+d. Sections 1, 5, 6, 7, and 8 survive termination of this Public License.
+
+### Section 7 – Other Terms and Conditions.
+
+a. The Licensor shall not be bound by any additional or different terms or conditions communicated by You unless expressly agreed.
+
+b. Any arrangements, understandings, or agreements regarding the Licensed Material not stated herein are separate from and independent of the terms and conditions of this Public License.
+
+### Section 8 – Interpretation.
+
+a. For the avoidance of doubt, this Public License does not, and shall not be interpreted to, reduce, limit, restrict, or impose conditions on any use of the Licensed Material that could lawfully be made without permission under this Public License.
+
+b. To the extent possible, if any provision of this Public License is deemed unenforceable, it shall be automatically reformed to the minimum extent necessary to make it enforceable. If the provision cannot be reformed, it shall be severed from this Public License without affecting the enforceability of the remaining terms and conditions.
+
+c. No term or condition of this Public License will be waived and no failure to comply consented to unless expressly agreed to by the Licensor.
+
+d. Nothing in this Public License constitutes or may be interpreted as a limitation upon, or waiver of, any privileges and immunities that apply to the Licensor or You, including from the legal processes of any jurisdiction or authority.
+
+> Creative Commons is not a party to its public licenses. Notwithstanding, Creative Commons may elect to apply one of its public licenses to material it publishes and in those instances will be considered the “Licensor.” Except for the limited purpose of indicating that material is shared under a Creative Commons public license or as otherwise permitted by the Creative Commons policies published at [creativecommons.org/policies](http://creativecommons.org/policies), Creative Commons does not authorize the use of the trademark “Creative Commons” or any other trademark or logo of Creative Commons without its prior written consent including, without limitation, in connection with any unauthorized modifications to any of its public licenses or any other arrangements, understandings, or agreements concerning use of licensed material. For the avoidance of doubt, this paragraph does not form part of the public licenses.
+>
+> Creative Commons may be contacted at creativecommons.org
+

Documentation/drivers/acpi_fan_control.md

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

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

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

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

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

Documentation/drivers/dt_entries.md

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

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

@@ -0,0 +1,33 @@
+# Platform independent drivers documentation
+
+The drivers can be found in `src/drivers`. They are intended for onboard
+and plugin devices, significantly reducing integration complexity and
+they allow to easily reuse existing code across platforms.
+
+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>
+```

Documentation/drivers/ipmi_bt.md

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

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

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

Documentation/drivers/smmstore.md

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

Documentation/drivers/smmstorev2.md

@@ -0,0 +1,256 @@
+# SMM based flash storage driver Version 2
+
+This documents the API exposed by the x86 system management based
+storage driver.
+
+## SMMSTOREv2
+
+SMMSTOREv2 is a [SMM] mediated driver to read from, write to and erase
+a predefined region in flash. It can be enabled by setting
+`CONFIG_SMMSTORE=y` and `CONFIG_SMMSTORE_V2=y` in menuconfig.
+
+This can be used by the OS or the payload to implement persistent
+storage to hold for instance configuration data, without needing to
+implement a (platform specific) storage driver in the payload itself.
+
+### Storage size and alignment
+
+SMMSTORE version 2 requires a minimum alignment of 64 KiB, which should
+be supported by all flash chips. Not having to perform read-modify-write
+operations is desired, as it reduces complexity and potential for bugs.
+
+This can be used by a FTW (FaultTolerantWrite) implementation that uses
+at least two regions in an A/B update scheme. The FTW implementation in
+edk2 uses three different regions in the store:
+
+- The variable store
+- The FTW spare block
+- The FTW working block
+
+All regions must be block-aligned, and the FTW spare size must be larger
+than that of the variable store. FTW working block can be much smaller.
+With 64 KiB as block size, the minimum size of the FTW-enabled store is:
+
+- The variable store: 1 block = 64 KiB
+- The FTW spare block: 2 blocks = 2 * 64 KiB
+- The FTW working block: 1 block = 64 KiB
+
+Therefore, the minimum size for edk2 FTW is 4 blocks, or 256 KiB.
+
+## API
+
+The API provides read and write access to an unformatted block storage.
+
+### Storage region
+
+By default SMMSTOREv2 will operate on a separate FMAP region called
+`SMMSTORE`. The default generated FMAP will include such a region. On
+systems with a locked FMAP, e.g. in an existing vboot setup with a
+locked RO region, the option exists to add a cbfsfile called `smm_store`
+in the `RW_LEGACY` (if CHROMEOS) or in the `COREBOOT` FMAP regions. It
+is recommended for new builds using a handcrafted FMD that intend to
+make use of SMMSTORE to include a sufficiently large `SMMSTORE` FMAP
+region. It is mandatory to align the `SMMSTORE` region to 64KiB for
+compatibility with the largest flash erase operation.
+
+When a default generated FMAP is used, the size of the FMAP region is
+equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least 64 KiB.
+To support a fault tolerant write mechanism, at least a multiple of
+this size is recommended.
+
+### Communication buffer
+
+To prevent malicious ring0 code to access arbitrary memory locations,
+SMMSTOREv2 uses a communication buffer in CBMEM/HOB for all transfers.
+This buffer has to be at least 64 KiB in size and must be installed
+before calling any of the SMMSTORE read or write operations. Usually,
+coreboot will install this buffer to transfer data between ring0 and
+the [SMM] handler.
+
+In order to get the communication buffer address, the payload or OS
+has to read the coreboot table with tag `0x0039`, containing:
+
+```C
+struct lb_smmstorev2 {
+	uint32_t tag;
+	uint32_t size;
+	uint32_t num_blocks;		/* Number of 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. */
+};
+```
+
+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
+called *blocks*. Every block is at least the size of 64KiB to support
+arbitrary NOR flash erase ops. A payload or OS must make no further
+assumptions about the block or communication buffer size.
+
+### Generating the SMI
+
+SMMSTOREv2 is called via an SMI, which is generated via a write to the
+IO port defined in the smi_cmd entry of the FADT ACPI table. `%al`
+contains `APM_CNT_SMMSTORE=0xed` and is written to the smi_cmd IO
+port. `%ah` contains the SMMSTOREv2 command. `%ebx` contains the
+parameter buffer to the SMMSTOREv2 command.
+
+### Return values
+
+If a command succeeds, SMMSTOREv2 will return with
+`SMMSTORE_RET_SUCCESS=0` in `%eax`. On failure SMMSTORE will return
+`SMMSTORE_RET_FAILURE=1`. For unsupported SMMSTORE commands
+`SMMSTORE_REG_UNSUPPORTED=2` is returned.
+
+**NOTE 1**: The caller **must** check the return value and should make
+no assumption on the returned data if `%eax` does not contain
+`SMMSTORE_RET_SUCCESS`.
+
+**NOTE 2**: If the SMI returns without changing `%ax`, it can be assumed
+that the SMMSTOREv2 feature is not installed.
+
+### Calling arguments
+
+SMMSTOREv2 supports 3 subcommands that are passed via `%ah`, the
+additional calling arguments are passed via `%ebx`.
+
+**NOTE**: The size of the struct entries are in the native word size of
+smihandler. This means 32 bits in almost all cases.
+
+#### - SMMSTORE_CMD_INIT_DEPRECATED = 4
+
+Unused, returns SMMSTORE_REG_UNSUPPORTED.
+
+#### - SMMSTORE_CMD_RAW_READ = 5
+
+SMMSTOREv2 allows reading arbitrary data. It is up to the caller to
+initialize the store with meaningful data before using it.
+
+The additional parameter buffer `%ebx` contains a pointer to the
+following struct:
+
+```C
+struct smmstore_params_raw_read {
+	uint32_t bufsize;
+	uint32_t bufoffset;
+	uint32_t block_id;
+} __packed;
+```
+
+INPUT:
+- `bufsize`: Size of data to read within the communication buffer
+- `bufoffset`: Offset within the communication buffer
+- `block_id`: Block to read from
+
+#### - SMMSTORE_CMD_RAW_WRITE = 6
+
+SMMSTOREv2 allows writing arbitrary data. It is up to the caller to
+erase a block before writing it.
+
+The additional parameter buffer `%ebx` contains a pointer to
+the following struct:
+
+```C
+struct smmstore_params_raw_write {
+        uint32_t bufsize;
+        uint32_t bufoffset;
+        uint32_t block_id;
+} __packed;
+```
+
+INPUT:
+- `bufsize`: Size of data to write within the communication buffer
+- `bufoffset`: Offset within the communication buffer
+- `block_id`: Block to write to
+
+#### - SMMSTORE_CMD_RAW_CLEAR = 7
+
+SMMSTOREv2 allows clearing blocks. A cleared block will read as `0xff`.
+By providing multiple blocks the caller can implement a fault tolerant
+write mechanism. It is up to the caller to clear blocks before writing
+to them.
+
+
+```C
+struct smmstore_params_raw_clear {
+	uint32_t block_id;
+} __packed;
+```
+
+INPUT:
+- `block_id`: Block to erase
+
+#### Security
+
+Pointers provided by the payload or OS are checked to not overlap with
+SMM. This protects the SMM handler from being compromised.
+
+As all information is exchanged using the communication buffer and
+coreboot tables, there's no risk that a malicious application capable
+of issuing SMIs could extract arbitrary data or modify the currently
+running kernel.
+
+## 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)
+
+Note that this differs significantly from coreboot's implementation.
+
+[SMM]: ../security/smm.md

Documentation/drivers/soundwire.md

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

Documentation/endverbatim.tex

@@ -0,0 +1 @@
+\end{verbatim}

Documentation/external_docs.md

@@ -0,0 +1,137 @@
+# 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/gcov.txt

@@ -0,0 +1,227 @@
+This patch contains our local modifications for gcov-io.h and libgcov.c.
+The file gcov-iov.h is taken from a gcc build (produced at compile
+time). The file gcov-io.c is unchanged.
+
+--- gcc-4.7.2/gcc/gcov-io.h	2011-12-04 10:27:19.000000000 -0800
++++ coreboot/src/lib/gcov-io.h	2013-01-12 16:45:57.000000000 -0800
+@@ -163,6 +163,24 @@
+ #ifndef GCC_GCOV_IO_H
+ #define GCC_GCOV_IO_H
+ 
++#ifdef __COREBOOT__
++#define GCOV_LINKAGE /* nothing */
++/* We need the definitions for
++    BITS_PER_UNIT and
++    LONG_LONG_TYPE_SIZE
++   They are defined in gcc/defaults.h and gcc/config/<arch_depend_files>
++   (like, gcc/config/i386/i386.h). And it can be overridden by setting
++   in build scripts. Here I hardcoded the value for x86. */
++#define BITS_PER_UNIT 8
++#define LONG_LONG_TYPE_SIZE 64
++
++/* There are many gcc_assertions. Set the value to 1 if we want a warning
++   message if the assertion fails.  */
++#ifndef ENABLE_ASSERT_CHECKING
++#define ENABLE_ASSERT_CHECKING 1
++#endif
++#endif /* __COREBOOT__ */
++
+ #if IN_LIBGCOV
+ /* About the target */
+ 
+@@ -232,7 +250,9 @@
+    is not also used in a DSO.  */
+ #if IN_LIBGCOV
+ 
++#ifndef __COREBOOT__
+ #include "tconfig.h"
++#endif /* __COREBOOT__ */
+ 
+ #define gcov_var __gcov_var
+ #define gcov_open __gcov_open
+@@ -455,8 +475,10 @@
+ /* Register a new object file module.  */
+ extern void __gcov_init (struct gcov_info *) ATTRIBUTE_HIDDEN;
+ 
++#ifndef __COREBOOT__
+ /* Called before fork, to avoid double counting.  */
+ extern void __gcov_flush (void) ATTRIBUTE_HIDDEN;
++#endif
+ 
+ /* The merge function that just sums the counters.  */
+ extern void __gcov_merge_add (gcov_type *, unsigned) ATTRIBUTE_HIDDEN;
+--- gcc-4.7.2/libgcc/libgcov.c	2012-01-11 10:50:21.000000000 -0800
++++ coreboot/src/lib/libgcov.c	2013-01-16 09:45:11.000000000 -0800
+@@ -25,12 +25,41 @@
+ see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see
+ <http://www.gnu.org/licenses/>.  */
+ 
++#define __COREBOOT__
++#ifdef __COREBOOT__
++#include <stdlib.h>
++#include <string.h>
++#include <console/console.h>
++#include <assert.h>
++typedef s32 pid_t;
++#define gcc_assert(x) ASSERT(x)
++#define fprintf(file, x...) printk(BIOS_ERR, x)
++#define alloca(size)   __builtin_alloca (size)
++#include "gcov-glue.c"
++
++/* Define MACROs to be used by coreboot compilation.  */
++# define L_gcov
++# define L_gcov_interval_profiler
++# define L_gcov_pow2_profiler
++# define L_gcov_one_value_profiler
++# define L_gcov_indirect_call_profiler
++# define L_gcov_average_profiler
++# define L_gcov_ior_profiler
++
++# define HAVE_CC_TLS 0
++# define __GCOV_KERNEL__
++
++# define IN_LIBGCOV 1
++# define IN_GCOV 0
++#else /* __COREBOOT__ */
+ #include "tconfig.h"
+ #include "tsystem.h"
+ #include "coretypes.h"
+ #include "tm.h"
+ #include "libgcc_tm.h"
++#endif /* __COREBOOT__ */
+ 
++#ifndef __COREBOOT__
+ #if defined(inhibit_libc)
+ #define IN_LIBGCOV (-1)
+ #else
+@@ -41,6 +70,7 @@
+ #define GCOV_LINKAGE /* nothing */
+ #endif
+ #endif
++#endif /* __COREBOOT__ */
+ #include "gcov-io.h"
+ 
+ #if defined(inhibit_libc)
+@@ -68,12 +98,17 @@
+ 
+ #else
+ 
++#ifndef __COREBOOT__
+ #include <string.h>
+ #if GCOV_LOCKED
+ #include <fcntl.h>
+ #include <errno.h>
+ #include <sys/stat.h>
+ #endif
++#else
++void __gcov_merge_add(gcov_type *counters  __attribute__ ((unused)),
++			unsigned n_counters __attribute__ ((unused))) {}
++#endif /* __COREBOOT__ */
+ 
+ #ifdef L_gcov
+ #include "gcov-io.c"
+@@ -99,6 +134,10 @@
+ static int
+ create_file_directory (char *filename)
+ {
++#ifdef __COREBOOT__
++  (void) filename;
++  return 0;
++#else
+ #if !defined(TARGET_POSIX_IO) && !defined(_WIN32)
+   (void) filename;
+   return -1;
+@@ -137,6 +176,7 @@
+       };
+   return 0;
+ #endif
++#endif
+ }
+ 
+ static struct gcov_fn_buffer *
+@@ -279,7 +319,7 @@
+   struct gcov_ctr_summary *cs_ptr;
+   const struct gcov_ctr_info *ci_ptr;
+   unsigned t_ix;
+-  int f_ix;
++  int f_ix = 0;
+   gcov_unsigned_t c_num;
+   const char *gcov_prefix;
+   int gcov_prefix_strip = 0;
+@@ -329,6 +369,7 @@
+ 	}
+     }
+ 
++#ifndef __COREBOOT__
+   {
+     /* Check if the level of dirs to strip off specified. */
+     char *tmp = getenv("GCOV_PREFIX_STRIP");
+@@ -352,6 +393,7 @@
+ 	prefix_length--;
+     }
+   else
++#endif
+     prefix_length = 0;
+ 
+   /* If no prefix was specified and a prefix stip, then we assume
+@@ -696,8 +738,10 @@
+       if (filename_length > gcov_max_filename)
+         gcov_max_filename = filename_length;
+ 
++#ifndef __COREBOOT__
+       if (!gcov_list)
+ 	atexit (gcov_exit);
++#endif
+ 
+       info->next = gcov_list;
+       gcov_list = info;
+@@ -767,14 +811,15 @@
+ 
+ #ifdef L_gcov_merge_single
+ /* The profile merging function for choosing the most common value.
+-   It is given an array COUNTERS of N_COUNTERS old counters and it
+-   reads the same number of counters from the gcov file.  The counters
+-   are split into 3-tuples where the members of the tuple have
+-   meanings:
+-
+-   -- the stored candidate on the most common value of the measured entity
+-   -- counter
+-   -- total number of evaluations of the value  */
++ * It is given an array COUNTERS of N_COUNTERS old counters and it
++ * reads the same number of counters from the gcov file.  The counters
++ * are split into 3-tuples where the members of the tuple have
++ * meanings:
++ *
++ * -- the stored candidate on the most common value of the measured entity
++ * -- counter
++ * -- total number of evaluations of the value
++ */
+ void
+ __gcov_merge_single (gcov_type *counters, unsigned n_counters)
+ {
+@@ -805,15 +850,16 @@
+ 
+ #ifdef L_gcov_merge_delta
+ /* The profile merging function for choosing the most common
+-   difference between two consecutive evaluations of the value.  It is
+-   given an array COUNTERS of N_COUNTERS old counters and it reads the
+-   same number of counters from the gcov file.  The counters are split
+-   into 4-tuples where the members of the tuple have meanings:
+-
+-   -- the last value of the measured entity
+-   -- the stored candidate on the most common difference
+-   -- counter
+-   -- total number of evaluations of the value  */
++ * difference between two consecutive evaluations of the value.  It is
++ * given an array COUNTERS of N_COUNTERS old counters and it reads the
++ * same number of counters from the gcov file.  The counters are split
++ * into 4-tuples where the members of the tuple have meanings:
++ *
++ * -- the last value of the measured entity
++ * -- the stored candidate on the most common difference
++ * -- counter
++ * -- total number of evaluations of the value
++ */
+ void
+ __gcov_merge_delta (gcov_type *counters, unsigned n_counters)
+ {

Documentation/getting_started/architecture.md

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

Documentation/getting_started/build_system.md

@@ -0,0 +1,101 @@
+# The coreboot build system
+(this document is still incomplete and will be filled in over time)
+
+## General operation
+The coreboot build system is based on GNU make but extends it significantly
+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`
+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`.
+
+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
+such as the stages, subdirectories with more source code, and the general
+addition of files.
+
+Each class has a name (eg. `romstage`, `subdirs`, `cbfs-files`) and is used
+by filling in a variable of that name followed by `-y` (eg. `romstage-y`,
+`subdirs-y`, `cbfs-files-y`).
+The `-y` suffix allows a simple interaction with our Kconfig build
+configuration system: Kconfig options are available as variables starting
+with a `CONFIG_` prefix and boolean options contain `y`, `n` or are empty.
+
+This allows `class-$(CONFIG_FOO) += bar` to conditionally add `bar` to
+`class` depending on the choice for `FOO`.
+
+## classes
+Classes can be defined as required. `subdirs` is handled internally since
+it's parsed per subdirectory to add further directories to the rule set.
+
+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`.
+
+Subdirectories are not read at the point where the `subdirs` statement
+resides but later, after the current directory is handled (and potentially
+others, too).
+
+### cbfs-files
+This class is used to add files to the final CBFS image. Since several more
+options need to be maintained than can comfortably fit in that single
+variable, additional variables are used.
+
+`cbfs-files-y` contains the file name used in the CBFS image (called `foo`
+here). Additional options are added in `foo-$(option)` variables. The
+supported options are:
+
+*  `file`: The on-disk file to add as `foo` (required)
+*  `type`: The file type. Can be `raw`, `stage`, `payload`, and `flat-binary`
+   (required)
+*  `compression`: Can be `none` or `lzma` (default: none)
+*  `position`: An absolute position constraint for the placement of the file
+   (default: none)
+*  `align`: Minimum alignment for the file (default: none)
+*  `options`: Additional cbfstool options (default: none)
+
+`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
+which regions should contain which files, and even change some flags based on
+the region.
+
+Since FMAP policies depend on features using FMAP, that's kept separate from
+the cbfs-files class.
+
+The `position` and `align` options for file `foo` can be overwritten for a
+region `REGION` using `foo-REGION-position` and `foo-REGION-align`.
+
+The regions that each file should end in can be defined by overriding a
+function called `regions-for-file` that's called as
+`$(call regions-for-file,$(filename))` and should return a comma-separated
+list of regions, such as `REGION1,REGION2,REGION3`.
+
+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`.

Documentation/getting_started/cbmem.md

@@ -0,0 +1,361 @@
+# 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/comparison_coreboot_uefi.svg

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

Documentation/getting_started/devicetree.md

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

@@ -0,0 +1,312 @@
+# 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/gpio.md

@@ -0,0 +1,258 @@
+# Configuring a mainboard's GPIOs in coreboot
+
+## Introduction
+
+Every mainboard needs to appropriately configure its General Purpose Inputs /
+Outputs (GPIOs). There are many facets of this issue, including which boot
+stage a GPIO might need to be configured.
+
+## Boot stages
+
+Typically, coreboot does most of its non-memory related initialization work in
+ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs
+are configured in this stage. However, some boards might need a few GPIOs
+configured before that; think of memory strapping pins which indicate what kind
+of DRAM is installed. These pins might need to be read before initializing the
+memory, so these GPIOs are then typically configured in bootblock or romstage.
+
+## Configuration
+
+Most mainboards will have a ``gpio.c`` file in their mainboard directory. This
+file typically contains tables which describe the configuration of the GPIO
+registers. Since these registers could be different on a per-SoC or per
+SoC-family basis, you may need to consult the datasheet for your SoC to find out
+how to appropriately set these registers. In addition, some mainboards are
+based on a baseboard/variant model, where several variant mainboards may share a
+lot of their circuitry and ICs and the commonality between the boards is
+collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared
+between multiple boards are placed in the baseboard's ``gpio.c`` file, while the
+ones that are board-specific go into each variant's ``gpio.c`` file.
+
+## Intel SoCs
+
+Many newer Intel SoCs share a common IP block for GPIOs, and that commonality
+has been taken advantage of in coreboot, which has a large set of macros that
+can be used to describe the configuration of each GPIO pad. This file lives in
+``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``.
+
+### Older Intel SoCs
+
+Baytrail and Braswell, for example, simply expect the mainboard to supply a
+callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio`
+objects, defining the configuration of each pin.
+
+### AMD SoCs
+
+Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the
+register values configuring each pin, similar to Intel.
+
+### Register details
+
+GPIO configuration registers typically control properties such as:
+1. Input / Output
+2. Pullups / Pulldowns
+3. Termination
+4. Tx / Rx Disable
+5. Which reset signal to use
+6. Native Function / IO
+7. Interrupts
+    * IRQ routing (e.g. on x86, APIC, SCI, SMI)
+    * Edge or Level Triggered
+    * Active High or Active Low
+8. Debouncing
+
+## Configuring GPIOs for pre-ramstage
+
+coreboot provides for several SoC-specific and mainboard-specific callbacks at
+specific points in time, such as bootblock-early, bootblock, romstage entry,
+pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are
+configured in either bootblock or romstage, depending on when they are needed,
+are denoted the "early" GPIOs. Some mainboard will use
+``bootblock_mainboard_init()`` to configure their early GPIOs, and this is
+probably a good place to start. Many mainboards will declare their GPIO
+configuration as structs, i.e. (Intel),
+
+```C
+struct pad_config {
+    /* offset of pad within community */
+        int             pad;
+    /* Pad config data corresponding to DW0, DW1,.... */
+        uint32_t        pad_config[GPIO_NUM_PAD_CFG_REGS];
+};
+```
+
+and will usually place these in an array, one for each pad to be configured.
+Mainboards using Intel SoCs can use a library which combines common
+configurations together into a set of macros, e.g.,
+
+```C
+    /* Native function configuration */
+    #define PAD_CFG_NF(pad, pull, rst, func)
+    /* General purpose output, no pullup/down. */
+    #define PAD_CFG_GPO(pad, val, rst)
+    /* General purpose output, with termination specified */
+    #define PAD_CFG_TERM_GPO(pad, val, pull, rst)
+    /* General purpose output, no pullup/down. */
+    #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull)
+    /* General purpose input */
+    #define PAD_CFG_GPI(pad, pull, rst)
+```
+etc.
+
+## Configuring GPIOs for ramstage and beyond...
+
+In ramstage, most mainboards will configure the rest of their GPIOs for the
+function they will be performing while the device is active. The goal is the
+same as above in bootblock; another ``static const`` array is created, and the
+rest of the GPIO registers are programmed.
+
+In the baseboard/variant model described above, the baseboard will provide the
+configuration for the GPIOs which are configured identically between variants,
+and will provide a mechanism for a variant to override the baseboard's
+configuration. This is usually done via two tables: the baseboard table and the
+variant's override table.
+
+This configuration is often hooked into the mainboard's `enable_dev` callback,
+defined in its `struct chip_operations`.
+
+## Unconnected and unused pads
+
+In digital electronics, it is generally recommended to tie unconnected GPIOs to
+a defined signal like VCC or GND by setting their direction to output, adding an
+external pull resistor or configuring an internal pull resistor. This is done to
+prevent floating of the pin state, which can cause various issues like EMI,
+higher power usage due to continuously switching logic, etc.
+
+On Intel PCHs from Sunrise Point onwards, termination of unconnected GPIOs is
+explicitly not required, when the input buffer is disabled by setting the bit
+`GPIORXDIS` which effectively disconnects the pad from the internal logic. All
+pads defaulting to GPIO mode have this bit set. However, in the mainboard's
+GPIO configuration the macro `PAD_NC(pad, NONE)` can be used to explicitly
+configure a pad as unconnected.
+
+In case there are no schematics available for a board and the vendor set a
+pad to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull
+resistor, an unconnected or otherwise unused pad can be assumed. In this case it
+is recommended to keep the pull resistor, because the external circuit might
+rely on it.
+
+Unconnected pads defaulting to a native function (input and output) usually
+don't need to be configured as GPIO with the `GPIORXDIS` bit set. For clarity
+and documentation purpose the macro may be used as well for them.
+
+Some pads configured as native input function explicitly require external
+pull-ups when being unused, according to the PDGs:
+- eDP_HPD
+- SMBCLK/SMBDATA
+- SML0CLK/SML0DATA/SML0ALERT
+- SATAGP*
+
+When the board was designed correctly, nothing needs to be done for them
+explicitly, while using `PAD_NC(pad, NONE)` can act as documentation. If such a
+pad is missing the external pull resistor due to bad board design, the pad
+should be configured with `PAD_NC(pad, NONE)` anyway to disconnect it
+internally.
+
+## Potential issues (gotchas!)
+
+There are a couple of configurations that you need to especially careful about,
+as they can have a large impact on your mainboard.
+
+The first is configuring a pin as an output, when it was designed to be an
+input. There is a real risk in this case of short-circuiting a component which
+could cause catastrophic failures, up to and including your mainboard!
+
+### Intel SoCs
+
+As per Intel Platform Controller Hub (PCH) EDS since Skylake, a GPIO PAD register
+supports four different types of GPIO reset as:
+
+```{eval-rst}
++------------------------+----------------+-------------+-------------+
+|                        |                |         PAD Reset ?       |
++ PAD Reset Config       + Platform Reset +-------------+-------------+
+|                        |                |     GPP     |     GPD     |
++========================+================+=============+=============+
+| | 00 - Power Good      |  Warm Reset    |     N       |    N        |
+| | (GPP: RSMRST,        +----------------+-------------+-------------+
+| | GPD: DSW_PWROK)      |  Cold Reset    |     N       |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  S3/S4/S5      |     N       |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  Global Reset  |     N       |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  Deep Sx       |     Y       |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  G3            |     Y       |    Y        |
++------------------------+----------------+-------------+-------------+
+| 01 - Deep              |  Warm Reset    |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  Cold Reset    |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  S3/S4/S5      |     N       |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  Global Reset  |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  Deep Sx       |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  G3            |     Y       |    Y        |
++------------------------+----------------+-------------+-------------+
+| 10 - Host Reset/PLTRST |  Warm Reset    |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  Cold Reset    |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  S3/S4/S5      |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  Global Reset  |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  Deep Sx       |     Y       |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  G3            |     Y       |    Y        |
++------------------------+----------------+-------------+-------------+
+| | 11 - Resume Reset    |  Warm Reset    |     n/a     |    N        |
+| | (GPP: Reserved,      +----------------+-------------+-------------+
+| | GPD: RSMRST)         |  Cold Reset    |     n/a     |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  S3/S4/S5      |     n/a     |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  Global Reset  |     n/a     |    N        |
+|                        +----------------+-------------+-------------+
+|                        |  Deep Sx       |     n/a     |    Y        |
+|                        +----------------+-------------+-------------+
+|                        |  G3            |     n/a     |    Y        |
++------------------------+----------------+-------------+-------------+
+```
+
+Each GPIO Community has a Pad Configuration Lock register for a GPP allowing locking
+specific register fields in the PAD configuration register.
+
+The Pad Config Lock registers reset type is default hardcoded to **Power Good** and
+it's **not** configurable by GPIO PAD DW0.PadRstCfg. Hence, it may appear that for a GPP,
+the Pad Reset Config (DW0 Bit 31) is configured differently from `Power Good`.
+
+This would create confusion where the Pad configuration is returned to its `default`
+value but remains `locked`, this would prevent software to reprogram the GPP.
+Additionally, this means software can't rely on GPIOs being reset by PLTRST# or Sx entry.
+
+Hence, as per GPIO BIOS Writers Guide (BWG) it's recommended to change the Pad Reset
+Configuration for lock GPP as `Power Good` so that pad configuration and lock bit are
+always in sync and can be reset at the same time.
+
+## Soft Straps
+
+Soft straps, that can be configured by the vendor in the Intel Flash Image Tool
+(FIT), can influence some pads' default mode. It is possible to select either a
+native function or GPIO mode for some pads on non-server SoCs, while on server
+SoCs most pads can be controlled. Thus, it is generally recommended to always
+configure all pads and don't just rely on the defaults mentioned in the
+datasheet(s) which might not reflect what the vendor configured.
+
+## Pad-related known issues and workarounds
+
+### LPC_CLKRUNB blocks S0ix states when board uses eSPI
+
+When using eSPI, the pad implementing `LPC_CLKRUNB` must be set to GPIO mode.
+Other pin settings i.e. Rx path enable/disable, Tx path enable/disable, pull up
+enable/disable etc are ignored. Leaving this pin in native mode will keep the
+LPC Controller awake and prevent S0ix entry. This issues is know at least on
+Apollolake and Geminilake.

Documentation/getting_started/index.md

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

Documentation/getting_started/submodules.md

@@ -0,0 +1,46 @@
+Use of git submodules in coreboot
+=================================
+coreboot uses git submodules to keep certain parts of the tree separate,
+with two major use cases:
+
+First, we use a vendor tool by NVIDIA for systems based on their SoC
+and since they publish it through git, we can just import it into our
+tree using submodules.
+
+Second, lots of boards these days require binaries and we want to keep
+them separate from coreboot proper to clearly delineate shiny Open Source
+from ugly blobs.
+Since we don't want to impose blobs on users who really don't need them,
+that repository is only downloaded and checked out on explicit request.
+
+Handling submodules
+-------------------
+For the most part, submodules should be automatically checked out on the
+first execution of the coreboot Makefile.
+
+To manually fetch all repositories (eg. when you want to prepare the tree
+for archiving, or to use it without network access), run
+
+    $ git submodule update --init --checkout
+
+This also checks out the binaries below `3rdparty/`
+
+Mirroring coreboot
+------------------
+When running a coreboot mirror to checkout from, for full operation, you
+should also mirror the blobs and nvidia-cbootimage repository, and place
+them in the same directory as the coreboot repository mirror.
+
+That is, when residing in coreboot's repository, `cd ../blobs.git`
+should move you to the blobs repository.
+
+With that, no matter what the URL of your coreboot repository is, the
+git client (of a sufficiently new version) is able to pick up the other
+repositories transparently.
+
+Minimum requirements
+--------------------
+git needs to be able to handle relative paths to submodule repositories,
+and it needs to know about non-automatic submodules.
+
+For these features, we require git version 1.7.6.1 or newer.

Documentation/getting_started/writing_documentation.md

@@ -0,0 +1,154 @@
+# coreboot documentation guidelines
+
+> Documentation is like sex: when it is good, it is very, very good;
+> and when it is bad, it is better than nothing.
+
+That said please always try to write documentation! One problem in the
+firmware development is the missing documentation. In this document
+you will get a brief introduction how to write, submit and publish
+documentation to coreboot.
+
+## Preparations
+
+coreboot uses [Sphinx] documentation tool. We prefer the markdown format
+over reStructuredText so only embedded ReST is supported. Checkout the
+[Markdown Guide] for more information.
+
+### Option 1: Use the docker image
+
+The easiest way to build the documentation is using a docker image.
+To build the image run the following in the base directory:
+
+	make -C util/docker/ doc.coreboot.org
+
+To build the documentation:
+
+	make -C util/docker docker-build-docs
+
+To have the documentation build and served over a web server live run:
+
+	make -C util/docker docker-livehtml-docs
+
+On the host machine, open a browser to the address <http://0.0.0.0:8000>.
+
+### Option 2: Install Sphinx
+
+Please follow this official [guide] to install sphinx. You will also need
+myst-parser 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
+
+The following combination of versions has been tested: sphinx 8.1.3,
+myst-parser 4.0.0, and sphinx-rtd-theme 2.0.0.
+
+Now change into the `Documentation` folder in the coreboot directory and run
+this command in there
+
+	make
+
+If no error occurs, you can find the generated HTML documentation in
+`Documentation/_build/html` now.
+
+### Optional
+
+Install [sphinx-autobuild] for rebuilding markdown/rst sources on the fly!
+
+## Basic and simple rules
+
+The following rules should be followed in order to get it at least reviewed
+on [review.coreboot.org].
+
+Documentation:
+
+1.  Must be written in **markdown** with **embedded reStructuredText**
+    format.
+2.  Must be written in **English**.
+3.  Must be placed into **Documentation/** directory subfolder.
+4.  Should follow the same directory structure as **src/** when practical.
+5.  Must be referenced from within other markdown files
+6.  The commit must follow the [Gerrit Guidelines].
+7.  Must have all **lowercase filenames**.
+8.  Running text should have a visible width of about **72 chars**.
+9.  Should not **duplicate** documentation, but reference it instead.
+10.  Must not include the same picture in multiple markdown files.
+11.  Images should be kept small. They should be under 700px in width, as
+     the current theme doesn't allow bigger images.
+12.  Shouldn't cover implementation details; for details, the code is the
+     reference.
+
+## Markdown and Tables
+
+Markdown tables are supported:
+
+    | 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}
+    +------------+------------+-----------+
+    | Header 1   | Header 2   | Header 3  |
+    +============+============+===========+
+    | body row 1 | column 2   | column 3  |
+    +------------+------------+-----------+
+    | body row 2 | Cells may span columns.|
+    +------------+------------+-----------+
+    | body row 3 | Cells may  | - Cells   |
+    +------------+ span rows. | - contain |
+    | body row 4 |            | - blocks. |
+    +------------+------------+-----------+
+    ``` #just a code block is enough
+
+## TocTree
+
+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:
+
+**Example toctree:**
+
+    ```{toctree}
+    :maxdepth: 1
+
+    Chapter 1 <chapter1.md>
+    Chapter 2 <chapter2.md>
+    Subchapter <sub/index.md>
+    ```
+
+References in regular text aren't considered as *toctree* .
+
+If you do only reference the document, but do not include it in any toctree,
+you'll see the following warning:
+**WARNING: document isn't included in any toctree**
+
+## CSV
+
+You can import CSV files and let sphinx automatically convert them to human
+readable tables, using the following reStructuredText snipped:
+
+    ```{eval-rst}
+    .. csv-table::
+       :header: "Key", "Value"
+       :file: keyvalues.csv
+    ```
+
+Of course this can only be done from a markdown file that is included in the
+TOC tree.
+
+[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/
+[Markdown Guide]: https://www.markdownguide.org/
+[Gerrit Guidelines]: ../contributing/gerrit_guidelines.md
+[review.coreboot.org]: https://review.coreboot.org

Documentation/gfx/display-panel.md

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

Documentation/gfx/libgfxinit.md

@@ -0,0 +1,158 @@
+libgfxinit - Native Graphics Initialization
+===========================================
+
+Introduction and Current State in coreboot
+------------------------------------------
+
+*libgfxinit* is a library of full-featured graphics initialization
+(aka. modesetting) drivers. It's implemented in SPARK (a subset of
+Ada with formal verification features). While not restricted to in
+any way, it currently only supports Intel's integrated graphics
+controllers (GMA).
+
+Currently, it supports the Intel Core i3/i5/i7 processor line, HDMI
+and DP on the Apollo Lake processors and everything but SDVO on G45
+and GM45 chipsets. At the time of writing, G45, GM45, everything
+from Arrandale to Coffee Lake, and Apollo Lake are verified to work
+within *coreboot*.
+
+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`).
+
+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`).
+
+In any case, a smaller framebuffer is up-scaled to each display's
+native resolution while keeping aspect ratio.
+
+GMA: Hook-up in Chipset Initialization
+--------------------------------------
+
+Both configurations described above implement a procedure
+`GMA.gfxinit()`:
+
+    procedure gfxinit (lightup_ok : out int);
+
+This procedure is exported as the C function `gma_gfxinit()` as
+follows:
+
+    void gma_gfxinit(int *lightup_ok);
+
+* `lightup_ok`: returns whether the initialization succeeded `1` or
+                failed `0`. Currently, only the case that no display
+                could be found counts as failure. A failure at a
+                later stage (e.g. failure to train a DP) is not
+                propagated.
+
+GMA: Per Board Configuration
+----------------------------
+
+In order to set up the display panel, see the
+[display panel-specific documentation](/gfx/display-panel.md).
+
+There are a few Kconfig symbols to consider. To indicate that a
+board can initialize graphics through *libgfxinit*:
+
+    select MAINBOARD_HAS_LIBGFXINIT
+
+Internal ports share some hardware blocks (e.g. backlight, panel
+power sequencer). Therefore, each system with an integrated panel
+should set `GFX_GMA_PANEL_1_PORT` to the respective port, e.g.:
+
+    config GFX_GMA_PANEL_1_PORT
+            default "DP3"
+
+For the most common cases, LVDS and eDP, exists a shorthand, one
+can select either:
+
+    select GFX_GMA_PANEL_1_ON_EDP	# the default, or
+    select GFX_GMA_PANEL_1_ON_LVDS
+
+Some newer chips feature a second block of panel control logic.
+For this, `GFX_GMA_PANEL_2_PORT` can be set.
+
+Boards with a DVI-I connector share the DDC (I2C) pins for both
+analog and digital displays. In this case, *libgfxinit* needs to
+know through which interface the EDID can be queried:
+
+    select GFX_GMA_ANALOG_I2C_HDMI_B	# or
+    select GFX_GMA_ANALOG_I2C_HDMI_C	# or
+    select GFX_GMA_ANALOG_I2C_HDMI_D
+
+*libgfxinit* needs to know which ports are implemented on a board
+and should be probed for displays. There are two mechanisms to
+constrain the list of ports to probe, 1. port presence straps on
+the mainboard, and 2. a list of ports provided by *coreboot* (see
+below).
+
+Presence straps are configured via the state of certains pins of
+the chipset at reset time. They are documented in the chipset's
+datasheets. By default, *libgfxinit* honors these straps for
+safety. However, some boards don't implement the straps correctly.
+If ports are not strapped as implemented by error, one can select
+an option to ignore the straps:
+
+    select GFX_GMA_IGNORE_PRESENCE_STRAPS
+
+In the opposite case, that ports are strapped as implemented,
+but are actually unconnected, one has to make sure that the
+list of ports in *coreboot* omits them.
+
+The mapping between the physical ports and these entries depends on
+the hardware implementation and can be recovered by testing or
+studying the output of `intelvbttool` or `intel_vbt_decode`.
+Each board has to implement the package `GMA.Mainboard` with a list:
+
+    ports : HW.GFX.GMA.Display_Probing.Port_List;
+
+or a function returning such a list:
+
+    function ports return HW.GFX.GMA.Display_Probing.Port_List;
+
+You can select from the following Ports:
+
+    type Port_Type is
+      (Disabled,	-- optionally terminates the list
+       LVDS,
+       eDP,
+       DP1,
+       DP2,
+       DP3,
+       HDMI1,		-- also DVI-D, or HDMI over DP++
+       HDMI2,
+       HDMI3,
+       Analog);		-- legacy VGA port, or analog part of DVI-I
+
+Each `DPx` and `HDMIx` pair share pins. If they are exposed as DP
+ports, they are usually DP++ (aka. dual-mode DP) ports that can
+also output HDMI signals through passive adapters. In this case,
+both DPx and HDMIx should be listed.
+
+A good example is the mainboard Kontron/KTQM77, it features two
+DP++ ports (DP2/HDMI2, DP3/HDMI3), one DVI-I port (HDMI1/Analog),
+eDP and LVDS. It defines `ports` as follows:
+
+    ports : constant Port_List :=
+      (DP2,
+       DP3,
+       HDMI1,
+       HDMI2,
+       HDMI3,
+       Analog,
+       LVDS,
+       eDP,
+       others => Disabled);
+
+The `GMA.gfxinit()` procedure probes for display EDIDs in the
+given order until all available pipes are taken. That's 1 pipe
+in VGA textmode, 2 pipes in high-resolution mode until Sandy
+Bridge, 3 pipes from Ivy Bridge on.

Documentation/hypertransport.svg

@@ -0,0 +1,59 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg version="1.1" id="Layer_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
+	 width="256px" height="512px" viewBox="0 0 256 512" enable-background="new 0 0 256 512" xml:space="preserve">
+<font horiz-adv-x="2048">
+<font-face font-family="ArialMT" units-per-em="2048" underline-position="-217" underline-thickness="150"/>
+<missing-glyph horiz-adv-x="1536" d="M256,0l0,1280l1024,0l0,-1280M288,32l960,0l0,1216l-960,0z"/>
+<glyph unicode=" " horiz-adv-x="569"/>
+<glyph unicode="(" horiz-adv-x="682" d="M479,-431C380,-306 296,-159 227,9C158,177 124,351 124,531C124,690 150,842 201,987C261,1156 354,1324 479,1491l129,0C527,1352 474,1253 448,1194C407,1102 375,1006 352,906C323,781 309,656 309,530C309,209 409,-111 608,-431z"/>
+<glyph unicode=")" horiz-adv-x="682" d="M253,-431l-129,0C323,-111 423,209 423,530C423,655 409,780 380,903C357,1003 326,1099 285,1191C259,1251 205,1351 124,1491l129,0C378,1324 471,1156 531,987C582,842 608,690 608,531C608,351 574,177 505,9C436,-159 352,-306 253,-431z"/>
+<glyph unicode="-" horiz-adv-x="682" d="M65,440l0,181l553,0l0,-181z"/>
+<glyph unicode="0" horiz-adv-x="1139" d="M85,723C85,896 103,1036 139,1142C174,1247 227,1329 298,1386C368,1443 456,1472 563,1472C642,1472 711,1456 770,1425C829,1393 878,1347 917,1288C956,1228 986,1155 1008,1070C1030,984 1041,868 1041,723C1041,551 1023,412 988,307C953,201 900,119 830,62C759,4 670,-25 563,-25C422,-25 311,26 230,127C133,249 85,448 85,723M270,723C270,482 298,322 355,243C411,163 480,123 563,123C646,123 715,163 772,243C828,323 856,483 856,723C856,964 828,1125 772,1204C715,1283 645,1323 561,1323C478,1323 412,1288 363,1218C301,1129 270,964 270,723z"/>
+<glyph unicode="1" horiz-adv-x="1139" d="M763,0l-180,0l0,1147C540,1106 483,1064 413,1023C342,982 279,951 223,930l0,174C324,1151 412,1209 487,1276C562,1343 616,1409 647,1472l116,0z"/>
+<glyph unicode="2" horiz-adv-x="1139" d="M1031,173l0,-173l-969,0C61,43 68,85 83,125C108,191 147,256 202,320C256,384 334,458 437,542C596,673 704,776 760,853C816,929 844,1001 844,1069C844,1140 819,1201 768,1250C717,1299 650,1323 568,1323C481,1323 412,1297 360,1245C308,1193 282,1121 281,1029l-185,19C109,1186 156,1291 239,1364C322,1436 433,1472 572,1472C713,1472 824,1433 906,1355C988,1277 1029,1180 1029,1065C1029,1006 1017,949 993,892C969,835 929,776 874,713C818,650 725,564 596,455C488,364 419,303 388,271C357,238 332,206 312,173z"/>
+<glyph unicode="3" horiz-adv-x="1139" d="M86,387l180,24C287,309 322,236 372,191C421,146 482,123 553,123C638,123 709,152 768,211C826,270 855,342 855,429C855,512 828,580 774,634C720,687 651,714 568,714C534,714 492,707 441,694l20,158C473,851 483,850 490,850C567,850 636,870 697,910C758,950 789,1012 789,1095C789,1161 767,1216 722,1259C677,1302 620,1324 549,1324C479,1324 421,1302 374,1258C327,1214 297,1148 284,1060l-180,32C126,1213 176,1306 254,1373C332,1439 429,1472 545,1472C625,1472 699,1455 766,1421C833,1386 885,1339 921,1280C956,1221 974,1158 974,1091C974,1028 957,970 923,918C889,866 839,825 772,794C859,774 926,733 974,670C1022,607 1046,528 1046,433C1046,305 999,197 906,108C813,19 695,-26 552,-26C423,-26 317,12 232,89C147,166 98,265 86,387z"/>
+<glyph unicode="8" horiz-adv-x="1139" d="M362,795C287,822 232,861 196,912C160,963 142,1023 142,1094C142,1201 180,1290 257,1363C334,1436 436,1472 563,1472C691,1472 794,1435 872,1361C950,1286 989,1196 989,1089C989,1021 971,962 936,912C900,861 846,822 773,795C863,766 932,718 979,653C1026,588 1049,510 1049,419C1049,294 1005,188 916,103C827,18 711,-25 566,-25C421,-25 305,18 216,104C127,189 83,296 83,424C83,519 107,599 156,664C204,728 273,772 362,795M326,1100C326,1031 348,974 393,930C438,886 496,864 567,864C636,864 693,886 738,930C782,973 804,1027 804,1090C804,1156 781,1212 736,1257C690,1302 633,1324 565,1324C496,1324 439,1302 394,1258C349,1214 326,1161 326,1100M268,423C268,372 280,322 305,274C329,226 365,189 413,163C461,136 513,123 568,123C654,123 725,151 781,206C837,261 865,332 865,417C865,504 836,575 779,632C721,689 649,717 562,717C477,717 407,689 352,633C296,577 268,507 268,423z"/>
+<glyph unicode="B" horiz-adv-x="1366" d="M150,0l0,1466l550,0C812,1466 902,1451 970,1422C1037,1392 1090,1346 1129,1285C1167,1223 1186,1158 1186,1091C1186,1028 1169,969 1135,914C1101,859 1050,814 981,780C1070,754 1138,710 1186,647C1233,584 1257,510 1257,425C1257,356 1243,293 1214,234C1185,175 1149,129 1106,97C1063,65 1010,41 946,25C881,8 802,0 709,0M344,850l317,0C747,850 809,856 846,867C895,882 933,906 958,940C983,974 995,1017 995,1068C995,1117 983,1160 960,1197C937,1234 903,1259 860,1273C817,1286 742,1293 637,1293l-293,0M344,173l365,0C772,173 816,175 841,180C886,188 923,201 953,220C983,239 1008,266 1027,302C1046,337 1056,378 1056,425C1056,480 1042,527 1014,568C986,608 947,636 898,653C848,669 776,677 683,677l-339,0z"/>
+<glyph unicode="C" horiz-adv-x="1479" d="M1204,514l194,-49C1357,306 1284,184 1179,101C1073,17 944,-25 791,-25C633,-25 505,7 406,72C307,136 231,229 180,351C128,473 102,604 102,744C102,897 131,1030 190,1144C248,1257 331,1344 439,1403C546,1462 665,1491 794,1491C941,1491 1064,1454 1164,1379C1264,1304 1334,1199 1373,1064l-191,-45C1148,1126 1099,1203 1034,1252C969,1301 888,1325 790,1325C677,1325 583,1298 508,1244C432,1190 379,1118 348,1027C317,936 302,842 302,745C302,620 320,512 357,419C393,326 449,256 526,210C603,164 686,141 775,141C884,141 976,172 1051,235C1126,298 1177,391 1204,514z"/>
+<glyph unicode="D" horiz-adv-x="1479" d="M158,0l0,1466l505,0C777,1466 864,1459 924,1445C1008,1426 1080,1391 1139,1340C1216,1275 1274,1191 1313,1090C1351,988 1370,872 1370,741C1370,630 1357,531 1331,445C1305,359 1272,288 1231,232C1190,175 1146,131 1098,99C1049,66 991,42 923,25C854,8 776,0 687,0M352,173l313,0C762,173 838,182 893,200C948,218 991,243 1024,276C1070,322 1106,384 1132,462C1157,539 1170,633 1170,744C1170,897 1145,1015 1095,1098C1044,1180 983,1235 911,1263C859,1283 775,1293 660,1293l-308,0z"/>
+<glyph unicode="I" horiz-adv-x="569" d="M191,0l0,1466l194,0l0,-1466z"/>
+<glyph unicode="L" horiz-adv-x="1139" d="M150,0l0,1466l194,0l0,-1293l722,0l0,-173z"/>
+<glyph unicode="P" horiz-adv-x="1366" d="M158,0l0,1466l553,0C808,1466 883,1461 934,1452C1006,1440 1066,1417 1115,1384C1164,1350 1203,1303 1233,1242C1262,1181 1277,1115 1277,1042C1277,917 1237,812 1158,726C1079,639 935,596 728,596l-376,0l0,-596M352,769l379,0C856,769 945,792 998,839C1051,886 1077,951 1077,1036C1077,1097 1062,1150 1031,1194C1000,1237 959,1266 908,1280C875,1289 815,1293 727,1293l-375,0z"/>
+<glyph unicode="S" horiz-adv-x="1366" d="M92,471l183,16C284,414 304,354 336,307C367,260 416,222 483,193C550,164 625,149 708,149C782,149 847,160 904,182C961,204 1003,234 1031,273C1058,311 1072,353 1072,398C1072,444 1059,484 1032,519C1005,553 961,582 900,605C861,620 774,644 639,677C504,709 410,739 356,768C286,805 234,850 200,905C165,959 148,1020 148,1087C148,1161 169,1230 211,1295C253,1359 314,1408 395,1441C476,1474 565,1491 664,1491C773,1491 869,1474 952,1439C1035,1404 1098,1352 1143,1284C1188,1216 1212,1139 1215,1053l-186,-14C1019,1132 985,1202 928,1249C870,1296 785,1320 672,1320C555,1320 469,1299 416,1256C362,1213 335,1161 335,1100C335,1047 354,1004 392,970C429,936 527,901 685,866C842,830 950,799 1009,772C1094,733 1157,683 1198,623C1239,562 1259,493 1259,414C1259,336 1237,263 1192,194C1147,125 1083,71 1000,33C916,-6 822,-25 717,-25C584,-25 473,-6 384,33C294,72 224,130 173,208C122,285 95,373 92,471z"/>
+<glyph unicode="T" horiz-adv-x="1251" d="M531,0l0,1293l-483,0l0,173l1162,0l0,-173l-485,0l0,-1293z"/>
+<glyph unicode="U" horiz-adv-x="1479" d="M1120,1466l194,0l0,-847C1314,472 1297,355 1264,268C1231,181 1171,111 1084,57C997,2 882,-25 741,-25C604,-25 491,-1 404,46C317,93 254,162 217,252C180,341 161,464 161,619l0,847l194,0l0,-846C355,493 367,399 391,339C414,278 455,232 513,199C570,166 641,150 724,150C867,150 968,182 1029,247C1090,312 1120,436 1120,620z"/>
+<glyph unicode="X" horiz-adv-x="1366" d="M9,0l567,764l-500,702l231,0l266,-376C628,1012 668,952 691,910C724,963 762,1019 807,1077l295,389l211,0l-515,-691l555,-775l-240,0l-369,523C723,553 702,586 680,621C647,568 624,531 610,511l-368,-511z"/>
+</font>
+
+	<rect x="7.465" y="10.627" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/>
+<rect x="150.491" y="10.923" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.178"/>
+<rect x="8.479" y="129.379" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/>
+<rect x="150.491" y="129.674" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.178"/>
+<rect x="8.479" y="241.805" fill="#A0A0A0" stroke="#000000" width="80.473" height="80.473"/>
+<rect x="150.491" y="242.1" fill="#A0A0A0" stroke="#000000" width="80.474" height="80.177"/>
+<line fill="none" stroke="#000000" x1="48.716" y1="91.101" x2="48.716" y2="129.379"/>
+<line fill="none" stroke="#000000" x1="88.953" y1="50.864" x2="150.491" y2="51.012"/>
+<line fill="none" stroke="#000000" x1="88.953" y1="169.763" x2="150.491" y2="169.763"/>
+<line fill="none" stroke="#000000" x1="190.729" y1="91.101" x2="190.729" y2="129.379"/>
+<line fill="none" stroke="#000000" x1="48.716" y1="209.852" x2="48.716" y2="241.805"/>
+<line fill="none" stroke="#000000" x1="88.953" y1="282.189" x2="150.491" y2="282.189"/>
+<text transform="matrix(1 0 0 1 23.6948 57.3003)" font-family="'ArialMT'" font-size="18">CPU2</text>
+<text transform="matrix(1 0 0 1 22.3374 174.46)" font-family="'ArialMT'" font-size="18">CPU0</text>
+<text transform="matrix(1 0 0 1 169.082 55.1167)" font-family="'ArialMT'" font-size="18">CPU3</text>
+<text transform="matrix(1 0 0 1 169.082 175.8271)" font-family="'ArialMT'" font-size="18">CPU1</text>
+<text transform="matrix(1 0 0 1 22.6807 277.1895)"><tspan x="0" y="0" font-family="'ArialMT'" font-size="18">PCI-X</tspan><tspan x="0" y="21.601" font-family="'ArialMT'" font-size="18">(8131)</tspan></text>
+<text transform="matrix(1 0 0 1 169.082 275.1895)"><tspan x="0" y="0" font-family="'ArialMT'" font-size="18">  SB</tspan><tspan x="0" y="21.6" font-family="'ArialMT'" font-size="18">(8111)</tspan></text>
+<text transform="matrix(1 0 0 1 93.0947 63.8721)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 124.5088 46.7715)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 196.6982 102.9844)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<text transform="matrix(1 0 0 1 161.1953 126.0615)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 22.3374 126.0615)" font-family="'ArialMT'" font-size="10">LDT2</text>
+<text transform="matrix(1 0 0 1 55.2783 103.5767)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<text transform="matrix(1 0 0 1 52.9111 221.3276)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<text transform="matrix(1 0 0 1 93.0947 181.6719)" font-family="'ArialMT'" font-size="10">LDT1</text>
+<text transform="matrix(1 0 0 1 124.5088 166.2979)" font-family="'ArialMT'" font-size="10">LDT0</text>
+<ellipse fill="#FF0606" cx="150.491" cy="51.012" rx="4.438" ry="4.563"/>
+<ellipse fill="#FF0606" cx="88.953" cy="169.763" rx="4.438" ry="4.563"/>
+<ellipse fill="#FF0606" cx="190.729" cy="129.379" rx="4.438" ry="4.563"/>
+</svg>

Documentation/index.md

@@ -0,0 +1,247 @@
+# 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.
+
+## Purpose of coreboot
+
+coreboot is a project to develop open source boot firmware for various
+architectures. Its design philosophy is to do the bare minimum necessary to
+ensure that hardware is usable and then pass control to a different program
+called the _payload_.
+
+### Separation of concerns
+
+The payload can then provide user interfaces, file system drivers,
+various policies etc. to load the OS. Through this separation of concerns
+coreboot maximizes reusability of the complicated and fundamental hardware
+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,
+GRUB2, the bootloader used by many Linux distributions, or depthcharge,
+a custom boot loader used on Chromebooks.
+
+### No resident services (if possible)
+
+Ideally coreboot completely hands over control to the payload with no
+piece of coreboot remaining resident in the system, or even available
+for callback.  Given the reality of contemporary computer design,
+there's often a small piece that survives for the whole runtime of
+the computer. It runs in a highly privileged CPU mode (e.g. SMM on x86)
+and provides some limited amount of services to the OS. But here, too,
+coreboot aims to keep everything at the minimum possible, both in scope
+(e.g. services provided) and code size.
+
+### No specification of its own
+
+coreboot uses a very minimal interface to the payload, and otherwise
+doesn't impose any standards on the ecosystem. This is made possible by
+separating out concerns (interfaces and resident services are delegated
+to the payload), but it's also a value that is deeply ingrained in the
+project. We fearlessly rip out parts of the architecture and remodel it
+when a better way of doing the same was identified.
+
+That said, since there are attempts to coerce coreboot to move in various
+directions by outside "standardization", long-established practices of
+coreboot as well as aligned projects can be documented as best practices,
+making them standards in their own right. However we reserve the right to
+retire them as the landscape shifts around us.
+
+### One tree for everything
+
+Another difference to various other firmware projects is that we try
+to avoid fragmentation: the traditional development model of firmware
+is one of "set and forget" in which some code base is copied, adapted
+for the purpose at hands, shipped and only touched again if there's an
+important fix to do.
+
+All newer development happens on another copy of some code base without
+flowing back to any older copy, and so normally there's a huge amount
+of fragmentation.
+
+In coreboot, we try to keep everything in a single source tree, and
+lift up older devices when we change something fundamentally. That way,
+new and old devices benefit alike from new development in the common parts.
+
+There's a downside to that: Some devices might have no maintainer anymore
+who could ensure that coreboot is still functional for them after a big
+rework, or maybe a rework even requires knowledge that doesn't exist
+anymore within the project (for example because the developer moved on
+to do something else).
+
+In this case, we announce the deprecation of the device and defer the big
+rework until the deprecation period passed, typically 6-12 months. This
+gives interested developers a chance to step in and bring devices up to
+latest standards.
+
+While without this deprecation mechanism we could inflate the number
+of supported devices (probably 300+), only a tiny fraction of them
+would even work, which helps nobody.
+
+## Scope of the coreboot project
+
+coreboot as a project is closer to the Linux kernel than to most
+user level programs. One place where this becomes apparent is the
+distribution mechanism: The project itself only provides source code
+and does not ship ready-to-install coreboot-based firmware binaries.
+
+What the project distributes, even if - strictly speaking - it's not
+part of the project, is a collection of vendor binaries (that we call
+"blobs") that are redistributable. They cover the parts of hardware init
+that we haven't managed to open up, and while some hardware requires them,
+there's still hardware that can boot without any such binary components.
+
+The build system can integrate them into the build automatically if
+required, but that requires explicit opt-in and downloads a separate
+repository to ensure that the distinction remains clear.
+
+There are various [distributions](distributions.md), some shipping
+coreboot with their hardware (e.g. Purism or Chromebooks), others
+providing after-market images for various devices (e.g. Libreboot,
+MrChromebox).
+
+If you want to use coreboot on your system, that's great!
+
+Please note that the infrastructure around coreboot.org is built for
+development purposes. We gladly help out users through our communication
+channels, but we also expect a "firmware developer mindset": If compiling
+your own firmware and, at some point, recovering from a bad flash by
+hooking wires onto chips in your computer sounds scary to you, you're
+right, as it is.
+
+If that's _way_ beyond your comfort zone, consider looking into the
+various distributions, as they typically provide pre-tested binaries
+which massively reduces the risk that the binary you write to flash is
+one that won't boot the system (with the consequence that to get it to work
+again, you'll need to attach various tools to various chips)
+
+## The coreboot community
+
+If you're interested in getting your hands dirty (incl. potentially wiring
+up an external flasher to your computer), you've come to the right place!
+
+We have various [forums](community/forums.md) where we discuss and coordinate
+our activities, review patches, and help out each other. To
+help promote a positive atmosphere, we established a [Code of
+Conduct](community/code_of_conduct.md). We invested a lot of time
+to balance it out, so please keep it in mind when engaging with the
+coreboot community.
+
+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
+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
+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
+standard configuration.
+
+However, we're continually working on improvements to our infrastructure to
+get better in that respect, e.g. by setting up boot testing facilities. This
+is obviously more complex than regular integration testing, so progress
+is slow.
+
+### What our releases mean
+
+We also schedule two source code releases every year, around April and
+October. These releases see some very limited testing and mostly serve
+as synchronization points for deprecation notices and for other projects
+such as external distributions.
+
+This approach and terminology differs somewhat from how other projects handle
+releases where releases are well-tested artifacts and the development
+repository tends to be unstable. The "rolling release" model of some projects,
+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/

Documentation/infrastructure/admin.md

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