.checkpatch.conf

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

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

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

.gitignore

@@ -1,47 +1,100 @@
-junit.xml
-abuild*.xml
 .config
 .config.old
-defconfig
-.coreboot-version
 .xcompile
 .ccwrap
 build/
 coreboot-builds/
-coreboot-builds*/
-generated/
-
+payloads/external/FILO/filo/
+payloads/external/GRUB2/grub2/
+payloads/external/SeaBIOS/seabios/
+util/crossgcc/acpica-unix-*/
+util/crossgcc/binutils-*/
+util/crossgcc/build-*binutils/
+util/crossgcc/build-*expat/
+util/crossgcc/build-*gcc/
+util/crossgcc/build-*gdb/
+util/crossgcc/build-*gmp/
+util/crossgcc/build-*libelf/
+util/crossgcc/build-*mpc/
+util/crossgcc/build-*mpfr/
+util/crossgcc/build-*python/
+util/crossgcc/expat-*/
+util/crossgcc/gcc-*/
+util/crossgcc/gdb-*/
+util/crossgcc/gmp-*/
+util/crossgcc/libelf-*/
+util/crossgcc/mingwrt-*/
+util/crossgcc/mpc-*/
+util/crossgcc/mpfr-*/
+util/crossgcc/Python-*/
+util/crossgcc/tarballs/
+util/crossgcc/w32api-*/
+util/crossgcc/xgcc/
 site-local
 
 *.\#
-*.a
 *.bin
 *.debug
-!Kconfig.debug
 *.elf
-*.fd
 *.o
-*.o.d
 *.out
-*.pyc
-*.sw[po]
-/*.rom
-.test
-.dependencies
+*.swp
 
 # 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
+#
+# KDE editors create lots of backup files whenever
+# a file is edited, so just ignore them
 *~
 *.kate-swp
+# Ignore Kdevelop project file
 *.kdev4
+
+util/*/.dependencies
+util/*/.test
+util/board_status/board-status
+util/cbfstool/cbfstool
+util/cbfstool/rmodtool
+util/cbmem/.dependencies
+util/cbmem/cbmem
+util/dumpmmcr/dumpmmcr
+util/ectool/ectool
+util/genprof/genprof
+util/getpir/getpir
+util/ifdtool/ifdtool
+util/ifdfake/ifdfake
+util/inteltool/.dependencies
+util/inteltool/inteltool
+util/k8resdump/k8resdump
+util/lbtdump/lbtdump
+util/mptable/mptable
+util/msrtool/Makefile
+util/msrtool/Makefile.deps
+util/msrtool/msrtool
+util/nvramtool/.dependencies
+util/nvramtool/nvramtool
+util/optionlist/Options.wiki
+util/romcc/romcc
+util/romcc/tests/fail_test*.S
+util/romcc/tests/*.S-O2-mmmx
+util/runfw/googlesnow
+util/superiotool/superiotool
+util/vgabios/testbios
+util/viatool/viatool
+
+documentation/*.aux
+documentation/*.idx
+documentation/*.log
+documentation/*.toc
+documentation/*.out
+documentation/*.pdf
+documentation/cpukconfig.tex
+documentation/mainboardkconfig.tex
+documentation/skconfig.tex
+documentation/socketfkconfig.tex

.gitmodules

@@ -1,81 +1,8 @@
-[submodule "3rdparty/blobs"]
-	path = 3rdparty/blobs
-	url = https://review.coreboot.org/blobs.git
+[submodule "3rdparty"]
+	path = 3rdparty
+	url = ../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
-
+	url = ../nvidia-cbootimage.git

.gitreview

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

.mailmap

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

3rdparty

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

3rdparty/amd_blobs

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

3rdparty/arm-trusted-firmware

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

3rdparty/blobs

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

3rdparty/cmocka

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

3rdparty/ffs

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

3rdparty/fsp

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

3rdparty/intel-microcode

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

3rdparty/intel-sec-tools

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

3rdparty/libgfxinit

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

3rdparty/libhwbase

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

3rdparty/open-power-signing-utils

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

3rdparty/opensbi

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

3rdparty/qc_blobs

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

3rdparty/stm

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

3rdparty/vboot

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

AUTHORS

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

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

Documentation/.mdl_style.rb

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

Documentation/COPYING

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

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

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

@@ -1,31 +0,0 @@
--------------------------------------------------------------------------------
-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/intel-gpio-cleanup.md

@@ -1,102 +0,0 @@
-```{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

@@ -1,19 +0,0 @@
-/*
- * 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

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

@@ -1,34 +0,0 @@
-# ACPI-specific documentation
-
-This section contains documentation about coreboot on ACPI. coreboot dropped
-backwards support for ACPI 1.0 and is only compatible to ACPI version 2.0 and
-upwards.
-
-
-```{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

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

Documentation/acpi/windows.md

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

Documentation/arch/index.md

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

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

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

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

Documentation/arch/x86/x86_64.md

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

Documentation/community/code_of_conduct.md

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

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

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

Documentation/community/forums.md

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

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

Documentation/community/language_style.md

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

Documentation/conf.py

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

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

Documentation/contributing/gerrit_guidelines.md

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

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

Documentation/contributing/gsoc.md

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

Documentation/contributing/index.md

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

Documentation/contributing/project_ideas.md

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

@@ -1,671 +0,0 @@
-%
-% 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

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

Documentation/distributions.md

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

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

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

Documentation/drivers/cbfs_smbios.md

@@ -1,143 +0,0 @@
-# CBFS SMBIOS hooks
-
-The document describes the coreboot options how to make CBFS files populate
-platform-unique SMBIOS data.
-
-## SMBIOS Serial Number
-
-The [DMTF SMBIOS specification] defines a field in the type 1 System
-Information and type 2 Baseboard Information called Serial Number. It
-is a null-terminated string field assumed to be unique per platform. Certain
-mainboard ports have SMBIOS hooks to generate the Serial Numbers from external
-data, e.g. Lenovo Thinkpads (see DRIVER_LENOVO_SERIALS). This driver aims to
-provide an option to populate the Serial Numbers from CBFS for boards that
-can't generate the it from any source.
-
-### Usage
-
-In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers`
-and select an option `Serial number in CBFS`. The Kconfig system will enable
-`DRIVERS_GENERIC_CBFS_SERIAL` and the relevant code parts will be compiled into
-coreboot image.
-
-After the coreboot build for your board completes, use the cbfstool to include
-the file containing the serial number:
-
-```shell
-./build/cbfstool build/coreboot.rom add -n serial_number -t raw -f /path/to/serial_file.txt
-```
-
-Where `serial_file.txt` is the unterminated string representation of the SMBIOS
-type 1 or type 2 Serial Number, e.g. `5Q4Q7Y1`. If you use vboot with 1 or 2 RW
-partitions you will have to specify the RW regions where the file is going to
-be added too. By default the RW CBFS partitions are truncated, so the files
-would probably not fit, one needs to expand them first.
-
-```shell
-./build/cbfstool build/coreboot.rom expand -r FW_MAIN_A
-./build/cbfstool build/coreboot.rom add -n serial_number -t raw \
-	-f /path/to/serial_file.txt -r FW_MAIN_A
-./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_A
-
-./build/cbfstool build/coreboot.rom expand -r FW_MAIN_B
-./build/cbfstool build/coreboot.rom add -n serial_number -t raw \
-	-f /path/to/serial_file.txt -r FW_MAIN_B
-./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_B
-```
-
-By default cbfstool adds files to COREBOOT region only, so when vboot is
-enabled and the platform is booting from RW partition, the file would not be
-picked up by the driver.
-
-One may retrieve the Serial Number from running system (if it exists) using one
-of the following commands:
-
-```shell
-# Type 1
-echo -n `sudo dmidecode -s system-serial-number` > serial_file.txt
-# OR Type 2
-echo -n `sudo dmidecode -s baseboard-serial-number` > serial_file.txt
-```
-
-Ensure the file does not end with whitespaces like LF and/or CR. The above
-commands will not add any whitespaces. The driver automatically terminates the
-Serial Number with the NULL character. If the CBFS file is not present, the
-driver will fall back to the string defined in `MAINBOARD_SERIAL_NUMBER` build
-option.
-
-Please note that this driver provides `smbios_mainboard_serial_number` hook
-overriding the default implementation which returns `MAINBOARD_SERIAL_NUMBER`
-build option. If you wish to populate only type 2 Serial Number field your
-board code needs to implement `smbios_system_serial_number`, otherwise the weak
-implementation of `smbios_system_serial_number` will call
-`smbios_mainboard_serial_number` from the `DRIVERS_GENERIC_CBFS_SERIAL`
-implementation overriding it. So selecting the `DRIVERS_GENERIC_CBFS_SERIAL`
-has a side-effect of populating both SMBIOS type 1 and type 2 Serial Numbers
-if the board does not implement its own `smbios_system_serial_number`.
-
-There is also SMBIOS type 3 Chassis Information Serial Number, but it is not
-populated by `DRIVERS_GENERIC_CBFS_SERIAL` nor by the default weak
-implementation (returns empty string). If you wish to populate type 3 Serial
-Number, your board code should override the default
-`smbios_chassis_serial_number` weak implementation.
-
-## SMBIOS System UUID
-
-The [DMTF SMBIOS specification] defines a field in the type 1 System
-Information Structure called System UUID. It is a 16 bytes value compliant with
-[RFC4122] and assumed to be unique per platform. Certain mainboard ports have
-SMBIOS hooks to generate the UUID from external data, e.g. Lenovo Thinkpads
-(see DRIVER_LENOVO_SERIALS). This driver aims to provide an option to populate
-the UUID from CBFS for boards that can't generate the UUID from any source.
-
-### Usage
-
-In the coreboot configuration menu (`make menuconfig`) go to `Generic Drivers`
-and select an option `System UUID in CBFS`. The Kconfig system will enable
-`DRIVERS_GENERIC_CBFS_UUID` and the relevant code parts will be compiled into
-coreboot image.
-
-After the coreboot build for your board completes, use the cbfstool to include
-the file containing the UUID:
-
-```shell
-./build/cbfstool build/coreboot.rom add -n system_uuid -t raw -f /path/to/uuid_file.txt
-```
-
-Where `uuid_file.txt` is the unterminated string representation of the SMBIOS
-type 1 UUID, e.g. `4c4c4544-0051-3410-8051-b5c04f375931`. If you use vboot with
-1 or 2 RW partitions you will have to specify the RW regions where the file is
-going to be added too. By default the RW CBFS partitions are truncated, so the
-files would probably not fit, one needs to expand them first.
-
-```shell
-./build/cbfstool build/coreboot.rom expand -r FW_MAIN_A
-./build/cbfstool build/coreboot.rom add -n system_uuid -t raw \
-	-f /path/to/uuid_file.txt -r FW_MAIN_A
-./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_A
-
-./build/cbfstool build/coreboot.rom expand -r FW_MAIN_B
-./build/cbfstool build/coreboot.rom add -n system_uuid -t raw \
-	-f /path/to/uuid_file.txt -r FW_MAIN_B
-./build/cbfstool build/coreboot.rom truncate -r FW_MAIN_B
-```
-
-By default cbfstool adds files to COREBOOT region only, so when vboot is
-enabled and the platform is booting from RW partition, the file would not be
-picked up by the driver.
-
-One may retrieve the UUID from running system (if it exists) using the
-following command:
-
-```shell
-echo -n `sudo dmidecode -s system-uuid` > uuid_file.txt
-```
-
-The above command ensures the file does not end with whitespaces like LF and/or
-CR. The above command will not add any whitespaces. But the driver will handle
-situations where up to 2 additional bytes like CR and LF will be included in
-the file. Any more than that will make the driver fail to populate UUID in
-SMBIOS.
-
-[DMTF SMBIOS specification]: https://www.dmtf.org/standards/smbios
-[RFC4122]: https://www.ietf.org/rfc/rfc4122.txt

Documentation/drivers/cfr.md

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

Documentation/drivers/cfr_internal.md

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

Documentation/drivers/dptf.md

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

Documentation/drivers/dt_entries.md

@@ -1,309 +0,0 @@
-# Driver Devicetree Entries
-
-Let's take a look at an example entry from
-``src/mainboard/google/hatch/variants/hatch/overridetree.cb``:
-
-```
-device pci 15.0 on
-	chip drivers/i2c/generic
-		register "hid" = ""ELAN0000""
-		register "desc" = ""ELAN Touchpad""
-		register "irq" = "ACPI_IRQ_LEVEL_LOW(GPP_A21_IRQ)"
-		register "detect" = "1"
-		register "wake" = "GPE0_DW0_21"
-		device i2c 15 on end
-	end
-end # I2C #0
-```
-
-When this entry is processed during ramstage, it will create a device in the
-ACPI SSDT table (all devices in devicetrees end up in the SSDT table).  The ACPI
-generation routines in coreboot actually generate the raw bytecode that
-represents the device's structure, but looking at ASL code is easier to
-understand; see below for what the disassembled bytecode looks like:
-
-```
-Scope (\_SB.PCI0.I2C0)
-{
-    Device (D015)
-    {
-        Name (_HID, "ELAN0000")  // _HID: Hardware ID
-        Name (_UID, Zero)  // _UID: Unique ID
-        Name (_DDN, "ELAN Touchpad")  // _DDN: DOS Device Name
-        Method (_STA, 0, NotSerialized)  // _STA: Status
-        {
-            Return (0x0F)
-        }
-        Name (_CRS, ResourceTemplate ()  // _CRS: Current Resource Settings
-        {
-            I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
-                AddressingMode7Bit, "\\_SB.PCI0.I2C0",
-                0x00, ResourceConsumer, , Exclusive, )
-            Interrupt (ResourceConsumer, Level, ActiveLow, Exclusive, ,, )
-            {
-                0x0000002D,
-            }
-        })
-        Name (_S0W, ACPI_DEVICE_SLEEP_D3_HOT)  // _S0W: S0 Device Wake State
-        Name (_PRW, Package (0x02)  // _PRW: Power Resources for Wake
-        {
-            0x15, // GPE #21
-            0x03  // Sleep state S3
-        })
-    }
-}
-```
-
-You can see it generates \_HID, \_UID, \_DDN, \_STA, \_CRS, \_S0W, and \_PRW
-names/methods in the Device's scope.
-
-## Utilizing a device driver
-
-The device driver must be enabled for your build.  There will be a CONFIG option
-in the Kconfig file in the directory that the driver is in (e.g.,
-``src/drivers/i2c/generic`` contains a Kconfig file; the option here is named
-CONFIG_DRIVERS_I2C_GENERIC).  The config option will need to be added to your
-mainboard's Kconfig file (e.g., ``src/mainboard/google/hatch/Kconfig``) in order
-to be compiled into your build.
-
-## Diving into the above example:
-
-Let's take a look at how the devicetree language corresponds to the generated
-ASL.
-
-First, note this:
-
-```
-    chip drivers/i2c/generic
-```
-
-This means that the device driver we're using has a corresponding structure,
-located at ``src/drivers/i2c/generic/chip.h``, named **struct
-drivers_i2c_generic_config** and it contains many properties you can specify to
-be included in the ACPI table.
-
-### hid
-
-```
-    register "hid" = ""ELAN0000""
-```
-
-This corresponds to **const char \*hid** in the struct.  In the ACPI ASL, it
-translates to:
-
-```
-    Name (_HID, "ELAN0000") // _HID: Hardware ID
-```
-
-under the device.  **This property is used to match the device to its driver
-during enumeration in the OS.**
-
-### desc
-
-```
-    register "desc" = ""ELAN Touchpad""
-```
-
-corresponds to **const char \*desc** and in ASL:
-
-```
-    Name (_DDN, "ELAN Touchpad") // _DDN: DOS Device Name
-```
-
-### irq
-
-It also adds the interrupt,
-
-```
-    Interrupt (ResourceConsumer, Level, ActiveLow, Exclusive, ,, )
-    {
-        0x0000002D,
-    }
-```
-
-which comes from:
-
-```
-    register "irq" = "ACPI_IRQ_LEVEL_LOW(GPP_A21_IRQ)"
-```
-
-The IRQ settings control the "Trigger" and "Polarity" settings seen above (level
-means it is a level-triggered interrupt as opposed to
-edge-triggered; active low means the interrupt is triggered when the signal is
-low).
-
-Also note that the IRQ names are SoC-specific, and you will need to
-find the names in your SoC's header file.  The ACPI_* macros are defined in
-``src/arch/x86/include/acpi/acpi_device.h``.
-
-Using a GPIO as an IRQ requires that it is configured in coreboot correctly.
-This is often done in a mainboard-specific file named ``gpio.c``.
-
-AMD platforms don't have the ability to route GPIOs to the IO-APIC. Instead the
-GPIO controller needs to be used directly. You can do this by setting the
-`irq_gpio` register and using the `ACPI_GPIO_IRQ_X_X` macros.
-
-i.e.,
-```
-register "irq_gpio" = "ACPI_GPIO_IRQ_EDGE_LOW(GPIO_40)"
-```
-
-### detect
-
-The next register is:
-
-```
-    register "detect" = "1"
-```
-
-This flag tells the I2C driver that it should attempt to detect the presence of
-the device (using an I2C zero-byte write), and only generate a SSDT entry if the
-device is actually present. This alleviates the OS from having to determine if
-a device is present or not (ChromeOS/Linux) and prevents resource conflict/
-driver issues (Windows).
-
-Currently, the detect feature works and is hooked up for all I2C touchpads,
-and should be used any time a board has multiple touchpad options.
-I2C audio devices should also work without issue.
-
-Touchscreens can use this feature as well, but special care is needed to
-implement the proper power sequencing for the device to be detected. Generally,
-this means driving the enable GPIO high and holding the reset GPIO low in early
-GPIO init (bootblock/romstage), then releasing reset in ramstage. The first
-mainboards in the tree to implement this are google/skyrim and google/guybrush.
-This feature has also been used in downstream forks without issue for some time
-now on several other boards.
-
-### wake
-
-The last register is:
-
-```
-    register "wake" = "GPE0_DW0_21"
-```
-
-which indicates that the method of waking the system using the touchpad will be
-through a GPE, #21 associated with DW0, which is set up in devicetree.cb from
-this example.  The "21" indicates GPP_X21, where GPP_X is mapped onto DW0
-elsewhere in the devicetree.
-
-### device
-
-The last bit of the definition of that device includes:
-
-```
-    device i2c 15 on end
-```
-
-which means it's an I2C device, with 7-bit address 0x15, and the device is "on",
-meaning it will be exposed in the ACPI table.  The PCI device that the
-controller is located in determines which I2C bus the device is expected to be
-found on.  In this example, this is I2C bus 0.  This also determines the ACPI
-"Scope" that the device names and methods will live under, in this case
-"\_SB.PCI0.I2C0".
-
-## Wake sources
-
-The ACPI spec defines two methods to describe how a device can wake the system.
-Only one of these methods should be used, otherwise duplicate wake events will
-be generated.
-
-### Using GPEs as a wake source
-
-The `wake` property specified above is used to tell the ACPI subsystem that the
-device can use a GPE to wake the system. The OS can control whether to enable
-or disable the wake source by unmasking/masking off the GPE.
-
-The `GPIO` -> `GPE` mapping must be configured in firmware. On AMD platforms this is
-generally done by a mainboard specific `gpio.c` file that defines the GPIO
-using `PAD_SCI`. The `GPIO` -> `GPE` mapping is returned by the
-`soc_get_gpio_event_table` method that is defined in the SoC specific `gpio.c`
-file. On Intel platforms, you fill in the `pmc_gpe0_dw0`, `pmc_gpe0_dw1`, and
-`pmc_gpe0_dw2` fields in the devicetree to map 3 GPIO communities to `tier-1`
-GPEs (the rest are available as `tier-2` GPEs).
-
-Windows has a large caveat when using this method. If you use the `gpio_irq`
-property to define a `GpioInt` in the `_CRS`, and then use the `wake` property
-to define a `GPE`, Windows will
-[BSOD](https://github.com/MicrosoftDocs/windows-driver-docs/blob/staging/windows-driver-docs-pr/debugger/bug-check-0xa5--acpi-bios-error.md)
-complaining about an invalid ACPI configuration.
-> 0x1000D - A device used both GPE and GPIO interrupts, which is not supported.
-
-In order to avoid this error, you should use the `irq` property instead. AMD
-platforms don't support routing GPIOs to the IO-APIC, so this workaround isn't
-feasible. The other option is to use a wake capable GPIO as described below.
-
-### Using GPIO interrupts as a wake source
-
-The `ACPI_IRQ_WAKE_{EDGE,LEVEL}_{LOW,HIGH}` macros can be used when setting the
-`irq` or `gpio_irq` properties. This ends up setting `ExclusiveAndWake` or
-`SharedAndWake` on the `Interrupt` or `GpioInt` ACPI resource.
-
-This method has a few caveats:
-* On Intel and AMD platforms the IO-APIC can't wake the system. This means using
-  the `ACPI_IRQ_WAKE_*` macros with the `irq` property won't actually wake the
-  system. Instead you need to use the `gpio_irq` property, or a `GPE` as
-  described above.
-* The OS needs to know how to enable the `wake` bit on the GPIO. For linux this
-  means the platform specific GPIO controller driver must implement the
-  `irq_set_wake` callback. For AMD systems this wasn't
-  [implemented](https://github.com/torvalds/linux/commit/d62bd5ce12d79bcd6a6c3e4381daa7375dc21158)
-  until linux v5.15. If the controller doesn't define this callback, it's
-  possible for the firmware to manually set the `wake` bit on the GPIO. This is
-  often done in a mainboard-specific file named `gpio.c`. This is not
-  recommended because then it's not possible for the OS to disable the wake
-  source.
-* As of
-  [linux v6.0-rc5](https://github.com/torvalds/linux/releases/tag/v6.0-rc5),
-  the ACPI subsystem doesn't take the interrupt `wake` bit into account when
-  deciding on which power state to put the device in before suspending the
-  system. This means that if you define a power resource for a device via
-  `has_power_resource`, `enable_gpio`, etc, then the linux kernel will place the
-  device into D3Cold. i.e., power off the device.
-
-## Other auto-generated names
-
-(see [ACPI specification
-6.3](https://uefi.org/sites/default/files/resources/ACPI_6_3_final_Jan30.pdf)
-for more details on ACPI methods)
-
-### _S0W (S0 Device Wake State)
-\_S0W indicates the deepest S0 sleep state this device can wake itself from,
-which in this case is `ACPI_DEVICE_SLEEP_D3_HOT`, representing _D3hot_.
-D3Hot means the `PR3` power resources are still on and the device is still
-responsive on the bus. For i2c devices this is generally the same state as `D0`.
-
-### \_PRW (Power Resources for Wake)
-\_PRW indicates the power resources and events required for wake.  There are no
-dependent power resources, but the GPE (GPE0_DW0_21) is mentioned here (0x15),
-as well as the deepest sleep state supporting waking the system (3), which is
-S3.
-
-### \_STA (Status)
-The \_STA method is generated automatically, and its values, 0xF, indicates the
-following:
-
-    Bit [0] – Set if the device is present.
-    Bit [1] – Set if the device is enabled and decoding its resources.
-    Bit [2] – Set if the device should be shown in the UI.
-    Bit [3] – Set if the device is functioning properly (cleared if device failed its diagnostics).
-
-### \_CRS (Current resource settings)
-The \_CRS method is generated automatically, as the driver knows it is an I2C
-controller, and so specifies how to configure the controller for proper
-operation with the touchpad.
-
-```
-Name (_CRS, ResourceTemplate ()  // _CRS: Current Resource Settings
-{
-    I2cSerialBusV2 (0x0015, ControllerInitiated, 400000,
-                    AddressingMode7Bit, "\\_SB.PCI0.I2C0",
-                    0x00, ResourceConsumer, , Exclusive, )
-```
-
-## Notes
-
- - **All device driver entries in devicetrees end up in the SSDT table, and are
-   generated in coreboot's ramstage**
-   (The lone exception to this rule is i2c touchpads with the 'detect' flag set;
-    in this case, devices not present will not be added to the SSDT)

Documentation/drivers/efi_capsule_generation.md

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

Documentation/drivers/index.md

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

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

Documentation/drivers/ipmi_kcs.md

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

Documentation/drivers/retimer.md

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

Documentation/drivers/smmstore.md

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

@@ -1,256 +0,0 @@
-# SMM based flash storage driver Version 2
-
-This documents the API exposed by the x86 system management based
-storage driver.
-
-## SMMSTOREv2
-
-SMMSTOREv2 is a [SMM] mediated driver to read from, write to and erase
-a predefined region in flash. It can be enabled by setting
-`CONFIG_SMMSTORE=y` and `CONFIG_SMMSTORE_V2=y` in menuconfig.
-
-This can be used by the OS or the payload to implement persistent
-storage to hold for instance configuration data, without needing to
-implement a (platform specific) storage driver in the payload itself.
-
-### Storage size and alignment
-
-SMMSTORE version 2 requires a minimum alignment of 64 KiB, which should
-be supported by all flash chips. Not having to perform read-modify-write
-operations is desired, as it reduces complexity and potential for bugs.
-
-This can be used by a FTW (FaultTolerantWrite) implementation that uses
-at least two regions in an A/B update scheme. The FTW implementation in
-edk2 uses three different regions in the store:
-
-- The variable store
-- The FTW spare block
-- The FTW working block
-
-All regions must be block-aligned, and the FTW spare size must be larger
-than that of the variable store. FTW working block can be much smaller.
-With 64 KiB as block size, the minimum size of the FTW-enabled store is:
-
-- The variable store: 1 block = 64 KiB
-- The FTW spare block: 2 blocks = 2 * 64 KiB
-- The FTW working block: 1 block = 64 KiB
-
-Therefore, the minimum size for edk2 FTW is 4 blocks, or 256 KiB.
-
-## API
-
-The API provides read and write access to an unformatted block storage.
-
-### Storage region
-
-By default SMMSTOREv2 will operate on a separate FMAP region called
-`SMMSTORE`. The default generated FMAP will include such a region. On
-systems with a locked FMAP, e.g. in an existing vboot setup with a
-locked RO region, the option exists to add a cbfsfile called `smm_store`
-in the `RW_LEGACY` (if CHROMEOS) or in the `COREBOOT` FMAP regions. It
-is recommended for new builds using a handcrafted FMD that intend to
-make use of SMMSTORE to include a sufficiently large `SMMSTORE` FMAP
-region. It is mandatory to align the `SMMSTORE` region to 64KiB for
-compatibility with the largest flash erase operation.
-
-When a default generated FMAP is used, the size of the FMAP region is
-equal to `CONFIG_SMMSTORE_SIZE`. UEFI payloads expect at least 64 KiB.
-To support a fault tolerant write mechanism, at least a multiple of
-this size is recommended.
-
-### Communication buffer
-
-To prevent malicious ring0 code to access arbitrary memory locations,
-SMMSTOREv2 uses a communication buffer in CBMEM/HOB for all transfers.
-This buffer has to be at least 64 KiB in size and must be installed
-before calling any of the SMMSTORE read or write operations. Usually,
-coreboot will install this buffer to transfer data between ring0 and
-the [SMM] handler.
-
-In order to get the communication buffer address, the payload or OS
-has to read the coreboot table with tag `0x0039`, containing:
-
-```C
-struct lb_smmstorev2 {
-	uint32_t tag;
-	uint32_t size;
-	uint32_t num_blocks;		/* Number of 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

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

Documentation/external_docs.md

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

Documentation/getting_started/architecture.md

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

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

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

Documentation/getting_started/comparison_coreboot_uefi.svg

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

Documentation/getting_started/devicetree.md

@@ -1,87 +0,0 @@
-# Adding new devices to a device tree
-
-## Introduction
-
-ACPI exposes a platform-independent interface for operating systems to perform
-power management and other platform-level functions.  Some operating systems
-also use ACPI to enumerate devices that are not immediately discoverable, such
-as those behind I2C or SPI buses (in contrast to PCI).  This document discusses
-the way that coreboot uses the concept of a "device tree" to generate ACPI
-tables for usage by the operating system.
-
-## Devicetree and overridetree (if applicable)
-
-For mainboards that are organized around a "reference board" or "baseboard"
-model (see ``src/mainboard/google/octopus`` or ``hatch`` for examples), there is
-typically a devicetree.cb file that all boards share, and any differences for a
-specific board ("variant") are captured in the overridetree.cb file.  Any
-settings changed in the overridetree take precedence over those in the main
-devicetree.  Note, not all mainboards will have the devicetree/overridetree
-distinction, and may only have a devicetree.cb file.  Or you can always just
-write the ASL (ACPI Source Language) code yourself.
-
-### Naming and referencing devices
-
-When declaring a device, it can optionally be given an alias that can be
-referred to elsewhere. This is particularly useful to declare a device in one
-device tree while allowing its configuration to be more easily changed in an
-overlay. For instance, the AMD Picasso SoC definition
-(`soc/amd/picasso/chipset.cb`) declares an IOMMU on a PCI bus that is disabled
-by default:
-
-```
-chip soc/amd/picasso
-	device domain 0 on
-		...
-		device pci 00.2 alias iommu off end
-		...
-	end
-end
-```
-
-A device based on this SoC can override the configuration for the IOMMU without
-duplicating addresses, as in
-`mainboard/google/zork/variants/baseboard/devicetree_trembyle.cb`:
-
-```
-chip soc/amd/picasso
-	device domain 0
-		...
-		device ref iommu on end
-		...
-	end
-end
-```
-
-In this example the override simply enables the IOMMU, but it could also
-set additional properties (or even add child devices) inside the IOMMU `device`
-block.
-
----
-
-It is important to note that devices that use `device ref` syntax to override
-previous definitions of a device by alias must be placed at **exactly the same
-location in the device tree** as the original declaration. If not, this will
-actually create another device rather than overriding the properties of the
-existing one. For instance, if the above snippet from `devicetree_trembyle.cb`
-were written as follows:
-
-```
-chip soc/amd/picasso
-	# NOTE: not inside domain 0!
-	device ref iommu on end
-end
-```
-
-Then this would leave the SoC's IOMMU disabled, and instead create a new device
-with no properties as a direct child of the SoC.
-
-## Device drivers
-
-Platform independent device drivers are hooked up via entries in a devicetree.
-See [Driver Devicetree Entries](../drivers/dt_entries.md) for more info.
-
-## Notes
-
- - **All fields that are left unspecified in the devicetree are initialized to
-   zero.**

Documentation/getting_started/faq.md

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

Documentation/getting_started/gpio.md

@@ -1,258 +0,0 @@
-# Configuring a mainboard's GPIOs in coreboot
-
-## Introduction
-
-Every mainboard needs to appropriately configure its General Purpose Inputs /
-Outputs (GPIOs). There are many facets of this issue, including which boot
-stage a GPIO might need to be configured.
-
-## Boot stages
-
-Typically, coreboot does most of its non-memory related initialization work in
-ramstage, when DRAM is available for use. Hence, the bulk of a mainboard's GPIOs
-are configured in this stage. However, some boards might need a few GPIOs
-configured before that; think of memory strapping pins which indicate what kind
-of DRAM is installed. These pins might need to be read before initializing the
-memory, so these GPIOs are then typically configured in bootblock or romstage.
-
-## Configuration
-
-Most mainboards will have a ``gpio.c`` file in their mainboard directory. This
-file typically contains tables which describe the configuration of the GPIO
-registers. Since these registers could be different on a per-SoC or per
-SoC-family basis, you may need to consult the datasheet for your SoC to find out
-how to appropriately set these registers. In addition, some mainboards are
-based on a baseboard/variant model, where several variant mainboards may share a
-lot of their circuitry and ICs and the commonality between the boards is
-collected into a virtual ``baseboard.`` In that case, the GPIOs which are shared
-between multiple boards are placed in the baseboard's ``gpio.c`` file, while the
-ones that are board-specific go into each variant's ``gpio.c`` file.
-
-## Intel SoCs
-
-Many newer Intel SoCs share a common IP block for GPIOs, and that commonality
-has been taken advantage of in coreboot, which has a large set of macros that
-can be used to describe the configuration of each GPIO pad. This file lives in
-``src/soc/intel/common/block/include/intelblocks/gpio_defs.h``.
-
-### Older Intel SoCs
-
-Baytrail and Braswell, for example, simply expect the mainboard to supply a
-callback, `mainboard_get_gpios` which returns an array of `struct soc_gpio`
-objects, defining the configuration of each pin.
-
-### AMD SoCs
-
-Some AMD SoCs use a list of `struct soc_amd_gpio` objects to define the
-register values configuring each pin, similar to Intel.
-
-### Register details
-
-GPIO configuration registers typically control properties such as:
-1. Input / Output
-2. Pullups / Pulldowns
-3. Termination
-4. Tx / Rx Disable
-5. Which reset signal to use
-6. Native Function / IO
-7. Interrupts
-    * IRQ routing (e.g. on x86, APIC, SCI, SMI)
-    * Edge or Level Triggered
-    * Active High or Active Low
-8. Debouncing
-
-## Configuring GPIOs for pre-ramstage
-
-coreboot provides for several SoC-specific and mainboard-specific callbacks at
-specific points in time, such as bootblock-early, bootblock, romstage entry,
-pre-silicon init, pre-RAM init, or post-RAM init. The GPIOs that are
-configured in either bootblock or romstage, depending on when they are needed,
-are denoted the "early" GPIOs. Some mainboard will use
-``bootblock_mainboard_init()`` to configure their early GPIOs, and this is
-probably a good place to start. Many mainboards will declare their GPIO
-configuration as structs, i.e. (Intel),
-
-```C
-struct pad_config {
-    /* offset of pad within community */
-        int             pad;
-    /* Pad config data corresponding to DW0, DW1,.... */
-        uint32_t        pad_config[GPIO_NUM_PAD_CFG_REGS];
-};
-```
-
-and will usually place these in an array, one for each pad to be configured.
-Mainboards using Intel SoCs can use a library which combines common
-configurations together into a set of macros, e.g.,
-
-```C
-    /* Native function configuration */
-    #define PAD_CFG_NF(pad, pull, rst, func)
-    /* General purpose output, no pullup/down. */
-    #define PAD_CFG_GPO(pad, val, rst)
-    /* General purpose output, with termination specified */
-    #define PAD_CFG_TERM_GPO(pad, val, pull, rst)
-    /* General purpose output, no pullup/down. */
-    #define PAD_CFG_GPO_GPIO_DRIVER(pad, val, rst, pull)
-    /* General purpose input */
-    #define PAD_CFG_GPI(pad, pull, rst)
-```
-etc.
-
-## Configuring GPIOs for ramstage and beyond...
-
-In ramstage, most mainboards will configure the rest of their GPIOs for the
-function they will be performing while the device is active. The goal is the
-same as above in bootblock; another ``static const`` array is created, and the
-rest of the GPIO registers are programmed.
-
-In the baseboard/variant model described above, the baseboard will provide the
-configuration for the GPIOs which are configured identically between variants,
-and will provide a mechanism for a variant to override the baseboard's
-configuration. This is usually done via two tables: the baseboard table and the
-variant's override table.
-
-This configuration is often hooked into the mainboard's `enable_dev` callback,
-defined in its `struct chip_operations`.
-
-## Unconnected and unused pads
-
-In digital electronics, it is generally recommended to tie unconnected GPIOs to
-a defined signal like VCC or GND by setting their direction to output, adding an
-external pull resistor or configuring an internal pull resistor. This is done to
-prevent floating of the pin state, which can cause various issues like EMI,
-higher power usage due to continuously switching logic, etc.
-
-On Intel PCHs from Sunrise Point onwards, termination of unconnected GPIOs is
-explicitly not required, when the input buffer is disabled by setting the bit
-`GPIORXDIS` which effectively disconnects the pad from the internal logic. All
-pads defaulting to GPIO mode have this bit set. However, in the mainboard's
-GPIO configuration the macro `PAD_NC(pad, NONE)` can be used to explicitly
-configure a pad as unconnected.
-
-In case there are no schematics available for a board and the vendor set a
-pad to something like `GPIORXDIS=1`, `GPIOTXDIS=1` with an internal pull
-resistor, an unconnected or otherwise unused pad can be assumed. In this case it
-is recommended to keep the pull resistor, because the external circuit might
-rely on it.
-
-Unconnected pads defaulting to a native function (input and output) usually
-don't need to be configured as GPIO with the `GPIORXDIS` bit set. For clarity
-and documentation purpose the macro may be used as well for them.
-
-Some pads configured as native input function explicitly require external
-pull-ups when being unused, according to the PDGs:
-- eDP_HPD
-- SMBCLK/SMBDATA
-- SML0CLK/SML0DATA/SML0ALERT
-- SATAGP*
-
-When the board was designed correctly, nothing needs to be done for them
-explicitly, while using `PAD_NC(pad, NONE)` can act as documentation. If such a
-pad is missing the external pull resistor due to bad board design, the pad
-should be configured with `PAD_NC(pad, NONE)` anyway to disconnect it
-internally.
-
-## Potential issues (gotchas!)
-
-There are a couple of configurations that you need to especially careful about,
-as they can have a large impact on your mainboard.
-
-The first is configuring a pin as an output, when it was designed to be an
-input. There is a real risk in this case of short-circuiting a component which
-could cause catastrophic failures, up to and including your mainboard!
-
-### 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

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

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

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

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

Documentation/gfx/libgfxinit.md

@@ -1,158 +0,0 @@
-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/index.md

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

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

Documentation/infrastructure/builders.md

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

Documentation/infrastructure/coverity.md

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

Documentation/infrastructure/index.md

@@ -1,20 +0,0 @@
-# Project infrastructure & services
-
-This section contains documentation about our infrastructure
-
-## Services
-
-```{toctree}
-:maxdepth: 1
-
-Project services <services.md>
-Administrator's handbook <admin.md>
-```
-
-## Jenkins builders and builds
-```{toctree}
-:maxdepth: 1
-
-Setting up Jenkins build machines <builders.md>
-Coverity Scan integration <coverity.md>
-```

Documentation/infrastructure/services.md

@@ -1,60 +0,0 @@
-# Accounts on coreboot.org
-
-There are a number of places where you can benefit from creating an account
-in our community. Since there is no single sign-on system in place (at this
-time), they come with their own setup routines.
-
-## Gerrit code review
-We exchange and review patches to the code using our [Gerrit code review
-system](https://review.coreboot.org).
-
-It allows logging in with a Google or GitHub account using OAuth2 as well
-as with any OpenID provider that you may already use.
-
-On the [settings screen](https://review.coreboot.org/settings) you can register
-all your email addresses you intend to use in the context of coreboot
-development so that commits with your email address in them are associated with
-you properly.
-
-Below is a list of its SSH host keys and fingerprints.
-```Bash
-[review.coreboot.org]:29418 ssh-rsa AAAAB3NzaC1yc2EAAAABIwAAAQEAvNDn8qGHlWM/5ndFltStlg3QTc8xvGOgyjxxZByhMZx8LVE4cfgF38WP3euq0avyFy7gAJNghHorXpYKoOzuQPn2WNi5QhyGsUhg7ZJz9hC7Z2gqxxsZF3E7rku4Uj9sN7hWx9fBngxD4z2tP4y/18FTT5XTMcC3Q2sBCOLM0XVAO5R/nb2GO3d27avy+sanKAFEwJHnZ996IoTlU8JJFyi1Y6g30dC2K75oFgCtzntxf++wvrkkKPa+CFQub8fp20shat9WwX9kXjpRjt/Yv9LgqFCaI5ztJvWXicAmbgghGVzbzz4GoSjjF9cxxJF//KTmNb4iGQqmP3Olm27xuw==
-
-[review.coreboot.org]:29418 ecdsa-sha2-nistp256 AAAAE2VjZHNhLXNoYTItbmlzdHAyNTYAAAAIbmlzdHAyNTYAAABBBBzlwf/bFejt4EEz1QmbNOfK/HN1NtdcefrRs5Gs42uGnIvjxsff+vEF3//jCTvFPadoy3DrPsbQB3ioQAcYppk=
-
-[review.coreboot.org]:29418 ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOC3Z32gc+1rJXhKX+SW0vESlXR/h/mhcxd+62B1PWC2
-```
-
-```Bash
-2048 SHA256:WW5prF7YE3MTnkRIxLklr9Gxddj9s5BZKUqWJF5dnTg review.coreboot.org:29418 (RSA)
-256 SHA256:IuLv/DgrBtVn36eMP1zFD0ISAl3IxIoCeiRms6UDhZc review.coreboot.org:29418 (ECDSA)
-256 SHA256:QFZieVHy8dCRl9tDib6qiwELnfa7SVU4ZWJ5VrXoC8k review.coreboot.org:29418 (ED25519)
-```
-
-### https push access
-When using the https URLs to git repositories, you can push with the "HTTP
-Credentials" you can have Gerrit generate for you on that page. By default,
-git uses `$HOME/.netrc` for http authentication data, so add a line there
-stating:
-
-    machine review.coreboot.org login $your-user-name password $your-password
-
-### Gerrit user avatar
-To setup an avatar to show in Gerrit, clone the avatars repository at
-<https://review.coreboot.org/gerrit-avatars.git> and add a file named
-$your-user-ID.jpg (the user ID is a number shown on the [settings screen](https://review.coreboot.org/settings)).
-The image must be provided in JPEG format, must be square and have at most 50000
-bytes.
-
-After you push for review, the system will automatically verify your change
-and, if adhering to these constraints, approve it. You can then immediately
-submit it.
-
-## Issue tracker
-We have an [issue tracker](https://ticket.coreboot.org) that is used for
-coreboot and related code, such as libpayload, as well as for the project's
-infrastructure.
-
-It can be helpful to refer to issues we track there in commit messages:
-
-    Fixes: https://ticket.coreboot.org/issues/$id

Documentation/internals/chip_operations.md

@@ -1,537 +0,0 @@
-# The `chip_operations` Structure in coreboot
-
-## Introduction
-
-The `chip_operations` structure is a fundamental component of coreboot's
-chipset abstraction layer. It provides a standardized interface for chipset-
-specific code to interact with coreboot's device initialization framework.
-This structure enables coreboot to support a wide variety of chipsets
-while maintaining a consistent initialization flow across different hardware
-platforms.
-
-In coreboot's architecture, a "chip" refers to a collection of hardware
-components that form a logical unit, such as a System-on-Chip (SoC),
-a CPU, or a distinct southbridge/northbridge. The `chip_operations`
-structure provides the hooks necessary for coreboot to discover, configure,
-and initialize these components during the boot process.
-
-The `chip_operations` structure is particularly crucial for the ramstage
-portion of coreboot, where it connects the static device tree definitions
-with the actual hardware initialization code. It serves as the bridge
-between the declarative device descriptions and the imperative code that
-brings those devices to life.
-
-
-## Structure Definition
-
-The `chip_operations` structure is defined in `src/include/device/device.h`
-as follows:
-
-```c
-struct chip_operations {
-    void (*enable_dev)(struct device *dev);
-    void (*init)(void *chip_info);
-    void (*final)(void *chip_info);
-    unsigned int initialized : 1;
-    unsigned int finalized : 1;
-    const char *name;
-};
-```
-
-
-### Field Descriptions
-
-- **enable_dev**: A function pointer that takes a `struct device*`
-parameter. This function is called for each device associated with the
-chip during the device enumeration phase (specifically, within the
-`scan_bus` operations triggered by `dev_enumerate`). Its primary
-purpose is to set up device operations (`dev->ops`) based on the
-device's role in the system.
-
-- **init**: A function pointer that takes a `void*` parameter pointing to
-the chip's configuration data (typically cast to a chip-specific struct).
-This function is called during the chip initialization phase
-(`BS_DEV_INIT_CHIPS`), before device enumeration. It usually performs
-early hardware setup needed before individual devices can be configured.
-
-- **final**: A function pointer that takes a `void*` parameter pointing to
-the chip's configuration data (typically cast to a chip-specific struct).
-This function is called during the final table writing phase of coreboot
-initialization (`BS_WRITE_TABLES`), after all devices have been
-initialized. It performs any necessary cleanup or late initialization
-operations.
-
-- **initialized**: A bit flag indicating whether the chip's init function
-has been called.
-
-- **finalized**: A bit flag indicating whether the chip's final function
-has been called.
-
-- **name**: A string containing the human-readable name of the chip, used
-for debugging and logging purposes.
-
-
-## Initialization Sequence and `chip_operations`
-
-The `chip_operations` structure integrates with coreboot's boot state
-machine, which is defined in `src/lib/hardwaremain.c`. The functions in
-this structure are called at specific points during the boot process:
-
-1. **BS_DEV_INIT_CHIPS** state: The `init` function is called for each
-chip in the device tree. This is handled by `dev_initialize_chips()`
-which iterates through all devices, identifies unique chip instances,
-and invokes their `init` functions.
-
-2. **BS_DEV_ENUMERATE** state: During the execution of this state,
-`dev_enumerate()` is called, which triggers bus scanning
-(e.g., `pci_scan_bus`). Within these scan routines, the `enable_dev`
-function is called for devices associated with a chip. This commonly
-assigns the appropriate `device_operations` structure to each device
-based on its type and purpose.
-
-3. **BS_WRITE_TABLES** state: The `final` function is called for each
-chip by `dev_finalize_chips()` after all devices have been initialized
-and just before payloads are loaded.
-
-This sequence ensures that chips can perform necessary setup before their
-individual devices are configured, and also perform cleanup or finalization
-after all devices have been initialized but before the final tables are
-written and the payload is executed.
-
-
-## Relationship Between `chip_operations` and `device_operations`
-
-It's important to understand the distinction and relationship between
-`chip_operations` and `device_operations`:
-
-- **chip_operations**: Operates at the chipset or SoC level, providing
-hooks for chip-wide initialization. It's responsible for the overall
-setup of a collection of devices that belong to the same logical chip.
-
-- **device_operations**: Operates at the individual device level,
-providing functions to manage specific devices within a chip. These
-operations include resource allocation, device initialization, and device-
-specific functionality.
-
-The key relationship is that `chip_operations.enable_dev` is typically
-responsible for assigning the appropriate `device_operations` structure
-to each device based on its type and function. This is where the bridge
-between the chip-level and device-level abstractions occurs.
-
-For example, a typical implementation of the `enable_dev` function might
-look like this:
-
-```c
-static void soc_enable(struct device *dev)
-{
-    if (dev->path.type == DEVICE_PATH_DOMAIN)
-        dev->ops = &pci_domain_ops;
-    else if (dev->path.type == DEVICE_PATH_CPU_CLUSTER)
-        dev->ops = &cpu_bus_ops;
-    else if (dev->path.type == DEVICE_PATH_GPIO)
-        block_gpio_enable(dev);
-    else if (dev->path.type == DEVICE_PATH_PCI &&
-             dev->path.pci.devfn == PCH_DEVFN_PMC)
-        dev->ops = &pmc_ops;
-}
-```
-
-This function examines each device's path type and assigns the appropriate
-operations based on the device's role in the system.
-
-
-## Integration with the Devicetree
-
-The `chip_operations` structure is tightly integrated with coreboot's
-devicetree mechanism. The devicetree is a hierarchical description of the
-hardware platform, defined in `.cb` files (typically `chipset.cb`,
-`devicetree.cb`, and optionally `overridetree.cb`).
-
-In the devicetree, a `chip` directive starts a collection of devices
-associated with a particular chip driver. The path specified with the
-`chip` directive corresponds to a directory in the coreboot source tree
-that contains the chip driver code, including a `chip.c` file that defines
-the `chip_operations` structure for that chip.
-
-For example, a devicetree might contain:
-
-```
-chip soc/intel/cannonlake
-    device domain 0 on
-        device pci 00.0 on end  # Host Bridge
-        device pci 12.0 on end  # Thermal Subsystem
-        # ... more devices ...
-    end
-end
-```
-
-This connects the devices under this chip directive with the
-`chip_operations` structure defined in
-`src/soc/intel/cannonlake/chip.c`:
-
-```c
-struct chip_operations soc_intel_cannonlake_ops = {
-    .name = "Intel Cannonlake",
-    .enable_dev = &soc_enable,
-    .init = &soc_init_pre_device,
-};
-```
-
-During coreboot's build process, the `sconfig` utility processes the
-devicetree files and generates code that links the devices defined in the
-devicetree with their corresponding `chip_operations` structures.
-
-
-## Chip Configuration Data
-
-Each chip typically defines a configuration structure in a `chip.h` file
-within its source directory. This structure contains configuration settings
-that can be specified in the devicetree using `register` directives.
-
-For example, a chip might define a configuration structure like:
-
-```c
-/* In src/soc/intel/cannonlake/chip.h */
-struct soc_intel_cannonlake_config {
-    uint8_t pcie_rp_aspm[CONFIG_MAX_ROOT_PORTS];
-    uint8_t usb2_ports[16];
-    uint8_t usb3_ports[10];
-    /* ... more configuration options ... */
-};
-```
-
-In the devicetree, you would configure these options using register
-directives:
-
-```
-chip soc/intel/cannonlake
-    register "pcie_rp_aspm[0]" = "ASPM_AUTO"
-    register "usb2_ports[5]" = "USB2_PORT_MID(OC_SKIP)"
-    # ... more register settings ...
-
-    device domain 0 on
-        # ... devices ...
-    end
-end
-```
-
-These configuration values are made available to the chip's `init` and
-`final` functions through the `chip_info` parameter, which points to
-an instance of the chip's configuration structure (after appropriate
-casting from `void *`).
-
-
-## Implementation Examples
-
-### Minimal Implementation
-
-Some chips may not need extensive initialization and can provide a
-minimal implementation of the `chip_operations` structure:
-
-```c
-struct chip_operations soc_ucb_riscv_ops = {
-    .name = "UCB RISC-V",
-};
-```
-
-This implementation only provides a name for debugging purposes but
-doesn't define any initialization functions.
-
-
-### Basic Implementation with Initialization
-
-A more typical implementation includes at least initialization hooks:
-
-```c
-struct chip_operations soc_amd_genoa_poc_ops = {
-    .name = "AMD Genoa SoC Proof of Concept",
-    .init = soc_init,
-    .final = soc_final,
-};
-```
-
-The `init` function might perform chip-wide initialization:
-
-```c
-static void soc_init(void *chip_info)
-{
-    default_dev_ops_root.write_acpi_tables = soc_acpi_write_tables;
-    amd_opensil_silicon_init();
-    data_fabric_print_mmio_conf();
-    fch_init(chip_info);
-}
-```
-
-
-### Complete Implementation
-
-A complete implementation includes all three function pointers:
-
-```c
-struct chip_operations soc_intel_xeon_sp_cpx_ops = {
-    .name = "Intel Cooper Lake-SP",
-    .enable_dev = chip_enable_dev,
-    .init = chip_init,
-    .final = chip_final,
-};
-```
-
-The `enable_dev` function would typically assign device operations
-based on device types:
-
-```c
-static void chip_enable_dev(struct device *dev)
-{
-    /* PCI root complex */
-    if (dev->path.type == DEVICE_PATH_DOMAIN)
-        dev->ops = &pci_domain_ops;
-    /* CPU cluster */
-    else if (dev->path.type == DEVICE_PATH_CPU_CLUSTER)
-        dev->ops = &cpu_cluster_ops;
-    /* PCIe root ports */
-    else if (dev->path.type == DEVICE_PATH_PCI &&
-             PCI_SLOT(dev->path.pci.devfn) == PCIE_PORT1_SLOT)
-        dev->ops = &pcie_rp_ops;
-    /* ... other device types ... */
-}
-```
-
-
-### Mainboard Implementation
-
-It's also common for the mainboard-specific code (e.g.,
-`src/mainboard/vendor/board/mainboard.c`) to define its own
-`chip_operations`, often named `mainboard_ops`. The `mainboard_ops.init`
-can perform early board-level setup, and `mainboard_ops.enable_dev` can
-assign operations for devices specific to the mainboard or set default
-operations.
-
-```c
-/* Example from src/mainboard/google/zork/mainboard.c */
-struct chip_operations mainboard_ops = {
-       .enable_dev = mainboard_enable,
-       .init = mainboard_init,
-       .final = mainboard_final,
-};
-```
-
-
-## Device Registration and Discovery
-
-The `chip_operations` structure plays a key role in device registration
-and discovery within coreboot. Here's how it fits into this process:
-
-1. **Static Device Definition**: Devices are statically defined in the
-devicetree files (`chipset.cb`, `devicetree.cb`, `overridetree.cb`).
-
-2. **Code Generation**: The `sconfig` utility processes these files and
-generates code in `build/static.c` that creates the device structures
-and links them to their corresponding chip configuration data.
-
-3. **Chip Initialization**: During the `BS_DEV_INIT_CHIPS` boot state,
-`dev_initialize_chips()` calls each chip's `init` function to perform
-chip-wide setup.
-
-4. **Device Enumeration and Enabling**: During the `BS_DEV_ENUMERATE`
-    boot state, `dev_enumerate()` initiates bus scanning. The scan
-    functions call the associated chip's `enable_dev` function for each
-    device, which assigns the appropriate device operations (`dev->ops`).
-
-5. **Device Configuration and Initialization**: Subsequent boot states
-    (`BS_DEV_RESOURCES`, `BS_DEV_ENABLE`, `BS_DEV_INIT`) configure and
-    initialize the devices according to their assigned device operations.
-
-6. **Chip Finalization**: After all devices have been initialized,
-    `dev_finalize_chips()` calls each chip's `final` function during the
-    `BS_WRITE_TABLES` boot state.
-
-
-## Build Process Integration
-
-The `chip_operations` structures are integrated into the coreboot build
-process through several mechanisms:
-
-1. **Devicetree Processing**: The `sconfig` utility processes the
-devicetree files and generates code that creates and links the device
-structures.
-
-2. **Static Structure Declaration**: Each chip (and often the mainboard)
-    defines its `chip_operations` structure in its respective `.c` file.
-    These structures are collected during the build process.
-
-3. **External References**: The generated code in `build/static.c`
-includes external references to these `chip_operations` structures.
-
-4. **Linking**: The linker collects all the `chip_operations` structures
-and includes them in the final firmware image.
-
-This process ensures that the appropriate chip operations are available
-during the boot process for each chip included in the devicetree.
-
-
-## Best Practices for Implementing `chip_operations`
-
-When implementing the `chip_operations` structure for a new chip,
-follow these best practices:
-
-1. **Provide a Meaningful Name**: The `name` field should be descriptive
-and identify the chip clearly for debugging purposes.
-
-2. **Implement `enable_dev` Correctly**: The `enable_dev` function should
-assign the appropriate device operations based on device types and
-functions. It should handle all device types that might be part of the chip.
-Consider interactions with the mainboard `enable_dev`.
-
-3. **Use Configuration Data**: The `init` and `final` functions should
-make use of the chip configuration data passed via the `chip_info`
-parameter (casting it to the correct type) to configure the chip
-according to the settings specified in the devicetree.
-
-4. **Minimize Dependencies**: The `init` function should minimize
-dependencies on other chips being initialized, as the order of chip
-initialization is not guaranteed.
-
-5. **Handle Resources Properly**: If the chip manages resources (memory
-regions, I/O ports, etc.), ensure that these are properly allocated and
-assigned to devices, usually within the associated `device_operations`.
-
-6. **Implement Error Handling**: Include appropriate error handling in
-the initialization functions to handle hardware initialization failures
-gracefully.
-
-7. **Document Special Requirements**: If the chip has special
-requirements or dependencies, document these clearly in comments or
-accompanying documentation.
-
-
-## Troubleshooting `chip_operations` Issues
-
-When implementing or debugging `chip_operations`, you might encounter
-certain issues:
-
-1. **Missing Device Operations**: If devices are not being initialized
-properly, check that the `enable_dev` function is correctly
-assigning device operations based on device types. Ensure it's being
-called during bus scanning.
-
-2. **Initialization Order Problems**: If a chip's initialization depends
-on another chip being initialized first, you might need to adjust the
-initialization sequence or add explicit dependencies, possibly using
-boot state callbacks if necessary.
-
-3. **Configuration Data Issues**: If chip configuration settings are not
-being applied correctly, check that the configuration structure is
-correctly defined in `chip.h`, that the register values in the
-devicetree match the expected format, and that the `chip_info` pointer
-is cast correctly in the `init`/`final` functions.
-
-4. **Build Errors**: If you encounter build errors related to
-`chip_operations`, check that the structure is correctly defined and
-that all required symbols are properly exported and linked. Check for
-conflicts if multiple files define the same symbol.
-
-5. **Runtime Failures**: If the chip initialization fails at runtime,
-add debug logging (using `printk`) to the `init`, `enable_dev`, and
-`final` functions to identify the specific point of failure.
-
-
-## Advanced `chip_operations` Patterns
-
-### Hierarchical Chip Initialization
-
-For complex chips with multiple components, you can implement a
-hierarchical initialization pattern within the `init` function:
-
-```c
-static void soc_init(void *chip_info)
-{
-    /* Initialize common components first */
-    common_init(chip_info);
-
-    /* Initialize specific blocks */
-    pcie_init(chip_info);
-    usb_init(chip_info);
-    sata_init(chip_info);
-
-    /* Final SoC-wide configuration */
-    power_management_init(chip_info);
-}
-```
-
-
-### Variant Support
-
-For chips with multiple variants, you can implement variant detection
-and specific initialization within the `init` function:
-
-```c
-static void soc_init(void *chip_info)
-{
-    uint32_t variant = read_chip_variant();
-
-    /* Common initialization */
-    common_init(chip_info);
-
-    /* Variant-specific initialization */
-    switch (variant) {
-    case VARIANT_A:
-        variant_a_init(chip_info);
-        break;
-    case VARIANT_B:
-        variant_b_init(chip_info);
-        break;
-    default:
-        printk(BIOS_WARNING, "Unknown variant %u\\n", variant);
-        break;
-    }
-}
-```
-
-
-### Conditional Feature Initialization
-
-You can conditionally initialize features based on configuration settings
-passed via `chip_info`:
-
-```c
-static void soc_init(void *chip_info)
-{
-    struct soc_config *config = chip_info;
-
-    /* Always initialize core components */
-    core_init();
-
-    /* Conditionally initialize optional features */
-    if (config->enable_xhci)
-        xhci_init(config);
-
-    if (config->enable_sata)
-        sata_init(config);
-
-    if (config->enable_pcie)
-        pcie_init(config);
-}
-```
-
-
-## Conclusion
-
-The `chip_operations` structure is a fundamental component of coreboot's
-chipset abstraction layer. It provides a standardized interface for chipset-
-specific code to interact with coreboot's device initialization framework,
-enabling support for a wide variety of chipsets while maintaining a
-consistent initialization flow.
-
-By implementing the `chip_operations` structure for a specific chipset
-(and often for the mainboard), developers can integrate their
-hardware-specific code with coreboot's device enumeration, configuration,
-and initialization process. This structure serves as the bridge between
-the declarative device descriptions in the devicetree and the imperative
-code that initializes the hardware.
-
-Understanding the `chip_operations` structure and its role in the
-coreboot boot process is essential for anyone working on chipset or
-mainboard support in coreboot. By following the best practices and
-patterns outlined in this document, developers can create robust and
-maintainable hardware support code that integrates seamlessly with the
-coreboot firmware ecosystem.

Documentation/internals/device_operations.md

@@ -1,696 +0,0 @@
-# Device Operations in coreboot Firmware
-
-## Introduction
-
-The `device_operations` structure is a cornerstone of coreboot's
-hardware abstraction layer. It represents a set of function pointers
-defining how the firmware interacts with a specific hardware device
-during various boot stages. This structure lets the coreboot
-architecture establish a consistent interface for device initialization,
-configuration, resource allocation, and ACPI table generation, while
-allowing device-specific implementations behind this common interface.
-
-At its core, `device_operations` applies the strategy pattern in
-systems programming. It decouples algorithms (device operations) from
-the core boot sequence, allowing devices to define their own behavior
-while the boot process follows a predictable flow. This pattern enables
-coreboot to support a wide range of hardware platforms with minimal
-changes to the core boot sequence code.
-
-
-## Structure Definition
-
-The `device_operations` structure, defined in
-`src/include/device/device.h`, consists of several function pointers,
-each representing a specific operation performed on a device during
-boot:
-
-```c
-struct device_operations {
-    void (*read_resources)(struct device *dev);
-    void (*set_resources)(struct device *dev);
-    void (*enable_resources)(struct device *dev);
-    void (*init)(struct device *dev);
-    void (*final)(struct device *dev);
-    void (*scan_bus)(struct device *bus);
-    void (*enable)(struct device *dev);
-    void (*vga_disable)(struct device *dev);
-    void (*reset_bus)(struct bus *bus);
-
-    int (*get_smbios_data)(struct device *dev, int *handle,
-        unsigned long *current);
-    void (*get_smbios_strings)(struct device *dev, struct smbios_type11 *t);
-
-    unsigned long (*write_acpi_tables)(const struct device *dev,
-        unsigned long start, struct acpi_rsdp *rsdp);
-    void (*acpi_fill_ssdt)(const struct device *dev);
-    const char *(*acpi_name)(const struct device *dev);
-    const char *(*acpi_hid)(const struct device *dev);
-
-    const struct pci_operations *ops_pci;
-    const struct i2c_bus_operations *ops_i2c_bus;
-    const struct spi_bus_operations *ops_spi_bus;
-    const struct smbus_bus_operations *ops_smbus_bus;
-    const struct pnp_mode_ops *ops_pnp_mode;
-    const struct gpio_operations *ops_gpio;
-    const struct mdio_bus_operations *ops_mdio;
-};
-```
-
-
-### Core Resource Management Functions
-
-*   `read_resources`: Discovers and collects resources required by the
-    device (I/O ports, memory regions, IRQs, etc.). This typically
-    involves reading configuration registers or static device tree
-    information.
-*   `set_resources`: Assigns finalized resources to the device after the
-    resource allocation phase. This writes the assigned base addresses,
-    lengths, and other parameters back to the device structure, but not
-    necessarily to hardware registers yet.
-*   `enable_resources`: Activates the assigned resources in the device's
-    hardware registers (e.g., writing to PCI BARs, enabling memory
-    decoding).
-
-
-### Device Lifecycle Functions
-
-*   `init`: Performs device-specific initialization, often requiring
-    access to the device's assigned resources. This is called after
-    resources have been enabled.
-*   `final`: Executes final setup or cleanup operations before the
-    payload is loaded. This is useful for tasks that depend on other
-    devices being initialized.
-*   `enable`: Enables the device in the hardware, often setting bits in
-    configuration registers to make the device active. Called after
-    `enable_resources`.
-
-
-### Bus Management Functions
-
-*   `scan_bus`: Enumerates child devices on a bus device (e.g., scanning
-    a PCI bus for devices, probing I2C devices). Only applicable to
-    devices that act as buses.
-*   `reset_bus`: Resets all devices on a specific bus.
-*   `vga_disable`: Disables VGA decoding on a PCI device when another VGA
-    device is active. Used to manage legacy VGA resources.
-
-
-### System Table Generation Functions
-
-*   `get_smbios_data`: Provides SMBIOS data specific to the device for
-    Type 9 (System Slots) or Type 41 (Onboard Devices Extended
-    Information).
-*   `get_smbios_strings`: Supplies string information for SMBIOS tables,
-    often related to the data provided by `get_smbios_data`.
-*   `write_acpi_tables`: Generates device-specific ACPI tables (like SSDTs)
-    or contributes data to system-wide tables.
-*   `acpi_fill_ssdt`: Adds device-specific objects (scopes, methods, data)
-    to the Secondary System Description Table (SSDT).
-*   `acpi_name`: Returns the ACPI name for the device (e.g.,
-    `\_SB.PCI0.GFX0`). This defines the device's path in the ACPI
-    namespace.
-*   `acpi_hid`: Returns the ACPI Hardware ID (HID) for the device (e.g.,
-    `PNP0A08`). Used by the OS to match drivers.
-
-
-### Bus-Specific Operation Pointers
-
-These fields point to bus-specific operation structures when a device
-functions as a bus controller (or exposes bus-like functionality). See
-the "Bus-Specific Operations" section for details.
-
-*   `ops_pci`: Operations for PCI configuration space access.
-*   `ops_i2c_bus`: Operations for I2C bus transactions (read, write,
-    transfer).
-*   `ops_spi_bus`: Operations for SPI bus transactions.
-*   `ops_smbus_bus`: Operations for SMBus transactions.
-*   `ops_pnp_mode`: Operations for Plug-and-Play device configuration.
-*   `ops_gpio`: Operations for GPIO control (get, set, configure
-    direction/pulls).
-*   `ops_mdio`: Operations for MDIO (Management Data Input/Output) bus
-    access, used for Ethernet PHYs.
-
-
-## Device Lifecycle in coreboot
-
-The function pointers in `device_operations` are called at specific
-stages during the boot process, following a sequence defined in
-coreboot's boot state machine (`src/lib/hardwaremain.c`). Understanding
-this lifecycle helps developers implement appropriate behavior for each
-function pointer.
-
-
-### Boot Sequence and Device Operations
-
-coreboot's main device initialization sequence involves these boot
-states:
-
-1.  **BS_DEV_INIT_CHIPS** (`dev_initialize_chips()`): Initializes chip
-    drivers (`chip_operations`).
-2.  **BS_DEV_ENUMERATE** (`dev_enumerate()`): Discovers and enumerates
-    devices.
-    *   Calls `scan_bus()` for each bus to detect child devices.
-3.  **BS_DEV_RESOURCES** (`dev_configure()`): Allocates resources across
-    all enumerated devices.
-    *   Calls `read_resources()` for each device to discover required
-        resources.
-    *   Calls `set_resources()` for each device to assign allocated
-        resources back to the `struct device`.
-4.  **BS_DEV_ENABLE** (`dev_enable()`): Enables devices and their
-    resources.
-    *   Calls `enable_resources()` for each device to activate assigned
-        resources in hardware.
-    *   Calls `enable()` for each device to perform general hardware
-        enablement.
-5.  **BS_DEV_INIT** (`dev_initialize()`): Initializes devices.
-    *   Calls `init()` for each device to perform device-specific setup.
-6.  **BS_POST_DEVICE** (`dev_finalize()`): Finalizes devices before
-    payload loading.
-    *   Calls `final()` for each device for any final cleanup or setup.
-
-The sequence is primarily driven by the `boot_states` array in
-`src/lib/hardwaremain.c`:
-
-```c
-static struct boot_state boot_states[] = {
-    /* ... other states ... */
-    BS_INIT_ENTRY(BS_PRE_DEVICE, bs_pre_device),
-    BS_INIT_ENTRY(BS_DEV_INIT_CHIPS, bs_dev_init_chips),
-    BS_INIT_ENTRY(BS_DEV_ENUMERATE, bs_dev_enumerate),
-    BS_INIT_ENTRY(BS_DEV_RESOURCES, bs_dev_resources),
-    BS_INIT_ENTRY(BS_DEV_ENABLE, bs_dev_enable),
-    BS_INIT_ENTRY(BS_DEV_INIT, bs_dev_init),
-    BS_INIT_ENTRY(BS_POST_DEVICE, bs_post_device),
-    /* ... other states ... */
-};
-```
-
-Later stages include ACPI and SMBIOS table generation, where functions
-like `write_acpi_tables()`, `acpi_fill_ssdt()`, `get_smbios_data()`, and
-`get_smbios_strings()` are invoked as part of the table construction
-process.
-
-
-## Inheritance and Code Reuse Patterns
-
-The `device_operations` structure enables several patterns for code
-reuse:
-
-
-### 1. Default Implementations
-
-coreboot provides default implementations for common device types (like
-root devices, PCI devices, PCI bridges), which can be used directly or
-extended. Chip or mainboard code often assigns these defaults if no
-specific driver is found.
-
-```c
-/* From src/device/root_device.c */
-struct device_operations default_dev_ops_root = {
-    .read_resources   = noop_read_resources,
-    .set_resources    = noop_set_resources,
-    .scan_bus         = scan_static_bus,
-    .reset_bus        = root_dev_reset,
-#if CONFIG(HAVE_ACPI_TABLES)
-    .acpi_name        = root_dev_acpi_name,
-#endif
-};
-```
-
-
-### 2. No-op Functions
-
-Simple shim functions (often static inline) are provided for cases where
-a device doesn't need to implement specific operations. Using these avoids
-leaving function pointers NULL.
-
-```c
-/* From src/include/device/device.h */
-static inline void noop_read_resources(struct device *dev) {}
-static inline void noop_set_resources(struct device *dev) {}
-```
-
-
-### 3. Chain of Responsibility / Delegation
-
-Some implementations delegate to parent devices or use helper functions
-when they can't handle an operation themselves or when common logic can
-be shared. For example, ACPI name generation often traverses up the
-device tree.
-
-```c
-/* Simplified example logic */
-const char *acpi_device_name(const struct device *dev)
-{
-    const char *name = NULL;
-    const struct device *pdev = dev;
-
-    /* Check for device specific handler */
-    if (dev->ops && dev->ops->acpi_name) {
-        name = dev->ops->acpi_name(dev);
-        if (name)
-            return name; /* Device handled it */
-    }
-
-    /* Walk up the tree to find if any parent can provide a name */
-    while (pdev->upstream && pdev->upstream->dev) {
-        pdev = pdev->upstream->dev;
-        if (pdev->ops && pdev->ops->acpi_name) {
-            /* Note: Parent's acpi_name might handle the original child 'dev' */
-            name = pdev->ops->acpi_name(dev);
-            if (name)
-                return name; /* Parent handled it */
-        }
-    }
-
-    /* Fallback or default logic if needed */
-    return NULL;
-}
-```
-This pattern allows parent devices (like buses) to provide default
-behavior or naming schemes if a child device doesn't specify its own.
-
-
-## Implementation Examples
-
-These examples show typical `device_operations` assignments. Actual
-implementations might involve more conditional compilation based on
-Kconfig options.
-
-
-### PCI Device Operations (Default)
-
-```c
-/* From src/device/pci_device.c */
-struct device_operations default_pci_ops_dev = {
-    .read_resources   = pci_dev_read_resources,
-    .set_resources    = pci_dev_set_resources,
-    .enable_resources = pci_dev_enable_resources,
-#if CONFIG(HAVE_ACPI_TABLES)
-    .write_acpi_tables = pci_rom_write_acpi_tables,
-    .acpi_fill_ssdt    = pci_rom_ssdt,
-#endif
-    .init             = pci_dev_init,
-    /* Assigns PCI-specific operations */
-    .ops_pci          = &pci_dev_ops_pci,
-};
-```
-
-
-### CPU Cluster Operations
-
-```c
-/* From src/soc/intel/alderlake/chip.c (representative example) */
-static struct device_operations cpu_bus_ops = {
-    .read_resources   = noop_read_resources,
-    .set_resources    = noop_set_resources,
-    .enable_resources = cpu_set_north_irqs,
-#if CONFIG(HAVE_ACPI_TABLES)
-    .acpi_fill_ssdt = cpu_fill_ssdt,
-#endif
-    /* CPU clusters often don't need scan_bus, init, etc. */
-};
-```
-
-
-### GPIO Controller Operations
-
-```c
-/* From src/soc/intel/common/block/gpio/gpio_dev.c */
-static struct gpio_operations gpio_ops = {
-    .get         = gpio_get,
-    .set         = gpio_set,
-    /* ... other GPIO functions ... */
-};
-
-struct device_operations block_gpio_ops = {
-    .read_resources = noop_read_resources,
-    .set_resources  = noop_set_resources,
-    /* Assigns GPIO-specific operations */
-    .ops_gpio      = &gpio_ops,
-};
-```
-
-
-## Registration and Discovery
-
-How are `device_operations` structures associated with `struct device`
-instances?
-
-
-### 1. Static Assignment (via `chip_operations`)
-
-For devices known at build time (defined in devicetree.cb), the
-`device_operations` structure is often assigned in the SOC's or
-mainboard's `chip_operations->enable_dev()` function based on the
-device path type or other properties.
-
-```c
-/* Example from src/soc/intel/alderlake/chip.c */
-static void soc_enable(struct device *dev)
-{
-    /* Assign ops based on the device's role in the tree */
-    if (dev->path.type == DEVICE_PATH_DOMAIN)
-        dev->ops = &pci_domain_ops; /* Handles PCI domain resources */
-    else if (dev->path.type == DEVICE_PATH_CPU_CLUSTER)
-        dev->ops = &cpu_bus_ops;   /* Handles CPU cluster setup */
-    else if (dev->path.type == DEVICE_PATH_GPIO)
-        block_gpio_enable(dev); /* Assigns block_gpio_ops */
-    /* ... other assignments for specific PCI devices, etc. ... */
-}
-```
-The `enable_dev` function is part of `struct chip_operations`, which
-handles broader chip-level initialization (see "Relationship with
-`chip_operations`" section).
-
-
-### 2. Dynamic Detection (PCI Drivers)
-
-For PCI devices discovered during bus scanning (`scan_bus`), coreboot
-looks through a list of registered PCI drivers (`_pci_drivers` array)
-to find one matching the device's vendor and device IDs.
-
-```c
-/* Logic from src/device/pci_device.c::set_pci_ops() */
-static void set_pci_ops(struct device *dev)
-{
-    struct pci_driver *driver;
-
-    /* Check if ops already assigned (e.g., by chip_ops->enable_dev) */
-    if (dev->ops)
-        return;
-
-    /* Look through registered PCI drivers */
-    for (driver = &_pci_drivers[0]; driver != &_epci_drivers[0]; driver++) {
-        if ((driver->vendor == dev->vendor) &&
-            device_id_match(driver, dev->device)) {
-            /* Found a matching driver, assign its ops */
-            dev->ops = (struct device_operations *)driver->ops;
-            printk(BIOS_SPEW, "%s: Assigned ops from driver for %04x:%04x\n",
-                   dev_path(dev), driver->vendor, driver->device);
-            return; /* Stop searching */
-        }
-    }
-
-    /* Fall back to default operations if no specific driver found */
-    if (!dev->ops) {
-        if ((dev->hdr_type & 0x7f) == PCI_HEADER_TYPE_BRIDGE) {
-            dev->ops = get_pci_bridge_ops(dev); /* Special ops for bridges */
-        } else {
-            dev->ops = &default_pci_ops_dev; /* Default for normal devices */
-        }
-        printk(BIOS_SPEW, "%s: Assigned default PCI ops\n", dev_path(dev));
-    }
-}
-```
-
-
-## Build Process Integration
-
-The `device_operations` structures are integrated into the coreboot
-build process:
-
-1.  **Static Device Tree**: The mainboard's `devicetree.cb` defines the
-    initial device hierarchy. The build process converts this into C
-    code (`static.c`) containing `struct device` instances.
-2.  **PCI Driver Registration**: PCI drivers (containing their own
-    `device_operations`) register themselves using the `__pci_driver`
-    linker set macro.
-
-    ```c
-    /* Example pattern */
-    struct pci_driver example_pci_driver __pci_driver = {
-        .ops    = &example_device_ops, /* Pointer to device_operations */
-        .vendor = VENDOR_ID,
-        .device = DEVICE_ID, /* Or .devices for a list */
-    };
-    ```
-3.  **Linking**: The build system collects all structures placed in the
-    `__pci_driver` section and creates the `_pci_drivers` array used by
-    `set_pci_ops()`. It ensures all necessary code (default ops, driver
-    ops, core device functions) is linked into the final firmware image.
-
-
-## Relationship with `chip_operations`
-
-It's important to distinguish `device_operations` from
-`chip_operations` (defined in `src/include/chip.h`).
-
-*   `chip_operations`: Defines operations related to the overall chipset
-    or mainboard logic. It includes functions called earlier in the boot
-    process, like `enable_dev`, `init`, and `final`.
-    *   `chip_operations->enable_dev()` is crucial as it often performs
-        initial setup for static devices and is the primary place where
-        `device_operations` pointers are *assigned* for non-PCI devices
-        based on their path or type.
-    *   `chip_operations->init()` runs during `BS_DEV_INIT_CHIPS`, before
-        most `device_operations` functions.
-*   `device_operations`: Defines operations for *individual* devices
-    within the device tree. These are called *after* the corresponding
-    `chip_operations` stage and operate on a specific `struct device`.
-
-Essentially, `chip_operations` sets the stage at the SoC/mainboard level,
-including assigning the correct `device_operations` to static devices,
-while `device_operations` handles the specific actions for each device
-later in the boot process.
-
-
-## Bus-Specific Operations
-
-The `ops_*` pointers within `struct device_operations` (e.g., `ops_pci`,
-`ops_i2c_bus`, `ops_spi_bus`, `ops_gpio`) provide a way for devices that
-act as bus controllers or expose bus-like interfaces to offer
-standardized access methods.
-
-*   **Purpose:** They abstract the low-level details of interacting with
-    that specific bus type. For example, a PCI host bridge device will
-    implement `struct pci_operations` via its `ops_pci` pointer,
-    allowing other code to perform PCI config reads/writes through it
-    without knowing the exact hardware mechanism. Similarly, an I2C
-    controller device implements `struct i2c_bus_operations` via
-    `ops_i2c_bus` to provide standard `read`, `write`, and `transfer`
-    functions for that bus segment.
-*   **Usage:** Code needing to interact with a bus first finds the
-    controller `struct device` in the tree, then accesses the relevant
-    bus operations through the appropriate `ops_*` pointer, passing the
-    target address or parameters. For instance, to talk to an I2C device
-    at address `0x50` on the bus controlled by `i2c_controller_dev`, one
-    might call:
-    `i2c_controller_dev->ops->ops_i2c_bus->transfer(...)`. Helper
-    functions often wrap this access pattern.
-*   **Implementation:** The structures like `struct pci_operations`,
-    `struct i2c_bus_operations`, etc., are defined in corresponding
-    header files (e.g., `src/include/device/pci_ops.h`,
-    `src/include/drivers/i2c/i2c_bus.h`). Devices acting as controllers
-    provide concrete implementations of these functions, tailored to their
-    hardware.
-
-This mechanism allows coreboot to manage diverse bus types using a
-consistent device model, where the controller device itself exposes the
-necessary functions for interacting with devices on its bus.
-
-
-## Best Practices
-
-When implementing `device_operations`:
-
-1.  **Leverage Defaults/No-ops**: Use default or no-op implementations
-    whenever possible. Only override functions that require custom
-    behavior for your specific device.
-2.  **Error Handling**: Check return values from functions called within
-    your ops implementations and handle errors gracefully (e.g., log an
-    error, return an error code if applicable).
-3.  **Resource Management**: In `read_resources`, accurately declare all
-    resources (MMIO, I/O ports, IRQs) your device needs, specifying
-    flags like fixed vs. alignment, or bridge vs. standard device.
-    Incorrect resource declaration is a common source of issues.
-4.  **Initialization Order**: Be mindful of dependencies in `init`. If
-    your device relies on another device being fully initialized, consider
-    deferring that part of the initialization to the `final` callback,
-    which runs later.
-5.  **Minimal Implementation**: Only implement the functions relevant to
-    your device type. A simple MMIO device might only need
-    `read_resources`, `set_resources`, `enable_resources`, and perhaps
-    ACPI functions. A bus device additionally needs `scan_bus`.
-6.  **Bus Operations**: If implementing a bus controller, correctly
-    implement the corresponding bus operations structure (e.g.,
-    `struct pci_operations`, `struct i2c_bus_operations`) and assign it
-    to the appropriate `ops_*` field.
-7.  **ACPI/SMBIOS**: If the device needs OS visibility via ACPI or
-    SMBIOS, implement the relevant functions (`acpi_name`, `acpi_hid`,
-    `acpi_fill_ssdt`, `get_smbios_data`, etc.). Ensure ACPI names and
-    HIDs are correct according to specifications and platform needs.
-
-
-## Logging and Debugging
-
-Use coreboot's logging facilities (`printk`) within your `device_operations`
-functions to provide visibility during development and debugging. Use
-appropriate log levels (e.g., `BIOS_DEBUG`, `BIOS_INFO`, `BIOS_ERR`).
-
-```c
-static void example_device_init(struct device *dev)
-{
-    printk(BIOS_DEBUG, "%s: Initializing device at %s\n", __func__,
-           dev_path(dev));
-
-    /* ... Device initialization code ... */
-    if (/* some condition */) {
-        printk(BIOS_SPEW, "%s: Condition met, applying setting X\n",
-               dev_path(dev));
-        /* ... */
-    }
-
-    if (/* error condition */) {
-        printk(BIOS_ERR, "%s: Failed to initialize feature Y!\n",
-               dev_path(dev));
-        /* Handle error */
-    }
-
-    printk(BIOS_DEBUG, "%s: Initialization complete for %s\n", __func__,
-           dev_path(dev));
-}
-```
-Consistent logging helps trace the boot process and pinpoint where issues
-occur.
-
-
-## Common Troubleshooting
-
-*   **Missing Resource Declarations**:
-    *   *Problem*: Device fails to function, or conflicts arise because a
-        required resource (MMIO range, I/O port, IRQ) was not declared
-        in `read_resources`. The resource allocator is unaware of the
-        need.
-    *   *Solution*: Verify that `read_resources` correctly calls functions
-        like `pci_dev_read_resources` or manually adds all necessary
-        resources using functions like `mmio_resource()`,
-        `io_resource()`, etc. Check PCI BARs or device datasheets.
-*   **Initialization Order Issues**:
-    *   *Problem*: `init()` fails because it depends on another device
-        that hasn't been fully initialized yet (e.g., accessing a shared
-        resource like SMBus before the SMBus controller is ready).
-    *   *Solution*: Move the dependent initialization code to the `final`
-        callback if possible. Alternatively, ensure the dependency is met
-        by careful ordering in the device tree or using boot state
-        callbacks if necessary for complex scenarios.
-*   **Resource Conflicts**:
-    *   *Problem*: Boot fails during resource allocation, or devices
-        misbehave because multiple devices requested the same
-        non-sharable resource (e.g., conflicting fixed MMIO regions).
-    *   *Solution*: Review resource declarations in `read_resources` across
-        all relevant devices. Ensure fixed resources don't overlap. Check
-        if bridge windows are correctly defined and large enough. Use
-        coreboot's resource reporting logs to identify overlaps.
-*   **ACPI Table Generation Errors**:
-    *   *Problem*: The operating system fails to recognize the device,
-        assigns the wrong driver, or the device doesn't function correctly
-        (e.g., power management issues).
-    *   *Solution*: Double-check the `acpi_name`, `acpi_hid`, `_CRS`
-        (generated from assigned resources), and `acpi_fill_ssdt`
-        implementations. Verify names match the ACPI hierarchy and HIDs
-        match expected driver bindings. Ensure SSDT methods correctly
-        access hardware. Use OS debugging tools (e.g., `acpidump`, Device
-        Manager errors) to diagnose.
-*   **Incorrect `ops` Pointer Assigned**:
-    *   *Problem*: Device behaves incorrectly because the wrong
-        `device_operations` structure was assigned (e.g., default PCI ops
-        assigned to a device needing a specific driver's ops).
-    *   *Solution*: Check the logic in `chip_operations->enable_dev` (for
-        static devices) or the PCI driver registration (`__pci_driver`
-        macro and `set_pci_ops` fallback logic) to ensure the correct
-        `ops` structure is being selected and assigned based on device
-        type, path, or PCI ID. Add debug prints to verify which `ops`
-        structure is assigned.
-
-
-## Advanced Usage
-
-### Complex Device Hierarchies
-
-For devices with non-standard interactions or complex initialization,
-custom `device_operations` can be created, often inheriting from defaults
-but overriding specific functions.
-
-```c
-static void advanced_device_init(struct device *dev)
-{
-    /* First, perform standard PCI init */
-    pci_dev_init(dev);
-
-    /* Then, add custom initialization steps */
-    printk(BIOS_DEBUG, "%s: Performing advanced init\n", dev_path(dev));
-    /* ... custom register writes, configuration ... */
-}
-
-static const char *advanced_device_acpi_name(const struct device *dev)
-{
-    /* Provide a custom ACPI name based on some property */
-    if (/* condition */)
-        return "ADV0001";
-    else
-        return "ADV0002";
-}
-
-/* Combine default and custom operations */
-static struct device_operations advanced_device_ops = {
-    /* Inherit resource handling from default PCI ops */
-    .read_resources   = pci_dev_read_resources,
-    .set_resources    = pci_dev_set_resources,
-    .enable_resources = pci_dev_enable_resources,
-
-    /* Override init */
-    .init             = advanced_device_init,
-
-    /* Override ACPI naming */
-    .acpi_name        = advanced_device_acpi_name,
-    /* Other functions might use defaults or no-ops */
-};
-```
-
-### Dynamic Configuration based on Probing
-
-Some `init` or other op implementations might probe the device's
-capabilities or read configuration data (e.g., from SPD, VPD, or straps)
-and alter their behavior accordingly.
-
-```c
-static void conditional_device_init(struct device *dev)
-{
-    uint8_t feature_flags;
-
-    /* Read capability register from the device */
-    feature_flags = pci_read_config8(dev, EXAMPLE_CAP_REG);
-
-    printk(BIOS_DEBUG, "%s: Feature flags: 0x%02x\n", dev_path(dev),
-           feature_flags);
-
-    /* Conditional initialization based on detected features */
-    if (feature_flags & FEATURE_X_ENABLED) {
-        printk(BIOS_INFO, "%s: Initializing Feature X\n", dev_path(dev));
-        init_feature_x(dev);
-    }
-    if (feature_flags & FEATURE_Y_ENABLED) {
-        printk(BIOS_INFO, "%s: Initializing Feature Y\n", dev_path(dev));
-        init_feature_y(dev);
-    }
-}
-```
-
-
-## Conclusion
-
-The `device_operations` structure is a powerful abstraction mechanism in
-coreboot. It enables consistent handling of diverse hardware while
-allowing for device-specific behavior. By providing a standard interface
-for device operations throughout the boot process, it simplifies the
-codebase, enhances maintainability, and provides the extensibility needed
-to support new hardware platforms.
-
-Understanding this structure, its relationship with `chip_operations`,
-and its role in the boot process is essential for coreboot developers,
-particularly when adding support for new devices or debugging hardware
-initialization issues. By following the patterns and best practices
-outlined here, developers can create robust and reusable device driver
-implementations that integrate smoothly into the coreboot architecture.

Documentation/internals/devicetree.md

@@ -1,684 +0,0 @@
-# Devicetree
-
-## Introduction to the coreboot devicetree
-
-The first thing that may come to mind when one hears "DeviceTree" is a
-different sort of description file that is generally passed to the Linux
-kernel to describe a system's components. Both that devicetree and
-coreboot's devicetree serve fundamentally the same purpose, but are
-otherwise unrelated and have completely different syntax. The term
-devicetree was used long before either version was created, and was
-initially used in coreboot as a generic term.
-
-coreboot's devicetree's main use is to define and describe the runtime
-configuration and settings of the hardware on a board, chip or device
-level. It defines which of the functions of the chips on the board are
-enabled, and how they're configured.
-
-The devicetree file is parsed during the build process by a utility
-named `sconfig`, which translates the devicetree into a tree of C
-structures containing the included devices. This code is placed in the
-file `static.c` and a couple of header files, all under the `build`
-directory. This file is then built into the binaries for the various
-coreboot stages and is referred to during the coreboot boot process.
-
-For the early stages of the coreboot boot process, the data that is
-generated by `sconfig` is a useful resource, but this structure is the
-critical architectural glue of ramstage. This structure gets filled in
-with pointers to every chip's initialization code, allowing ramstage to
-find and initialize those devices through the `chip_operations`
-structures.
-
-
-### History of coreboot's devicetree
-
-The initial devicetree in coreboot was introduced in 2003 by Ron Minnich
-as a part of the linuxbios config file, 'config.lb'. At this point both
-the devicetree and config options were in the same file. In 2009,
-when Kconfig was added into the coreboot build, devicetree was split
-out into its own file for each mainboard in a commit with this message:
-
-```text
-devicetree.cb
-
-The devicetree that formerly resided in src/mainboard/*/*/Config.lb.
-
-Just without the build system crap
-```
-
-The devicetree structure was initially mainly used only in ramstage for
-PCI device enumeration, configuration and resource allocation. It has
-since expanded for use in the pre-ram stages as a read-only structure.
-
-The language used in the devicetree has been expanded greatly since it
-was first introduced as well, adding new features every year or so.
-
-
-### Devicetree Registers
-
-In coreboot, the devicetree register setting is one of the two main
-methods used to configure a board's properties. In this way, devicetree
-is similar in function to Kconfig. It's more flexible in many ways as
-it can specify not only single values, but also arrays or structures.
-It's also even more static than Kconfig because there's no update
-mechanism for it other than editing the devicetree files.
-
-Chip-specific configuration values are often set using `register`
-definitions within a `chip` block, corresponding to a `struct` defined
-in the chip's `chip.h` file.
-
-For example, in a `chip drivers/gpio/acpi` block, you might set a GPE:
-
-```text
-register "gpe0_sts" = "0x42"
-```
-
-
-### Adding new static configuration options: Devicetree or Kconfig
-
-When adding options for a new board or chip, there is frequently a
-decision that needs to be made about how the option should be added.
-Using the devicetree or Kconfig are the two typical methods of
-build-time configuration. Below are some general guidelines on when to
-use each.
-
-Kconfig should be used if the option configures the build in a Makefile,
-or if the option is something that should be user selectable. Kconfig
-is also preferred if the configuration is a global option and not limited
-to a single chip. Another thing Kconfig excels at is handling decisions
-based on other configuration options, which devicetree cannot do.
-
-Devicetree should obviously be used to define the hardware hierarchy.
-It's also preferred if the option is only used in C code and is static
-for a mainboard, or if the option is chip-specific. As mentioned
-earlier, devicetree registers can also define structures or arrays,
-which Kconfig cannot.
-
-Both Kconfig and devicetree can be used in C code for runtime
-configuration, but there's a significant difference in how they are
-handled. Because Kconfig generates a `#define` for the choice, the
-compiler can eliminate code paths not used by the option. Devicetree
-options, however, are actual runtime selections, and the code for all
-choices remains in the final build.
-
-
-## Basic Devicetree Syntax
-
-The coreboot devicetree uses a custom language parsed by the `sconfig`
-utility. Here's a brief overview of the main keywords and concepts:
-
-*   **`chip <directory>`**: Defines a collection of devices associated
-    with the code in the specified directory. `sconfig` may also parse a
-    `chip.h` file within this directory for register definitions.
-*   **`device <type> <id> [on|off] [alias <name>] ... end`**: Defines a
-    specific hardware device.
-    *   `<type>`: Specifies the device type (e.g., `pci`, `cpu_cluster`,
-        `i2c`).
-    *   `<id>`: A unique identifier for the device within its type/bus
-        (e.g., PCI BDF `17.0`, I2C address `0x50`).
-    *   `on`/`off`: Enables or disables the device definition.
-    *   `alias <name>`: Assigns a human-readable alias for referencing
-        this device elsewhere (often used in `chipset.cb`).
-    *   `end`: Marks the end of the device definition block. Registers
-        and other properties are defined between `device` and `end`.
-*   **`register "<name>" = <value>`**: Sets the value of a configuration
-    register defined in the corresponding `chip.h` structure. The value
-    can be a number, string, or complex structure initialization.
-*   **`probe <field> <option>`**: Used for firmware configuration
-    (`fw_config`), indicating a setting should be probed at runtime.
-*   **`ops "<identifier>"`**: Associates a `chip_operations` structure
-    with the device, used primarily in ramstage for device initialization.
-*   **`fw_config field <name> size <bits> ... end`**: Defines a firmware
-    configuration field, often used for passing board-specific data to
-    payloads. Options within the field are defined using `option`.
-*   **`ref <alias>`**: Used within `device` definitions in `devicetree.cb`
-    or `overridetree.cb` to refer to a device defined (usually via an
-    `alias`) in a lower-level file like `chipset.cb`.
-*   **`# <comment text>`**: Single-line comments.
-
-Device definitions can be nested within `chip` blocks. `end` keywords
-close the current block (`device` or `chip`).
-
-
-## Three levels of devicetree files
-
-There are currently three different levels of devicetrees used to build
-up the structure of components and register values in coreboot. From
-the lowest, most general level to the highest and most specific, they
-are `chipset.cb`, `devicetree.cb`, and `overridetree.cb`.
-
-Unless there's a specific reason to name them something other than these
-names, they should be used.
-
-For newer SoCs and chipsets, there will generally be a `chipset.cb` file.
-Every mainboard requires a `devicetree.cb` file, although it can be empty
-if everything is inherited from the `chipset.cb`. An `overridetree.cb`
-file is only required if variants have differences from the primary
-mainboard's `devicetree.cb`.
-
-
-### SoC / chipset level, `chipset.cb`
-
-The `chipset.cb` file was added in October 2020, allowing a single
-chipset or SoC to provide a "base level" devicetree, reducing
-duplication between mainboards.
-
-The `chipset.cb` file also typically defines human-readable "aliases"
-for particular devices so that mainboards can use those instead of PCI
-device/function numbers or other hardware identifiers.
-
-The use of the `chipset.cb` file is specified in Kconfig by the
-`CHIPSET_DEVICETREE` symbol, which provides the path to the file.
-
-In a `chipset.cb` file, you might see lines like this:
-
-```text
-# Chip definition for the SoC/chipset itself
-chip soc/intel/common/block
-
-    # Define PCI device 17.0, alias it to "sata", and default it off
-    device pci 17.0 alias sata off end
-
-    # Define PCI device 1e.0, alias it to "uart0", and default it off
-    device pci 1e.0 alias uart0 off end
-
-end # chip soc/intel/common/block
-```
-
-This defines the devices, assigns aliases, and sets their default state.
-
-
-### Primary mainboard level, `devicetree.cb`
-
-Each mainboard must have a `devicetree.cb` file. The filename and path are
-typically set by the `DEVICETREE` Kconfig symbol, defaulting to
-`src/mainboard/<VENDOR>/<BOARD>/devicetree.cb`.
-
-If a mainboard using the above `chipset.cb` wanted both devices enabled,
-its `devicetree.cb` might contain:
-
-```text
-# Reference the SATA device by its alias and enable it
-device ref sata on end
-
-# Reference the UART0 device by its alias and enable it
-device ref uart0 on end
-```
-
-The `ref` keyword looks up the device (usually by alias) defined in a
-lower-level file (`chipset.cb` in this case) and modifies its properties.
-
-
-### Mainboard variant level, `overridetree.cb`
-
-Introduced in 2018 to reduce duplication and maintenance for board
-variants, the `overridetree.cb` file is the most specific level.
-
-This allows a base `devicetree.cb` at the top mainboard level shared by
-all variants. Each variant then only needs an `overridetree.cb` to
-specify its differences.
-
-The override tree filename is set in Kconfig with the
-`OVERRIDE_DEVICETREE` symbol and is typically named `overridetree.cb`.
-
-Finally, if one variant of the mainboard lacked a SATA connector, it
-could disable the SATA device again using the following in its specific
-`overridetree.cb`:
-
-```text
-# Reference the SATA device by alias and disable it for this variant
-device ref sata off end
-```
-
-
-## Additional files
-
-
-### `chip.h` files
-
-coreboot looks at a "chip" as a collection of devices. This collection
-can be a single logical device or multiple different ones. The `chip`
-keyword starts this collection. Following the `chip` keyword is a
-directory path (relative to `src/`) containing the code for that chip
-or logical block of hardware.
-
-There may optionally be a `chip.h` file in that directory. If present,
-`sconfig` parses this file to define a C structure containing the
-"register definitions" for the chip. The values for this structure's
-members are set using the `register` keyword in one of the devicetree
-files (`chipset.cb`, `devicetree.cb`, `overridetree.cb`). If not
-explicitly set, members typically default to 0 or follow standard C
-initialization rules. The `chip.h` file frequently also contains C
-macros, enums, and sub-structures used for setting the members of the
-main register structure.
-
-The C structure for the chip's register definition is named after the
-directory containing the `chip.h` file, with slashes (`/`) changed to
-underscores (`_`), and `_config` appended. The leading `src/` is omitted.
-
-This means that a line in a devicetree file like:
-`chip drivers/i2c/hid`
-would cause `sconfig` to look for `src/drivers/i2c/hid/chip.h`. If found,
-the register definition structure it contains would be named
-`drivers_i2c_hid_config`.
-
-Here is the content of `src/drivers/i2c/hid/chip.h`:
-
-```c
-/* SPDX-License-Identifier: GPL-2.0-only */
-
-#ifndef __DRIVERS_I2C_HID_CHIP_H__
-#define __DRIVERS_I2C_HID_CHIP_H__
-#include <drivers/i2c/generic/chip.h>
-#define I2C_HID_CID         "PNP0C50"
-
-struct drivers_i2c_hid_config {
-        struct drivers_i2c_generic_config generic;
-        uint8_t hid_desc_reg_offset;
-};
-
-#endif /* __I2C_HID_CHIP_H__ */
-```
-
-In a devicetree, you could set `hid_desc_reg_offset` like this:
-
-```text
-chip drivers/i2c/hid
-    device i2c 0x2c on
-        # Set the HID descriptor register offset
-        register "hid_desc_reg_offset" = "0x01"
-    end
-end
-```
-
-
-## The `sconfig` utility and generated files
-
-
-### `util/sconfig`
-
-`sconfig` is the tool that parses the coreboot devicetrees and turns
-them into a collection of C structures. This is a coreboot-specific
-tool, built using flex & bison to define and parse the domain-specific
-language used by coreboot's devicetree.
-
-`sconfig` is called by the makefiles during the build process and doesn't
-generally need to be run directly. If run manually (e.g.,
-`build/util/sconfig/sconfig --help`), it shows its command-line options.
-The exact options might vary slightly, but typically include:
-
-```text
-usage: sconfig <options>
-
- -c | --output_c          : Path to output static.c file (required)
- -r | --output_h          : Path to header static.h file (required)
- -d | --output_d          : Path to header static_devices.h file (required)
- -f | --output_f          : Path to header static_fw_config.h file (required)
- -m | --mainboard_devtree : Path to mainboard devicetree file (required)
- -o | --override_devtree  : Path to override devicetree file (optional)
- -p | --chipset_devtree   : Path to chipset/SOC devicetree file (optional)
-```
-
-
-### `sconfig` inputs
-
-The `sconfig` input files `chip.h`, `chipset.cb`, `devicetree.cb`, and
-`overridetree.cb` were discussed previously. As the usage above shows,
-the only required input file is the mainboard devicetree (`-m`). The
-additional devicetree files, `chipset.cb` (`-p`) and `overridetree.cb`
-(`-o`), are optional. The `chip.h` files do not need to be specified on
-the command line; their locations are determined by the `chip` directory
-paths within the `.cb` files.
-
-Constructing the devicetree input files will be discussed later.
-
-
-### `sconfig` outputs
-
-#### `static.c`
-
-This is the primary C file generated by `sconfig`. It contains the static
-definitions of the device tree structures, including device nodes, bus
-links, and register configuration data.
-
-For historic reasons, `static.c` is generated in the
-`build/mainboard/<VENDOR>/<BOARD>` directory.
-
-
-#### `static.h`
-
-The `static.h` file is the main header file included by most coreboot C
-files that need access to the devicetree data. It is included by
-`src/include/device/device.h`, which provides the primary API
-(definitions, structures, function prototypes) for interacting with the
-devicetree-generated output.
-
-`static.h` used to contain all generated declarations directly. As of
-October 2020, it simply includes the other two generated header files
-(`static_devices.h` and `static_fw_config.h`). This separation allows
-the firmware config options (`fw_config`) to be used independently, for
-example, by a payload.
-
-
-#### `static_devices.h`
-
-The file `static_devices.h` contains `extern` declarations for all the
-device structures (`struct device`) defined in `static.c`. This allows
-other C files to reference the generated device tree nodes.
-
-
-#### `static_fw_config.h`
-
-`static_fw_config.h` contains only the `FW_CONFIG_FIELD_*` macro results,
-derived from `fw_config` entries in the devicetree. This makes it easily
-consumable by payloads or other components needing platform `FW_CONFIG`
-data without pulling in the full device tree structure.
-
-
-## Devicetree Example
-
-
-### A very simple devicetree
-
-This is the `devicetree.cb` file from
-`src/mainboard/sifive/hifive-unleashed`, with line numbers added for
-reference. Non-x86 devicetree files are often simpler than their x86
-counterparts.
-
-```text
-    1  # SPDX-License-Identifier: GPL-2.0-only
-    2  chip soc/sifive/fu540
-    3          device cpu_cluster 0 on  end
-    4  end
-```
-
-This can be broken down as follows:
-
-Line 1: Comments start with `#`. This line is the SPDX license
-identifier for the file.
-
-Line 2: `chip soc/sifive/fu540` starts a block for the SiFive FU540 SoC.
-`sconfig` will look for code and potentially a `chip.h` in
-`src/soc/sifive/fu540/`.
-
-Line 3: `device cpu_cluster 0 on end` defines a device of type
-`cpu_cluster` with ID `0`. It's marked as enabled (`on`). Since there are
-no registers or other properties defined between `device` and `end`, this
-is a simple enablement entry.
-
-Line 4: `end` closes the block started by the `chip` keyword on line 2.
-
-
-### Generated files
-
-Continuing with the simple `sifive/hifive-unleashed` mainboard example,
-these are the files generated by `sconfig` from the devicetree above (as
-of mid-2022; exact output can change). Because the input devicetree is
-minimal, the generated files are also quite sparse.
-
-
-#### `build/static.h`
-
-```c
-#ifndef __STATIC_DEVICE_TREE_H
-#define __STATIC_DEVICE_TREE_H
-
-#include <static_fw_config.h>
-#include <static_devices.h>
-
-#endif /* __STATIC_DEVICE_TREE_H */
-```
-(Includes the other generated headers.)
-
-
-#### `build/static_devices.h`
-
-```c
-#ifndef __STATIC_DEVICES_H
-#define __STATIC_DEVICES_H
-#include <device/device.h>
-/* expose_device_names */
-#endif /* __STATIC_DEVICE_NAMES_H */
-```
-(Includes `device/device.h` but contains no actual device externs beyond
-the implicit root device, as the simple example didn't define complex
-devices requiring separate structs.)
-
-
-#### `build/static_fw_config.h`
-
-```c
-#ifndef __STATIC_FW_CONFIG_H
-#define __STATIC_FW_CONFIG_H
-#endif /* __STATIC_FW_CONFIG_H */
-```
-(Empty because the example `devicetree.cb` did not use `fw_config`.)
-
-
-#### `build/mainboard/sifive/hifive-unleashed/static.c`
-
-##### Includes
-
-```text
-1  #include <boot/coreboot_tables.h>
-2  #include <device/device.h>
-3  #include <device/pci.h>
-4  #include <fw_config.h>
-5  #include <static.h>
-```
-
-Lines 1-5: Includes header files required for the following structure
-definitions and macros.
-
-
-##### Declarations for chip-ops
-
-```text
-6
-7   #if !DEVTREE_EARLY
-8   __attribute__((weak)) struct chip_operations mainboard_ops = {};
-9   extern struct chip_operations soc_sifive_fu540_ops;
-10  #endif
-```
-
-Lines 7 & 10: The `ops` structures inside this `#if !DEVTREE_EARLY` block
-are only relevant and linked in ramstage.
-
-Lines 8-9: Declarations for `chip_operations` structures. This section
-expands as more chips are added to the devicetree.
-*   Line 8: `mainboard_ops` is always present. It's defined as `weak`
-    because the mainboard C code may or may not provide this structure.
-*   Line 9: This `extern` is generated by the `chip soc/sifive/fu540`
-    declaration in the `devicetree.cb`. There will be a similar line for
-    every `chip` declared.
-
-##### `STORAGE` definition
-
-```text
-11
-12  #define STORAGE static __unused DEVTREE_CONST
-```
-
-Line 12: This macro conditionally adds `const` based on the build stage.
-It resolves to `static __unused const` in early stages (pre-RAM) and
-`static __unused` in ramstage, where the structures might be modified.
-
-##### Structure definitions
-
-```text
-13
-14
-15  /* pass 0 */
-16  STORAGE struct bus dev_root_links[];
-17  STORAGE struct device _dev_0;
-18  DEVTREE_CONST struct device * DEVTREE_CONST last_dev = &_dev_0;
-```
-
-Lines 16-18: Forward declarations of the static structures generated by
-`sconfig` based on the devicetree input. `_dev_0` corresponds to the
-`cpu_cluster 0` device.
-
-##### Register Structures
-
-```text
-19
-20  /* chip configs */
-```
-
-Line 20: This section is empty for this mainboard because the
-`soc/sifive/fu540/chip.h` file (if it exists) does not define a register
-structure, or the devicetree did not instantiate it using `register`.
-Otherwise, this section would contain the static initialization of chip
-configuration structures based on `register` entries.
-
-##### `dev_root` structure
-
-Lines 21-44: `dev_root`. This structure represents the root of the
-coreboot device tree. It is always generated, regardless of the content
-of the `devicetree.cb` file. It serves as the entry point for traversing
-the tree.
-
-```text
-21
-22  /* pass 1 */
-23  DEVTREE_CONST struct device dev_root = {
-24          #if !DEVTREE_EARLY
-25                  .ops = &default_dev_ops_root,
-26          #endif
-27                  .bus = &dev_root_links[0],
-28                  .path = { .type = DEVICE_PATH_ROOT },
-29                  .enabled = 1,
-30                  .hidden = 0,
-31                  .mandatory = 0,
-32                  .on_mainboard = 1,
-33                  .link_list = &dev_root_links[0],
-34                  .sibling = NULL,
-35          #if !DEVTREE_EARLY
-36                  .chip_ops = &mainboard_ops,
-37                  .name = mainboard_name,
-38          #endif
-39                  .next=&_dev_0,
-40          #if !DEVTREE_EARLY
-41          #if CONFIG(GENERATE_SMBIOS_TABLES)
-42          #endif
-43          #endif
-44  };
-```
-
-*   Lines 24-26: Points to a default ramstage `device_operation`
-    structure (`default_dev_ops_root`) found in
-    `src/device/root_device.c`. This structure typically does little by
-    default but can be overridden or utilized by mainboard code via the
-    `chip_operations->enable_dev()` hook for tasks like ACPI table
-    generation.
-*   Line 27: `.bus`: Pointer to the bus structure associated with this
-    device. For the root device, this points to its own bus structure.
-*   Line 28: `.path`: The unique path identifier for this device. The type
-    is `DEVICE_PATH_ROOT`.
-*   Lines 29-32: Device status flags.
-    *   `enabled`: Set based on `on`/`off` in the devicetree (always on
-        for `dev_root`). Can be modified later (e.g., during enumeration
-        in ramstage).
-    *   `hidden`, `mandatory`: Set only by corresponding keywords in the
-        devicetree (not used here).
-    *   `on_mainboard`: Indicates the device was defined in the static
-        devicetree, as opposed to being discovered dynamically (e.g., via
-        PCI enumeration). Always true for `dev_root`.
-*   Line 33: `.link_list`: Pointer to the list of child buses attached to
-    this device.
-*   Line 34: `.sibling`: Pointer to the next device at the same level in
-    the tree. Should always be `NULL` for `dev_root`.
-*   Line 36: `.chip_ops`: Pointer to the mainboard's `chip_operations`
-    structure (the `weak` `mainboard_ops`). Although not a physical
-    chip, the mainboard gets this to hook into the boot process like
-    other chips.
-*   Line 37: `.name`: A string identifier, typically the mainboard name,
-    set at build time (from `src/device/root_device.c`).
-*   Line 39: `.next`: Pointer used internally by `sconfig` during tree
-    construction. Points to the next device structure processed (`_dev_0`).
-
-##### `dev_root_links`
-
-Lines 45-52: The `dev_root` bus structure array.
-
-This array (`struct bus`) holds pointers defining the bus topology. Each
-element represents a link on a bus. `dev_root` acts as the bridge for the
-top-level bus.
-
-A new bus structure array is typically created for each distinct bus type
-or domain originating from a bridge device in the devicetree (e.g., PCI
-domain 0, LPC bus).
-
-```text
-45  STORAGE struct bus dev_root_links[] = {
-46          [0] = {
-47                  .link_num = 0,
-48                  .dev = &dev_root,
-49                  .children = &_dev_0,
-50                  .next = NULL,
-51          },
-52  };
-```
-
-*   Line 47: `.link_num`: Index of this link within the bus array.
-*   Line 48: `.dev`: Pointer back to the bridge device structure for this
-    bus (`dev_root`).
-*   Line 49: `.children`: Pointer to the first child device structure on
-    this bus (`_dev_0`).
-*   Line 50: `.next`: Pointer to the next bridge device on the *parent*
-    bus. Since `dev_root` has no parent bus, this is `NULL`.
-
-##### `_dev_0`
-
-Lines 53-72: The `cpu_cluster` device structure (`_dev_0`).
-
-This structure corresponds directly to the
-`device cpu_cluster 0 on end` line in the `devicetree.cb`.
-
-```text
-53  STORAGE struct device _dev_0 = {
-54          #if !DEVTREE_EARLY
-55                  .ops = NULL,
-56          #endif
-57                  .bus = &dev_root_links[0],
-58                  .path = {.type=DEVICE_PATH_CPU_CLUSTER,{.cpu_cluster={ .cluster = 0x0 }}},
-59                  .enabled = 1,
-60                  .hidden = 0,
-61                  .mandatory = 0,
-62                  .on_mainboard = 1,
-63                  .link_list = NULL,
-64                  .sibling = NULL,
-65          #if !DEVTREE_EARLY
-66                  .chip_ops = &soc_sifive_fu540_ops,
-67          #endif
-68          #if !DEVTREE_EARLY
-69          #if CONFIG(GENERATE_SMBIOS_TABLES)
-70          #endif
-71          #endif
-72  };
-```
-
-*   Lines 54-56: `.ops`: Pointer to a `device_operations` structure. This
-    is `NULL` because this entry represents the `chip` itself, not a
-    specific functional sub-device requiring device-level operations. The
-    chip-level operations are handled by `chip_ops`.
-*   Line 57: `.bus`: Pointer to the bus structure this device resides on.
-    Since it's directly under `dev_root`, it points to `dev_root_links[0]`.
-*   Line 58: `.path`: The unique device path structure (defined in
-    `src/include/device/path.h`). Type is `DEVICE_PATH_CPU_CLUSTER`,
-    and the cluster ID is `0`, matching the devicetree entry. This path
-    is used when searching the tree (e.g., with `dev_find_path()`).
-*   Lines 59-62: Enumeration Status. Similar to `dev_root`. `enabled = 1`
-    comes from the `on` keyword.
-*   Line 63: `.link_list`: Pointer to child buses. `NULL` because this
-    `cpu_cluster` device doesn't bridge to any further buses in this
-    simple example.
-*   Line 64: `.sibling`: Pointer to the next device at the same level
-    (i.e., another device directly under `dev_root`). `NULL` as it's the
-    only child.
-*   Lines 65-67: `.chip_ops`: Pointer to the processor's `chip_operations`
-    structure (`soc_sifive_fu540_ops`), used in ramstage for SoC/CPU
-    initialization steps. This link comes from the `chip soc/sifive/fu540`
-    declaration.
-*   Lines 68-71: Placeholder for SMBIOS information, enabled by Kconfig.
-    Not used in this example.