Compare commits
4 commits
main
...
4.10_branc
| Author | SHA1 | Date | |
|---|---|---|---|
|
789711036a | ||
|
|
0802d7b3d1 | ||
|
|
7f742241b8 | ||
|
|
f672d50e2b |
29153 changed files with 1818708 additions and 2540223 deletions
|
|
@ -1,16 +1,15 @@
|
|||
# Override checkpatch's default max line length 100
|
||||
--max-line-length=96
|
||||
|
||||
# Not Linux, so don't expect a Linux tree.
|
||||
--no-tree
|
||||
|
||||
# Ignore aspects we don't follow here.
|
||||
--ignore C99_COMMENTS
|
||||
--ignore GLOBAL_INITIALISERS
|
||||
--ignore COMPARISON_TO_NULL
|
||||
--ignore INITIALISED_STATIC
|
||||
--ignore LINE_SPACING
|
||||
--ignore NEW_TYPEDEFS
|
||||
--ignore PREFER_ALIGNED
|
||||
--ignore PREFER_PACKED
|
||||
--ignore PREFER_PRINTF
|
||||
--ignore SPLIT_STRING
|
||||
--ignore BLOCK_COMMENT_STYLE
|
||||
--ignore AVOID_EXTERNS
|
||||
|
|
@ -21,9 +20,6 @@
|
|||
--ignore SPDX_LICENSE_TAG
|
||||
--ignore UNDOCUMENTED_DT_STRING
|
||||
--ignore PRINTK_WITHOUT_KERN_LEVEL
|
||||
--ignore ASSIGN_IN_IF
|
||||
--ignore UNNECESSARY_ELSE
|
||||
--ignore GERRIT_CHANGE_ID
|
||||
|
||||
# FILE_PATH_CHANGES seems to not be working correctly. It will
|
||||
# choke on added / deleted files even if the MAINTAINERS file
|
||||
|
|
@ -34,8 +30,5 @@
|
|||
# some commits unnecessarily.
|
||||
--ignore EXECUTE_PERMISSIONS
|
||||
|
||||
# Exclude vendorcode directories that don't follow coreboot's coding style.
|
||||
--exclude src/vendorcode/amd
|
||||
--exclude src/vendorcode/cavium
|
||||
--exclude src/vendorcode/intel
|
||||
--exclude src/vendorcode/mediatek
|
||||
# Exclude the vendorcode directory
|
||||
--exclude src/vendorcode
|
||||
|
|
|
|||
249
.clang-format
249
.clang-format
|
|
@ -1,228 +1,21 @@
|
|||
# SPDX-License-Identifier: GPL-2.0-only
|
||||
#
|
||||
# clang-format configuration file. Intended for clang-format >= 16.
|
||||
#
|
||||
# For more information, see:
|
||||
#
|
||||
# https://clang.llvm.org/docs/ClangFormat.html
|
||||
# https://clang.llvm.org/docs/ClangFormatStyleOptions.html
|
||||
# https://clang-format-configurator.site/
|
||||
#
|
||||
|
||||
---
|
||||
Language: Cpp
|
||||
AccessModifierOffset: -4
|
||||
AlignAfterOpenBracket: Align
|
||||
AlignArrayOfStructures: Left
|
||||
AlignConsecutiveAssignments:
|
||||
Enabled: false
|
||||
AcrossEmptyLines: false
|
||||
AcrossComments: true
|
||||
AlignCompound: false
|
||||
PadOperators: true
|
||||
AlignConsecutiveBitFields:
|
||||
Enabled: true
|
||||
AcrossEmptyLines: false
|
||||
AcrossComments: false
|
||||
AlignCompound: false
|
||||
PadOperators: true
|
||||
AlignConsecutiveDeclarations:
|
||||
Enabled: false
|
||||
AcrossEmptyLines: false
|
||||
AcrossComments: false
|
||||
AlignCompound: false
|
||||
PadOperators: true
|
||||
AlignConsecutiveMacros:
|
||||
Enabled: true
|
||||
AcrossEmptyLines: false
|
||||
AcrossComments: false
|
||||
AlignCompound: false
|
||||
PadOperators: true
|
||||
AlignEscapedNewlines: Left
|
||||
AlignOperands: Align
|
||||
AlignTrailingComments:
|
||||
Kind: Always
|
||||
OverEmptyLines: 0
|
||||
AllowAllArgumentsOnNextLine: true
|
||||
AllowAllParametersOfDeclarationOnNextLine: false
|
||||
AllowShortBlocksOnASingleLine: Never
|
||||
AllowShortCaseLabelsOnASingleLine: false
|
||||
AllowShortEnumsOnASingleLine: true
|
||||
AllowShortFunctionsOnASingleLine: None
|
||||
AllowShortIfStatementsOnASingleLine: Never
|
||||
AllowShortLambdasOnASingleLine: All
|
||||
AllowShortLoopsOnASingleLine: false
|
||||
AlwaysBreakAfterDefinitionReturnType: None
|
||||
AlwaysBreakAfterReturnType: None
|
||||
AlwaysBreakBeforeMultilineStrings: false
|
||||
AlwaysBreakTemplateDeclarations: MultiLine
|
||||
|
||||
# git grep '^#define [^[:space:]]*__.*[^[:space:]]*__attribute__' | grep -v "vendorcode\|payloads\|util" | sed "s|.*:||;s|^#define \([^[:space:]]*__[^([:space:]]*\).*$| - '\1'|" | LC_ALL=C sort -u
|
||||
AttributeMacros:
|
||||
- '__aligned'
|
||||
- '__always_inline'
|
||||
- '__always_unused'
|
||||
- '__cpu_driver'
|
||||
- '__fallthrough'
|
||||
- '__maybe_unused'
|
||||
- '__must_check'
|
||||
- '__noreturn'
|
||||
- '__packed'
|
||||
- '__pci_driver'
|
||||
- '__printf'
|
||||
- '__weak'
|
||||
BinPackArguments: true
|
||||
BinPackParameters: true
|
||||
BitFieldColonSpacing: Both
|
||||
BraceWrapping:
|
||||
AfterCaseLabel: false
|
||||
AfterClass: false
|
||||
AfterControlStatement: Never
|
||||
AfterEnum: false
|
||||
AfterExternBlock: false
|
||||
AfterFunction: true
|
||||
AfterNamespace: true
|
||||
AfterObjCDeclaration: false
|
||||
AfterStruct: false
|
||||
AfterUnion: false
|
||||
BeforeCatch: false
|
||||
BeforeElse: false
|
||||
BeforeLambdaBody: false
|
||||
BeforeWhile: false
|
||||
IndentBraces: false
|
||||
SplitEmptyFunction: true
|
||||
SplitEmptyRecord: true
|
||||
SplitEmptyNamespace: true
|
||||
BreakAfterAttributes: Never
|
||||
BreakAfterJavaFieldAnnotations: false
|
||||
BreakArrays: false
|
||||
BreakBeforeBinaryOperators: None
|
||||
BreakBeforeConceptDeclarations: Always
|
||||
BreakBeforeBraces: Custom
|
||||
BreakBeforeInlineASMColon: OnlyMultiline
|
||||
BreakBeforeTernaryOperators: false
|
||||
BreakConstructorInitializers: AfterColon
|
||||
BreakInheritanceList: AfterColon
|
||||
BreakStringLiterals: false
|
||||
ColumnLimit: 96
|
||||
CommentPragmas: '^ IWYU pragma:'
|
||||
CompactNamespaces: false
|
||||
ConstructorInitializerIndentWidth: 8
|
||||
ContinuationIndentWidth: 8
|
||||
Cpp11BracedListStyle: true
|
||||
DerivePointerAlignment: false
|
||||
DisableFormat: false
|
||||
EmptyLineAfterAccessModifier: Never
|
||||
EmptyLineBeforeAccessModifier: LogicalBlock
|
||||
ExperimentalAutoDetectBinPacking: false
|
||||
FixNamespaceComments: false
|
||||
|
||||
# git grep '^#define [^[:space:]]*for_each[^[:space:]]*(' | grep -v "vendorcode\|payloads\|util" | sed "s|.*:||;s|^#define \([^[:space:]]*for_each[^[:space:]]*\)(.*$| - '\1'|" | LC_ALL=C sort -u
|
||||
ForEachMacros:
|
||||
- 'list_for_each'
|
||||
|
||||
# git grep -i '^#define \+if[^[:space:]]*(' | grep -v "vendorcode\|payloads\|util" | sed "s|.*:||;s|^#define \([^[:space:]]*if[^[:space:]]*\)(.*$| - '\1'|I" | grep -v IFIX | LC_ALL=C sort -u
|
||||
IfMacros:
|
||||
- 'IF_CHANNEL_POPULATED'
|
||||
- 'IF_DIMM_POPULATED'
|
||||
- 'IF_RANK_POPULATED'
|
||||
- 'IfBit0'
|
||||
IncludeBlocks: Preserve
|
||||
IncludeIsMainSourceRegex: ''
|
||||
IndentAccessModifiers: false
|
||||
IndentCaseBlocks: false
|
||||
IndentCaseLabels: false
|
||||
IndentExternBlock: AfterExternBlock
|
||||
IndentGotoLabels: false
|
||||
IndentPPDirectives: None
|
||||
IndentRequiresClause: true
|
||||
IndentWidth: 8
|
||||
IndentWrappedFunctionNames: false
|
||||
InsertBraces: false
|
||||
InsertNewlineAtEOF: true
|
||||
InsertTrailingCommas: None
|
||||
IntegerLiteralSeparator:
|
||||
Binary: 0
|
||||
BinaryMinDigits: 0
|
||||
Decimal: 0
|
||||
DecimalMinDigits: 0
|
||||
Hex: 0
|
||||
HexMinDigits: 0
|
||||
JavaScriptQuotes: Leave
|
||||
JavaScriptWrapImports: true
|
||||
KeepEmptyLinesAtTheStartOfBlocks: false
|
||||
LambdaBodyIndentation: Signature
|
||||
LineEnding: LF
|
||||
MacroBlockBegin: ''
|
||||
MacroBlockEnd: ''
|
||||
MaxEmptyLinesToKeep: 1
|
||||
NamespaceIndentation: None
|
||||
ObjCBinPackProtocolList: Auto
|
||||
ObjCBlockIndentWidth: 8
|
||||
ObjCBreakBeforeNestedBlockParam: true
|
||||
ObjCSpaceAfterProperty: true
|
||||
ObjCSpaceBeforeProtocolList: true
|
||||
PackConstructorInitializers: BinPack
|
||||
PenaltyBreakAssignment: 10
|
||||
PenaltyBreakBeforeFirstCallParameter: 30
|
||||
PenaltyBreakComment: 10
|
||||
PenaltyBreakFirstLessLess: 0
|
||||
PenaltyBreakOpenParenthesis: 0
|
||||
PenaltyBreakString: 10
|
||||
PenaltyBreakTemplateDeclaration: 10
|
||||
PenaltyExcessCharacter: 100
|
||||
PenaltyIndentedWhitespace: 0
|
||||
PenaltyReturnTypeOnItsOwnLine: 60
|
||||
PointerAlignment: Right
|
||||
PPIndentWidth: -1
|
||||
QualifierAlignment: Left
|
||||
ReferenceAlignment: Pointer
|
||||
ReflowComments: false
|
||||
RemoveBracesLLVM: false
|
||||
RemoveSemicolon: false
|
||||
RequiresClausePosition: OwnLine
|
||||
RequiresExpressionIndentation: OuterScope
|
||||
SeparateDefinitionBlocks: Leave
|
||||
ShortNamespaceLines: 1
|
||||
SortIncludes: Never
|
||||
SortJavaStaticImport: Before
|
||||
SortUsingDeclarations: Never
|
||||
SpaceAfterCStyleCast: false
|
||||
SpaceAfterLogicalNot: false
|
||||
SpaceAfterTemplateKeyword: true
|
||||
SpaceAroundPointerQualifiers: Default
|
||||
SpaceBeforeAssignmentOperators: true
|
||||
SpaceBeforeCaseColon: false
|
||||
SpaceBeforeCpp11BracedList: false
|
||||
SpaceBeforeCtorInitializerColon: true
|
||||
SpaceBeforeInheritanceColon: true
|
||||
SpaceBeforeParens: ControlStatementsExceptControlMacros
|
||||
SpaceBeforeParensOptions:
|
||||
AfterControlStatements: true
|
||||
AfterForeachMacros: false
|
||||
AfterFunctionDefinitionName: false
|
||||
AfterFunctionDeclarationName: false
|
||||
AfterIfMacros: false
|
||||
AfterOverloadedOperator: false
|
||||
AfterRequiresInClause: false
|
||||
AfterRequiresInExpression: false
|
||||
BeforeNonEmptyParentheses: false
|
||||
SpaceBeforeRangeBasedForLoopColon: true
|
||||
SpaceBeforeSquareBrackets: false
|
||||
SpaceInEmptyBlock: false
|
||||
SpaceInEmptyParentheses: false
|
||||
SpacesBeforeTrailingComments: 1
|
||||
SpacesInAngles: Never
|
||||
SpacesInConditionalStatement: false
|
||||
SpacesInContainerLiterals: false
|
||||
SpacesInCStyleCastParentheses: false
|
||||
SpacesInLineCommentPrefix:
|
||||
Minimum: 1
|
||||
Maximum: 1
|
||||
SpacesInParentheses: false
|
||||
SpacesInSquareBrackets: false
|
||||
Standard: c++17
|
||||
TabWidth: 8
|
||||
UseTab: ForContinuationAndIndentation
|
||||
...
|
||||
|
||||
BasedOnStyle: LLVM
|
||||
Language: Cpp
|
||||
IndentWidth: 8
|
||||
UseTab: Always
|
||||
BreakBeforeBraces: Linux
|
||||
AllowShortIfStatementsOnASingleLine: false
|
||||
IndentCaseLabels: false
|
||||
SortIncludes: false
|
||||
ContinuationIndentWidth: 8
|
||||
ColumnLimit: 96
|
||||
AlwaysBreakBeforeMultilineStrings: true
|
||||
AllowShortLoopsOnASingleLine: false
|
||||
AllowShortFunctionsOnASingleLine: false
|
||||
AlignEscapedNewlinesLeft: false
|
||||
AlignTrailingComments: true
|
||||
AllowAllParametersOfDeclarationOnNextLine: false
|
||||
AlignAfterOpenBracket: true
|
||||
SpaceAfterCStyleCast: false
|
||||
MaxEmptyLinesToKeep: 2
|
||||
BreakBeforeBinaryOperators: NonAssignment
|
||||
BreakStringLiterals: false
|
||||
|
|
|
|||
|
|
@ -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
|
||||
115
.gitignore
vendored
115
.gitignore
vendored
|
|
@ -1,3 +1,6 @@
|
|||
payloads/libpayload/install/
|
||||
payloads/nvramcui/build
|
||||
payloads/nvramcui/libpayload
|
||||
junit.xml
|
||||
abuild*.xml
|
||||
.config
|
||||
|
|
@ -8,40 +11,124 @@ defconfig
|
|||
.ccwrap
|
||||
build/
|
||||
coreboot-builds/
|
||||
coreboot-builds*/
|
||||
generated/
|
||||
|
||||
payloads/coreinfo/lpbuild/
|
||||
payloads/coreinfo/lp.config*
|
||||
payloads/external/depthcharge/depthcharge/
|
||||
payloads/external/FILO/filo/
|
||||
payloads/external/GRUB2/grub2/
|
||||
payloads/external/LinuxBoot/linuxboot/
|
||||
payloads/external/SeaBIOS/seabios/
|
||||
payloads/external/tianocore/tianocore/
|
||||
payloads/external/tint/tint/
|
||||
payloads/external/U-Boot/u-boot/
|
||||
payloads/external/Memtest86Plus/memtest86plus/
|
||||
payloads/external/iPXE/ipxe/
|
||||
util/crossgcc/acpica-unix-*/
|
||||
util/crossgcc/binutils-*/
|
||||
util/crossgcc/build-*BINUTILS/
|
||||
util/crossgcc/build-*EXPAT/
|
||||
util/crossgcc/build-*GCC/
|
||||
util/crossgcc/build-*GDB/
|
||||
util/crossgcc/build-*GMP/
|
||||
util/crossgcc/build-*LIBELF/
|
||||
util/crossgcc/build-*MPC/
|
||||
util/crossgcc/build-*MPFR/
|
||||
util/crossgcc/build-*PYTHON/
|
||||
util/crossgcc/build-*LVM/
|
||||
util/crossgcc/build-*IASL/
|
||||
util/crossgcc/expat-*/
|
||||
util/crossgcc/gcc-*/
|
||||
util/crossgcc/gdb-*/
|
||||
util/crossgcc/gmp-*/
|
||||
util/crossgcc/libelf-*/
|
||||
util/crossgcc/mingwrt-*/
|
||||
util/crossgcc/mpc-*/
|
||||
util/crossgcc/mpfr-*/
|
||||
util/crossgcc/Python-*/
|
||||
util/crossgcc/*.src/
|
||||
util/crossgcc/tarballs/
|
||||
util/crossgcc/w32api-*/
|
||||
util/crossgcc/xgcc/
|
||||
util/crossgcc/xgcc-*/
|
||||
util/crossgcc/xgcc
|
||||
site-local
|
||||
|
||||
*.\#
|
||||
*.a
|
||||
*.bin
|
||||
*.debug
|
||||
!Kconfig.debug
|
||||
*.elf
|
||||
*.fd
|
||||
*.o
|
||||
*.o.d
|
||||
*.out
|
||||
*.pyc
|
||||
*.sw[po]
|
||||
/*.rom
|
||||
.test
|
||||
.dependencies
|
||||
coreboot-builds*/
|
||||
|
||||
# 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/amdfwtool/amdfwtool
|
||||
util/archive/archive
|
||||
util/bimgtool/bimgtool
|
||||
util/bincfg/bincfg
|
||||
util/board_status/board-status
|
||||
util/bucts/bucts
|
||||
util/cbfstool/cbfs-compression-tool
|
||||
util/cbfstool/cbfstool
|
||||
util/cbfstool/fmaptool
|
||||
util/cbfstool/ifwitool
|
||||
util/cbfstool/rmodtool
|
||||
util/cbmem/.dependencies
|
||||
util/cbmem/cbmem
|
||||
util/dumpmmcr/dumpmmcr
|
||||
util/ectool/ectool
|
||||
util/futility/futility
|
||||
util/genprof/genprof
|
||||
util/getpir/getpir
|
||||
util/ifdtool/ifdtool
|
||||
util/intelmetool/intelmetool
|
||||
util/inteltool/.dependencies
|
||||
util/inteltool/inteltool
|
||||
util/intelvbttool/intelvbttool
|
||||
util/k8resdump/k8resdump
|
||||
util/lbtdump/lbtdump
|
||||
util/mptable/mptable
|
||||
util/msrtool/Makefile
|
||||
util/msrtool/Makefile.deps
|
||||
util/msrtool/msrtool
|
||||
util/nvramtool/.dependencies
|
||||
util/nvramtool/nvramtool
|
||||
util/optionlist/Options.wiki
|
||||
util/romcc/build
|
||||
util/runfw/googlesnow
|
||||
util/superiotool/superiotool
|
||||
util/vgabios/testbios
|
||||
util/viatool/viatool
|
||||
util/autoport/autoport
|
||||
util/kbc1126/kbc1126_ec_dump
|
||||
util/kbc1126/kbc1126_ec_insert
|
||||
|
||||
Documentation/*.aux
|
||||
Documentation/*.idx
|
||||
Documentation/*.log
|
||||
Documentation/*.toc
|
||||
Documentation/*.out
|
||||
Documentation/*.pdf
|
||||
Documentation/_build
|
||||
|
||||
doxygen/*
|
||||
|
|
|
|||
69
.gitmodules
vendored
69
.gitmodules
vendored
|
|
@ -1,81 +1,36 @@
|
|||
[submodule "3rdparty/blobs"]
|
||||
path = 3rdparty/blobs
|
||||
url = https://review.coreboot.org/blobs.git
|
||||
url = ../blobs.git
|
||||
update = none
|
||||
ignore = dirty
|
||||
[submodule "util/nvidia-cbootimage"]
|
||||
path = util/nvidia/cbootimage
|
||||
url = https://review.coreboot.org/nvidia-cbootimage.git
|
||||
url = ../nvidia-cbootimage.git
|
||||
[submodule "vboot"]
|
||||
path = 3rdparty/vboot
|
||||
url = https://review.coreboot.org/vboot.git
|
||||
branch = main
|
||||
url = ../vboot.git
|
||||
[submodule "arm-trusted-firmware"]
|
||||
path = 3rdparty/arm-trusted-firmware
|
||||
url = https://review.coreboot.org/arm-trusted-firmware.git
|
||||
url = ../arm-trusted-firmware.git
|
||||
[submodule "3rdparty/chromeec"]
|
||||
path = 3rdparty/chromeec
|
||||
url = ../chrome-ec.git
|
||||
[submodule "libhwbase"]
|
||||
path = 3rdparty/libhwbase
|
||||
url = https://review.coreboot.org/libhwbase.git
|
||||
url = ../libhwbase.git
|
||||
[submodule "libgfxinit"]
|
||||
path = 3rdparty/libgfxinit
|
||||
url = https://review.coreboot.org/libgfxinit.git
|
||||
url = ../libgfxinit.git
|
||||
[submodule "3rdparty/fsp"]
|
||||
path = 3rdparty/fsp
|
||||
url = https://review.coreboot.org/fsp.git
|
||||
url = ../fsp.git
|
||||
update = none
|
||||
ignore = dirty
|
||||
[submodule "opensbi"]
|
||||
path = 3rdparty/opensbi
|
||||
url = https://review.coreboot.org/opensbi.git
|
||||
url = ../opensbi.git
|
||||
[submodule "intel-microcode"]
|
||||
path = 3rdparty/intel-microcode
|
||||
url = https://review.coreboot.org/intel-microcode.git
|
||||
url = ../intel-microcode.git
|
||||
update = none
|
||||
ignore = dirty
|
||||
branch = main
|
||||
[submodule "3rdparty/ffs"]
|
||||
path = 3rdparty/ffs
|
||||
url = https://review.coreboot.org/ffs.git
|
||||
[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
|
||||
|
||||
|
|
|
|||
|
|
@ -2,4 +2,4 @@
|
|||
host=review.coreboot.org
|
||||
port=29418
|
||||
project=coreboot
|
||||
defaultbranch=main
|
||||
defaultbranch=master
|
||||
|
|
|
|||
425
.mailmap
425
.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>
|
||||
1
3rdparty/amd_blobs
vendored
1
3rdparty/amd_blobs
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit aa9288a33c6d7a67e55b8757390029207593fa9f
|
||||
2
3rdparty/arm-trusted-firmware
vendored
2
3rdparty/arm-trusted-firmware
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 9109143417b24337d39a2a9583828a44996f8aac
|
||||
Subproject commit 693e278e308441d716f7f5116c43aa150955da31
|
||||
2
3rdparty/blobs
vendored
2
3rdparty/blobs
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 4a8de0324e7d389454ec33cdf66939b653bf6800
|
||||
Subproject commit d7600dd8718a076f0f9a89e53968b484254624dc
|
||||
1
3rdparty/chromeec
vendored
Submodule
1
3rdparty/chromeec
vendored
Submodule
|
|
@ -0,0 +1 @@
|
|||
Subproject commit 11bd4c0f4d11357ab830982d7dec164813c886dd
|
||||
1
3rdparty/cmocka
vendored
1
3rdparty/cmocka
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 8be37372097d1aa5e03b565936db7891b6180e73
|
||||
1
3rdparty/ffs
vendored
1
3rdparty/ffs
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 3ec70fbc458e32eef0d0b1de79688b4dc48cbd57
|
||||
2
3rdparty/fsp
vendored
2
3rdparty/fsp
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 81399b3b61479abc379c2d01362d4b6dc6f515c9
|
||||
Subproject commit 59964173e18950debcc6b8856c5c928935ce0b4f
|
||||
2
3rdparty/intel-microcode
vendored
2
3rdparty/intel-microcode
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 250941fb670645d7d91f761cc63656ad3a1ec367
|
||||
Subproject commit 1dd14da6d1ea5cfbd95923653f31c04aac3aa655
|
||||
1
3rdparty/intel-sec-tools
vendored
1
3rdparty/intel-sec-tools
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 0031ac73447baeb197fb2d80e5fba2470716e76d
|
||||
2
3rdparty/libgfxinit
vendored
2
3rdparty/libgfxinit
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 3c3828add50024e90e57d6fbe0e660d1b66302d9
|
||||
Subproject commit b3b9fa34bb99d33d0fc6a69c64966a71cebd5bd6
|
||||
2
3rdparty/libhwbase
vendored
2
3rdparty/libhwbase
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 584629b9f4771b7618951cec57df2ca3af9c6981
|
||||
Subproject commit bd0ed91cb985a697033edd9fd62d322aa017e791
|
||||
1
3rdparty/open-power-signing-utils
vendored
1
3rdparty/open-power-signing-utils
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 591c8f53482243626901e1cc8a4ae321f314040d
|
||||
2
3rdparty/opensbi
vendored
2
3rdparty/opensbi
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 5019fd124b4c46e1581129c5154fc2cdd3b777ed
|
||||
Subproject commit 804b997ed415001097803e4b537fd63d043874b9
|
||||
1
3rdparty/qc_blobs
vendored
1
3rdparty/qc_blobs
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 6379308814bd00a8b6e36a4715bdb86ba019a3a7
|
||||
1
3rdparty/stm
vendored
1
3rdparty/stm
vendored
|
|
@ -1 +0,0 @@
|
|||
Subproject commit 1f3258261a4f4d6c60ec4447c7a03acf2509b984
|
||||
2
3rdparty/vboot
vendored
2
3rdparty/vboot
vendored
|
|
@ -1 +1 @@
|
|||
Subproject commit 5c360ef458b0a013d8a6d47724bb0fffb5accbcf
|
||||
Subproject commit dac763c782ce05476dec02e855f349d2b6f3a910
|
||||
910
AUTHORS
910
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
|
||||
一颗小土豆
|
||||
小田喜陽彦
|
||||
忧郁沙茶
|
||||
陳建宏
|
||||
7
Documentation/.gitignore
vendored
7
Documentation/.gitignore
vendored
|
|
@ -1,7 +0,0 @@
|
|||
*.aux
|
||||
*.idx
|
||||
*.log
|
||||
*.toc
|
||||
*.out
|
||||
*.pdf
|
||||
_build
|
||||
|
|
@ -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
|
||||
68
Documentation/Binary_Extraction.md
Normal file
68
Documentation/Binary_Extraction.md
Normal file
|
|
@ -0,0 +1,68 @@
|
|||
# Intel IFD Binary Extraction Tutorial
|
||||
|
||||
## Part 1: Extracting Binaries
|
||||
|
||||
To begin extracting the binaries, first create a directory labeled "binaries"
|
||||
in the coreboot directory (i.e. /path/to/coreboot/binaries/).
|
||||
|
||||
Now, execute the following commands to extract the binaries from a ROM image.
|
||||
**Note:** Make sure you are in the root coreboot directory.
|
||||
|
||||
cd /path/to/coreboot/util/ifdtool
|
||||
./ifdtool COREBOOT_IMAGE
|
||||
./ifdtool -d COREBOOT_IMAGE
|
||||
./ifdtool -x COREBOOT_IMAGE
|
||||
|
||||
In the above steps, COREBOOT_IMAGE is the name of the ROM image to extract the
|
||||
binaries from, including the file path (ex. /build/coreboot.rom).
|
||||
|
||||
Copy the extracted .bin files to the binaries directory you created previously.
|
||||
**Note:** You may want to rename your various .bin files to more clearly
|
||||
indicate what they are and their purpose.
|
||||
|
||||
To extract the mrc.bin, move to the /coreboot/build directory and run the
|
||||
following command:
|
||||
|
||||
cd /path/to/coreboot/build/
|
||||
./cbfstool COREBOOT_IMAGE extract -n mrc.bin -f /path/to/destination/filename
|
||||
|
||||
where COREBOOT_IMAGE is the filepath to the ROM image (same image as above),
|
||||
/path/to/destination is the filepath to the destination directory and filename
|
||||
is the output filename. An example command is given below:
|
||||
|
||||
./cbfstool coreboot.rom extract -n mrc.bin -f /path/to/coreboot/binaries/mrc.bin
|
||||
|
||||
## Part 2: Using extract_blobs.sh
|
||||
|
||||
To simplify some of the steps above, there is a script in the
|
||||
/path/to/coreboot/util/chromeos/ directory called extract_blobs.sh what will
|
||||
extract the flashdescriptor.bin and intel_me.bin files.
|
||||
|
||||
To run this script, switch to the /path/to/coreboot/util/chromeos/ directory
|
||||
and execute the script providing a coreboot image as an argument.
|
||||
|
||||
cd /path/to/coreboot/util/chromeos/
|
||||
./extract_blobs.sh COREBOOT_IMAGE
|
||||
|
||||
Executing those commands will result in two binary blobs to appear in the
|
||||
/path/to/coreboot/util/chromeos/ directory under the names
|
||||
'flashdescriptor.bin' and 'me.bin'.
|
||||
|
||||
## Part 3: Changing the coreboot configuration settings
|
||||
|
||||
To begin using the binaries extracted above, enable the use of binary
|
||||
repositories in the menuconfig. From the main coreboot directory, run
|
||||
'make menuconfig'. Select "General Setup", then select "Allow use of
|
||||
binary-only repository", then exit to the main menu.
|
||||
|
||||
To configure the ROM image for a specific board, select "Mainboard". Select
|
||||
"Mainboard vendor" and scroll to the correct vendor. Then select "Mainboard
|
||||
model" and select the name of the board model. Exit back to the main menu.
|
||||
|
||||
To add the binaries you extracted, select "Chipset". Scroll and select "Add a
|
||||
System Agent Binary" and set the filepath to your mrc.bin file's filepath.
|
||||
Scroll and select "Add Intel descriptor.bin file" and type the filepath for
|
||||
your descriptor.bin file. Scroll down and select "Add Intel ME/TXE firmware
|
||||
file" and type the filepath for your ME file. Exit to the main menu.
|
||||
|
||||
Select "Exit", and select "Yes" when prompted to save your configuration.
|
||||
2441
Documentation/Doxyfile.coreboot
Normal file
2441
Documentation/Doxyfile.coreboot
Normal file
File diff suppressed because it is too large
Load diff
2441
Documentation/Doxyfile.coreboot_simple
Normal file
2441
Documentation/Doxyfile.coreboot_simple
Normal file
File diff suppressed because it is too large
Load diff
239
Documentation/Intel/Board/board.html
Normal file
239
Documentation/Intel/Board/board.html
Normal file
|
|
@ -0,0 +1,239 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Board</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>x86 Board Development</h1>
|
||||
<p>
|
||||
Board development requires System-on-a-Chip (SoC) support.
|
||||
The combined steps are listed
|
||||
<a target="_blank" href="../development.html">here</a>.
|
||||
The development steps for the board are listed below:
|
||||
</p>
|
||||
<ol>
|
||||
<li><a href="#RequiredFiles">Required Files</a></li>
|
||||
<li>Enable <a href="#SerialOutput">Serial Output</a></li>
|
||||
<li>Load the <a href="#SpdData">Memory Timing Data</a></li>
|
||||
<li><a href="#DisablePciDevices">Disable</a> the PCI devices</li>
|
||||
<li><a href="#AcpiTables">ACPI Tables</a></li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="RequiredFiles">Required Files</a></h2>
|
||||
<p>
|
||||
Create the board directory as src/mainboard/<Vendor>/<Board>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The following files are required to build a new board:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Kconfig.name - Defines the Kconfig value for the board</li>
|
||||
<li>Kconfig
|
||||
<ol type="A">
|
||||
<li>Selects the SoC for the board and specifies the SPI flash size
|
||||
<ol type="I">
|
||||
<li>BOARD_ROMSIZE_KB_<Size></li>
|
||||
<li>SOC_<Vendor>_<Chip Family></li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Declare the Kconfig values for:
|
||||
<ol type="I">
|
||||
<li>MAINBOARD_DIR</li>
|
||||
<li>MAINBOARD_PART_NUMBER</li>
|
||||
<li>MAINBOARD_VENDOR</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>devicetree.cb - Enable root bridge and serial port
|
||||
<ol type="A">
|
||||
<li>The first line must be "chip soc/Intel/<soc family>";
|
||||
this path is used by the generated static.c to include the chip.h
|
||||
header file
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>romstage.c
|
||||
<ol type="A">
|
||||
<li>Add routine mainboard_romstage_entry which calls romstage_common</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Configure coreboot build:
|
||||
<ol type="A">
|
||||
<li>Set LOCALVERSION</li>
|
||||
<li>Select vendor for the board</li>
|
||||
<li>Select the board</li>
|
||||
<li>CBFS_SIZE = 0x00100000</li>
|
||||
<li>Set the CPU_MICROCODE_CBFS_LEN</li>
|
||||
<li>Set the CPU_MICROCODE_CBFS_LOC</li>
|
||||
<li>Set the FSP_IMAGE_ID_STRING</li>
|
||||
<li>Set the FSP_LOC</li>
|
||||
<li>No payload</li>
|
||||
<li>Choose the default value for all other options</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="SerialOutput">Enable Serial Output</a></h2>
|
||||
<p>
|
||||
Use the following steps to enable serial output:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Implement the car_mainboard_pre_console_init routine in the com_init.c
|
||||
file:
|
||||
<ol type="A">
|
||||
<li>Power on and enable the UART controller</li>
|
||||
<li>Connect the UART receive and transmit data lines to the
|
||||
appropriate SoC pins
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add Makefile.inc
|
||||
<ol type="A">
|
||||
<li>Add com_init.c to romstage</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="SpdData">Memory Timing Data</a></h2>
|
||||
<p>
|
||||
Memory timing data is located in the flash. This data is in the format of
|
||||
<a target="_blank" href="https://en.wikipedia.org/wiki/Serial_presence_detect">serial presence detect</a>
|
||||
(SPD) data.
|
||||
Use the following steps to load the SPD data:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Edit Kconfig to add the DISPLAY_SPD_DATA" value which enables the
|
||||
display of the SPD data being passed to MemoryInit
|
||||
</li>
|
||||
<li>Create an "spd" subdirectory</li>
|
||||
<li>Create an spd/spd.c file for the SPD implementation
|
||||
<ol type="A">
|
||||
<li>Implement the mainboard_fill_spd_data routine
|
||||
<ol type="i">
|
||||
<li>Read the SPD data either from the spd.bin file or using I2C or SMBUS</li>
|
||||
<li>Fill in the pei_data structure with SPD data for each of the DIMMs</li>
|
||||
<li>Set the DIMM channel configuration</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add an .spd.hex file containing the memory timing data to the spd subdirectory</li>
|
||||
<li>Create spd/Makefile.inc
|
||||
<ol type="A">
|
||||
<li>Add spd.c to romstage</li>
|
||||
<li>Add the .spd.hex file to SPD_SOURCES</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Edit Makefile.inc to add the spd subdirectory</li>
|
||||
<li>Edit romstage.c
|
||||
<ol type="A">
|
||||
<li>Call mainboard_fill_spd_data</li>
|
||||
<li>Add mainboard_memory_init_params to copy the SPD and DRAM
|
||||
configuration data from the pei_data structure into the UPDs
|
||||
for MemoryInit
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Edit devicetree.cb
|
||||
<ol type="A">
|
||||
<li>Include the UPD parameters for MemoryInit except for:
|
||||
<ul>
|
||||
<li>Address of SPD data</li>
|
||||
<li>DRAM configuration set above</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>A working FSP
|
||||
<a target="_blank" href="../fsp1_1.html#MemoryInit">MemoryInit</a>
|
||||
routine is required to complete debugging</li>
|
||||
<li>Debug the result until port 0x80 outputs
|
||||
<ol type="A">
|
||||
<li>0x34:
|
||||
- Just after entering
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
|
||||
</li>
|
||||
<li>0x36:
|
||||
- Just before displaying the
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l106">UPD parameters</a>
|
||||
for FSP MemoryInit
|
||||
</li>
|
||||
<li>0x92: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l219">POST_FSP_MEMORY_INIT</a>
|
||||
- Just before calling FSP
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l125">MemoryInit</a>
|
||||
</li>
|
||||
<li>0x37:
|
||||
- Just after returning from FSP
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l127">MemoryInit</a>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Continue debugging with CONFIG_DISPLAY_HOBS enabled until TempRamExit is called</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="DisablePciDevices">Disable PCI Devices</a></h2>
|
||||
<p>
|
||||
Ramstage's BS_DEV_ENUMERATE state displays the PCI vendor and device IDs for all
|
||||
of the devices in the system. Edit the devicetree.cb file:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Edit the devicetree.cb file:
|
||||
<ol type="A">
|
||||
<li>Add an entry for a PCI device.function and turn it off. The entry
|
||||
should look similar to:
|
||||
<pre><code>device pci 14.0 off end</code></pre>
|
||||
</li>
|
||||
<li>Turn on the devices for:
|
||||
<ul>
|
||||
<li>Memory Controller</li>
|
||||
<li>Debug serial device</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Debug until the BS_DEV_ENUMERATE state shows the proper state for all of the devices</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="AcpiTables">ACPI Tables</a></h2>
|
||||
<ol>
|
||||
<li>Edit Kconfig
|
||||
<ol type="A">
|
||||
<li>Add "select HAVE_ACPI_TABLES"</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add the acpi_tables.c module:
|
||||
<ol type="A">
|
||||
<li>Include soc/acpi.h</li>
|
||||
<li>Add the acpi_create_fadt routine
|
||||
<ol type="I">
|
||||
<li>fill in the ACPI header</li>
|
||||
<li>Call the acpi_fill_in_fadt routine</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add the dsdt.asl module:
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<p>Modified: 20 February 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
113
Documentation/Intel/Board/galileo.html
Normal file
113
Documentation/Intel/Board/galileo.html
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Galileo</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>Intel® Galileo Development Board</h1>
|
||||
<table>
|
||||
<tr>
|
||||
<td><a target="_blank" href="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg"><img alt="Galileo Gen 2" src="http://www.mouser.com/images/microsites/Intel_Galileo2_lrg.jpg" width=500></a></td>
|
||||
<td>
|
||||
The Intel® Galileo Gen 2 mainboard code was developed along with the Intel®
|
||||
<a target="_blank" href="../SoC/quark.html">Quark™</a> SoC:
|
||||
<ul>
|
||||
<li><a target="_blank" href="../development.html">Overall</a> development</li>
|
||||
<li><a target="_blank" href="../SoC/soc.html">SoC</a> support</li>
|
||||
<li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
|
||||
<li><a target="_blank" href="board.html">Board</a> support</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2>Galileo Board Documentation</h2>
|
||||
<ul>
|
||||
<li>Common Components
|
||||
<ul>
|
||||
<li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li>
|
||||
<li>Analog Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li>
|
||||
<li>Ethernet (10/100 MB/S): Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/dp83848-ep.pdf">DP83848</a></li>
|
||||
<li>Load Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps22920.pdf">TPS22920x</a></li>
|
||||
<li>Memory (256 MiB): Micron <a target="_blank" href="https://www.micron.com/~/media/Documents/Products/Data%20Sheet/DRAM/DDR3/1Gb_1_35V_DDR3L.pdf">MT41K128M8</a></li>
|
||||
<li>SoC: Intel® Quark™ <a target="_blank" href="../SoC/quark.html">X-1000</a></li>
|
||||
<li>Serial EEPROM (1 KiB): ON Semiconductor® <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li>
|
||||
<li>SPI Flash (8 MiB): Winbond™ <a target="_blank" href="http://www.winbond-usa.com/resource-files/w25q64fv_revl1_100713.pdf">W25Q64FV</a></li>
|
||||
<li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li>
|
||||
<li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ug/slvu570/slvu570.pdf">TPS652510</a></li>
|
||||
<li>Termination Regulator: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps51200.pdf">TPS51200</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Make a bootable <a target="_blank" href="https://software.intel.com/en-us/get-started-galileo-linux-step1">micro SD card</a></li>
|
||||
</ul>
|
||||
|
||||
<h3>Galileo Gen 2 Board Documentation</h3>
|
||||
<ul>
|
||||
<li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_blockdiagram.jpg">Block Diagram</a></li>
|
||||
<li><a target="_blank" href="https://software.intel.com/en-us/iot/library/galileo-getting-started">Getting Started</a></li>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/galileo/galileo-overview.html">Overview</a></li>
|
||||
<li><a target="_blank" href="http://files.linuxgizmos.com/intel_galileo_gen2_ports.jpg">Port Diagram</a></li>
|
||||
<li><a target="_blank" href="http://download.intel.com/support/galileo/sb/intelgalileogen2prodbrief_330736_003.pdf">Product Brief</a></li>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g2-schematic.pdf">Schematic</a></li>
|
||||
<li><a target="_blank" href="http://download.intel.com/support/galileo/sb/galileo_boarduserguide_330237_001.pdf">User Guide</a></li>
|
||||
<li>Components
|
||||
<ul>
|
||||
<li>A/D: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/adc108s102.pdf">ADC108S102</a></li>
|
||||
<li>I2C 16-channel, 12-bit PWM: NXP Semiconductors <a target="_blank" href="http://cache.nxp.com/documents/data_sheet/PCA9685.pdf">PCA9685</a></li>
|
||||
<li>I2C I/O Ports: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/PCAL9535A.pdf">PCAL9535A</a></li>
|
||||
<li>Octal Buffer/Driver: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv541at.pdf">SN74LV541AT</a></li>
|
||||
<li>Quadruple Bus Buffer: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lv125a.pdf">SN74LV125A</a></li>
|
||||
<li>Quadruple Bus Buffer with 3-State Outputs: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/sn74lvc126a.pdf">SN74LVC126A</a></li>
|
||||
<li>Serial EEPROM (1 KiB): ON Semiconductor® <a target="_blank" href="http://www.onsemi.com/pub_link/Collateral/CAT24C01-D.PDF">CAT24C08</a></li>
|
||||
<li>Single 2-input multiplexer: NXP Semiconductors <a target="_blank" href="http://www.nxp.com/documents/data_sheet/74LVC1G157.pdf">74LVC1G157</a></li>
|
||||
<li>Step Down Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/slvsag7c/slvsag7c.pdf">TPS62130</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h3>Galileo Gen 1 Board Documentation</h3>
|
||||
<ul>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/galileo-g1-datasheet.pdf">Datasheet</a></li>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/galileo-g1-schematic.pdf">Schematic</a></li>
|
||||
<li>Components
|
||||
<ul>
|
||||
<li>A/D: Analog Devices <a target="_blank" href="http://www.analog.com/media/en/technical-documentation/data-sheets/AD7298-1.pdf">AD7298</a></li>
|
||||
<li>Analog Switch, 2 channel: Texas Instruments <a target="_blank" href="http://www.ti.com.cn/cn/lit/ds/symlink/ts5a23159.pdf">TS5A23159</a></li>
|
||||
<li>EEPROM & GPIO: Cypress <a target="_blank" href="http://www.cypress.com/file/37971/download">CY8C9540A</a></li>
|
||||
<li>Power Distribution Switch: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/tps2044b.pdf">TPS2051BDBVR</a></li>
|
||||
<li>RS232 Converter: Texas Instruments <a target="_blank" href="http://www.ti.com/lit/ds/symlink/max3232.pdf">MAX3232</a></li>
|
||||
<li>Voltage-Level Translator: Texas Instruments<a target="_blank" href="http://www.ti.com/lit/ds/symlink/txs0108e.pdf">TXS0108E</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2>Debug Tools</h2>
|
||||
<ul>
|
||||
<li>Flash Programmer:
|
||||
<ul>
|
||||
<li>Dediprog <a target="_blank" href="http://www.dediprog.com/pd/spi-flash-solution/SF100">SF100</a> ISP IC Programmer</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>JTAG Connector: <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=Olimex+ARM-JTAG-20-10">Olimex ARM-JTAG-20-10</a></li>
|
||||
<li>JTAG Debugger:
|
||||
<ul>
|
||||
<li>Olimex LTD <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=Olimex+ARM-USB-OCD-H">ARM-USB-OCD-H</a></li>
|
||||
<li>Tincan Tools <a target="_blank" href="https://www.tincantools.com/wiki/Flyswatter2">Flyswatter2</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a target="_blank" href="http://download.intel.com/support/processors/quark/sb/sourcedebugusingopenocd_quark_appnote_330015_003.pdf">Hardware Setup and Software Installation</a></li>
|
||||
<li>USB Serial cable: FTDI <a target="_blank" href="https://www.google.com/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=FTDI+TTL-232R-3V3">TTL-232R-3V3</a></li>
|
||||
</ul>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>Modified: 29 February 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
220
Documentation/Intel/SoC/quark.html
Normal file
220
Documentation/Intel/SoC/quark.html
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Quark™ SoC</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>Intel® Quark™ SoC</h1>
|
||||
<table>
|
||||
<tr>
|
||||
<td><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png"><img alt="Quark Block Diagram" src="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png" width=500></a></td>
|
||||
<td>
|
||||
The Quark™ SoC code was developed using the
|
||||
<a target="_blank" href="../Board/galileo.html">Galileo Gen 2</a>
|
||||
board:
|
||||
<ul>
|
||||
<li><a target="_blank" href="../development.html">Overall</a> development</li>
|
||||
<li><a target="_blank" href="soc.html">SoC</a> support</li>
|
||||
<li><a target="_blank" href="../fsp1_1.html">FSP 1.1</a> integration</li>
|
||||
<li><a target="_blank" href="../Board/board.html">Board</a> support</li>
|
||||
<li><a target="_blank" href="#QuarkFsp">Quark™ FSP</a></li>
|
||||
<li><a target="_blank" href="#CorebootPayloadPkg">CorebootPayloadPkg</a></li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2>Quark™ Documentation</h2>
|
||||
<ul>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/images/embedded/16x9/edc-quark-block-diagram-16x9.png">Block Diagram</a></li>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/www/us/en/embedded/products/quark/specifications.html">Specifications</a>:
|
||||
<ul>
|
||||
<li><a target="_blank" href="http://ark.intel.com/products/79084/Intel-Quark-SoC-X1000-16K-Cache-400-MHz">X1000</a>
|
||||
- <a target="_blank" href="http://www.intel.com/content/www/us/en/search.html?keyword=X1000">Documentation</a>:
|
||||
<ul>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/datasheets/quark-x1000-datasheet.pdf">Datasheet</a></li>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/support/us/en/documents/processors/quark/sb/intelquarkcore_devman_001.pdf">Developer's Manual</a></li>
|
||||
<li><a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/intel-quark-product-brief-v3.pdf">Product Brief</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a target="_blank" href="../index.html#Documentation">More documentation</a></li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="CorebootPayloadPkg">Quark™ EDK2 CorebootPayloadPkg</a></h2>
|
||||
<p>
|
||||
Build Instructions:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Set up <a href="#BuildEnvironment">build environment</a></li>
|
||||
<li>Linux (assumes GCC48):
|
||||
<pre><code>build -p CorebootPayloadPkg/CorebootPayloadPkgIa32.dsc -a IA32 \
|
||||
-t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 \
|
||||
-DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL \
|
||||
-DMAX_LOGICAL_PROCESSORS=1
|
||||
ls Build/CorebootPayloadPkgIA32/DEBUG_GCC48/FV/UEFIPAYLOAD.fd
|
||||
</code></pre>
|
||||
</li>
|
||||
<li>Windows (assumes Visual Studio 2015):
|
||||
<pre><code>build -p CorebootPayloadPkg\CorebootPayloadPkgIa32.dsc -a IA32 -t VS2015x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042 -DSHELL_TYPE=BUILD_SHELL -DMAX_LOGICAL_PROCESSORS=1
|
||||
dir Build\CorebootPayloadPkgIA32\DEBUG_VS2015x86\FV\UEFIPAYLOAD.fd
|
||||
</code></pre>
|
||||
</li>
|
||||
<li>In the .config for coreboot, set the following Kconfig values:
|
||||
<ul>
|
||||
<li>CONFIG_PAYLOAD_ELF=y</li>
|
||||
<li>CONFIG_PAYLOAD_FILE="path to UEFIPAYLOAD.fd"</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Build coreboot</li>
|
||||
<li>Copy the image build/coreboot.rom into flash</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="BuildEnvironment">Quark™ EDK2 Build Environment</a></h2>
|
||||
<p>
|
||||
Use the following steps to setup a build environment:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Get the EDK2 sources:
|
||||
<ol type="A">
|
||||
<li>EDK2: git clone <a target="_blank" href="https://github.com/tianocore/edk2.git">https://github.com/tianocore/edk2.git</a></li>
|
||||
<li>EDK2-non-osi: git clone <a target="_blank" href="https://github.com/tianocore/edk2-non-osi.git">https://github.com/tianocore/edk2-non-osi.git</a></li>
|
||||
<li>Win32 BaseTools: git clone <a target="_blank" href="https://github.com/tianocore/edk2-BaseTools-win32.git">https://github.com/tianocore/edk2-BaseTools-win32.git</a></li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Set up a build window:
|
||||
<ul>
|
||||
<li>Linux:
|
||||
<pre><code>export WORKSPACE=$PWD
|
||||
export PACKAGES_PATH="$PWD/edk2:$PWD/edk2-non-osi"
|
||||
cd edk2
|
||||
export WORKSPACE=$PWD
|
||||
. edksetup.sh
|
||||
</code></pre>
|
||||
</li>
|
||||
<li>Windows:
|
||||
<pre><code>set WORKSPACE=%CD%
|
||||
set PACKAGES_PATH=%WORKSPACE%\edk2;%WORKSPACE%\edk2-non-osi
|
||||
set EDK_TOOLS_BIN=%WORKSPACE%\edk2-BaseTools-win32
|
||||
cd edk2
|
||||
edksetup.bat
|
||||
</code></pre>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="QuarkFsp">Quark™ FSP</a></h2>
|
||||
<p>
|
||||
Getting the Quark FSP source:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Set up an EDK-II <a href="#BuildEnvironment">Build Environment</a></li>
|
||||
<li>cd edk2</li>
|
||||
<li>mkdir QuarkFspPkg</li>
|
||||
<li>cd QuarkFspPkg</li>
|
||||
<li>Use git to clone <a target="_blank" href="https://review.gerrithub.io/#/admin/projects/LeeLeahy/quarkfsp">QuarkFspPkg</a> into the QuarkFpsPkg directory (.)</li>
|
||||
</ol>
|
||||
|
||||
<h3>Building QuarkFspPkg</h3>
|
||||
<p>
|
||||
There are two versions of FSP: FSP 1.1 and FSP 2.0. There are also two
|
||||
different implementations of FSP, one using subroutines without SEC and
|
||||
PEI core and the original implementation which relies on SEC and PEI core.
|
||||
Finally there are two different build x86 types release (r32) and debug (d32).
|
||||
</p>
|
||||
<p>Note that the subroutine implementations are a <b>work in progress</b>.</p>
|
||||
<p>
|
||||
Build commands shown building debug FSP:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Linux:
|
||||
<ul>
|
||||
<li>QuarkFspPkg/BuildFsp1_1.sh -d32</li>
|
||||
<li>QuarkFspPkg/BuildFsp1_1Pei.sh -d32</li>
|
||||
<li>QuarkFspPkg/BuildFsp2_0.sh -d32</li>
|
||||
<li>QuarkFspPkg/BuildFsp2_0Pei.sh -d32</li>
|
||||
</ul>
|
||||
<li>Windows:
|
||||
<ul>
|
||||
<li>QuarkFspPkg/BuildFsp1_1.bat -d32</li>
|
||||
<li>Windows: QuarkFspPkg/BuildFsp2_0.bat -d32</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
<h3>Copying FSP files into coreboot Source Tree</h3>
|
||||
<p>
|
||||
There are some helper scripts to copy the FSP output into the coreboot
|
||||
source tree. The parameters to these scripts are:
|
||||
</p>
|
||||
<ol>
|
||||
<li>EDK2 tree root</li>
|
||||
<li>coreboot tree root</li>
|
||||
<li>Build type: DEBUG or RELEASE</li>
|
||||
</ol>
|
||||
<p>
|
||||
Script files:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Linux:
|
||||
<ul>
|
||||
<li>QuarkFspPkg/coreboot_fsp1_1.sh</li>
|
||||
<li>QuarkFspPkg/coreboot_fsp1_1Pei.sh</li>
|
||||
<li>QuarkFspPkg/coreboot_fsp2_0.sh</li>
|
||||
<li>QuarkFspPkg/coreboot_fsp2_0Pei.sh</li>
|
||||
</ul>
|
||||
</ul>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2>Quark™ EDK2 BIOS</h2>
|
||||
<p>
|
||||
Build Instructions:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Set up <a href="#BuildEnvironment">build environment</a></li>
|
||||
<li>Build the image:
|
||||
<ul>
|
||||
<li>Linux:
|
||||
<pre><code>build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t GCC48 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042
|
||||
ls Build/Quark/DEBUG_GCC48/FV/Quark.fd
|
||||
</code></pre>
|
||||
</li>
|
||||
<li>Windows:
|
||||
<pre><code>build -p QuarkPlatformPkg/Quark.dsc -a IA32 -t VS2012x86 -b DEBUG -DDEBUG_PROPERTY_MASK=0x27 -DDEBUG_PRINT_ERROR_LEVEL=0x80000042
|
||||
dir Build\Quark\DEBUG_VS2012x86\FV\Quark.fd
|
||||
</code></pre>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
Documentation:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a target="_blank" href="https://github.com/tianocore/edk2/tree/master/QuarkPlatformPkg">EDK II firmware for Intel® Quark™ SoC X1000 based platforms</a></li>
|
||||
<li>Intel® Quark™ SoC X1000 <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/guides/quark-x1000-uefi-firmware-writers-guide.pdf">UEFI Firmware Writer's Guide</a></li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<p>Modified: 17 May 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
731
Documentation/Intel/SoC/soc.html
Normal file
731
Documentation/Intel/SoC/soc.html
Normal file
|
|
@ -0,0 +1,731 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>SoC</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>x86 System on a Chip (SoC) Development</h1>
|
||||
<p>
|
||||
SoC development is best done in parallel with development for a specific
|
||||
board. The combined steps are listed
|
||||
<a target="_blank" href="../development.html">here</a>.
|
||||
The development steps for the SoC are listed below:
|
||||
</p>
|
||||
<ol>
|
||||
<li><a target="_blank" href="../fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
|
||||
<li>SoC <a href="#RequiredFiles">Required Files</a></li>
|
||||
<li><a href="#Descriptor">Start Booting</a></li>
|
||||
<li><a href="#EarlyDebug">Early Debug</a></li>
|
||||
<li><a href="#Bootblock">Bootblock</a></li>
|
||||
<li><a href="#TempRamInit">TempRamInit</a></li>
|
||||
<li><a href="#Romstage">Romstage</a>
|
||||
<ol type="A">
|
||||
<li>Enable <a href="#SerialOutput">Serial Output"</a></li>
|
||||
<li>Get the <a href="#PreviousSleepState">Previous Sleep State</a></li>
|
||||
<li>Add the <a href="#MemoryInit">MemoryInit</a> Support</li>
|
||||
<li>Disable the <a href="#DisableShadowRom">Shadow ROM</a></li>
|
||||
</ol>
|
||||
</li>
|
||||
<li><a href="#Ramstage">Ramstage</a>
|
||||
<ol type="A">
|
||||
<li><a href="#DeviceTree">Start Device Tree Processing</a></li>
|
||||
<li>Set up the <a href="#MemoryMap">Memory Map"</a></li>
|
||||
</ol>
|
||||
</li>
|
||||
<li><a href="#AcpiTables">ACPI Tables</a></li>
|
||||
<li><a href="#LegacyHardware">Legacy Hardware</a></li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="RequiredFiles">Required Files</a></h2>
|
||||
<p>
|
||||
Create the directory as src/soc/<Vendor>/<Chip Family>.
|
||||
</p>
|
||||
|
||||
<p>
|
||||
The following files are required to build a new SoC:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Include files
|
||||
<ul>
|
||||
<li>include/soc/pei_data.h</li>
|
||||
<li>include/soc/pm.h</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Kconfig - Defines the Kconfig value for the SoC and selects the tool
|
||||
chains for the various stages:
|
||||
<ul>
|
||||
<li>select ARCH_BOOTBLOCK_<Tool Chain></li>
|
||||
<li>select ARCH_RAMSTAGE_<Tool Chain></li>
|
||||
<li>select ARCH_ROMSTAGE_<Tool Chain></li>
|
||||
<li>select ARCH_VERSTAGE_<Tool Chain></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Makefile.inc - Specify the include paths</li>
|
||||
<li>memmap.c - Top of usable RAM</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="Descriptor">Start Booting</a></h2>
|
||||
<p>
|
||||
Some SoC parts require additional firmware components in the flash.
|
||||
This section describes how to add those pieces.
|
||||
</p>
|
||||
|
||||
<h3>Intel Firmware Descriptor</h3>
|
||||
<p>
|
||||
The Intel Firmware Descriptor (IFD) is located at the base of the flash part.
|
||||
The following command overwrites the base of the flash image with the Intel
|
||||
Firmware Descriptor:
|
||||
</p>
|
||||
<pre><code>dd if=descriptor.bin of=build/coreboot.rom conv=notrunc >/dev/null 2>&1</code></pre>
|
||||
|
||||
|
||||
<h3><a name="MEB">Management Engine Binary</a></h3>
|
||||
<p>
|
||||
Some SoC parts contain and require that the Management Engine (ME) be running
|
||||
before it is possible to bring the x86 processor out of reset. A binary file
|
||||
containing the management engine code must be added to the firmware using the
|
||||
ifdtool. The following commands add this binary blob:
|
||||
</p>
|
||||
<pre><code>util/ifdtool/ifdtool -i ME:me.bin build/coreboot.rom
|
||||
mv build/coreboot.rom.new build/coreboot.rom
|
||||
</code></pre>
|
||||
|
||||
|
||||
<h3><a name="EarlyDebug">Early Debug</a></h3>
|
||||
<p>
|
||||
Early debugging between the reset vector and the time the serial port is enabled
|
||||
is most easily done by writing values to port 0x80.
|
||||
</p>
|
||||
|
||||
|
||||
<h3>Success</h3>
|
||||
<p>
|
||||
When the reset vector is successfully invoked, port 0x80 will output the following value:
|
||||
</p>
|
||||
<ul>
|
||||
<li>0x01: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l45">POST_RESET_VECTOR_CORRECT</a>
|
||||
- Bootblock successfully executed the
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc;hb=HEAD#l4">reset vector</a>
|
||||
and entered the 16-bit code at
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc;hb=HEAD#l35">_start</a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="Bootblock">Bootblock</a></h2>
|
||||
<p>
|
||||
Implement the bootblock using the following steps:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Create the directory as src/soc/<Vendor>/<Chip Family>/bootblock</li>
|
||||
<li>Add the timestamp.inc file which initializes the floating point registers and saves
|
||||
the initial timestamp.
|
||||
</li>
|
||||
<li>Add the bootblock.c file which:
|
||||
<ol type="A">
|
||||
<li>Enables memory-mapped PCI config access</li>
|
||||
<li>Updates the microcode by calling intel_update_microcode_from_cbfs</li>
|
||||
<li>Enable ROM caching</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file
|
||||
<ol type="A">
|
||||
<li>Add the BOOTBLOCK_CPU_INIT value to point to the bootblock.c file</li>
|
||||
<li>Add the CHIPSET_BOOTBLOCK_INCLUDE value to point to the timestamp.inc file</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Edit the src/soc/<Vendor>/<Chip Family>/Makefile.inc file
|
||||
<ol type="A">
|
||||
<li>Add the bootblock subdirectory</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Edit the src/soc/<Vendor>/<Chip Family>/memmap.c file
|
||||
<ol type="A">
|
||||
<li>Add the fsp/memmap.h include file</li>
|
||||
<li>Add the mmap_region_granularity routine</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add the necessary .h files to define the necessary values and structures</li>
|
||||
<li>When successful port 0x80 will output the following values:
|
||||
<ol type="A">
|
||||
<li>0x01: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l45">POST_RESET_VECTOR_CORRECT</a>
|
||||
- Bootblock successfully executed the
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc;hb=HEAD#l4">reset vector</a>
|
||||
and entered the 16-bit code at
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc;hb=HEAD#l35">_start</a>
|
||||
</li>
|
||||
<li>0x10: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l53">POST_ENTER_PROTECTED_MODE</a>
|
||||
- Bootblock executing in
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/entry32.inc;hb=HEAD#l55">32-bit mode</a>
|
||||
</li>
|
||||
<li>0x10 - Verstage/romstage reached 32-bit mode</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
<b>Build Note:</b> The following files are included into the default bootblock image:
|
||||
</p>
|
||||
<ul>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootblock_romcc.S;hb=HEAD">src/arch/x86/bootblock_romcc.S</a>
|
||||
added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l133">src/arch/x86/Makefile.inc</a>
|
||||
and includes the following files:
|
||||
<ul>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/prologue.inc">src/arch/x86/prologue.inc</a></li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/reset16.inc">src/cpu/x86/16bit/reset16.inc</a></li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/16bit/entry16.inc">src/cpu/x86/16bit/entry16.inc</a></li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/32bit/entry32.inc">src/cpu/x86/32bit/entry32.inc</a></li>
|
||||
<li>The code in
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/bootblock_romcc.S">src/arch/x86/bootblock_romcc.S</a>
|
||||
includes src/soc/<Vendor>/<Chip Family>/bootblock/timestamp.inc using the
|
||||
CONFIG_CHIPSET_BOOTBLOCK_INCLUDE value set above
|
||||
</li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/sse_enable.inc">src/cpu/x86/sse_enable.inc</a></li>
|
||||
<li>The code in
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l156">src/arch/x86/Makefile.inc</a>
|
||||
invokes the ROMCC tool to convert the following "C" code into assembler as bootblock.inc:
|
||||
<ul>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/bootblock_romcc.h">src/arch/x86/include/arch/bootblock_romcc.h</a></li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/x86/lapic/boot_cpu.c">src/cpu/x86/lapic/boot_cpu.c</a></li>
|
||||
<li>The CONFIG_BOOTBLOCK_CPU_INIT value set above typically points to the code in
|
||||
src/soc/<Vendor>/<Chip Family>/bootblock/bootblock.c
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/id.S">src/arch/x86/id.S</a>
|
||||
added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l110">src/arch/x86/Makefile.inc</a>
|
||||
</li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/fit.S">src/cpu/intel/fit/fit.S</a>
|
||||
added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/cpu/intel/fit/Makefile.inc;hb=HEAD">src/cpu/intel/fit/Makefile.inc</a>
|
||||
</li>
|
||||
<li><a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/walkcbfs.S">src/arch/x86/walkcbfs.S</a>
|
||||
added by <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/Makefile.inc;hb=HEAD#l137">src/arch/x86/Makefile.inc</a>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="TempRamInit">TempRamInit</a></h2>
|
||||
<p>
|
||||
Enable the call to TempRamInit in two stages:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Finding the FSP binary in the read-only CBFS region</li>
|
||||
<li>Call TempRamInit</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<h3>Find FSP Binary</h3>
|
||||
<p>
|
||||
Use the following steps to locate the FSP binary:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Edit the src/soc/<Vendor>/<Chip Family>/Kconfig file
|
||||
<ol type="A">
|
||||
<li>Add "select USE_GENERIC_FSP_CAR_INC" to enable the use of
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc">src/drivers/intel/fsp1_1/cache_as_ram.inc</a>
|
||||
</li>
|
||||
<li>Add "select SOC_INTEL_COMMON" to enable the use of the files from src/soc/intel/common
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Debug the result until port 0x80 outputs
|
||||
<ol type="A">
|
||||
<li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
|
||||
- Just before calling
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
|
||||
</li>
|
||||
<li>Alternating 0xba and 0x01 - The FSP image was not found</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add the <a target="_blank" href="../fsp1_1.html#FspBinary">FSP binary file</a> to the flash image</li>
|
||||
<li>Set the following Kconfig values:
|
||||
<ul>
|
||||
<li>CONFIG_FSP_LOC to the FSP base address specified in the previous step</li>
|
||||
<li>CONFIG_FSP_IMAGE_ID_STRING</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Debug the result until port 0x80 outputs
|
||||
<ol type="A">
|
||||
<li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
|
||||
- Just before calling
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
|
||||
</li>
|
||||
<li>Alternating 0xbb and 0x02 - TempRamInit executed, no CPU microcode update found</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<h3>Calling TempRamInit</h3>
|
||||
<p>
|
||||
Use the following steps to debug the call to TempRamInit:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Add the CPU microcode update file
|
||||
<ol type="A">
|
||||
<li>Add the microcode file with the following command
|
||||
<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t microcode -n cpu_microcode_blob.bin -b <base address> -f cpu_microcode_blob.bin</code></pre>
|
||||
</li>
|
||||
<li>Set the Kconfig values
|
||||
<ul>
|
||||
<li>CONFIG_CPU_MICROCODE_CBFS_LOC set to the value from the previous step</li>
|
||||
<li>CONFIG_CPU_MICROCODE_CBFS_LEN</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Debug the result until port 0x80 outputs
|
||||
<ol type="A">
|
||||
<li>0x90: <a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>
|
||||
- Just before calling
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">TempRamInit</a>
|
||||
</li>
|
||||
<li>0x2A - Just before calling
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">cache_as_ram_main</a>
|
||||
which is the start of the verstage code which may be part of romstage
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="Romstage">Romstage</a></h2>
|
||||
|
||||
<h3><a name="SerialOutput">Serial Output</a></h3>
|
||||
<p>
|
||||
The following steps add the serial output support for romstage:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Create the romstage subdirectory</li>
|
||||
<li>Add romstage/romstage.c
|
||||
<ol type="A">
|
||||
<li>Program the necessary base addresses</li>
|
||||
<li>Disable the TCO</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add romstage/Makefile.inc
|
||||
<ol type="A">
|
||||
<li>Add romstage.c to romstage</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Add gpio configuration support if necessary</li>
|
||||
<li>Add the necessary .h files to support the build</li>
|
||||
<li>Update Makefile.inc
|
||||
<ol type="A">
|
||||
<li>Add the romstage subdirectory</li>
|
||||
<li>Add the gpio configuration support file to romstage</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Set the necessary Kconfig values to enable serial output:
|
||||
<ul>
|
||||
<li>CONFIG_DRIVERS_UART_<driver>=y</li>
|
||||
<li>CONFIG_CONSOLE_SERIAL=y</li>
|
||||
<li>CONFIG_UART_FOR_CONSOLE=<port></li>
|
||||
<li>CONFIG_CONSOLE_SERIAL_115200=y</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<h3><a name="PreviousSleepState">Determine Previous Sleep State</a></h3>
|
||||
<p>
|
||||
The following steps implement the code to get the previous sleep state:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Implement the fill_power_state routine which determines the previous sleep state</li>
|
||||
<li>Debug the result until port 0x80 outputs
|
||||
<ol type="A">
|
||||
<li>0x32:
|
||||
- Just after entering
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l99">romstage_common</a>
|
||||
</li>
|
||||
<li>0x33 - Just after calling
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/romstage.c;hb=HEAD#l113">soc_pre_ram_init</a>
|
||||
</li>
|
||||
<li>0x34:
|
||||
- Just after entering
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l67">raminit</a>
|
||||
</li>
|
||||
</ol>
|
||||
</ol>
|
||||
|
||||
|
||||
<h3><a name="MemoryInit">MemoryInit Support</a></h3>
|
||||
<p>
|
||||
The following steps implement the code to support the FSP MemoryInit call:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Add the chip.h header file to define the UPD values which get passed
|
||||
to MemoryInit. Skip the values containing SPD addresses and DRAM
|
||||
configuration data which is determined by the board.
|
||||
<p>
|
||||
<b>Build Note</b>: The src/mainboard/<Vendor>/<Board>/devicetree.cb
|
||||
file specifies the default values for these parameters. The build
|
||||
process creates the static.c module which contains the config data
|
||||
structure containing these values.
|
||||
</p>
|
||||
</li>
|
||||
<li>Edit romstage/romstage.c
|
||||
<ol type="A">
|
||||
<li>Implement the romstage/romstage.c/soc_memory_init_params routine to
|
||||
copy the values from the config structure into the UPD structure
|
||||
</li>
|
||||
<li>Implement the soc_display_memory_init_params routine to display
|
||||
the updated UPD parameters by calling fsp_display_upd_value
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<h3><a name="DisableShadowRom">Disable Shadow ROM</a></h3>
|
||||
<p>
|
||||
A shadow of the SPI flash part is mapped from 0x000e0000 to 0x000fffff.
|
||||
This shadow needs to be disabled to allow RAM to properly respond to
|
||||
this address range.
|
||||
</p>
|
||||
<ol>
|
||||
<li>Edit romstage/romstage.c and add the soc_after_ram_init routine</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="Ramstage">Ramstage</a></h2>
|
||||
|
||||
<h3><a name="DeviceTree">Start Device Tree Processing</a></h3>
|
||||
<p>
|
||||
The src/mainboard/<Vendor>/<Board>/devicetree.cb file drives the
|
||||
execution during ramstage. This file is processed by the util/sconfig utility
|
||||
to generate build/mainboard/<Vendor>/<Board>/static.c. The various
|
||||
state routines in
|
||||
src/lib/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/lib/hardwaremain.c;hb=HEAD#l128">hardwaremain.c</a>
|
||||
call dev_* routines which use the tables in static.c to locate operation tables
|
||||
associated with the various chips and devices. After location the operation
|
||||
tables, the state routines call one or more functions depending upon the
|
||||
state of the state machine.
|
||||
</p>
|
||||
|
||||
<h4><a name="ChipOperations">Chip Operations</a></h4>
|
||||
<p>
|
||||
Kick-starting the ramstage state machine requires creating the operation table
|
||||
for the chip listed in devicetree.cb:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c:
|
||||
<ol type="A">
|
||||
<li>
|
||||
This chip's operation table has the name
|
||||
soc_<SoC Vendor>_<SoC Family>_ops which is derived from the
|
||||
chip path specified in the devicetree.cb file.
|
||||
</li>
|
||||
<li>Use the CHIP_NAME macro to specify the name for the chip</li>
|
||||
<li>For FSP 1.1, specify a .init routine which calls intel_silicon_init</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Edit src/soc/<SoC Vendor>/<SoC Family>/Makefile.inc and add chip.c to ramstage</li>
|
||||
</ol>
|
||||
|
||||
<h4>Domain Operations</h4>
|
||||
<p>
|
||||
coreboot uses the domain operation table to initiate operations on all of the
|
||||
devices in the domain. By default coreboot enables all PCI devices which it
|
||||
finds. Listing a device in devicetree.cb gives the board vendor control over
|
||||
the device state. Non-PCI devices may also be listed under PCI device such as
|
||||
the LPC bus or SMbus devices.
|
||||
</p>
|
||||
<ol>
|
||||
<li>Edit src/soc/<SoC Vendor>/<SoC Family>/chip.c:
|
||||
<ol type="A">
|
||||
<li>
|
||||
The domain operation table is typically placed in
|
||||
src/soc/<SoC Vendor>/<SoC Family>/chip.c.
|
||||
The table typically looks like the following:
|
||||
<pre><code>static struct device_operations pci_domain_ops = {
|
||||
.read_resources = pci_domain_read_resources,
|
||||
.set_resources = pci_domain_set_resources,
|
||||
.scan_bus = pci_domain_scan_bus,
|
||||
};
|
||||
</code></pre>
|
||||
</li>
|
||||
<li>
|
||||
Create a .enable_dev entry in the chip operations table which points to a
|
||||
routine which sets the domain table for the device with the DEVICE_PATH_DOMAIN.
|
||||
<pre><code> if (dev->path.type == DEVICE_PATH_DOMAIN) {
|
||||
dev->ops = &pci_domain_ops;
|
||||
}
|
||||
</code></pre>
|
||||
</li>
|
||||
<li>
|
||||
During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
|
||||
for the PCI devices on the bus.
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Set CONFIG_DEBUG_BOOT_STATE=y in the .config file</li>
|
||||
<li>
|
||||
Debug the result until the PCI vendor and device IDs are displayed
|
||||
during the BS_DEV_ENUMERATE state.
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<h3><a name="DeviceDrivers">PCI Device Drivers</a></h3>
|
||||
<p>
|
||||
PCI device drivers consist of a ".c" file which contains a "pci_driver" data
|
||||
structure at the end of the file with the attribute tag "__pci_driver". This
|
||||
attribute tag places an entry into a link time table listing the various
|
||||
coreboot device drivers.
|
||||
</p>
|
||||
<p>
|
||||
Specify the following fields in the table:
|
||||
</p>
|
||||
<ol>
|
||||
<li>.vendor - PCI vendor ID value of the device</li>
|
||||
<li>.device - PCI device ID value of the device or<br>
|
||||
.devices - Address of a zero terminated array of PCI device IDs
|
||||
</li>
|
||||
<li>.ops - Operations table for the device. This is the address
|
||||
of a "static struct device_operations" data structure specifying
|
||||
the routines to execute during the different states and sub-states
|
||||
of ramstage's processing.
|
||||
</li>
|
||||
<li>Turn on the device in mainboard/<Vendor>/<Board>/devicetree.cb</li>
|
||||
<li>
|
||||
Debug until the device is on and properly configured in coreboot and
|
||||
usable by the payload
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<h4><a name="SubsystemIds">Subsystem IDs</a></h4>
|
||||
<p>
|
||||
PCI subsystem IDs are assigned during the BS_DEV_ENABLE state. The device
|
||||
driver may use the common mechanism to assign subsystem IDs by adding
|
||||
the ".ops_pci" to the pci_driver data structure. This field points to
|
||||
a "struct pci_operations" that specifies a routine to set the subsystem
|
||||
IDs for the device. The routine might look something like this:
|
||||
</p>
|
||||
<pre><code>static void pci_set_subsystem(struct device *dev, unsigned vendor, unsigned device)
|
||||
{
|
||||
if (!vendor || !device) {
|
||||
vendor = pci_read_config32(dev, PCI_VENDOR_ID);
|
||||
device = vendor >> 16;
|
||||
}
|
||||
printk(BIOS_SPEW,
|
||||
"PCI: %02x:%02x:%d subsystem vendor: 0x%04x, device: 0x%04x\n",
|
||||
0, PCI_SLOT(dev->path.pci.devfn), PCI_FUNC(dev->path.pci.devfn),
|
||||
vendor & 0xffff, device);
|
||||
pci_write_config32(dev, PCI_SUBSYSTEM_VENDOR_ID,
|
||||
((device & 0xffff) << 16) | (vendor & 0xffff));
|
||||
}
|
||||
</code></pre>
|
||||
|
||||
|
||||
|
||||
<h3>Set up the <a name="MemoryMap">Memory Map</a></h3>
|
||||
<p>
|
||||
The memory map is built by the various PCI device drivers during the
|
||||
BS_DEV_RESOURCES state of ramstage. The northcluster driver will typically
|
||||
specify the DRAM resources while the other drivers will typically specify
|
||||
the IO resources. These resources are hung off the struct device *data structure by
|
||||
src/device/device_util.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/device/device_util.c;hb=HEAD#l448">new_resource</a>.
|
||||
</p>
|
||||
<p>
|
||||
During the BS_WRITE_TABLES state, coreboot collects these resources and
|
||||
places them into a data structure identified by LB_MEM_TABLE.
|
||||
</p>
|
||||
<p>
|
||||
Edit the device driver file:
|
||||
</p>
|
||||
<ol>
|
||||
<li>
|
||||
Implement a read_resources routine which calls macros defined in
|
||||
src/include/device/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/device/device.h;hb=HEAD#l237">device.h</a>
|
||||
like:
|
||||
<ul>
|
||||
<li>ram_resource</li>
|
||||
<li>reserved_ram_resource</li>
|
||||
<li>bad_ram_resource</li>
|
||||
<li>uma_resource</li>
|
||||
<li>mmio_resource</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
Testing: Verify that the resources are properly displayed by coreboot during the BS_WRITE_TABLES state.
|
||||
</p>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="AcpiTables">ACPI Tables</a></h2>
|
||||
<p>
|
||||
One of the payloads that needs ACPI tables is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>.
|
||||
</p>
|
||||
|
||||
<h3>FADT</h3>
|
||||
<p>
|
||||
The EDK2 module
|
||||
CorebootModulePkg/Library/CbParseLib/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbParseLib/CbParseLib.c#l450">CbParseLib.c</a>
|
||||
requires that the FADT contains the values in the table below.
|
||||
These values are placed into a HOB identified by
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CorebootModulePkg.dec#l36">gUefiAcpiBoardInfoGuid</a>
|
||||
by routine
|
||||
CorebootModulePkg/CbSupportPei/CbSupportPei/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/CbSupportPei/CbSupportPei.c#l364">CbPeiEntryPoint</a>.
|
||||
</p>
|
||||
<table border="1">
|
||||
<tr bgcolor="#c0ffc0">
|
||||
<td>coreboot Field</td>
|
||||
<td>EDK2 Field</td>
|
||||
<td>gUefiAcpiBoardInfoGuid</td>
|
||||
<td>Use</li>
|
||||
<td>
|
||||
<a target="_blank" href="http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf">ACPI Spec.</a>
|
||||
Section
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>gpe0_blk<br>gpe0_blk_len</td>
|
||||
<td>Gpe0Blk<br>Gpe0BlkLen</td>
|
||||
<td>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootModulePkg/Library/CbParseLib/CbParseLib.c#l477">PmGpeEnBase</a>
|
||||
</td>
|
||||
<td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l129">Shutdown</a></td>
|
||||
<td>4.8.4.1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>pm1a_cnt_blk</td>
|
||||
<td>Pm1aCntBlk</td>
|
||||
<td>PmCtrlRegBase</td>
|
||||
<td>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l139">Shutdown</a><br>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l40">Suspend</a>
|
||||
</td>
|
||||
<td>4.8.3.2.1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>pm1a_evt_blk</td>
|
||||
<td>Pm1aEvtBlk</td>
|
||||
<td>PmEvtBase</td>
|
||||
<td><a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l134">Shutdown</a></td>
|
||||
<td>4.8.3.1.1</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>pm_tmr_blk</td>
|
||||
<td>PmTmrBlk</td>
|
||||
<td>PmTimerRegBase</td>
|
||||
<td>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/AcpiTimerLib/AcpiTimerLib.c#l55">Timer</a>
|
||||
</td>
|
||||
<td>4.8.3.3</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>reset_reg.</td>
|
||||
<td>ResetReg.Address</td>
|
||||
<td>ResetRegAddress</td>
|
||||
<td>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l71">Cold</a>
|
||||
and
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l98">Warm</a>
|
||||
resets
|
||||
</td>
|
||||
<td>4.3.3.6</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>reset_value</td>
|
||||
<td>ResetValue</td>
|
||||
<td>ResetValue</td>
|
||||
<td>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l71">Cold</a>
|
||||
and
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/CorebootPayloadPkg/Library/ResetSystemLib/ResetSystemLib.c#l98">Warm</a>
|
||||
resets
|
||||
</td>
|
||||
<td>4.8.3.6</td>
|
||||
</tr>
|
||||
</table>
|
||||
<p>
|
||||
The EDK2 data structure is defined in
|
||||
MdeModulePkg/Include/IndustryStandard/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/MdePkg/Include/IndustryStandard/Acpi61.h#l111">Acpi61.h</a>
|
||||
The coreboot data structure is defined in
|
||||
src/arch/x86/include/arch/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/arch/x86/include/arch/acpi.h;hb=HEAD#l237">acpi.h</a>
|
||||
</p>
|
||||
|
||||
<ol>
|
||||
<li>
|
||||
Select <a target="_blank" href="../Board/board.html#AcpiTables">HAVE_ACPI_TABLES</a>
|
||||
in the board's Kconfig file
|
||||
</li>
|
||||
<li>Create a acpi.c module:
|
||||
<ol type="A">
|
||||
<li>Add the acpi_fill_in_fadt routine and initialize the values above</li>
|
||||
</ol>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="LegacyHardware">Legacy Hardware</a></h2>
|
||||
<p>
|
||||
One of the payloads that needs legacy hardare is the EDK2 <a target="_blank" href="quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>.
|
||||
</p>
|
||||
|
||||
<table border="1">
|
||||
<tr bgcolor="c0ffc0">
|
||||
<th>Peripheral</th>
|
||||
<th>Use</th>
|
||||
<th>8259 Interrupt Vector</th>
|
||||
<th>IDT Base Offset</th>
|
||||
<th>Interrupt Handler</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<a target="_blank" href="http://www.scs.stanford.edu/10wi-cs140/pintos/specs/8254.pdf">8254</a>
|
||||
Programmable Interval Timer
|
||||
</td>
|
||||
<td>
|
||||
EDK2: PcAtChipsetPkg/8254TimerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Timer.c">Timer.c</a>
|
||||
</td>
|
||||
<td>0</td>
|
||||
<td>0x340</td>
|
||||
<td>
|
||||
<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8254TimerDxe/Timer.c#l71">TimerInterruptHandler</a>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<a target="_blank" href="https://www.google.com/url?sa=t&rct=j&q=&esrc=s&source=web&cd=1&cad=rja&uact=8&ved=0ahUKEwibxYKU3ZDLAhVOzWMKHfuqB40QFggcMAA&url=http%3A%2F%2Fbochs.sourceforge.net%2Ftechspec%2Fintel-8259a-pic.pdf.gz&usg=AFQjCNF1NT0OQ6ys1Pn6Iv9sv6cKRzZbGg&sig2=HfBszp9xTVO_fajjPWCsJw">8259</a>
|
||||
Programmable Interrupt Controller
|
||||
</td>
|
||||
<td>
|
||||
EDK2: PcAtChipsetPkg/8259InterruptControllerDxe/<a target="_blank" href="https://github.com/tianocore/edk2/blob/master/PcAtChipsetPkg/8259InterruptControllerDxe/8259.c">8259.c</a>
|
||||
</td>
|
||||
<td>
|
||||
Master interrupts: 0, 2 - 7<br>
|
||||
Slave interrupts: 8 - 15<br>
|
||||
Interrupt vector 1 is never generated, the cascaded input generates interrupts 8 - 15
|
||||
</td>
|
||||
<td>
|
||||
Master: 0x340, 0x350 - 0x378<br>
|
||||
Slave: 0x380 - 0x3b8<br>
|
||||
Interrupt descriptors are 8 bytes each
|
||||
</td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<hr>
|
||||
<p>Modified: 4 March 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
377
Documentation/Intel/development.html
Normal file
377
Documentation/Intel/development.html
Normal file
|
|
@ -0,0 +1,377 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Development</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>Intel® x86 coreboot/FSP Development Process</h1>
|
||||
<p>
|
||||
The x86 development process for coreboot is broken into the following components:
|
||||
</p>
|
||||
<ul>
|
||||
<li>coreboot <a target="_blank" href="SoC/soc.html">SoC</a> development</li>
|
||||
<li>coreboot <a target="_blank" href="Board/board.html">mainboard</a> development</li>
|
||||
<li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration</li>
|
||||
</ul>
|
||||
<p>
|
||||
The development process has two main phases:
|
||||
</p>
|
||||
<ol>
|
||||
<li>Minimal coreboot; This phase is single threaded</li>
|
||||
<li>Adding coreboot features</li>
|
||||
</ol>
|
||||
|
||||
<h2>Minimal coreboot</h2>
|
||||
<p>
|
||||
The combined steps below describe how to bring up a minimal coreboot for a
|
||||
system-on-a-chip (SoC) and a development board:
|
||||
</p>
|
||||
<table>
|
||||
<tr bgcolor="#ffffc0">
|
||||
<td>The initial coreboot steps are single threaded!
|
||||
The initial minimal FSP development is also single threaded.
|
||||
Progress can speed up by adding more developers after the minimal coreboot/FSP
|
||||
implementation reaches the payload.
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<ol>
|
||||
<li>Get the necessary tools:
|
||||
<ul>
|
||||
<li>Linux: Use your package manager to install m4 bison flex and the libcurses development
|
||||
package.
|
||||
<ul>
|
||||
<li>Ubuntu or other Linux distribution that use apt, run:
|
||||
<pre><code>sudo apt-get install m4 bison flex libncurses5-dev
|
||||
</code></pre>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Build the cross tools for i386:
|
||||
<ul>
|
||||
<li>Linux:
|
||||
<pre><code>make crossgcc-i386</code></pre>
|
||||
To use multiple processors for the toolchain build (which takes a long time), use:
|
||||
<pre><code>make crossgcc-i386 CPUS=N</code></pre>
|
||||
where N is the number of cores to use for the build.
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>Get something to build:
|
||||
<ol type="A">
|
||||
<li><a target="_blank" href="fsp1_1.html#RequiredFiles">FSP 1.1</a> required files</li>
|
||||
<li><a target="_blank" href="SoC/soc.html#RequiredFiles">SoC</a> required files</li>
|
||||
<li><a target="_blank" href="Board/board.html#RequiredFiles">Board</a> required files</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Get result to start <a target="_blank" href="SoC/soc.html#Descriptor">booting</a></li>
|
||||
<li><a target="_blank" href="SoC/soc.html#EarlyDebug">Early Debug</a></li>
|
||||
<li>Implement and debug the <a target="_blank" href="SoC/soc.html#Bootblock">bootblock</a> code</li>
|
||||
<li>Implement and debug the call to <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></li>
|
||||
<li>Enable the serial port
|
||||
<ol type="A">
|
||||
<li>Power on, enable and configure GPIOs for the
|
||||
<a target="_blank" href="Board/board.html#SerialOutput">debug serial UART</a>
|
||||
</li>
|
||||
<li>Add the <a target="_blank" href="SoC/soc.html#SerialOutput">serial outupt</a>
|
||||
support to romstage
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Enable <a target="_blank" href="fsp1_1.html#corebootFspDebugging">coreboot/FSP</a> debugging</li>
|
||||
<li>Determine the <a target="_blank" href="SoC/soc.html#PreviousSleepState">Previous Sleep State</a></li>
|
||||
<li>Enable DRAM:
|
||||
<ol type="A">
|
||||
<li>Implement the SoC
|
||||
<a target="_blank" href="SoC/soc.html#MemoryInit">MemoryInit</a>
|
||||
Support
|
||||
</li>
|
||||
<li>Implement the board support to read the
|
||||
<a target="_blank" href="Board/board.html#SpdData">Memory Timing Data</a>
|
||||
</li>
|
||||
</ol>
|
||||
</li>
|
||||
<li>Disable the
|
||||
<a target="_blank" href="SoC/soc.html#DisableShadowRom">Shadow ROM</a>
|
||||
</li>
|
||||
<li>Enable CONFIG_DISPLAY_MTRRS to verify the MTRR configuration</li>
|
||||
<li>
|
||||
Implement the .init routine for the
|
||||
<a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a>
|
||||
structure which calls FSP SiliconInit
|
||||
</li>
|
||||
<li>
|
||||
Start ramstage's
|
||||
<a target="_blank" href="SoC/soc.html#DeviceTree">device tree processing</a>
|
||||
to display the PCI vendor and device IDs
|
||||
</li>
|
||||
<li>
|
||||
Disable the
|
||||
<a target="_blank" href="Board/board.html#DisablePciDevices">PCI devices</a>
|
||||
</li>
|
||||
<li>
|
||||
Implement the
|
||||
<a target="_blank" href="SoC/soc.html#MemoryMap">memory map</a>
|
||||
</li>
|
||||
<li>coreboot should now attempt to load the payload</li>
|
||||
</ol>
|
||||
|
||||
|
||||
|
||||
<h2>Add coreboot Features</h2>
|
||||
<p>
|
||||
Most of the coreboot development gets done in this phase. Implementation tasks in this
|
||||
phase are easily done in parallel.
|
||||
</p>
|
||||
<ul>
|
||||
<li>Payload and OS Features:
|
||||
<ul>
|
||||
<li><a target="_blank" href="SoC/soc.html#AcpiTables">ACPI Tables</a></li>
|
||||
<li><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<table border="1">
|
||||
<tr bgcolor="#c0ffc0">
|
||||
<th colspan=3><h1>Features</h1></th>
|
||||
</tr>
|
||||
<tr bgcolor="#c0ffc0">
|
||||
<th>SoC</th>
|
||||
<th>Where</th>
|
||||
<th>Testing</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>8254 Programmable Interval Timer</td>
|
||||
<td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
|
||||
<td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>8259 Programmable Interrupt Controller</td>
|
||||
<td><a target="_blank" href="SoC/soc.html#LegacyHardware">Legacy hardware</a> support</td>
|
||||
<td><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a> gets to shell prompt</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Cache-as-RAM</td>
|
||||
<td>
|
||||
<a target="_blank" href="SoC/soc.html#TempRamInit">Find</a>
|
||||
FSP binary:
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l38">cache_as_ram.inc</a><br>
|
||||
Enable: FSP 1.1 <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a>
|
||||
called from
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l73">cache_as_ram.inc</a><br>
|
||||
Disable: FSP 1.1 TempRamExit called from
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
|
||||
</td>
|
||||
<td>FindFSP: POST code 0x90
|
||||
(<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
|
||||
is displayed<br>
|
||||
Enable: POST code
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
|
||||
is displayed<br>
|
||||
Disable: CONFIG_DISPLAY_MTRRS=y, MTRRs displayed after call to TempRamExit
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Memory Map</td>
|
||||
<td>
|
||||
Implement a device driver for the
|
||||
<a target="_blank" href="SoC/soc.html#MemoryMap">north cluster</a>
|
||||
</td>
|
||||
<td>coreboot displays the memory map correctly during the BS_WRITE_TABLES state</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MTRRs</td>
|
||||
<td>
|
||||
Set values: src/drivers/intel/fsp1_1/stack.c/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/stack.c;hb=HEAD#l42">setup_stack_and_mtrrs</a><br>
|
||||
Load values: src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l71">after_raminit.S</a>
|
||||
</td>
|
||||
<td>Set: Post code 0x91
|
||||
(<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l213">POST_FSP_TEMP_RAM_EXIT</a>)
|
||||
is displayed by
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l41">after_raminit.S</a><br>
|
||||
Load: Post code 0x3C is displayed by
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l152">after_raminit.S</a><br>
|
||||
and CONFIG_DISPLAY_MTRRS=y displays the correct memory regions</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>PCI Device Support</td>
|
||||
<td>Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a></td>
|
||||
<td>The device is detected by coreboot and usable by the payload</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Ramstage state machine</td>
|
||||
<td>
|
||||
Implement the chip and domain operations to start the
|
||||
<a target="_blank" href="SoC/soc.html#DeviceTree">device tree</a>
|
||||
processing
|
||||
</td>
|
||||
<td>
|
||||
During the BS_DEV_ENUMERATE state, ramstage now display the device IDs
|
||||
for the PCI devices on the bus.
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ROM Shadow<br>0x000E0000 - 0x000FFFFF</td>
|
||||
<td>
|
||||
Disable: src/soc/<Vendor>/<Chip Family>/romstage/romstage.c/<a target="_blank" href="SoC/soc.html#DisableShadowRom">soc_after_ram_init routine</a>
|
||||
</td>
|
||||
<td>Operates as RAM: Writes followed by a read to the 0x000E0000 - 0x000FFFFF region returns the value written</td>
|
||||
</tr>
|
||||
|
||||
|
||||
<tr bgcolor="#c0ffc0">
|
||||
<th>Board</th>
|
||||
<th>Where</th>
|
||||
<th>Testing</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Device Tree</td>
|
||||
<td>
|
||||
<a target="_blank" href="SoC/soc.html#DeviceTree">List</a> PCI vendor and device IDs by starting
|
||||
the device tree processing<br>
|
||||
<a target="_blank" href="Board/board.html#DisablePciDevices">Disable</a> PCI devices<br>
|
||||
Enable: Implement a PCI <a target="_blank" href="SoC/soc.html#DeviceDrivers">device driver</a>
|
||||
<td>
|
||||
List: BS_DEV_ENUMERATE state displays PCI vendor and device IDs<br>
|
||||
Disable: BS_DEV_ENUMERATE state shows the devices as disabled<br>
|
||||
Enable: BS_DEV_ENUMERATE state shows the device as on and the device works for the payload
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>DRAM</td>
|
||||
<td>
|
||||
Load SPD data: src/soc/mainboard/<Vendor>/<Board>/spd/<a target="_blank" href="Board/board.html#SpdData">spd.c</a><br>
|
||||
UPD Setup:
|
||||
<ul>
|
||||
<li>src/soc<Vendor>//<Chip Family>/romstage/<a target="_blank" href="SoC/soc.html#MemoryInit">romstage.c</a></li>
|
||||
<li>src/mainboard/<Vendor>/<Board>/<a target="_blank" href="Board/board.html#SpdData">romstage.c</a></li>
|
||||
</ul>
|
||||
FSP 1.1 MemoryInit called from src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/raminit.c;hb=HEAD#l126">raminit.c</a>
|
||||
</td>
|
||||
<td>Select the following Kconfig values
|
||||
<ul>
|
||||
<li>DISPLAY_HOBS</li>
|
||||
<li>DISPLAY_UPD_DATA</li>
|
||||
</ul>
|
||||
Testing successful if:
|
||||
<ul>
|
||||
<li>MemoryInit UPD values are correct</li>
|
||||
<li>MemoryInit returns 0 (success) and</li>
|
||||
<li>The message "ERROR - coreboot's requirements not met by FSP binary!"
|
||||
is not displayed
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>Serial Port</td>
|
||||
<td>
|
||||
SoC <a target="_blank" href="SoC/soc.html#SerialOutput">Support</a><br>
|
||||
Enable: src/soc/mainboard/<Board>/com_init.c/<a target="_blank" href="Board/board.html#SerialOutput">car_mainboard_pre_console_init</a>
|
||||
</td>
|
||||
<td>Debug serial output works</td>
|
||||
</tr>
|
||||
|
||||
|
||||
<tr bgcolor="#c0ffc0">
|
||||
<th>Payload</th>
|
||||
<th>Where</th>
|
||||
<th>Testing</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>ACPI Tables</td>
|
||||
<td>
|
||||
SoC <a target="_blank" href="SoC/soc.html#AcpiTables">Support</a><br>
|
||||
</td>
|
||||
<td>Verified by payload or OS</td>
|
||||
</tr>
|
||||
|
||||
|
||||
<tr bgcolor="#c0ffc0">
|
||||
<th>FSP</th>
|
||||
<th>Where</th>
|
||||
<th>Testing</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TempRamInit</td>
|
||||
<td>FSP <a target="_blank" href="SoC/soc.html#TempRamInit">TempRamInit</a></td>
|
||||
<td>FSP binary found: POST code 0x90
|
||||
(<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l205">POST_FSP_TEMP_RAM_INIT</a>)
|
||||
is displayed<br>
|
||||
TempRamInit successful: POST code
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/cache_as_ram.inc;hb=HEAD#l151">0x2A</a>
|
||||
is displayed<br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>MemoryInit</td>
|
||||
<td><a target="_blank" href="SoC/soc.html#MemoryInit">SoC</a> support<br>
|
||||
<a target="_blank" href="Board/board.html#SpdData">Board</a> support<br>
|
||||
</td>
|
||||
<td>Select the following Kconfig values
|
||||
<ul>
|
||||
<li>DISPLAY_HOBS</li>
|
||||
<li>DISPLAY_UPD_DATA</li>
|
||||
</ul>
|
||||
Testing successful if:
|
||||
<ul>
|
||||
<li>MemoryInit UPD values are correct</li>
|
||||
<li>MemoryInit returns 0 (success) and</li>
|
||||
<li>The message "ERROR - coreboot's requirements not met by FSP binary!"
|
||||
is not displayed
|
||||
</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>TempRamExit</td>
|
||||
<td>src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l51">after_raminit.S</a></td>
|
||||
<td>Post code 0x91
|
||||
(<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/include/console/post_codes.h;hb=HEAD#l212">POST_FSP_TEMP_RAM_EXIT</a>)
|
||||
is displayed before calling TempRamExit by
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a>,
|
||||
CONFIG_DISPLAY_MTRRS=y displays the correct memory regions and
|
||||
Post code 0x39 is displayed by
|
||||
<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/after_raminit.S;hb=HEAD#l141">after_raminit.S</a><br>
|
||||
</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>SiliconInit</td>
|
||||
<td>
|
||||
Implement the .init routine for the
|
||||
<a target="_blank" href="SoC/soc.html#ChipOperations">chip operations</a> structure
|
||||
</td>
|
||||
<td>During BS_DEV_INIT_CHIPS state, SiliconInit gets called and returns 0x00000000</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>FspNotify</td>
|
||||
<td>
|
||||
The code which calls FspNotify is located in
|
||||
src/drivers/intel/fsp1_1/<a target="_blank" href="https://review.coreboot.org/gitweb?p=coreboot.git;a=blob;f=src/drivers/intel/fsp1_1/fsp_util.c;hb=HEAD#l182">fsp_util.c</a>.
|
||||
The fsp_notify_boot_state_callback routine is called three times as specified
|
||||
by the BOOT_STATE_INIT_ENTRY macros below the routine.
|
||||
</td>
|
||||
<td>
|
||||
The FspNotify routines are called during:
|
||||
<ul>
|
||||
<li>BS_DEV_RESOURCES - on exit</li>
|
||||
<li>BS_PAYLOAD_LOAD - on exit</li>
|
||||
<li>BS_OS_RESUME - on entry (S3 resume)</li>
|
||||
</ul>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<p>Modified: 4 March 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
79
Documentation/Intel/fsp1_1.html
Normal file
79
Documentation/Intel/fsp1_1.html
Normal file
|
|
@ -0,0 +1,79 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>FSP 1.1</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>FSP 1.1</h1>
|
||||
|
||||
<h2>x86 FSP 1.1 Integration</h2>
|
||||
<p>
|
||||
Firmware Support Package (FSP) integration requires System-on-a-Chip (SoC)
|
||||
and board support. The combined steps are listed
|
||||
<a target="_blank" href="development.html">here</a>.
|
||||
The development steps for FSP are listed below:
|
||||
</p>
|
||||
<ol>
|
||||
<li><a href="#RequiredFiles">Required Files</a></li>
|
||||
<li>Add the <a href="#FspBinary">FSP Binary File</a> to the coreboot File System</li>
|
||||
<li>Enable <a href="#corebootFspDebugging">coreboot/FSP Debugging</a></li>
|
||||
</ol>
|
||||
|
||||
<p>
|
||||
FSP Documentation:
|
||||
</p>
|
||||
<ul>
|
||||
<li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v1-1.pdf">V1.1</a></li>
|
||||
</ul>
|
||||
|
||||
<hr>
|
||||
<h2><a name="RequiredFiles">Required Files</a></h2>
|
||||
<h3><a name="corebootRequiredFiles">coreboot Required Files</a></h3>
|
||||
<ol>
|
||||
<li>Create the following directories if they do not already exist:
|
||||
<ul>
|
||||
<li>src/vendorcode/intel/fsp/fsp1_1/<Chip Family></li>
|
||||
<li>3rdparty/blobs/mainboard/<Board Vendor>/<Board Name></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>
|
||||
The following files may need to be copied from the FSP build or release into the
|
||||
directories above if they are not present or are out of date:
|
||||
<ul>
|
||||
<li>FspUpdVpd.h: src/vendorcode/intel/fsp/fsp1_1/<Chip Family>/FspUpdVpd.h</li>
|
||||
<li>FSP.bin: 3rdparty/blobs/mainboard/<Board Vendor>/<Board Name>/fsp.bin</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ol>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="FspBinary">Add the FSP Binary File to coreboot File System</a></h2>
|
||||
<p>
|
||||
Add the FSP binary to the coreboot flash image using the following command:
|
||||
</p>
|
||||
<pre><code>util/cbfstool/cbfstool build/coreboot.rom add -t fsp -n fsp.bin -b <base address> -f fsp.bin</code></pre>
|
||||
<p>
|
||||
This command relocates the FSP binary to the 4K byte aligned location in CBFS so that the
|
||||
FSP code for TempRamInit may be executed in place.
|
||||
</p>
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="corebootFspDebugging">Enable coreboot/FSP Debugging</a></h2>
|
||||
<p>
|
||||
Set the following Kconfig values:
|
||||
</p>
|
||||
<ul>
|
||||
<li>CONFIG_DISPLAY_FSP_ENTRY_POINTS - Display the FSP entry points in romstage</li>
|
||||
<li>CONFIG_DISPLAY_HOBS - Display and verify the hand-off-blocks (HOBs) returned by MemoryInit</li>
|
||||
<li>CONFIG_DISPLAY_VBT - Display Video BIOS Table (VBT) used for GOP</li>
|
||||
<li>CONFIG_DISPLAY_UPD_DATA - Display the user specified product data passed to MemoryInit and SiliconInit</li>
|
||||
</ul>
|
||||
|
||||
|
||||
<hr>
|
||||
<p>Modified: 17 May 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
128
Documentation/Intel/index.html
Normal file
128
Documentation/Intel/index.html
Normal file
|
|
@ -0,0 +1,128 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Intel® x86</title>
|
||||
</head>
|
||||
<body>
|
||||
|
||||
<h1>Intel® x86</h1>
|
||||
|
||||
<h2>Intel® x86 Boards</h2>
|
||||
<ul>
|
||||
<li><a target="_blank" href="Board/galileo.html">Galileo</a></li>
|
||||
<li><a target="_blank" href="http://wiki.minnowboard.org/Coreboot">MinnowBoard MAX</a></li>
|
||||
</ul>
|
||||
|
||||
<h2>Intel® x86 SoCs</h2>
|
||||
<ul>
|
||||
<li><a target="_blank" href="SoC/quark.html">Quark™</a></li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2>x86 coreboot Development</h2>
|
||||
<ul>
|
||||
<li>Get the <a target="_blank" href="https://www.coreboot.org/Git">coreboot source</li>
|
||||
<li><a target="_blank" href="development.html">Overall</a> development</li>
|
||||
<li><a target="_blank" href="fsp1_1.html">FSP 1.1</a> integration
|
||||
</li>
|
||||
<li><a target="_blank" href="SoC/soc.html">SoC</a> support</li>
|
||||
<li><a target="_blank" href="Board/board.html">Board</a> support</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2>Payload Development</h2>
|
||||
<ul>
|
||||
<li><a target="_blank" href="SoC/quark.html#CorebootPayloadPkg">CorebootPayloadPkg</a>
|
||||
<ul>
|
||||
<li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK-II-Development-Process">EDK II Development Process</a></li>
|
||||
<li>EDK II <a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/EDK%20II%20White%20papers">White Papers</a></li>
|
||||
<li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/SourceForge-to-Github-Quick-Start">SourceForge to Github Quick Start</a></li>
|
||||
<li>UEFI <a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI%20Spec%202_5_Errata_A.PDF">2.5 Errata A</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
|
||||
|
||||
|
||||
<hr>
|
||||
<h2><a name="Documentation">Documentation</a></h2>
|
||||
<ul>
|
||||
<li>Intel® 64 and IA-32 Architectures <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/manuals/64-ia-32-architectures-software-developer-manual-325462.pdf">Software Developer Manual</a></li>
|
||||
<li><a target="_blank" href="http://www.uefi.org/specifications">UEFI Specifications</a></li>
|
||||
</ul>
|
||||
|
||||
<h3><a name="Edk2Documentation">EDK-II Documentation</a></h3>
|
||||
<ul>
|
||||
<li>Build <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/Build_Spec_1_26.pdf">V1.26</a></li>
|
||||
<li>Coding Standards <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/CCS_2_1_Draft.pdf">V2.1</a></li>
|
||||
<li>DEC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DEC_Spec_1_25.pdf">V1.25</a></li>
|
||||
<li>DSC <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/DSC_Spec_1_26.pdf">V1.26</a></li>
|
||||
<li><a target="_blank" href="https://github.com/tianocore/tianocore.github.io/wiki/UEFI-Driver-Writer's-Guide">Driver Writer's Guide</a></li>
|
||||
<li>Expression Syntax <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/ExpressionSyntax_1.1.pdf">V1.1</a></li>
|
||||
<li>FDF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/FDF_Spec_1_26.pdf">V1.26</a></li>
|
||||
<li>INF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/INF_Spec_1_25.pdf">V1.25</a></li>
|
||||
<li>PCD <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/PCD_Infrastructure.pdf">PCD</a>V0.55</li>
|
||||
<li>UNI <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/UNI_File_Spec_v1_2_Errata_A.pdf">V1.2 Errata A</a></li>
|
||||
<li>VRF <a target="_blank" href="https://github.com/tianocore-docs/Docs/raw/master/Specifications/VFR_1_9.pdf">V1.9</a></li>
|
||||
</ul>
|
||||
|
||||
<h3><a name="FspDocumentation">FSP Documentation</a></h3>
|
||||
<ul>
|
||||
<li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v2.pdf">V2.0</a></li>
|
||||
<li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec-v1-1.pdf">V1.1</a></li>
|
||||
<li>Intel® Firmware Support Package External Architecture Specification <a target="_blank" href="http://www.intel.com/content/dam/www/public/us/en/documents/technical-specifications/fsp-architecture-spec.pdf">V1.0</a></li>
|
||||
</ul>
|
||||
|
||||
<h3><a name="FeatureDocumentation">Feature Documentation</a></h3>
|
||||
<table border="1">
|
||||
<tr bgcolor="#c0ffc0"><th>Feature/Specification</th><th>Linux View/Test</th><th>EDK-II View/Test</th></tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="https://en.wikipedia.org/wiki/E820">e820</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/dmesg.1.html">dmesg</a></td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="http://www.uefi.org/specifications">ACPI</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/precise/man1/acpidump.1.html">acpidump</a></td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="https://en.wikipedia.org/wiki/Extended_Display_Identification_Data">EDID</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">get-edid | parse-edid</a></td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="http://www.nxp.com/documents/user_manual/UM10204.pdf">I2C</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/get-edid.1.html">i2cdetect</a></td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="http://www.intel.com/design/archives/processors/pro/docs/242016.htm">Multiprocessor</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man1/lscpu.1.html">lscpu</a></td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="https://pcisig.com/specifications">PCI</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/lspci.8.html">lspci</a></td>
|
||||
<td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">pci</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="https://www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.0.0.pdf">SMBIOS</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/trusty/man8/dmidecode.8.html">dmidecode</a></td>
|
||||
<td><a target="_blank" href="http://www.uefi.org/sites/default/files/resources/UEFI_Shell_Spec_2_0.pdf">smbiosview</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><a target="_blank" href="http://www.usb.org/developers/docs/">USB</a></td>
|
||||
<td><a target="_blank" href="http://manpages.ubuntu.com/manpages/xenial/man8/lsusb.8.html">lsusb</a></td>
|
||||
<td> </td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<hr>
|
||||
<p>Modified: 18 June 2016</p>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -1,24 +1,49 @@
|
|||
## SPDX-License-Identifier: GPL-2.0-only
|
||||
#
|
||||
# Makefile for coreboot paper.
|
||||
# hacked together by Stefan Reinauer <stepan@openbios.org>
|
||||
#
|
||||
|
||||
BUILDDIR ?= _build
|
||||
SPHINXOPTS ?= -j auto -W --keep-going
|
||||
PDFLATEX=pdflatex -t a4
|
||||
|
||||
export SPHINXOPTS
|
||||
FIGS=codeflow.pdf hypertransport.pdf
|
||||
|
||||
all: sphinx
|
||||
all: corebootPortingGuide.pdf
|
||||
|
||||
$(BUILDDIR):
|
||||
mkdir -p $(BUILDDIR)
|
||||
SVG2PDF=$(shell which svg2pdf)
|
||||
INKSCAPE=$(shell which inkscape)
|
||||
CONVERT=$(shell which convert)
|
||||
|
||||
sphinx: $(BUILDDIR)
|
||||
$(MAKE) -f Makefile.sphinx html BUILDDIR="$(BUILDDIR)"
|
||||
codeflow.pdf: codeflow.svg
|
||||
ifneq ($(strip $(SVG2PDF)),)
|
||||
svg2pdf $< $@
|
||||
else ifneq ($(strip $(INKSCAPE)),)
|
||||
inkscape $< --export-pdf=$@
|
||||
else ifneq ($(strip $(CONVERT)),)
|
||||
convert $< $@
|
||||
endif
|
||||
|
||||
hypertransport.pdf: hypertransport.svg
|
||||
ifneq ($(strip $(SVG2PDF)),)
|
||||
svg2pdf $< $@
|
||||
else ifneq ($(strip $(INKSCAPE)),)
|
||||
inkscape $< --export-pdf=$@
|
||||
else ifneq ($(strip $(CONVERT)),)
|
||||
convert $< $@
|
||||
endif
|
||||
|
||||
corebootPortingGuide.toc: $(FIGS) corebootBuildingGuide.tex
|
||||
# 2 times to make sure we have a current toc.
|
||||
$(PDFLATEX) corebootBuildingGuide.tex
|
||||
$(PDFLATEX) corebootBuildingGuide.tex
|
||||
|
||||
corebootPortingGuide.pdf: $(FIGS) corebootBuildingGuide.tex corebootPortingGuide.toc
|
||||
$(PDFLATEX) corebootBuildingGuide.tex
|
||||
|
||||
sphinx:
|
||||
$(MAKE) -f Makefile.sphinx html
|
||||
|
||||
clean-sphinx:
|
||||
$(MAKE) -f Makefile.sphinx clean BUILDDIR="$(BUILDDIR)"
|
||||
$(MAKE) -f Makefile.sphinx clean
|
||||
|
||||
clean: clean-sphinx
|
||||
rm -f *.aux *.idx *.log *.toc *.out $(FIGS)
|
||||
|
|
@ -26,24 +51,5 @@ clean: clean-sphinx
|
|||
distclean: clean
|
||||
rm -f corebootPortingGuide.pdf
|
||||
|
||||
livesphinx: $(BUILDDIR)
|
||||
$(MAKE) -f Makefile.sphinx livehtml BUILDDIR="$(BUILDDIR)"
|
||||
|
||||
test:
|
||||
@echo "Test for logging purposes - Failing tests will not fail the build"
|
||||
-$(MAKE) -f Makefile.sphinx clean && $(MAKE) -k -f Makefile.sphinx html
|
||||
|
||||
help:
|
||||
@echo "all - Builds all documentation targets"
|
||||
@echo "sphinx - Builds html documentation in _build directory"
|
||||
@echo "clean - Cleans intermediate files"
|
||||
@echo "clean-sphinx - Removes sphinx output files"
|
||||
@echo "distclean - Removes PDF files as well"
|
||||
@echo "test - Runs documentation tests"
|
||||
@echo
|
||||
@echo " Makefile.sphinx builds - run with $(MAKE) -f Makefile-sphinx [target]"
|
||||
@echo
|
||||
@$(MAKE) -s -f Makefile.sphinx help 2>/dev/null
|
||||
|
||||
.phony: help livesphinx sphinx test
|
||||
.phony: distclean clean clean-sphinx
|
||||
livesphinx:
|
||||
$(MAKE) -f Makefile.sphinx livehtml SPHINXOPTS="$(SPHINXOPTS)"
|
||||
|
|
|
|||
|
|
@ -1,29 +1,233 @@
|
|||
## SPDX-License-Identifier: GPL-2.0-only
|
||||
# Minimal makefile for Sphinx documentation
|
||||
# Makefile for Sphinx documentation
|
||||
#
|
||||
|
||||
# You can set these variables from the command line, and also
|
||||
# from the environment for the first two.
|
||||
SPHINXOPTS ?=
|
||||
SPHINXBUILD ?= sphinx-build
|
||||
SPHINXAUTOBUILD = sphinx-autobuild
|
||||
SOURCEDIR = .
|
||||
BUILDDIR = _build
|
||||
# You can set these variables from the command line.
|
||||
SPHINXOPTS =
|
||||
SPHINXBUILD = sphinx-build
|
||||
SPHINXAUTOBUILD = sphinx-autobuild
|
||||
PAPER =
|
||||
BUILDDIR = _build
|
||||
|
||||
# Put it first so that "make" without argument is like "make help".
|
||||
# Internal variables.
|
||||
PAPEROPT_a4 = -D latex_paper_size=a4
|
||||
PAPEROPT_letter = -D latex_paper_size=letter
|
||||
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
# the i18n builder cannot share the environment and doctrees with the others
|
||||
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
|
||||
|
||||
.PHONY: help
|
||||
help:
|
||||
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
@echo "Please use \`make <target>' where <target> is one of"
|
||||
@echo " html to make standalone HTML files"
|
||||
@echo " dirhtml to make HTML files named index.html in directories"
|
||||
@echo " singlehtml to make a single large HTML file"
|
||||
@echo " pickle to make pickle files"
|
||||
@echo " json to make JSON files"
|
||||
@echo " htmlhelp to make HTML files and a HTML help project"
|
||||
@echo " qthelp to make HTML files and a qthelp project"
|
||||
@echo " applehelp to make an Apple Help Book"
|
||||
@echo " devhelp to make HTML files and a Devhelp project"
|
||||
@echo " epub to make an epub"
|
||||
@echo " epub3 to make an epub3"
|
||||
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
|
||||
@echo " latexpdf to make LaTeX files and run them through pdflatex"
|
||||
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
|
||||
@echo " text to make text files"
|
||||
@echo " man to make manual pages"
|
||||
@echo " texinfo to make Texinfo files"
|
||||
@echo " info to make Texinfo files and run them through makeinfo"
|
||||
@echo " gettext to make PO message catalogs"
|
||||
@echo " changes to make an overview of all changed/added/deprecated items"
|
||||
@echo " xml to make Docutils-native XML files"
|
||||
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
|
||||
@echo " linkcheck to check all external links for integrity"
|
||||
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
|
||||
@echo " coverage to run coverage check of the documentation (if enabled)"
|
||||
@echo " dummy to check syntax errors of document sources"
|
||||
|
||||
.PHONY: help Makefile.sphinx
|
||||
.PHONY: clean
|
||||
clean:
|
||||
rm -rf $(BUILDDIR)
|
||||
|
||||
.PHONY: html
|
||||
html:
|
||||
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
|
||||
|
||||
.PHONY: livehtml
|
||||
livehtml:
|
||||
@echo "Starting sphinx-autobuild. The HTML pages are in $(BUILDDIR)."
|
||||
@echo "Press Ctrl-C to stop."
|
||||
@echo
|
||||
$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
$(SPHINXAUTOBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)
|
||||
|
||||
# Catch-all target: route all unknown targets to Sphinx using the new
|
||||
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
|
||||
%: Makefile.sphinx
|
||||
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
|
||||
.PHONY: dirhtml
|
||||
dirhtml:
|
||||
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
|
||||
|
||||
.PHONY: singlehtml
|
||||
singlehtml:
|
||||
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
|
||||
@echo
|
||||
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
|
||||
|
||||
.PHONY: pickle
|
||||
pickle:
|
||||
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
|
||||
@echo
|
||||
@echo "Build finished; now you can process the pickle files."
|
||||
|
||||
.PHONY: json
|
||||
json:
|
||||
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
|
||||
@echo
|
||||
@echo "Build finished; now you can process the JSON files."
|
||||
|
||||
.PHONY: htmlhelp
|
||||
htmlhelp:
|
||||
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run HTML Help Workshop with the" \
|
||||
".hhp project file in $(BUILDDIR)/htmlhelp."
|
||||
|
||||
.PHONY: qthelp
|
||||
qthelp:
|
||||
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
|
||||
@echo
|
||||
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
|
||||
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
|
||||
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/coreboot.qhcp"
|
||||
@echo "To view the help file:"
|
||||
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/coreboot.qhc"
|
||||
|
||||
.PHONY: applehelp
|
||||
applehelp:
|
||||
$(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp
|
||||
@echo
|
||||
@echo "Build finished. The help book is in $(BUILDDIR)/applehelp."
|
||||
@echo "N.B. You won't be able to view it unless you put it in" \
|
||||
"~/Library/Documentation/Help or install it in your application" \
|
||||
"bundle."
|
||||
|
||||
.PHONY: devhelp
|
||||
devhelp:
|
||||
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
|
||||
@echo
|
||||
@echo "Build finished."
|
||||
@echo "To view the help file:"
|
||||
@echo "# mkdir -p $$HOME/.local/share/devhelp/coreboot"
|
||||
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/coreboot"
|
||||
@echo "# devhelp"
|
||||
|
||||
.PHONY: epub
|
||||
epub:
|
||||
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
|
||||
@echo
|
||||
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
|
||||
|
||||
.PHONY: epub3
|
||||
epub3:
|
||||
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
|
||||
@echo
|
||||
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
|
||||
|
||||
.PHONY: latex
|
||||
latex:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo
|
||||
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
|
||||
@echo "Run \`make' in that directory to run these through (pdf)latex" \
|
||||
"(use \`make latexpdf' here to do that automatically)."
|
||||
|
||||
.PHONY: latexpdf
|
||||
latexpdf:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through pdflatex..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
.PHONY: latexpdfja
|
||||
latexpdfja:
|
||||
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
|
||||
@echo "Running LaTeX files through platex and dvipdfmx..."
|
||||
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
|
||||
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
|
||||
|
||||
.PHONY: text
|
||||
text:
|
||||
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
|
||||
@echo
|
||||
@echo "Build finished. The text files are in $(BUILDDIR)/text."
|
||||
|
||||
.PHONY: man
|
||||
man:
|
||||
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
|
||||
@echo
|
||||
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
|
||||
|
||||
.PHONY: texinfo
|
||||
texinfo:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo
|
||||
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
|
||||
@echo "Run \`make' in that directory to run these through makeinfo" \
|
||||
"(use \`make info' here to do that automatically)."
|
||||
|
||||
.PHONY: info
|
||||
info:
|
||||
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
|
||||
@echo "Running Texinfo files through makeinfo..."
|
||||
make -C $(BUILDDIR)/texinfo info
|
||||
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
|
||||
|
||||
.PHONY: gettext
|
||||
gettext:
|
||||
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
|
||||
@echo
|
||||
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
|
||||
|
||||
.PHONY: changes
|
||||
changes:
|
||||
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
|
||||
@echo
|
||||
@echo "The overview file is in $(BUILDDIR)/changes."
|
||||
|
||||
.PHONY: linkcheck
|
||||
linkcheck:
|
||||
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
|
||||
@echo
|
||||
@echo "Link check complete; look for any errors in the above output " \
|
||||
"or in $(BUILDDIR)/linkcheck/output.txt."
|
||||
|
||||
.PHONY: doctest
|
||||
doctest:
|
||||
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
|
||||
@echo "Testing of doctests in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/doctest/output.txt."
|
||||
|
||||
.PHONY: coverage
|
||||
coverage:
|
||||
$(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
|
||||
@echo "Testing of coverage in the sources finished, look at the " \
|
||||
"results in $(BUILDDIR)/coverage/python.txt."
|
||||
|
||||
.PHONY: xml
|
||||
xml:
|
||||
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
|
||||
@echo
|
||||
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
|
||||
|
||||
.PHONY: pseudoxml
|
||||
pseudoxml:
|
||||
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
|
||||
@echo
|
||||
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
|
||||
|
||||
.PHONY: dummy
|
||||
dummy:
|
||||
$(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy
|
||||
@echo
|
||||
@echo "Build finished. Dummy builder generates no files."
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ coreboot POST Codes
|
|||
This is an (incomplete) list of POST codes emitted by coreboot v4.
|
||||
|
||||
0x10 Entry into protected mode
|
||||
0x01 Entry into 'entry16.S' reset code jumps to here
|
||||
0x01 Entry into 'crt0.s' reset code jumps to here
|
||||
0x11 Start copying coreboot to RAM with decompression if compressed
|
||||
0x12 Copy/decompression finished jumping to RAM
|
||||
0x80 Entry into coreboot in RAM
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@ change.
|
|||
|
||||
\section{Scope}
|
||||
This document defines how LinuxBIOS programmers can specify chips that
|
||||
are used, specified, and initialized. The current scope is for superio
|
||||
are used, specified, and initalized. The current scope is for superio
|
||||
chips, but the architecture should allow for specification of other chips such
|
||||
as southbridges. Multiple chips of same or different type are supported.
|
||||
|
||||
|
|
|
|||
290
Documentation/RFC/config.tex
Normal file
290
Documentation/RFC/config.tex
Normal file
|
|
@ -0,0 +1,290 @@
|
|||
New config language for LinuxBIOS
|
||||
|
||||
\begin{abstract}
|
||||
We describe the new configuration language for LinuxBIOS.
|
||||
\end{abstract}
|
||||
|
||||
\section{Scope}
|
||||
This document defines the new configuration language for LinuxBIOS.
|
||||
|
||||
\section{Goals}
|
||||
The goals of the new language are these:
|
||||
\begin{itemize}
|
||||
\item Simplified Makefiles so people can see what is set
|
||||
\item Move from the regular-expression-based language to something
|
||||
a bit more comprehensible and flexible
|
||||
\item make the specification easier for people to use and understand
|
||||
\item allow unique register-set-specifiers for each chip
|
||||
\item allow generic register-set-specifiers for each chip
|
||||
\item generate static initialization code, as needed, for the
|
||||
specifiers.
|
||||
\end{itemize}
|
||||
|
||||
\section{Language}
|
||||
Here is the new language. It is very similar to the old one, differing
|
||||
in only a few respects. It borrows heavily from Greg Watson's suggestions.
|
||||
|
||||
I am presenting it in a pseudo-BNF in the hopes it will be easier. Things
|
||||
in '' are keywords; things in ``'' are strings in the actual text.
|
||||
\begin{verbatim}
|
||||
#exprs are composed of factor or factor + factor etc.
|
||||
expr ::= factor ( ``+'' factor | ``-'' factor | )*
|
||||
#factors are term or term * term or term / term or ...
|
||||
factor ::= term ( ``*'' term | ``/'' term | ... )*
|
||||
#
|
||||
unary-op ::= ``!'' ID
|
||||
# term is a number, hexnumber, ID, unary-op, or a full-blown expression
|
||||
term ::= NUM | XNUM | ID | unary-op | ``(`` expr ``)''
|
||||
|
||||
# Option command. Can be an expression or quote-string.
|
||||
# Options are used in the config tool itself (in expressions and 'if')
|
||||
# and are also passed to the C compiler when building linuxbios.
|
||||
# It is an error to have two option commands in a file.
|
||||
# It is an error to have an option command after the ID has been used
|
||||
# in an expression (i.e. 'set after used' is an error)
|
||||
option ::= 'option' ID '=' (``value'' | term)
|
||||
|
||||
# Default command. The ID is set to this value if no option command
|
||||
# is scanned.
|
||||
# Multiple defaults for an ID will produce warning, but not errors.
|
||||
# It is OK to scan a default command after use of an ID.
|
||||
# Options always over-ride defaults.
|
||||
default ::= 'default' ID '=' (``value'' | term)
|
||||
|
||||
# the mainboard, southbridge, northbridge commands
|
||||
# cause sourcing of Config.lb files as in the old config tool
|
||||
# as parts are sourced, a device tree is built. The structure
|
||||
# of the tree is determined by the structure of the components
|
||||
# as they are specified. To attach a superio to a southbridge, for
|
||||
# example, one would do this:
|
||||
# southbridge acer/5432
|
||||
# superio nsc/123
|
||||
# end
|
||||
# end
|
||||
# the tool generates static initializers for this hierarchy.
|
||||
|
||||
# add C code to the current component (motherboard, etc. )
|
||||
# to initialise the component-INDEPENDENT structure members
|
||||
init ::= 'init' ``CODE''
|
||||
|
||||
# add C code to the current component (motherboard, etc. )
|
||||
# to initialise the component-DEPENDENT structure members
|
||||
register ::= 'register' ``CODE''
|
||||
|
||||
|
||||
# mainboard command
|
||||
# statements in this block will set variables controlling the mainboard,
|
||||
# and will also place components (northbridge etc.) in the device tree
|
||||
# under this mainboard
|
||||
mainboard ::= 'mainboard' PATH (statements)* 'end'
|
||||
|
||||
# standard linuxbios commands
|
||||
southbridge ::= 'southbridge' PATH (statemnts)* 'end'
|
||||
northbridge ::= 'northbridge' PATH (statemnts)* 'end'
|
||||
superio ::= 'superio PATH (statemnts)* 'end'
|
||||
cpu ::= 'cpu' PATH (statemnts)* 'end'
|
||||
arch ::= 'arch' PATH (statemnts)* 'end'
|
||||
|
||||
# files for building linuxbios
|
||||
# include a file in crt0.S
|
||||
mainboardinit ::= 'mainboardinit' PATH
|
||||
|
||||
# object file
|
||||
object ::= 'object' PATH
|
||||
# driver objects are just built into the image in a different way
|
||||
driver ::= 'driver' PATH
|
||||
|
||||
# Use the Config.lb file in the PATH
|
||||
dir ::= 'dir' PATH
|
||||
|
||||
# add a file to the set of ldscript files
|
||||
ldscript ::= 'ldscript' PATH
|
||||
|
||||
# dependencies or actions for the makerule command
|
||||
dep ::= 'dep' ``dependency-string''
|
||||
act ::= 'act' ``actions''
|
||||
depsacts ::= (dep | act)*
|
||||
# set up a makerule
|
||||
#
|
||||
makerule ::= 'makerule' PATH depsacts
|
||||
|
||||
#defines for use in makefiles only
|
||||
# note usable in the config tool, not passed to cc
|
||||
makedefine ::= 'makedefine' ``RAWTEXT''
|
||||
|
||||
# add an action to an existing make rule
|
||||
addaction ::= 'addaction' PATH ``ACTION''
|
||||
|
||||
# statements
|
||||
statement ::=
|
||||
option
|
||||
| default
|
||||
| cpu
|
||||
| arch
|
||||
| northbridge
|
||||
| southbridge
|
||||
| superio
|
||||
| object
|
||||
| driver
|
||||
| mainboardinit
|
||||
| makerule
|
||||
| makedefine
|
||||
| addaction
|
||||
| init
|
||||
| register
|
||||
| iif
|
||||
| dir
|
||||
| ldscript
|
||||
|
||||
statements ::= (statement)*
|
||||
|
||||
# target directory specification
|
||||
target ::= 'target' PATH
|
||||
|
||||
# and the whole thing
|
||||
board ::= target (option)* mainboard
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
\subsubsection{Command definitions}
|
||||
\subsubsubsection{option}
|
||||
\subsubsubsection{default}
|
||||
\subsubsubsection{cpu}
|
||||
\subsubsubsection{arch}
|
||||
\subsubsubsection{northbridge}
|
||||
\subsubsubsection{southbridge}
|
||||
\subsubsubsection{superio}
|
||||
\subsubsubsection{object}
|
||||
\subsubsubsection{driver}
|
||||
\subsubsubsection{mainboardinit}
|
||||
\subsubsubsection{makerule}
|
||||
\subsubsubsection{makedefine}
|
||||
\subsubsubsection{addaction}
|
||||
\subsubsubsection{init}
|
||||
\subsubsubsection{register}
|
||||
\subsubsubsection{iif}
|
||||
\subsubsubsection{dir}
|
||||
\subsubsubsection{ldscript}
|
||||
|
||||
|
||||
A sample file:
|
||||
|
||||
\begin{verbatim}
|
||||
target x
|
||||
|
||||
# over-ride the default ROM size in the mainboard file
|
||||
option CONFIG_ROM_SIZE=1024*1024
|
||||
mainboard amd/solo
|
||||
end
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
Sample mainboard file
|
||||
\begin{verbatim}
|
||||
#
|
||||
###
|
||||
### Set all of the defaults for an x86 architecture
|
||||
###
|
||||
arch i386 end
|
||||
cpu k8 end
|
||||
#
|
||||
option CONFIG_DEBUG=1
|
||||
default CONFIG_USE_FALLBACK_IMAGE=1
|
||||
option A=(1+2)
|
||||
option B=0xa
|
||||
#
|
||||
###
|
||||
### Build our 16 bit and 32 bit linuxBIOS entry code
|
||||
###
|
||||
mainboardinit cpu/i386/entry16.inc
|
||||
mainboardinit cpu/i386/entry32.inc
|
||||
ldscript cpu/i386/entry16.lds
|
||||
ldscript cpu/i386/entry32.lds
|
||||
#
|
||||
###
|
||||
### Build our reset vector (This is where linuxBIOS is entered)
|
||||
###
|
||||
if CONFIG_USE_FALLBACK_IMAGE
|
||||
mainboardinit cpu/i386/reset16.inc
|
||||
ldscript cpu/i386/reset16.lds
|
||||
else
|
||||
mainboardinit cpu/i386/reset32.inc
|
||||
ldscript cpu/i386/reset32.lds
|
||||
end
|
||||
.
|
||||
.
|
||||
.
|
||||
if CONFIG_USE_FALLBACK_IMAGE mainboardinit arch/i386/lib/noop_failover.inc end
|
||||
#
|
||||
###
|
||||
### Romcc output
|
||||
###
|
||||
#makerule ./failover.E dep "$(CONFIG_MAINBOARD)/failover.c" act "$(CPP) -I$(TOP)/src $(CPPFLAGS) $(CONFIG_MAINBOARD)/failover.c > ./failever.E"
|
||||
#makerule ./failover.inc dep "./romcc ./failover.E" act "./romcc -O ./failover.E > failover.inc"
|
||||
#mainboardinit ./failover.inc
|
||||
makerule ./auto.E dep "$(CONFIG_MAINBOARD)/auto.c" act "$(CPP) -I$(TOP)/src -$(ROMCCPPFLAGS) $(CPPFLAGS) $(CONFIG_MAINBOARD)/auto.c > ./auto.E"
|
||||
makerule ./auto.inc dep "./romcc ./auto.E" act "./romcc -O ./auto.E > auto.inc"
|
||||
mainboardinit ./auto.inc
|
||||
#
|
||||
###
|
||||
### Include the secondary Configuration files
|
||||
###
|
||||
northbridge amd/amdk8
|
||||
end
|
||||
southbridge amd/amd8111
|
||||
end
|
||||
#mainboardinit arch/i386/smp/secondary.inc
|
||||
superio nsc/pc87360
|
||||
register "com1={1} com2={0} floppy=1 lpt=1 keyboard=1"
|
||||
end
|
||||
dir /pc80
|
||||
##dir /src/superio/winbond/w83627hf
|
||||
cpu p5 end
|
||||
cpu p6 end
|
||||
cpu k7 end
|
||||
cpu k8 end
|
||||
#
|
||||
###
|
||||
### Build the objects we have code for in this directory.
|
||||
###
|
||||
##object mainboard.o
|
||||
driver mainboard.o
|
||||
object static_devices.o
|
||||
if CONFIG_HAVE_MP_TABLE object mptable.o end
|
||||
if CONFIG_HAVE_PIRQ_TABLE object irq_tables.o end
|
||||
### Location of the DIMM EEPROMS on the SMBUS
|
||||
### This is fixed into a narrow range by the DIMM package standard.
|
||||
###
|
||||
option SMBUS_MEM_DEVICE_START=(0xa << 3)
|
||||
option SMBUS_MEM_DEVICE_END=(SMBUS_MEM_DEVICE_START +1)
|
||||
option SMBUS_MEM_DEVICE_INC=1
|
||||
#
|
||||
### The linuxBIOS bootloader.
|
||||
###
|
||||
option CONFIG_PAYLOAD_SIZE = (CONFIG_ROM_SECTION_SIZE - CONFIG_ROM_IMAGE_SIZE)
|
||||
option CONFIG_ROM_PAYLOAD_START = (0xffffffff - CONFIG_ROM_SIZE + CONFIG_ROM_SECTION_OFFSET + 1)
|
||||
#
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
I've found the output of the new tool to be easier to
|
||||
handle. Makefile.settings looks like this, for example:
|
||||
\begin{verbatim}
|
||||
TOP:=/home/rminnich/src/yapps2/freebios2
|
||||
TARGET_DIR:=x
|
||||
export CONFIG_MAINBOARD:=/home/rminnich/src/yapps2/freebios2/src/mainboard/amd/solo
|
||||
export CONFIG_ARCH:=i386
|
||||
export CONFIG_RAMBASE:=0x4000
|
||||
export CONFIG_ROM_IMAGE_SIZE:=65535
|
||||
export CONFIG_PAYLOAD_SIZE:=131073
|
||||
export CONFIG_MAX_CPUS:=1
|
||||
export CONFIG_HEAP_SIZE:=8192
|
||||
export CONFIG_STACK_SIZE:=8192
|
||||
export CONFIG_MEMORY_HOLE:=0
|
||||
export COREBOOT_VERSION:=1.1.0
|
||||
export CC:=$(CONFIG_CROSS_COMPILE)gcc
|
||||
|
||||
\end{verbatim}
|
||||
|
||||
In other words, instead of expressions, we see the values. It's easier to
|
||||
deal with.
|
||||
|
|
@ -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).
|
||||
|
||||
|
|
@ -73,17 +73,17 @@ calling the platform specific acpigen_soc_{set,clear}_tx_gpio
|
|||
functions internally. Thus, all the ACPI AML calling conventions for
|
||||
the platform functions apply to these helper functions as well.
|
||||
|
||||
3. Get Rx GPIO
|
||||
int acpigen_get_rx_gpio(struct acpi_gpio gpio)
|
||||
|
||||
This function takes as input, an struct acpi_gpio type and outputs
|
||||
AML code to read the *logical* value of a gpio (after taking its
|
||||
polarity into consideration), into the Local0 variable. It calls
|
||||
the platform specific acpigen_soc_read_rx_gpio() to actually read
|
||||
the raw Rx gpio value.
|
||||
|
||||
## Implementation Details
|
||||
|
||||
ACPI library in coreboot will provide weak definitions for all the
|
||||
above functions with error messages indicating that these functions
|
||||
are being used. This allows drivers to conditionally make use of GPIOs
|
||||
based on device-tree entries or any other config option. It is
|
||||
recommended that the SoC code in coreboot should provide
|
||||
implementations of all the above functions generating ACPI AML code
|
||||
irrespective of them being used in any driver. This allows mainboards
|
||||
to use any drivers and take advantage of this common infrastructure.
|
||||
|
||||
Platforms are restricted to using Local5, Local6 and Local7 variables
|
||||
only in implementations of the above functions. Any AML methods called
|
||||
by the above functions do not have any such restrictions on use of
|
||||
|
|
@ -150,6 +150,7 @@ for the GPIO.
|
|||
*/
|
||||
acpigen_write_if_and(Local5, TX_BIT);
|
||||
acpigen_write_store_args(ONE_OP, LOCAL0_OP);
|
||||
acpigen_pop_len();
|
||||
acpigen_write_else();
|
||||
acpigen_write_store_args(ZERO_OP, LOCAL0_OP);
|
||||
acpigen_pop_len();
|
||||
|
|
|
|||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
@ -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.
|
||||
File diff suppressed because it is too large
Load diff
|
|
@ -5,15 +5,7 @@ architectures.
|
|||
|
||||
## RISC-V
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
RISC-V documentation <riscv/index.md>
|
||||
```
|
||||
- [RISC-V documentation](riscv/index.md)
|
||||
|
||||
## x86
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
|
||||
x86 documentation <x86/index.md>
|
||||
```
|
||||
- [x86 documentation](x86/index.md)
|
||||
|
|
|
|||
|
|
@ -19,27 +19,12 @@ 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.
|
||||
Traps are delegated in the ramstage.
|
||||
|
||||
## SMP within a stage
|
||||
At the beginning of each stage, all harts save 0 are spinning in a loop on
|
||||
|
|
@ -59,6 +44,3 @@ The hart blocks until fn is non-null, and then calls it. If fn returns, we
|
|||
will panic if possible, but behavior is largely undefined.
|
||||
|
||||
Only hart 0 runs through most of the code in each stage.
|
||||
|
||||
[RISCV-PK]: https://github.com/riscv/riscv-pk
|
||||
[OpenSBI]: https://github.com/riscv/opensbi
|
||||
|
|
|
|||
|
|
@ -2,9 +2,43 @@
|
|||
|
||||
This section contains documentation about coreboot on x86 architecture.
|
||||
|
||||
```{toctree}
|
||||
:maxdepth: 1
|
||||
* [x86 PAE support](pae.md)
|
||||
|
||||
x86 PAE support <pae.md>
|
||||
x86_64 support <x86_64.md>
|
||||
```
|
||||
## State of x86_64 support
|
||||
At the moment there's no single board that supports x86_64 or to be exact
|
||||
`ARCH_RAMSTAGE_X86_64` and `ARCH_ROMSTAGE_X86_64`.
|
||||
|
||||
In order to add support for x86_64 the following assumptions are made:
|
||||
* The CPU supports long mode
|
||||
* All memory returned by malloc must be below 4GiB in physical memory
|
||||
* All code that is to be run must be below 4GiB in physical memory
|
||||
* The high dword of pointers is always zero
|
||||
* The reference implementation is qemu
|
||||
* The CPU supports 1GiB hugepages
|
||||
|
||||
## Assuptions for ARCH_ROMSTAGE_X86_64 reference implementation
|
||||
* 0-4GiB are identity mapped using 1GiB huge-pages
|
||||
* Memory above 4GiB isn't accessible
|
||||
* pagetables reside in _pagetables
|
||||
* Romstage must install new pagetables in CBMEM after RAMINIT
|
||||
|
||||
## Assuptions for ARCH_RAMSTAGE_X86_64 reference implementation
|
||||
* Romstage installed pagetables according to memory layout
|
||||
* Memory above 4GiB is accessible
|
||||
|
||||
## Steps to add basic support for x86_64
|
||||
* Add x86_64 toolchain support - *DONE*
|
||||
* Fix compilation errors - *DONE*
|
||||
* Fix linker errors - *TODO*
|
||||
* Add x86_64 rmodule support - *ONGERRIT*
|
||||
* Add x86_64 exception handlers - *TODO*
|
||||
* Setup page tables for long mode - *TODO*
|
||||
* Add assembly code for long mode - *TODO*
|
||||
* Add assembly code to return to protected mode - *TODO*
|
||||
* Implement reference code for mainboard `emulation/qemu-q35` - *TODO*
|
||||
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
938
Documentation/coding_style.md
Normal file
938
Documentation/coding_style.md
Normal file
|
|
@ -0,0 +1,938 @@
|
|||
# Coding Style
|
||||
|
||||
This is a short document describing the preferred coding style for the
|
||||
coreboot project. It is in many ways exactly the same as the Linux
|
||||
kernel coding style. In fact, most of this document has been copied from
|
||||
the [Linux kernel coding style](http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git/plain/Documentation/CodingStyle?id=HEAD)
|
||||
|
||||
Please at least consider the points made here.
|
||||
|
||||
First off, I'd suggest printing out a copy of the GNU coding standards,
|
||||
and NOT read it. Burn them, it's a great symbolic gesture.
|
||||
|
||||
Anyway, here goes:
|
||||
|
||||
## Indentation
|
||||
|
||||
Tabs are 8 characters, and thus indentations are also 8 characters.
|
||||
There are heretic movements that try to make indentations 4 (or even 2!)
|
||||
characters deep, and that is akin to trying to define the value of PI to
|
||||
be 3.
|
||||
|
||||
Rationale: The whole idea behind indentation is to clearly define where
|
||||
a block of control starts and ends. Especially when you've been looking
|
||||
at your screen for 20 straight hours, you'll find it a lot easier to
|
||||
see how the indentation works if you have large indentations.
|
||||
|
||||
Now, some people will claim that having 8-character indentations makes
|
||||
the code move too far to the right, and makes it hard to read on a
|
||||
80-character terminal screen. The answer to that is that if you need
|
||||
more than 3 levels of indentation, you're screwed anyway, and should
|
||||
fix your program.
|
||||
|
||||
In short, 8-char indents make things easier to read, and have the added
|
||||
benefit of warning you when you're nesting your functions too deep.
|
||||
Heed that warning.
|
||||
|
||||
The preferred way to ease multiple indentation levels in a switch
|
||||
statement is to align the "switch" and its subordinate "case" labels
|
||||
in the same column instead of "double-indenting" the "case" labels.
|
||||
E.g.:
|
||||
|
||||
```c
|
||||
switch (suffix) {
|
||||
case 'G':
|
||||
case 'g':
|
||||
mem <<= 30;
|
||||
break;
|
||||
case 'M':
|
||||
case 'm':
|
||||
mem <<= 20;
|
||||
break;
|
||||
case 'K':
|
||||
case 'k':
|
||||
mem <<= 10;
|
||||
/* fall through */
|
||||
default:
|
||||
break;
|
||||
}
|
||||
```
|
||||
|
||||
Don't put multiple statements on a single line unless you have
|
||||
something to hide:
|
||||
|
||||
```c
|
||||
if (condition) do_this;
|
||||
do_something_everytime;
|
||||
```
|
||||
|
||||
Don't put multiple assignments on a single line either. Kernel coding
|
||||
style is super simple. Avoid tricky expressions.
|
||||
|
||||
Outside of comments, documentation and except in Kconfig, spaces are
|
||||
never used for indentation, and the above example is deliberately
|
||||
broken.
|
||||
|
||||
Get a decent editor and don't leave whitespace at the end of lines.
|
||||
|
||||
## Breaking long lines and strings
|
||||
|
||||
Coding style is all about readability and maintainability using commonly
|
||||
available tools.
|
||||
|
||||
The limit on the length of lines is 80 columns and this is a strongly
|
||||
preferred limit.
|
||||
|
||||
Statements longer than 80 columns will be broken into sensible chunks,
|
||||
unless exceeding 80 columns significantly increases readability and does
|
||||
not hide information. Descendants are always substantially shorter than
|
||||
the parent and are placed substantially to the right. The same applies
|
||||
to function headers with a long argument list. However, never break
|
||||
user-visible strings such as printk messages, because that breaks the
|
||||
ability to grep for them.
|
||||
|
||||
## Placing Braces and Spaces
|
||||
|
||||
The other issue that always comes up in C styling is the placement of
|
||||
braces. Unlike the indent size, there are few technical reasons to
|
||||
choose one placement strategy over the other, but the preferred way, as
|
||||
shown to us by the prophets Kernighan and Ritchie, is to put the opening
|
||||
brace last on the line, and put the closing brace first, thusly:
|
||||
|
||||
```c
|
||||
if (x is true) {
|
||||
we do y
|
||||
}
|
||||
```
|
||||
|
||||
This applies to all non-function statement blocks (if, switch, for,
|
||||
while, do). E.g.:
|
||||
|
||||
```c
|
||||
switch (action) {
|
||||
case KOBJ_ADD:
|
||||
return "add";
|
||||
case KOBJ_REMOVE:
|
||||
return "remove";
|
||||
case KOBJ_CHANGE:
|
||||
return "change";
|
||||
default:
|
||||
return NULL;
|
||||
}
|
||||
```
|
||||
|
||||
However, there is one special case, namely functions: they have the
|
||||
opening brace at the beginning of the next line, thus:
|
||||
|
||||
```c
|
||||
int function(int x)
|
||||
{
|
||||
body of function
|
||||
}
|
||||
```
|
||||
|
||||
Heretic people all over the world have claimed that this inconsistency
|
||||
is ... well ... inconsistent, but all right-thinking people know that
|
||||
(a) K&R are _right_ and (b) K&R are right. Besides, functions are
|
||||
special anyway (you can't nest them in C).
|
||||
|
||||
Note that the closing brace is empty on a line of its own, _except_ in
|
||||
the cases where it is followed by a continuation of the same statement,
|
||||
ie a "while" in a do-statement or an "else" in an if-statement, like
|
||||
this:
|
||||
|
||||
```c
|
||||
do {
|
||||
body of do-loop
|
||||
} while (condition);
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```c
|
||||
if (x == y) {
|
||||
..
|
||||
} else if (x > y) {
|
||||
...
|
||||
} else {
|
||||
....
|
||||
}
|
||||
```
|
||||
|
||||
Rationale: K&R.
|
||||
|
||||
Also, note that this brace-placement also minimizes the number of empty
|
||||
(or almost empty) lines, without any loss of readability. Thus, as the
|
||||
supply of new-lines on your screen is not a renewable resource (think
|
||||
25-line terminal screens here), you have more empty lines to put
|
||||
comments on.
|
||||
|
||||
Do not unnecessarily use braces where a single statement will do.
|
||||
|
||||
```c
|
||||
if (condition)
|
||||
action();
|
||||
```
|
||||
|
||||
and
|
||||
|
||||
```c
|
||||
if (condition)
|
||||
do_this();
|
||||
else
|
||||
do_that();
|
||||
```
|
||||
|
||||
This does not apply if only one branch of a conditional statement is a
|
||||
single statement; in the latter case use braces in both branches:
|
||||
|
||||
```c
|
||||
if (condition) {
|
||||
do_this();
|
||||
do_that();
|
||||
} else {
|
||||
otherwise();
|
||||
}
|
||||
```
|
||||
|
||||
### Spaces
|
||||
|
||||
Linux kernel style for use of spaces depends (mostly) on
|
||||
function-versus-keyword usage. Use a space after (most) keywords. The
|
||||
notable exceptions are sizeof, typeof, alignof, and __attribute__,
|
||||
which look somewhat like functions (and are usually used with
|
||||
parentheses in Linux, although they are not required in the language, as
|
||||
in: "sizeof info" after "struct fileinfo info;" is declared).
|
||||
|
||||
So use a space after these keywords:
|
||||
|
||||
```
|
||||
if, switch, case, for, do, while
|
||||
```
|
||||
|
||||
but not with sizeof, typeof, alignof, or __attribute__. E.g.,
|
||||
|
||||
```c
|
||||
s = sizeof(struct file);
|
||||
```
|
||||
|
||||
Do not add spaces around (inside) parenthesized expressions. This
|
||||
example is
|
||||
|
||||
- bad*:
|
||||
|
||||
```c
|
||||
s = sizeof( struct file );
|
||||
```
|
||||
|
||||
When declaring pointer data or a function that returns a pointer type,
|
||||
the preferred use of '*' is adjacent to the data name or function
|
||||
name and not adjacent to the type name. Examples:
|
||||
|
||||
```c
|
||||
char *linux_banner;
|
||||
unsigned long long memparse(char *ptr, char **retptr);
|
||||
char *match_strdup(substring_t *s);
|
||||
```
|
||||
|
||||
Use one space around (on each side of) most binary and ternary
|
||||
operators, such as any of these:
|
||||
|
||||
```
|
||||
= + - < > * / % | & ^ <= >= == != ? :
|
||||
```
|
||||
|
||||
but no space after unary operators:
|
||||
|
||||
```
|
||||
& * + - ~ ! sizeof typeof alignof __attribute__ defined
|
||||
```
|
||||
|
||||
no space before the postfix increment & decrement unary operators:
|
||||
|
||||
```
|
||||
++ --
|
||||
```
|
||||
|
||||
no space after the prefix increment & decrement unary operators:
|
||||
|
||||
```
|
||||
++ --
|
||||
```
|
||||
|
||||
and no space around the '.' and "->" structure member operators.
|
||||
|
||||
Do not leave trailing whitespace at the ends of lines. Some editors with
|
||||
"smart" indentation will insert whitespace at the beginning of new
|
||||
lines as appropriate, so you can start typing the next line of code
|
||||
right away. However, some such editors do not remove the whitespace if
|
||||
you end up not putting a line of code there, such as if you leave a
|
||||
blank line. As a result, you end up with lines containing trailing
|
||||
whitespace.
|
||||
|
||||
Git will warn you about patches that introduce trailing whitespace, and
|
||||
can optionally strip the trailing whitespace for you; however, if
|
||||
applying a series of patches, this may make later patches in the series
|
||||
fail by changing their context lines.
|
||||
|
||||
### Naming
|
||||
|
||||
C is a Spartan language, and so should your naming be. Unlike Modula-2
|
||||
and Pascal programmers, C programmers do not use cute names like
|
||||
ThisVariableIsATemporaryCounter. A C programmer would call that variable
|
||||
"tmp", which is much easier to write, and not the least more difficult
|
||||
to understand.
|
||||
|
||||
HOWEVER, while mixed-case names are frowned upon, descriptive names for
|
||||
global variables are a must. To call a global function "foo" is a
|
||||
shooting offense.
|
||||
|
||||
GLOBAL variables (to be used only if you _really_ need them) need to
|
||||
have descriptive names, as do global functions. If you have a function
|
||||
that counts the number of active users, you should call that
|
||||
"count_active_users()" or similar, you should _not_ call it
|
||||
"cntusr()".
|
||||
|
||||
Encoding the type of a function into the name (so-called Hungarian
|
||||
notation) is brain damaged - the compiler knows the types anyway and can
|
||||
check those, and it only confuses the programmer. No wonder MicroSoft
|
||||
makes buggy programs.
|
||||
|
||||
LOCAL variable names should be short, and to the point. If you have some
|
||||
random integer loop counter, it should probably be called "i". Calling
|
||||
it "loop_counter" is non-productive, if there is no chance of it
|
||||
being mis-understood. Similarly, "tmp" can be just about any type of
|
||||
variable that is used to hold a temporary value.
|
||||
|
||||
If you are afraid to mix up your local variable names, you have another
|
||||
problem, which is called the function-growth-hormone-imbalance syndrome.
|
||||
See chapter 6 (Functions).
|
||||
|
||||
## Typedefs
|
||||
|
||||
Please don't use things like "vps_t".
|
||||
|
||||
It's a _mistake_ to use typedef for structures and pointers. When you
|
||||
see a
|
||||
|
||||
```c
|
||||
vps_t a;
|
||||
```
|
||||
|
||||
in the source, what does it mean?
|
||||
|
||||
In contrast, if it says
|
||||
|
||||
```c
|
||||
struct virtual_container *a;
|
||||
```
|
||||
|
||||
you can actually tell what "a" is.
|
||||
|
||||
Lots of people think that typedefs "help readability". Not so. They
|
||||
are useful only for:
|
||||
|
||||
(a) totally opaque objects (where the typedef is actively used to
|
||||
_hide_ what the object is).
|
||||
|
||||
Example: "pte_t" etc. opaque objects that you can only access using
|
||||
the proper accessor functions.
|
||||
|
||||
NOTE! Opaqueness and "accessor functions" are not good in themselves.
|
||||
The reason we have them for things like pte_t etc. is that there really
|
||||
is absolutely _zero_ portably accessible information there.
|
||||
|
||||
(b) Clear integer types, where the abstraction _helps_ avoid confusion
|
||||
whether it is "int" or "long".
|
||||
|
||||
u8/u16/u32 are perfectly fine typedefs, although they fit into category
|
||||
(d) better than here.
|
||||
|
||||
NOTE! Again - there needs to be a _reason_ for this. If something is
|
||||
"unsigned long", then there's no reason to do
|
||||
|
||||
```c
|
||||
typedef unsigned long myflags_t;
|
||||
```
|
||||
|
||||
but if there is a clear reason for why it under certain circumstances
|
||||
might be an "unsigned int" and under other configurations might be
|
||||
"unsigned long", then by all means go ahead and use a typedef.
|
||||
|
||||
(c) when you use sparse to literally create a _new_ type for
|
||||
type-checking.
|
||||
|
||||
(d) New types which are identical to standard C99 types, in certain
|
||||
exceptional circumstances.
|
||||
|
||||
Although it would only take a short amount of time for the eyes and
|
||||
brain to become accustomed to the standard types like 'uint32_t',
|
||||
some people object to their use anyway.
|
||||
|
||||
Therefore, the Linux-specific 'u8/u16/u32/u64' types and their signed
|
||||
equivalents which are identical to standard types are permitted --
|
||||
although they are not mandatory in new code of your own.
|
||||
|
||||
When editing existing code which already uses one or the other set of
|
||||
types, you should conform to the existing choices in that code.
|
||||
|
||||
(e) Types safe for use in userspace.
|
||||
|
||||
In certain structures which are visible to userspace, we cannot require
|
||||
C99 types and cannot use the 'u32' form above. Thus, we use __u32
|
||||
and similar types in all structures which are shared with userspace.
|
||||
|
||||
Maybe there are other cases too, but the rule should basically be to
|
||||
NEVER EVER use a typedef unless you can clearly match one of those
|
||||
rules.
|
||||
|
||||
In general, a pointer, or a struct that has elements that can reasonably
|
||||
be directly accessed should _never_ be a typedef.
|
||||
|
||||
## Functions
|
||||
|
||||
Functions should be short and sweet, and do just one thing. They should
|
||||
fit on one or two screenfuls of text (the ISO/ANSI screen size is 80x24,
|
||||
as we all know), and do one thing and do that well.
|
||||
|
||||
The maximum length of a function is inversely proportional to the
|
||||
complexity and indentation level of that function. So, if you have a
|
||||
conceptually simple function that is just one long (but simple)
|
||||
case-statement, where you have to do lots of small things for a lot of
|
||||
different cases, it's OK to have a longer function.
|
||||
|
||||
However, if you have a complex function, and you suspect that a
|
||||
less-than-gifted first-year high-school student might not even
|
||||
understand what the function is all about, you should adhere to the
|
||||
maximum limits all the more closely. Use helper functions with
|
||||
descriptive names (you can ask the compiler to in-line them if you think
|
||||
it's performance-critical, and it will probably do a better job of it
|
||||
than you would have done).
|
||||
|
||||
Another measure of the function is the number of local variables. They
|
||||
shouldn't exceed 5-10, or you're doing something wrong. Re-think the
|
||||
function, and split it into smaller pieces. A human brain can generally
|
||||
easily keep track of about 7 different things, anything more and it gets
|
||||
confused. You know you're brilliant, but maybe you'd like to
|
||||
understand what you did 2 weeks from now.
|
||||
|
||||
In source files, separate functions with one blank line. If the function
|
||||
is exported, the EXPORT* macro for it should follow immediately after
|
||||
the closing function brace line. E.g.:
|
||||
|
||||
```c
|
||||
int system_is_up(void)
|
||||
{
|
||||
return system_state == SYSTEM_RUNNING;
|
||||
}
|
||||
EXPORT_SYMBOL(system_is_up);
|
||||
```
|
||||
|
||||
In function prototypes, include parameter names with their data types.
|
||||
Although this is not required by the C language, it is preferred in
|
||||
Linux because it is a simple way to add valuable information for the
|
||||
reader.
|
||||
|
||||
## Centralized exiting of functions
|
||||
|
||||
Albeit deprecated by some people, the equivalent of the goto statement
|
||||
is used frequently by compilers in form of the unconditional jump
|
||||
instruction.
|
||||
|
||||
The goto statement comes in handy when a function exits from multiple
|
||||
locations and some common work such as cleanup has to be done. If there
|
||||
is no cleanup needed then just return directly.
|
||||
|
||||
The rationale is:
|
||||
|
||||
- unconditional statements are easier to understand and follow
|
||||
- nesting is reduced
|
||||
- errors by not updating individual exit points when making
|
||||
modifications are prevented
|
||||
- saves the compiler work to optimize redundant code away ;)
|
||||
|
||||
```c
|
||||
int fun(int a)
|
||||
{
|
||||
int result = 0;
|
||||
char *buffer = kmalloc(SIZE);
|
||||
|
||||
if (buffer == NULL)
|
||||
return -ENOMEM;
|
||||
|
||||
if (condition1) {
|
||||
while (loop1) {
|
||||
...
|
||||
}
|
||||
result = 1;
|
||||
goto out;
|
||||
}
|
||||
...
|
||||
out:
|
||||
kfree(buffer);
|
||||
return result;
|
||||
}
|
||||
```
|
||||
|
||||
## Commenting
|
||||
|
||||
Comments are good, but there is also a danger of over-commenting. NEVER
|
||||
try to explain HOW your code works in a comment: it's much better to
|
||||
write the code so that the _working_ is obvious, and it's a waste of
|
||||
time to explain badly written code.
|
||||
|
||||
Generally, you want your comments to tell WHAT your code does, not HOW.
|
||||
Also, try to avoid putting comments inside a function body: if the
|
||||
function is so complex that you need to separately comment parts of it,
|
||||
you should probably go back to chapter 6 for a while. You can make small
|
||||
comments to note or warn about something particularly clever (or ugly),
|
||||
but try to avoid excess. Instead, put the comments at the head of the
|
||||
function, telling people what it does, and possibly WHY it does it.
|
||||
|
||||
When commenting the kernel API functions, please use the kernel-doc
|
||||
format. See the files Documentation/kernel-doc-nano-HOWTO.txt and
|
||||
scripts/kernel-doc for details.
|
||||
|
||||
coreboot style for comments is the C89 "/* ... */" style. You may
|
||||
use C99-style "// ..." comments.
|
||||
|
||||
The preferred style for *short* (multi-line) comments is:
|
||||
|
||||
```c
|
||||
/* This is the preferred style for short multi-line
|
||||
comments in the Linux kernel source code.
|
||||
Please use it consistently. */
|
||||
```
|
||||
|
||||
The preferred style for *long* (multi-line) comments is:
|
||||
|
||||
```c
|
||||
/*
|
||||
* This is the preferred style for multi-line
|
||||
* comments in the Linux kernel source code.
|
||||
* Please use it consistently.
|
||||
*
|
||||
* Description: A column of asterisks on the left side,
|
||||
* with beginning and ending almost-blank lines.
|
||||
*/
|
||||
```
|
||||
|
||||
It's also important to comment data, whether they are basic types or
|
||||
derived types. To this end, use just one data declaration per line (no
|
||||
commas for multiple data declarations). This leaves you room for a small
|
||||
comment on each item, explaining its use.
|
||||
|
||||
## You've made a mess of it
|
||||
That's OK, we all do. You've probably been told by your long-time Unix user
|
||||
helper that "GNU emacs" automatically formats the C sources for you, and
|
||||
you've noticed that yes, it does do that, but the defaults it uses are less
|
||||
than desirable (in fact, they are worse than random typing - an infinite
|
||||
number of monkeys typing into GNU emacs would never make a good program).
|
||||
|
||||
So, you can either get rid of GNU emacs, or change it to use saner values.
|
||||
To do the latter, you can stick the following in your .emacs file:
|
||||
|
||||
```lisp
|
||||
(defun c-lineup-arglist-tabs-only (ignored)
|
||||
"Line up argument lists by tabs, not spaces"
|
||||
(let* ((anchor (c-langelem-pos c-syntactic-element))
|
||||
(column (c-langelem-2nd-pos c-syntactic-element))
|
||||
(offset (- (1+ column) anchor))
|
||||
(steps (floor offset c-basic-offset)))
|
||||
(* (max steps 1)
|
||||
c-basic-offset)))
|
||||
|
||||
(add-hook 'c-mode-common-hook
|
||||
(lambda ()
|
||||
;; Add kernel style
|
||||
(c-add-style
|
||||
"linux-tabs-only"
|
||||
'("linux" (c-offsets-alist
|
||||
(arglist-cont-nonempty
|
||||
c-lineup-gcc-asm-reg
|
||||
c-lineup-arglist-tabs-only))))))
|
||||
|
||||
(add-hook 'c-mode-hook
|
||||
(lambda ()
|
||||
(let ((filename (buffer-file-name)))
|
||||
;; Enable kernel mode for the appropriate files
|
||||
(when (and filename
|
||||
(string-match (expand-file-name "~/src/linux-trees")
|
||||
filename))
|
||||
(setq indent-tabs-mode t)
|
||||
(c-set-style "linux-tabs-only")))))
|
||||
```
|
||||
|
||||
This will make emacs go better with the kernel coding style for C files
|
||||
below ~/src/linux-trees.
|
||||
|
||||
But even if you fail in getting emacs to do sane formatting, not
|
||||
everything is lost: use "indent".
|
||||
|
||||
Now, again, GNU indent has the same brain-dead settings that GNU emacs
|
||||
has, which is why you need to give it a few command line options.
|
||||
However, that's not too bad, because even the makers of GNU indent
|
||||
recognize the authority of K&R (the GNU people aren't evil, they are
|
||||
just severely misguided in this matter), so you just give indent the
|
||||
options "-kr -i8" (stands for "K&R, 8 character indents"), or use
|
||||
"scripts/Lindent", which indents in the latest style.
|
||||
|
||||
"indent" has a lot of options, and especially when it comes to comment
|
||||
re-formatting you may want to take a look at the man page. But remember:
|
||||
"indent" is not a fix for bad programming.
|
||||
|
||||
## Kconfig configuration files
|
||||
|
||||
For all of the Kconfig* configuration files throughout the source tree,
|
||||
the indentation is somewhat different. Lines under a "config"
|
||||
definition are indented with one tab, while help text is indented an
|
||||
additional two spaces. Example:
|
||||
|
||||
```kconfig
|
||||
config AUDIT
|
||||
bool "Auditing support"
|
||||
depends on NET
|
||||
help
|
||||
Enable auditing infrastructure that can be used with another
|
||||
kernel subsystem, such as SELinux (which requires this for
|
||||
logging of avc messages output). Does not do system-call
|
||||
auditing without CONFIG_AUDITSYSCALL.
|
||||
```
|
||||
|
||||
Seriously dangerous features (such as write support for certain
|
||||
filesystems) should advertise this prominently in their prompt string:
|
||||
|
||||
```kconfig
|
||||
config ADFS_FS_RW
|
||||
bool "ADFS write support (DANGEROUS)"
|
||||
depends on ADFS_FS
|
||||
...
|
||||
```
|
||||
|
||||
For full documentation on the configuration files, see the file
|
||||
Documentation/kbuild/kconfig-language.txt.
|
||||
|
||||
Data structures
|
||||
---------------
|
||||
|
||||
Data structures that have visibility outside the single-threaded
|
||||
environment they are created and destroyed in should always have
|
||||
reference counts. In the kernel, garbage collection doesn't exist (and
|
||||
outside the kernel garbage collection is slow and inefficient), which
|
||||
means that you absolutely _have_ to reference count all your uses.
|
||||
|
||||
Reference counting means that you can avoid locking, and allows multiple
|
||||
users to have access to the data structure in parallel - and not having
|
||||
to worry about the structure suddenly going away from under them just
|
||||
because they slept or did something else for a while.
|
||||
|
||||
Note that locking is _not_ a replacement for reference counting.
|
||||
Locking is used to keep data structures coherent, while reference
|
||||
counting is a memory management technique. Usually both are needed, and
|
||||
they are not to be confused with each other.
|
||||
|
||||
Many data structures can indeed have two levels of reference counting,
|
||||
when there are users of different "classes". The subclass count counts
|
||||
the number of subclass users, and decrements the global count just once
|
||||
when the subclass count goes to zero.
|
||||
|
||||
Examples of this kind of "multi-level-reference-counting" can be found
|
||||
in memory management ("struct mm_struct": mm_users and mm_count),
|
||||
and in filesystem code ("struct super_block": s_count and
|
||||
s_active).
|
||||
|
||||
Remember: if another thread can find your data structure, and you don't
|
||||
have a reference count on it, you almost certainly have a bug.
|
||||
|
||||
Macros, Enums and RTL
|
||||
---------------------
|
||||
|
||||
Names of macros defining constants and labels in enums are capitalized.
|
||||
|
||||
```c
|
||||
#define CONSTANT 0x12345
|
||||
```
|
||||
|
||||
Enums are preferred when defining several related constants.
|
||||
|
||||
CAPITALIZED macro names are appreciated but macros resembling functions
|
||||
may be named in lower case.
|
||||
|
||||
Generally, inline functions are preferable to macros resembling
|
||||
functions.
|
||||
|
||||
Macros with multiple statements should be enclosed in a do - while
|
||||
block:
|
||||
|
||||
```c
|
||||
#define macrofun(a, b, c) \
|
||||
do { \
|
||||
if (a == 5) \
|
||||
do_this(b, c); \
|
||||
} while (0)
|
||||
```
|
||||
|
||||
Things to avoid when using macros:
|
||||
|
||||
1) macros that affect control flow:
|
||||
|
||||
```c
|
||||
#define FOO(x) \
|
||||
do { \
|
||||
if (blah(x) < 0) \
|
||||
return -EBUGGERED; \
|
||||
} while(0)
|
||||
```
|
||||
|
||||
is a *very* bad idea. It looks like a function call but exits the
|
||||
"calling" function; don't break the internal parsers of those who
|
||||
will read the code.
|
||||
|
||||
2) macros that depend on having a local variable with a magic name:
|
||||
|
||||
```c
|
||||
#define FOO(val) bar(index, val)
|
||||
```
|
||||
|
||||
might look like a good thing, but it's confusing as hell when one reads
|
||||
the code and it's prone to breakage from seemingly innocent changes.
|
||||
|
||||
3) macros with arguments that are used as l-values: FOO(x) = y; will
|
||||
bite you if somebody e.g. turns FOO into an inline function.
|
||||
|
||||
4) forgetting about precedence: macros defining constants using
|
||||
expressions must enclose the expression in parentheses. Beware of
|
||||
similar issues with macros using parameters.
|
||||
|
||||
```c
|
||||
#define CONSTANT 0x4000
|
||||
#define CONSTEXP (CONSTANT | 3)
|
||||
```
|
||||
|
||||
The cpp manual deals with macros exhaustively. The gcc internals manual
|
||||
also covers RTL which is used frequently with assembly language in the
|
||||
kernel.
|
||||
|
||||
Printing kernel messages
|
||||
------------------------
|
||||
|
||||
Kernel developers like to be seen as literate. Do mind the spelling of
|
||||
kernel messages to make a good impression. Do not use crippled words
|
||||
like "dont"; use "do not" or "don't" instead. Make the messages
|
||||
concise, clear, and unambiguous.
|
||||
|
||||
Kernel messages do not have to be terminated with a period.
|
||||
|
||||
Printing numbers in parentheses (%d) adds no value and should be
|
||||
avoided.
|
||||
|
||||
There are a number of driver model diagnostic macros in
|
||||
<linux/device.h> which you should use to make sure messages are
|
||||
matched to the right device and driver, and are tagged with the right
|
||||
level: dev_err(), dev_warn(), dev_info(), and so forth. For messages
|
||||
that aren't associated with a particular device, <linux/printk.h>
|
||||
defines pr_debug() and pr_info().
|
||||
|
||||
Coming up with good debugging messages can be quite a challenge; and
|
||||
once you have them, they can be a huge help for remote troubleshooting.
|
||||
Such messages should be compiled out when the DEBUG symbol is not
|
||||
defined (that is, by default they are not included). When you use
|
||||
dev_dbg() or pr_debug(), that's automatic. Many subsystems have
|
||||
Kconfig options to turn on -DDEBUG. A related convention uses
|
||||
VERBOSE_DEBUG to add dev_vdbg() messages to the ones already enabled
|
||||
by DEBUG.
|
||||
|
||||
Allocating memory
|
||||
-----------------
|
||||
|
||||
coreboot provides a single general purpose memory allocator: malloc()
|
||||
|
||||
The preferred form for passing a size of a struct is the following:
|
||||
|
||||
```c
|
||||
p = malloc(sizeof(*p));
|
||||
```
|
||||
|
||||
The alternative form where struct name is spelled out hurts readability
|
||||
and introduces an opportunity for a bug when the pointer variable type
|
||||
is changed but the corresponding sizeof that is passed to a memory
|
||||
allocator is not.
|
||||
|
||||
Casting the return value which is a void pointer is redundant. The
|
||||
conversion from void pointer to any other pointer type is guaranteed by
|
||||
the C programming language.
|
||||
|
||||
You should contain your memory usage to stack variables whenever
|
||||
possible. Only use malloc() as a last resort. In ramstage, you may also
|
||||
be able to get away with using static variables. Never use malloc()
|
||||
outside of ramstage.
|
||||
|
||||
Since coreboot only runs for a very short time, there is no memory
|
||||
deallocator, although a corresponding free() is offered. It is a no-op.
|
||||
Use of free() is not required though it is accepted. It is useful when
|
||||
sharing code with other codebases that make use of free().
|
||||
|
||||
The inline disease
|
||||
------------------
|
||||
|
||||
There appears to be a common misperception that gcc has a magic "make
|
||||
me faster" speedup option called "inline". While the use of inlines
|
||||
can be appropriate (for example as a means of replacing macros, see
|
||||
Chapter 12), it very often is not. Abundant use of the inline keyword
|
||||
leads to a much bigger kernel, which in turn slows the system as a whole
|
||||
down, due to a bigger icache footprint for the CPU and simply because
|
||||
there is less memory available for the pagecache. Just think about it; a
|
||||
pagecache miss causes a disk seek, which easily takes 5 milliseconds.
|
||||
There are a LOT of cpu cycles that can go into these 5 milliseconds.
|
||||
|
||||
A reasonable rule of thumb is to not put inline at functions that have
|
||||
more than 3 lines of code in them. An exception to this rule are the
|
||||
cases where a parameter is known to be a compiletime constant, and as a
|
||||
result of this constantness you *know* the compiler will be able to
|
||||
optimize most of your function away at compile time. For a good example
|
||||
of this later case, see the kmalloc() inline function.
|
||||
|
||||
Often people argue that adding inline to functions that are static and
|
||||
used only once is always a win since there is no space tradeoff. While
|
||||
this is technically correct, gcc is capable of inlining these
|
||||
automatically without help, and the maintenance issue of removing the
|
||||
inline when a second user appears outweighs the potential value of the
|
||||
hint that tells gcc to do something it would have done anyway.
|
||||
|
||||
Function return values and names
|
||||
--------------------------------
|
||||
|
||||
Functions can return values of many different kinds, and one of the most
|
||||
common is a value indicating whether the function succeeded or failed.
|
||||
Such a value can be represented as an error-code integer (-Exxx =
|
||||
failure, 0 = success) or a "succeeded" boolean (0 = failure, non-zero
|
||||
= success).
|
||||
|
||||
Mixing up these two sorts of representations is a fertile source of
|
||||
difficult-to-find bugs. If the C language included a strong distinction
|
||||
between integers and booleans then the compiler would find these
|
||||
mistakes for us... but it doesn't. To help prevent such bugs, always
|
||||
follow this convention:
|
||||
|
||||
If the name of a function is an action or an imperative command,
|
||||
the function should return an error-code integer. If the name
|
||||
is a predicate, the function should return a "succeeded" boolean.
|
||||
|
||||
For example, "add work" is a command, and the add_work() function
|
||||
returns 0 for success or -EBUSY for failure. In the same way, "PCI
|
||||
device present" is a predicate, and the pci_dev_present() function
|
||||
returns 1 if it succeeds in finding a matching device or 0 if it
|
||||
doesn't.
|
||||
|
||||
All EXPORTed functions must respect this convention, and so should all
|
||||
public functions. Private (static) functions need not, but it is
|
||||
recommended that they do.
|
||||
|
||||
Functions whose return value is the actual result of a computation,
|
||||
rather than an indication of whether the computation succeeded, are not
|
||||
subject to this rule. Generally they indicate failure by returning some
|
||||
out-of-range result. Typical examples would be functions that return
|
||||
pointers; they use NULL or the ERR_PTR mechanism to report failure.
|
||||
|
||||
Don't re-invent the kernel macros
|
||||
----------------------------------
|
||||
|
||||
The header file include/linux/kernel.h contains a number of macros that
|
||||
you should use, rather than explicitly coding some variant of them
|
||||
yourself. For example, if you need to calculate the length of an array,
|
||||
take advantage of the macro
|
||||
|
||||
```c
|
||||
#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
|
||||
```
|
||||
|
||||
There are also min() and max() macros that do strict type checking if
|
||||
you need them. Feel free to peruse that header file to see what else is
|
||||
already defined that you shouldn't reproduce in your code.
|
||||
|
||||
Editor modelines and other cruft
|
||||
--------------------------------
|
||||
|
||||
Some editors can interpret configuration information embedded in source
|
||||
files, indicated with special markers. For example, emacs interprets
|
||||
lines marked like this:
|
||||
|
||||
```
|
||||
-*- mode: c -*-
|
||||
```
|
||||
|
||||
Or like this:
|
||||
|
||||
```
|
||||
/*
|
||||
Local Variables:
|
||||
compile-command: "gcc -DMAGIC_DEBUG_FLAG foo.c"
|
||||
End:
|
||||
*/
|
||||
```
|
||||
|
||||
Vim interprets markers that look like this:
|
||||
|
||||
```
|
||||
/* vim:set sw=8 noet */
|
||||
```
|
||||
|
||||
Do not include any of these in source files. People have their own
|
||||
personal editor configurations, and your source files should not
|
||||
override them. This includes markers for indentation and mode
|
||||
configuration. People may use their own custom mode, or may have some
|
||||
other magic method for making indentation work correctly.
|
||||
|
||||
Inline assembly
|
||||
---------------
|
||||
|
||||
In architecture-specific code, you may need to use inline assembly to
|
||||
interface with CPU or platform functionality. Don't hesitate to do so
|
||||
when necessary. However, don't use inline assembly gratuitously when C
|
||||
can do the job. You can and should poke hardware from C when possible.
|
||||
|
||||
Consider writing simple helper functions that wrap common bits of inline
|
||||
assembly, rather than repeatedly writing them with slight variations.
|
||||
Remember that inline assembly can use C parameters.
|
||||
|
||||
Large, non-trivial assembly functions should go in .S files, with
|
||||
corresponding C prototypes defined in C header files. The C prototypes
|
||||
for assembly functions should use "asmlinkage".
|
||||
|
||||
You may need to mark your asm statement as volatile, to prevent GCC from
|
||||
removing it if GCC doesn't notice any side effects. You don't always
|
||||
need to do so, though, and doing so unnecessarily can limit
|
||||
optimization.
|
||||
|
||||
When writing a single inline assembly statement containing multiple
|
||||
instructions, put each instruction on a separate line in a separate
|
||||
quoted string, and end each string except the last with nt to
|
||||
properly indent the next instruction in the assembly output:
|
||||
|
||||
```c
|
||||
asm ("magic %reg1, #42nt"
|
||||
"more_magic %reg2, %reg3"
|
||||
: /* outputs */ : /* inputs */ : /* clobbers */);
|
||||
```
|
||||
|
||||
References
|
||||
----------
|
||||
|
||||
The C Programming Language, Second Edition by Brian W. Kernighan and
|
||||
Dennis M. Ritchie. Prentice Hall, Inc., 1988. ISBN 0-13-110362-8
|
||||
(paperback), 0-13-110370-9 (hardback). URL:
|
||||
<http://cm.bell-labs.com/cm/cs/cbook/>
|
||||
|
||||
The Practice of Programming by Brian W. Kernighan and Rob Pike.
|
||||
Addison-Wesley, Inc., 1999. ISBN 0-201-61586-X. URL:
|
||||
<http://cm.bell-labs.com/cm/cs/tpop/>
|
||||
|
||||
GNU manuals - where in compliance with K&R and this text - for cpp, gcc,
|
||||
gcc internals and indent, all available from
|
||||
<http://www.gnu.org/manual/>
|
||||
|
||||
WG14 is the international standardization working group for the
|
||||
programming language C, URL: <http://www.open-std.org/JTC1/SC22/WG14/>
|
||||
|
||||
Kernel CodingStyle, by greg@kroah.com at OLS 2002:
|
||||
<http://www.kroah.com/linux/talks/ols_2002_kernel_codingstyle_talk/html/>
|
||||
|
|
@ -86,13 +86,8 @@ organizers may take any action they deem appropriate, up to and including
|
|||
a temporary ban or permanent expulsion from the community without warning
|
||||
(and without refund in the case of a paid event).
|
||||
|
||||
As a part of running the project, coreboot leadership has the right to
|
||||
revoke privileges as they see fit. This is not done lightly. Over the
|
||||
history of the coreboot project, there have been only a handful of times
|
||||
where an action needed to be taken.
|
||||
|
||||
Community organizers can be members of the arbitration team, the
|
||||
leadership board, or organizers of events and online communities.
|
||||
Community organizers can be members of the arbitration team, or organizers
|
||||
of events and online communities.
|
||||
|
||||
## Addressing Grievances
|
||||
|
||||
|
|
@ -100,22 +95,6 @@ If you feel you have been falsely or unfairly accused of violating this
|
|||
Code of Conduct, you should notify the arbitration team with a concise
|
||||
description of your grievance.
|
||||
|
||||
Discussions about these actions are not done publicly, for obvious
|
||||
reasons. If someone believes that the circumstances that led to an
|
||||
action have changed, please send an email to all the members of the
|
||||
arbitration team and/or leadership board for discussion.
|
||||
|
||||
## Legal action
|
||||
|
||||
Threatening or starting legal action against the project, sibling
|
||||
projects hosted on coreboot.org infrastructure, project or infrastructure
|
||||
maintainers leads to an immediate ban from coreboot.org and related
|
||||
systems.
|
||||
|
||||
The ban can be reconsidered, but it's the default action because the
|
||||
people who pour lots of time and money into the projects aren't interested
|
||||
in seeing their resources used against them.
|
||||
|
||||
## Scope
|
||||
|
||||
We expect all community participants (contributors, paid or otherwise;
|
||||
|
|
@ -125,21 +104,15 @@ communications pertaining to community business.
|
|||
|
||||
## Contact info
|
||||
|
||||
Our arbitration team currently consists of the following people
|
||||
* Daniel Pono Takamori <pono@sfconservancy.org> (USA)
|
||||
Our arbitration team consists of the following people
|
||||
* Stefan Reinauer <stefan.reinauer@coreboot.org> (USA)
|
||||
* Patrick Georgi <patrick@coreboot.org> (Germany)
|
||||
* Ronald Minnich <rminnich@coreboot.org> (USA)
|
||||
* Martin Roth <martin@coreboot.org> (USA)
|
||||
|
||||
If you have an issue with someone on the arbitration team, please reach
|
||||
out to the coreboot leadership board directly.
|
||||
|
||||
The leadership board's information can be found on the
|
||||
[coreboot Leadership and Admin Boards](https://coreboot.org/leadership.html)
|
||||
page on the website.
|
||||
|
||||
## License and attribution
|
||||
|
||||
This Code of Conduct is distributed under
|
||||
a [Creative Commons Attribution-ShareAlike
|
||||
license](http://creativecommons.org/licenses/by-sa/3.0/). It is based
|
||||
on the [Citizen Code of Conduct](https://web.archive.org/web/20200330154000/http://citizencodeofconduct.org/)
|
||||
on the [Citizen Code of Conduct](http://citizencodeofconduct.org/)
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ their development kit with them and conduct development sessions.
|
|||
|
||||
[Open Source Firmware at Facebook](https://fosdem.org/2019/schedule/event/open_source_firmware_at_facebook/) by [David Hendricks](https://github.com/dhendrix) and [Andrea Barberio](https://github.com/insomniacslk) at [FOSDEM 2019](https://fosdem.org/2019/) ([video](https://video.fosdem.org/2019/K.4.401/open_source_firmware_at_facebook.mp4)) ([slides](https://insomniac.slackware.it/static/2019_fosdem_linuxboot_at_facebook.pdf)) (2019-02-03)
|
||||
|
||||
[Open Source Firmware - A love story](https://www.youtube.com/watch?v=xfqKm190dbU) by [Philipp Deppenwiese](https://cybersecurity.9elements.com) at [35c3](https://web.archive.org/web/20211027210118/https://events.ccc.de/congress/2018/wiki/index.php/Main_Page)
|
||||
[Open Source Firmware - A love story](https://www.youtube.com/watch?v=xfqKm190dbU) by [Philipp Deppenwiese](https://cybersecurity.9elements.com) at [35c3](https://events.ccc.de/congress/2018)
|
||||
([slides](https://cdn.media.ccc.de/congress/2018/slides-h264-hd/35c3-9778-deu-eng-Open_Source_Firmware_hd-slides.mp4)) (2018-12-27)
|
||||
|
||||
[coreboot mainboard porting with Intel FSP 2.0](https://www.youtube.com/watch?v=qUgo-AVsSCI) by Subrata Banik at OSFC 2018
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -11,29 +11,8 @@ You can subscribe on its
|
|||
read its
|
||||
[archives](https://mail.coreboot.org/hyperkitty/list/coreboot@coreboot.org/).
|
||||
|
||||
## Real time chat
|
||||
## IRC
|
||||
|
||||
We also have a real time chat room on [IRC](ircs://irc.libera.chat/#coreboot),
|
||||
also bridged to [Matrix](https://matrix.to/#/#coreboot: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.
|
||||
We also have a
|
||||
[real time chat](https://webchat.freenode.net?channels=%23coreboot)
|
||||
on the Freenode IRC network's #coreboot channel.
|
||||
|
|
|
|||
|
|
@ -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>
|
||||
```
|
||||
|
|
@ -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
|
||||
|
|
@ -1,48 +1,196 @@
|
|||
# Configuration file for the Sphinx documentation builder.
|
||||
#
|
||||
# For the full list of built-in configuration values, see the documentation:
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html
|
||||
|
||||
# -- Project information -----------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
|
||||
|
||||
# -*- coding: utf-8 -*-
|
||||
import subprocess
|
||||
from recommonmark.parser import CommonMarkParser
|
||||
|
||||
project = 'coreboot'
|
||||
copyright = 'CC-by 4.0 the coreboot project'
|
||||
author = 'the coreboot project'
|
||||
# Add any paths that contain templates here, relative to this directory.
|
||||
templates_path = ['_templates']
|
||||
|
||||
# The suffix(es) of source filenames.
|
||||
source_suffix = ['.md']
|
||||
|
||||
# The master toctree document.
|
||||
master_doc = 'index'
|
||||
|
||||
# General information about the project.
|
||||
project = u'coreboot'
|
||||
copyright = u'CC-by 4.0 the coreboot project'
|
||||
author = u'the coreboot project'
|
||||
|
||||
# The version info for the project you're documenting, acts as replacement for
|
||||
# |version| and |release|, also used in various other places throughout the
|
||||
# built documents.
|
||||
#
|
||||
# The full version, including alpha/beta/rc tags.
|
||||
release = subprocess.check_output(('git', 'describe')).decode("utf-8")
|
||||
# The short X.Y version.
|
||||
version = release.split("-")[0]
|
||||
|
||||
|
||||
# -- 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'
|
||||
language = None
|
||||
|
||||
# -- Options for HTML output -------------------------------------------------
|
||||
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
|
||||
# List of patterns, relative to source directory, that match files and
|
||||
# directories to ignore when looking for source files.
|
||||
# This patterns also effect to html_static_path and html_extra_path
|
||||
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
|
||||
|
||||
# The name of the Pygments (syntax highlighting) style to use.
|
||||
pygments_style = 'sphinx'
|
||||
|
||||
# A list of ignored prefixes for module index sorting.
|
||||
# modindex_common_prefix = []
|
||||
|
||||
# If true, keep warnings as "system message" paragraphs in the built documents.
|
||||
# keep_warnings = False
|
||||
|
||||
# If true, `todo` and `todoList` produce output, else they produce nothing.
|
||||
todo_include_todos = False
|
||||
|
||||
|
||||
# -- Options for HTML output ----------------------------------------------
|
||||
|
||||
# The theme to use for HTML and HTML Help pages. See the documentation for
|
||||
# a list of builtin themes.
|
||||
#
|
||||
html_theme = 'sphinx_rtd_theme'
|
||||
|
||||
# Add any paths that contain custom static files (such as style sheets) here,
|
||||
# relative to this directory. They are copied after the builtin static files,
|
||||
# so a file named "default.css" will overwrite the builtin "default.css".
|
||||
html_static_path = ['_static']
|
||||
html_css_files = [
|
||||
'theme_overrides.css', # override wide tables in RTD theme
|
||||
|
||||
html_context = {
|
||||
'css_files': [
|
||||
'_static/theme_overrides.css', # override wide tables in RTD theme
|
||||
],
|
||||
}
|
||||
|
||||
# Output file base name for HTML help builder.
|
||||
htmlhelp_basename = 'corebootdoc'
|
||||
|
||||
# -- Options for LaTeX output ---------------------------------------------
|
||||
|
||||
latex_elements = {
|
||||
# The paper size ('letterpaper' or 'a4paper').
|
||||
#
|
||||
# 'papersize': 'letterpaper',
|
||||
|
||||
# The font size ('10pt', '11pt' or '12pt').
|
||||
#
|
||||
# 'pointsize': '10pt',
|
||||
|
||||
# Additional stuff for the LaTeX preamble.
|
||||
#
|
||||
# 'preamble': '',
|
||||
|
||||
# Latex figure (float) alignment
|
||||
#
|
||||
# 'figure_align': 'htbp',
|
||||
}
|
||||
|
||||
# Grouping the document tree into LaTeX files. List of tuples
|
||||
# (source start file, target name, title,
|
||||
# author, documentclass [howto, manual, or own class]).
|
||||
latex_documents = [
|
||||
(master_doc, 'coreboot.tex', u'coreboot Documentation',
|
||||
u'the coreboot project', 'manual'),
|
||||
]
|
||||
|
||||
# The name of an image file (relative to this directory) to place at the top of
|
||||
# the title page.
|
||||
#
|
||||
# latex_logo = None
|
||||
|
||||
# For "manual" documents, if this is true, then toplevel headings are parts,
|
||||
# not chapters.
|
||||
#
|
||||
# latex_use_parts = False
|
||||
|
||||
# If true, show page references after internal links.
|
||||
#
|
||||
# latex_show_pagerefs = False
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#
|
||||
# latex_show_urls = False
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#
|
||||
# latex_appendices = []
|
||||
|
||||
# If false, will not define \strong, \code, itleref, \crossref ... but only
|
||||
# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added
|
||||
# packages.
|
||||
#
|
||||
# latex_keep_old_macro_names = True
|
||||
|
||||
# If false, no module index is generated.
|
||||
#
|
||||
# latex_domain_indices = True
|
||||
|
||||
|
||||
# -- Options for manual page output ---------------------------------------
|
||||
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
(master_doc, 'coreboot', u'coreboot Documentation',
|
||||
[author], 1)
|
||||
]
|
||||
|
||||
# If true, show URL addresses after external links.
|
||||
#
|
||||
# man_show_urls = False
|
||||
|
||||
|
||||
# -- Options for Texinfo output -------------------------------------------
|
||||
|
||||
# Grouping the document tree into Texinfo files. List of tuples
|
||||
# (source start file, target name, title, author,
|
||||
# dir menu entry, description, category)
|
||||
texinfo_documents = [
|
||||
(master_doc, 'coreboot', u'coreboot Documentation',
|
||||
author, 'coreboot', 'One line description of project.',
|
||||
'Miscellaneous'),
|
||||
]
|
||||
|
||||
enable_auto_toc_tree = True
|
||||
|
||||
class MyCommonMarkParser(CommonMarkParser):
|
||||
# remove this hack once upsteam RecommonMark supports inline code
|
||||
def visit_code(self, mdnode):
|
||||
from docutils import nodes
|
||||
n = nodes.literal(mdnode.literal, mdnode.literal)
|
||||
self.current_node.append(n)
|
||||
|
||||
# Documents to append as an appendix to all manuals.
|
||||
#
|
||||
# texinfo_appendices = []
|
||||
|
||||
# If false, no module index is generated.
|
||||
#
|
||||
# texinfo_domain_indices = True
|
||||
|
||||
# How to display URL addresses: 'footnote', 'no', or 'inline'.
|
||||
#
|
||||
# texinfo_show_urls = 'footnote'
|
||||
|
||||
# If true, do not generate a @detailmenu in the "Top" node's menu.
|
||||
#
|
||||
# texinfo_no_detailmenu = False
|
||||
|
||||
|
||||
def setup(app):
|
||||
from recommonmark.transform import AutoStructify
|
||||
app.add_source_parser('.md', MyCommonMarkParser)
|
||||
|
||||
app.add_config_value('recommonmark_config', {
|
||||
'enable_auto_toc_tree': True,
|
||||
'enable_auto_doc_ref': False, # broken in Sphinx 1.6+
|
||||
'enable_eval_rst': True,
|
||||
'url_resolver': lambda url: '/' + url
|
||||
}, True)
|
||||
app.add_transform(AutoStructify)
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load diff
|
|
@ -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
|
||||
|
||||
|
|
@ -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/
|
||||
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -20,24 +20,6 @@ doubt if you can bring yourself up to speed in a required time frame
|
|||
with the projects. We can then try together to figure out if you're a
|
||||
good match for a project, even when requirements might not all be met.
|
||||
|
||||
## Small projects
|
||||
|
||||
This is a collection of tasks which don't require deep knowledge on
|
||||
coreboot itself. If you are a beginner and want to get familiar with the
|
||||
the project and the code base, or if you just want to get your hands
|
||||
dirty with some small tasks, then these are for you.
|
||||
|
||||
* Resolve static analysis issues reported by [scan-build] and
|
||||
[Coverity scan]. More details on the page for
|
||||
[Coverity scan integration].
|
||||
|
||||
* Resolve issues reported by the [linter][Linter issues]
|
||||
|
||||
[scan-build]: https://coreboot.org/scan-build/
|
||||
[Coverity scan]: https://scan.coverity.com/projects/coreboot
|
||||
[Coverity scan integration]: ../infrastructure/coverity.md
|
||||
[Linter issues]: https://qa.coreboot.org/job/coreboot-untested-files/lastSuccessfulBuild/artifact/lint.txt
|
||||
|
||||
## Provide toolchain binaries
|
||||
Our crossgcc subproject provides a uniform compiler environment for
|
||||
working on coreboot and related projects. Sadly, building it takes hours,
|
||||
|
|
@ -45,9 +27,7 @@ which is a bad experience when trying to build coreboot the first time.
|
|||
|
||||
Provide packages/installers of our compiler toolchain for Linux distros,
|
||||
Windows, Mac OS. For Windows, this should also include the environment
|
||||
(shell, make, ...). A student doesn't have to cover _all_ platforms, but
|
||||
pick a set of systems that match their interest and knowledge and lay
|
||||
out a plan on how to do this.
|
||||
(shell, make, ...).
|
||||
|
||||
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
|
||||
|
|
@ -63,6 +43,7 @@ non-Linux builds or Docker for different Linux distributions.
|
|||
* hardware requirements: Nothing special
|
||||
|
||||
### Mentors
|
||||
* Patrick Georgi <patrick@georgi.software>
|
||||
|
||||
## Support Power9/Power8 in coreboot
|
||||
There are some basic PPC64 stubs in coreboot, and there's open hardware
|
||||
|
|
@ -83,11 +64,52 @@ across architectures.
|
|||
### Mentors
|
||||
* Timothy Pearson <tpearson@raptorengineering.com>
|
||||
|
||||
## Port payloads to ARM, AArch64 or RISC-V
|
||||
## Support QEMU AArch64 or MIPS
|
||||
Having QEMU support for the architectures coreboot can boot helps with
|
||||
some (limited) compatibility testing: While QEMU generally doesn't need
|
||||
much hardware init, any CPU state changes in the boot flow will likely
|
||||
be quite close to reality.
|
||||
|
||||
That could be used as a baseline to ensure that changes to architecture
|
||||
code doesn't entirely break these architectures
|
||||
|
||||
### Requirements
|
||||
* coreboot knowledge: Should know the general boot flow in coreboot.
|
||||
* other knowledge: This will require knowing how the architecture
|
||||
typically boots, to adapt the coreboot payload interface to be
|
||||
appropriate and, for example, provide a device tree in the platform's
|
||||
typical format.
|
||||
* hardware requirements: since QEMU runs practically everywhere and
|
||||
needs no recovery mechanism, these are suitable projects when no special
|
||||
hardware is available.
|
||||
|
||||
### Mentors
|
||||
* Patrick Georgi <patrick@georgi.software>
|
||||
|
||||
## Add Kernel Address Sanitizer functionality to coreboot
|
||||
The Kernel Address Sanitizer (KASAN) is a runtime dynamic memory error detector.
|
||||
The idea is to check every memory access (variables) for its validity
|
||||
during runtime and find bugs like stack overflow or out-of-bounds accesses.
|
||||
Implementing this stub into coreboot like "Undefined behavior sanitizer support"
|
||||
would help to ensure code quality and make the runtime code more robust.
|
||||
|
||||
### Requirements
|
||||
* knowledge in the coreboot build system and the concept of stages
|
||||
* the KASAN feature can be improved in a way so that the memory space needed
|
||||
during runtime is not on a fixed address provided during compile time but
|
||||
determined during runtime. For this to achieve a small patch to the GCC will
|
||||
be helpful. Therefore minor GCC knowledge would be beneficial.
|
||||
* Implementation can be initially done in QEMU and improved on different
|
||||
mainboards and platforms
|
||||
|
||||
### Mentors
|
||||
* Werner Zeh <werner.zeh@gmx.net>
|
||||
|
||||
## Port payloads to ARM, AArch64, MIPS or RISC-V
|
||||
While we have a rather big set of payloads for x86 based platforms, all other
|
||||
architectures are rather limited. Improve the situation by porting a payload
|
||||
to one of the platforms, for example GRUB2, U-Boot (the UI part), edk2,
|
||||
FILO, or Linux-as-Payload.
|
||||
to one of the platforms, for example GRUB2, U-Boot (the UI part), Tianocore,
|
||||
yabits, FILO, or Linux-as-Payload.
|
||||
|
||||
Since this is a bit of a catch-all idea, an application to GSoC should pick a
|
||||
combination of payload and architecture to support.
|
||||
|
|
@ -129,6 +151,27 @@ their bug reports.
|
|||
going on from the resulting logs.
|
||||
|
||||
### Mentors
|
||||
* Patrick Georgi <patrick@georgi.software>
|
||||
|
||||
## Make coreboot coverity clean
|
||||
coreboot and several other of our projects are automatically tested
|
||||
using Synopsys' free "Coverity Scan" service. While some fare pretty
|
||||
good, like [em100](https://scan.coverity.com/projects/em100) at 0 known
|
||||
defects, there are still many open issues in other projects, most notably
|
||||
[coreboot](https://scan.coverity.com/projects/coreboot) itself (which
|
||||
is also the largest codebase).
|
||||
|
||||
Not all of the reports are actual issues, but the project benefits a
|
||||
lot if the list of unhandled reports is down to 0 because that provides
|
||||
a baseline when future changes reintroduce new issues: it's easier to
|
||||
triage and handle a list of 5 issues rather than more than 350.
|
||||
|
||||
This project would be going through all reports and handling them
|
||||
appropriately: Figure out if reports are valid or not and mark them
|
||||
as such. For valid reports, provide patches to fix the underlying issue.
|
||||
|
||||
### Mentors
|
||||
* Patrick Georgi <patrick@georgi.software>
|
||||
|
||||
## Extend Ghidra to support analysis of firmware images
|
||||
[Ghidra](https://ghidra-sre.org) is a recently released cross-platform
|
||||
|
|
@ -137,11 +180,6 @@ 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
|
||||
|
|
@ -163,84 +201,3 @@ This is a research-heavy project.
|
|||
|
||||
### 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>
|
||||
|
|
|
|||
|
|
@ -386,7 +386,7 @@ want to submit all commits in the currently checked-out branch for
|
|||
review on gerrit:
|
||||
{ \small
|
||||
\begin{verbatim}
|
||||
$ git config remote.origin.push HEAD:refs/for/main
|
||||
$ git config remote.origin.push HEAD:refs/for/master
|
||||
\end{verbatim}
|
||||
}
|
||||
|
||||
|
|
@ -399,10 +399,10 @@ $ make gitconfig
|
|||
|
||||
\subsection{Work flow}
|
||||
|
||||
It is recommended that you make a new branch when you start to work, not pushing changes to main.
|
||||
It is recommended that you make a new branch when you start to work, not pushing changes to master.
|
||||
{ \small
|
||||
\begin{verbatim}
|
||||
$ git checkout main -b mybranch
|
||||
$ git checkout master -b mybranch
|
||||
\end{verbatim}
|
||||
}
|
||||
After you have done your changes, run:
|
||||
|
|
@ -452,7 +452,7 @@ make a new local commit that fixes the issues reported by the
|
|||
reviewers, then rebase the change by preserving the same Change-ID. We
|
||||
recommend you to use the git rebase command in interactive mode,
|
||||
|
||||
Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/main.
|
||||
Once your patch gets a +2 comment, your patch can be merged (cherry-pick, actually) to origin/master.
|
||||
|
||||
%
|
||||
% Working with Gerrit
|
||||
|
|
@ -474,9 +474,9 @@ click \url{https://review.coreboot.org}
|
|||
|Search for status:open |
|
||||
+-----------------------------------------------------------+
|
||||
|Subject Status Owner Project Branch Updated CR V |
|
||||
|cpu: Rename.. Alexandru coreboot main 1:20 PM +1 |
|
||||
|cpu: Only a.. Alexandru coreboot main 1:17 PM X |
|
||||
|arch/x86: D.. Alexandru coreboot main 1:09 PM |
|
||||
|cpu: Rename.. Alexandru coreboot master 1:20 PM +1 |
|
||||
|cpu: Only a.. Alexandru coreboot master 1:17 PM X |
|
||||
|arch/x86: D.. Alexandru coreboot master 1:09 PM |
|
||||
| |
|
||||
| Next -> |
|
||||
|Press '?' to view keyboard shortcuts | Powered by Gerrit |
|
||||
|
|
@ -637,7 +637,7 @@ Gerrit makes reviews easier by showing changes in a side-by-side
|
|||
display, and allowing inline comments to be added by any reviewer.
|
||||
|
||||
Gerrit simplifies Git based project maintainership by permitting any
|
||||
authorized user to submit changes to the upstream Git repository, rather
|
||||
authorized user to submit changes to the master Git repository, rather
|
||||
than requiring all approved changes to be merged in by hand by the
|
||||
project maintainer. This functionality enables a more centralized
|
||||
usage of Git.
|
||||
|
|
|
|||
Binary file not shown.
|
Before Width: | Height: | Size: 195 KiB |
|
|
@ -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>
|
||||
|
Before Width: | Height: | Size: 3.6 KiB |
|
|
@ -8,33 +8,27 @@ and those providing after-market firmware to extend the usefulness of devices.
|
|||
|
||||
## Hardware shipping with coreboot
|
||||
|
||||
### Purism
|
||||
|
||||
[Purism](https://www.puri.sm) sells laptops with a focus on user privacy and
|
||||
security; part of that effort is to minimize the amount of proprietary and/or
|
||||
binary code. Their laptops ship with a blob-free OS and coreboot firmware
|
||||
with a neutralized Intel Management Engine (ME) and SeaBIOS as the payload.
|
||||
|
||||
### ChromeOS Devices
|
||||
|
||||
All ChromeOS devices ([Chromebooks](https://chromebookdb.com/), Chromeboxes,
|
||||
Chromebit, etc) released from 2012 onward use coreboot for their main system
|
||||
firmware. Additionally, starting with the 2013 Chromebook Pixel, the firmware
|
||||
running on the Embedded Controller (EC) – a small microcontroller which provides
|
||||
functions like battery management, keyboard support, and sensor interfacing –
|
||||
running on the Embedded Controller (EC - a small microcontroller which provides
|
||||
functions like battery management, keyboard support, and sensor interfacing)
|
||||
is open source as well.
|
||||
|
||||
### Nitrokey
|
||||
### Libretrend
|
||||
|
||||
[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.
|
||||
[Libretrend](https://libretrend.com) sells the Librebox, a NUC-like PC which
|
||||
ships with coreboot firmware.
|
||||
|
||||
### 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
|
||||
|
||||
|
|
@ -43,48 +37,36 @@ 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
|
||||
### Libreboot
|
||||
|
||||
[Dasharo](https://dasharo.com/) is an open-source based firmware distribution
|
||||
focusing on clean and simple code, long-term maintenance, transparent
|
||||
validation, privacy-respecting implementation, liberty for the owners, and
|
||||
trustworthiness for all.
|
||||
[Libreboot](https://libreboot.org) is a downstream coreboot distribution that
|
||||
provides ready-made firmware images for supported devices: those which can be
|
||||
built entirely from source code. Their copy of the coreboot repository is
|
||||
therefore stripped of all devices that require binary components to boot.
|
||||
|
||||
Contributions are welcome,
|
||||
[this document](https://docs.dasharo.com/ways-you-can-help-us/).
|
||||
### MrChromebox
|
||||
|
||||
[MrChromebox](https://mrchromebox.tech/) provides upstream coreboot firmware
|
||||
images for the vast majority of x86-based Chromebooks and Chromeboxes, using
|
||||
Tianocore as the payload to provide a modern UEFI bootloader. Why replace
|
||||
coreboot with coreboot? Mr Chromebox's images are built using upstream
|
||||
coreboot (vs Google's older, static tree/branch), include many features and
|
||||
fixes not found in the stock firmware, and offer much broader OS compatibility
|
||||
(i.e., they run Windows as well as Linux). They also offer updated CPU
|
||||
microcode, as well as firmware updates for the device's embedded controller
|
||||
(EC). This firmware "takes the training wheels off" your ChromeOS device :)
|
||||
|
||||
### John Lewis
|
||||
|
||||
[John Lewis](https://johnlewis.ie/custom-chromebook-firmware) also provides
|
||||
replacement firmware for ChromeOS devices, for the express purpose of
|
||||
running Linux on Chromebooks. John Lewis' firmware supports a much smaller
|
||||
set of devices, and uses SeaBIOS as the payload to support Legacy BIOS booting.
|
||||
His firmware images are significantly older, and not actively maintained or
|
||||
supported, but worth a look if you need Legacy Boot support and is not
|
||||
available via Mr Chromebox's firmware.
|
||||
|
||||
### Heads
|
||||
|
||||
|
|
@ -99,25 +81,6 @@ Heads is not just another Linux distribution – it combines physical hardening
|
|||
of specific hardware platforms and flash security features with custom coreboot
|
||||
firmware and a Linux boot loader in ROM.
|
||||
|
||||
### Libreboot
|
||||
|
||||
[Libreboot](https://libreboot.org) is a downstream coreboot distribution that
|
||||
provides ready-made firmware images for supported devices: those which can be
|
||||
built entirely from source code. Their copy of the coreboot repository is
|
||||
therefore stripped of all devices that require binary components to boot.
|
||||
|
||||
### MrChromebox
|
||||
|
||||
[MrChromebox](https://mrchromebox.tech/) provides upstream coreboot firmware
|
||||
images for the vast majority of x86-based Chromebooks and Chromeboxes, using
|
||||
edk2 as the payload to provide a modern UEFI bootloader. Why replace
|
||||
coreboot with coreboot? Mr Chromebox's images are built using upstream
|
||||
coreboot (vs Google's older, static tree/branch), include many features and
|
||||
fixes not found in the stock firmware, and offer much broader OS compatibility
|
||||
(i.e., they run Windows as well as Linux). They also offer updated CPU
|
||||
microcode, as well as firmware updates for the device's embedded controller
|
||||
(EC). This firmware "takes the training wheels off" your ChromeOS device :)
|
||||
|
||||
### Skulls
|
||||
|
||||
[Skulls](https://github.com/merge/skulls) provides firmware images for
|
||||
|
|
|
|||
319
Documentation/doxygen/Doxyfile.coreboot_platform
Normal file
319
Documentation/doxygen/Doxyfile.coreboot_platform
Normal file
|
|
@ -0,0 +1,319 @@
|
|||
# Doxyfile 1.8.11
|
||||
|
||||
#---------------------------------------------------------------------------
|
||||
# Project related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
DOXYFILE_ENCODING = UTF-8
|
||||
PROJECT_NAME = "coreboot for $(DOXYGEN_PLATFORM)"
|
||||
PROJECT_NUMBER =
|
||||
PROJECT_BRIEF = "coreboot is an Open Source project aimed at replacing the proprietary BIOS found in most computers."
|
||||
PROJECT_LOGO = Documentation/coreboot_logo.png
|
||||
OUTPUT_DIRECTORY = $(DOXYGEN_OUTPUT_DIR)
|
||||
CREATE_SUBDIRS = YES
|
||||
ALLOW_UNICODE_NAMES = NO
|
||||
OUTPUT_LANGUAGE = English
|
||||
BRIEF_MEMBER_DESC = YES
|
||||
REPEAT_BRIEF = YES
|
||||
ABBREVIATE_BRIEF =
|
||||
ALWAYS_DETAILED_SEC = YES
|
||||
INLINE_INHERITED_MEMB = NO
|
||||
FULL_PATH_NAMES = YES
|
||||
STRIP_FROM_PATH =
|
||||
STRIP_FROM_INC_PATH =
|
||||
SHORT_NAMES = NO
|
||||
JAVADOC_AUTOBRIEF = YES
|
||||
QT_AUTOBRIEF = NO
|
||||
MULTILINE_CPP_IS_BRIEF = NO
|
||||
INHERIT_DOCS = YES
|
||||
SEPARATE_MEMBER_PAGES = NO
|
||||
TAB_SIZE = 8
|
||||
ALIASES =
|
||||
TCL_SUBST =
|
||||
OPTIMIZE_OUTPUT_FOR_C = YES
|
||||
OPTIMIZE_OUTPUT_JAVA = NO
|
||||
OPTIMIZE_FOR_FORTRAN = NO
|
||||
OPTIMIZE_OUTPUT_VHDL = NO
|
||||
EXTENSION_MAPPING =
|
||||
MARKDOWN_SUPPORT = YES
|
||||
AUTOLINK_SUPPORT = YES
|
||||
BUILTIN_STL_SUPPORT = NO
|
||||
CPP_CLI_SUPPORT = NO
|
||||
SIP_SUPPORT = NO
|
||||
IDL_PROPERTY_SUPPORT = YES
|
||||
DISTRIBUTE_GROUP_DOC = NO
|
||||
GROUP_NESTED_COMPOUNDS = NO
|
||||
SUBGROUPING = YES
|
||||
INLINE_GROUPED_CLASSES = NO
|
||||
INLINE_SIMPLE_STRUCTS = NO
|
||||
TYPEDEF_HIDES_STRUCT = NO
|
||||
LOOKUP_CACHE_SIZE = 0
|
||||
#---------------------------------------------------------------------------
|
||||
# Build related configuration options
|
||||
#---------------------------------------------------------------------------
|
||||
EXTRACT_ALL = YES
|
||||
EXTRACT_PRIVATE = NO
|
||||
EXTRACT_PACKAGE = NO
|
||||
EXTRACT_STATIC = YES
|
||||
EXTRACT_LOCAL_CLASSES = YES
|
||||
EXTRACT_LOCAL_METHODS = NO
|
||||
EXTRACT_ANON_NSPACES = NO
|
||||
HIDE_UNDOC_MEMBERS = NO
|
||||
HIDE_UNDOC_CLASSES = NO
|
||||
HIDE_FRIEND_COMPOUNDS = NO
|
||||
HIDE_IN_BODY_DOCS = NO
|
||||
INTERNAL_DOCS = NO
|
||||
CASE_SENSE_NAMES = YES
|
||||
HIDE_SCOPE_NAMES = NO
|
||||
HIDE_COMPOUND_REFERENCE= NO
|
||||
SHOW_INCLUDE_FILES = YES
|
||||
SHOW_GROUPED_MEMB_INC = NO
|
||||
FORCE_LOCAL_INCLUDES = NO
|
||||
INLINE_INFO = YES
|
||||
SORT_MEMBER_DOCS = YES
|
||||
SORT_BRIEF_DOCS = NO
|
||||
SORT_MEMBERS_CTORS_1ST = NO
|
||||
SORT_GROUP_NAMES = NO
|
||||
SORT_BY_SCOPE_NAME = NO
|
||||
STRICT_PROTO_MATCHING = NO
|
||||
GENERATE_TODOLIST = YES
|
||||
GENERATE_TESTLIST = YES
|
||||
GENERATE_BUGLIST = YES
|
||||
GENERATE_DEPRECATEDLIST= YES
|
||||
ENABLED_SECTIONS =
|
||||
MAX_INITIALIZER_LINES = 30
|
||||
SHOW_USED_FILES = YES
|
||||
SHOW_FILES = YES
|
||||
SHOW_NAMESPACES = YES
|
||||
FILE_VERSION_FILTER =
|
||||
LAYOUT_FILE =
|
||||
CITE_BIB_FILES =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to warning and progress messages
|
||||
#---------------------------------------------------------------------------
|
||||
QUIET = YES
|
||||
WARNINGS = YES
|
||||
WARN_IF_UNDOCUMENTED = YES
|
||||
WARN_IF_DOC_ERROR = YES
|
||||
WARN_NO_PARAMDOC = YES
|
||||
WARN_AS_ERROR = NO
|
||||
WARN_FORMAT = "$file:$line: $text"
|
||||
WARN_LOGFILE =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the input files
|
||||
#---------------------------------------------------------------------------
|
||||
INPUT = $(DOXYFILES)
|
||||
INPUT_ENCODING = UTF-8
|
||||
FILE_PATTERNS =
|
||||
RECURSIVE = NO
|
||||
EXCLUDE =
|
||||
EXCLUDE_SYMLINKS = NO
|
||||
EXCLUDE_PATTERNS =
|
||||
EXCLUDE_SYMBOLS =
|
||||
EXAMPLE_PATH =
|
||||
EXAMPLE_PATTERNS =
|
||||
EXAMPLE_RECURSIVE = NO
|
||||
IMAGE_PATH =
|
||||
INPUT_FILTER =
|
||||
FILTER_PATTERNS =
|
||||
FILTER_SOURCE_FILES = NO
|
||||
FILTER_SOURCE_PATTERNS =
|
||||
USE_MDFILE_AS_MAINPAGE =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to source browsing
|
||||
#---------------------------------------------------------------------------
|
||||
SOURCE_BROWSER = YES
|
||||
INLINE_SOURCES = NO
|
||||
STRIP_CODE_COMMENTS = NO
|
||||
REFERENCED_BY_RELATION = YES
|
||||
REFERENCES_RELATION = YES
|
||||
REFERENCES_LINK_SOURCE = YES
|
||||
SOURCE_TOOLTIPS = YES
|
||||
USE_HTAGS = NO
|
||||
VERBATIM_HEADERS = YES
|
||||
CLANG_ASSISTED_PARSING = NO
|
||||
CLANG_OPTIONS =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the alphabetical class index
|
||||
#---------------------------------------------------------------------------
|
||||
ALPHABETICAL_INDEX = YES
|
||||
COLS_IN_ALPHA_INDEX = 5
|
||||
IGNORE_PREFIX =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the HTML output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_HTML = YES
|
||||
HTML_OUTPUT = html
|
||||
HTML_FILE_EXTENSION = .html
|
||||
HTML_HEADER =
|
||||
HTML_FOOTER =
|
||||
HTML_STYLESHEET =
|
||||
HTML_EXTRA_STYLESHEET =
|
||||
HTML_EXTRA_FILES =
|
||||
HTML_COLORSTYLE_HUE = 220
|
||||
HTML_COLORSTYLE_SAT = 100
|
||||
HTML_COLORSTYLE_GAMMA = 80
|
||||
HTML_TIMESTAMP = NO
|
||||
HTML_DYNAMIC_SECTIONS = NO
|
||||
HTML_INDEX_NUM_ENTRIES = 100
|
||||
GENERATE_DOCSET = NO
|
||||
DOCSET_FEEDNAME = "Doxygen documentation"
|
||||
DOCSET_BUNDLE_ID = org.doxygen.Project
|
||||
DOCSET_PUBLISHER_ID = org.doxygen.Publisher
|
||||
DOCSET_PUBLISHER_NAME = Publisher
|
||||
GENERATE_HTMLHELP = NO
|
||||
CHM_FILE =
|
||||
HHC_LOCATION =
|
||||
GENERATE_CHI = NO
|
||||
CHM_INDEX_ENCODING =
|
||||
BINARY_TOC = NO
|
||||
TOC_EXPAND = NO
|
||||
GENERATE_QHP = NO
|
||||
QCH_FILE =
|
||||
QHP_NAMESPACE = org.doxygen.Project
|
||||
QHP_VIRTUAL_FOLDER = doc
|
||||
QHP_CUST_FILTER_NAME =
|
||||
QHP_CUST_FILTER_ATTRS =
|
||||
QHP_SECT_FILTER_ATTRS =
|
||||
QHG_LOCATION =
|
||||
GENERATE_ECLIPSEHELP = NO
|
||||
ECLIPSE_DOC_ID = org.doxygen.Project
|
||||
DISABLE_INDEX = NO
|
||||
GENERATE_TREEVIEW = YES
|
||||
ENUM_VALUES_PER_LINE = 4
|
||||
TREEVIEW_WIDTH = 250
|
||||
EXT_LINKS_IN_WINDOW = NO
|
||||
FORMULA_FONTSIZE = 10
|
||||
FORMULA_TRANSPARENT = YES
|
||||
USE_MATHJAX = NO
|
||||
MATHJAX_FORMAT = HTML-CSS
|
||||
MATHJAX_RELPATH = http://cdn.mathjax.org/mathjax/latest
|
||||
MATHJAX_EXTENSIONS =
|
||||
MATHJAX_CODEFILE =
|
||||
SEARCHENGINE = YES
|
||||
SERVER_BASED_SEARCH = NO
|
||||
EXTERNAL_SEARCH = NO
|
||||
SEARCHENGINE_URL =
|
||||
SEARCHDATA_FILE = searchdata.xml
|
||||
EXTERNAL_SEARCH_ID =
|
||||
EXTRA_SEARCH_MAPPINGS =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the LaTeX output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_LATEX = NO
|
||||
LATEX_OUTPUT = latex
|
||||
LATEX_CMD_NAME = latex
|
||||
MAKEINDEX_CMD_NAME = makeindex
|
||||
COMPACT_LATEX = NO
|
||||
PAPER_TYPE = a4wide
|
||||
EXTRA_PACKAGES =
|
||||
LATEX_HEADER =
|
||||
LATEX_FOOTER =
|
||||
LATEX_EXTRA_STYLESHEET =
|
||||
LATEX_EXTRA_FILES =
|
||||
PDF_HYPERLINKS = NO
|
||||
USE_PDFLATEX = NO
|
||||
LATEX_BATCHMODE = NO
|
||||
LATEX_HIDE_INDICES = NO
|
||||
LATEX_SOURCE_CODE = NO
|
||||
LATEX_BIB_STYLE = plain
|
||||
LATEX_TIMESTAMP = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the RTF output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_RTF = NO
|
||||
RTF_OUTPUT = rtf
|
||||
COMPACT_RTF = NO
|
||||
RTF_HYPERLINKS = NO
|
||||
RTF_STYLESHEET_FILE =
|
||||
RTF_EXTENSIONS_FILE =
|
||||
RTF_SOURCE_CODE = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the man page output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_MAN = NO
|
||||
MAN_OUTPUT = man
|
||||
MAN_EXTENSION = .3
|
||||
MAN_SUBDIR =
|
||||
MAN_LINKS = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the XML output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_XML = NO
|
||||
XML_OUTPUT = xml
|
||||
XML_PROGRAMLISTING = YES
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the DOCBOOK output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_DOCBOOK = NO
|
||||
DOCBOOK_OUTPUT = docbook
|
||||
DOCBOOK_PROGRAMLISTING = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options for the AutoGen Definitions output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_AUTOGEN_DEF = NO
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the Perl module output
|
||||
#---------------------------------------------------------------------------
|
||||
GENERATE_PERLMOD = NO
|
||||
PERLMOD_LATEX = NO
|
||||
PERLMOD_PRETTY = YES
|
||||
PERLMOD_MAKEVAR_PREFIX =
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the preprocessor
|
||||
#---------------------------------------------------------------------------
|
||||
ENABLE_PREPROCESSING = YES
|
||||
MACRO_EXPANSION = YES
|
||||
EXPAND_ONLY_PREDEF = YES
|
||||
SEARCH_INCLUDES = YES
|
||||
INCLUDE_PATH =
|
||||
INCLUDE_FILE_PATTERNS =
|
||||
PREDEFINED = __attribute__(x)=
|
||||
EXPAND_AS_DEFINED =
|
||||
SKIP_FUNCTION_MACROS = YES
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to external references
|
||||
#---------------------------------------------------------------------------
|
||||
TAGFILES =
|
||||
GENERATE_TAGFILE =
|
||||
ALLEXTERNALS = NO
|
||||
EXTERNAL_GROUPS = YES
|
||||
EXTERNAL_PAGES = YES
|
||||
PERL_PATH = /usr/bin/perl
|
||||
#---------------------------------------------------------------------------
|
||||
# Configuration options related to the dot tool
|
||||
#---------------------------------------------------------------------------
|
||||
CLASS_DIAGRAMS = YES
|
||||
MSCGEN_PATH =
|
||||
DIA_PATH =
|
||||
HIDE_UNDOC_RELATIONS = NO
|
||||
HAVE_DOT = NO
|
||||
DOT_NUM_THREADS = 0
|
||||
DOT_FONTNAME = Helvetica
|
||||
DOT_FONTSIZE = 10
|
||||
DOT_FONTPATH =
|
||||
CLASS_GRAPH = YES
|
||||
COLLABORATION_GRAPH = YES
|
||||
GROUP_GRAPHS = YES
|
||||
UML_LOOK = YES
|
||||
UML_LIMIT_NUM_FIELDS = 10
|
||||
TEMPLATE_RELATIONS = NO
|
||||
INCLUDE_GRAPH = YES
|
||||
INCLUDED_BY_GRAPH = YES
|
||||
CALL_GRAPH = YES
|
||||
CALLER_GRAPH = YES
|
||||
GRAPHICAL_HIERARCHY = YES
|
||||
DIRECTORY_GRAPH = YES
|
||||
DOT_IMAGE_FORMAT = png
|
||||
INTERACTIVE_SVG = NO
|
||||
DOT_PATH =
|
||||
DOTFILE_DIRS =
|
||||
MSCFILE_DIRS =
|
||||
DIAFILE_DIRS =
|
||||
PLANTUML_JAR_PATH =
|
||||
PLANTUML_INCLUDE_PATH =
|
||||
DOT_GRAPH_MAX_NODES = 50
|
||||
MAX_DOT_GRAPH_DEPTH = 0
|
||||
DOT_TRANSPARENT = NO
|
||||
DOT_MULTI_TARGETS = YES
|
||||
GENERATE_LEGEND = YES
|
||||
DOT_CLEANUP = YES
|
||||
|
|
@ -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)
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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"
|
||||
```
|
||||
|
|
@ -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
|
||||
},
|
||||
};
|
||||
```
|
||||
|
|
@ -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
|
||||
}"
|
||||
```
|
||||
|
|
@ -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)
|
||||
|
|
@ -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.
|
||||
|
|
@ -1,33 +1,7 @@
|
|||
# Platform independent drivers documentation
|
||||
# Platform indenpendend 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.
|
||||
they allow to easily reuse existing code accross platforms.
|
||||
|
||||
For details on how to connect device drivers to a mainboard, see [Driver Devicetree Entries](dt_entries.md).
|
||||
|
||||
```{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>
|
||||
```
|
||||
* [IPMI KCS](ipmi_kcs.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
|
||||
|
|
@ -42,15 +42,6 @@ The following registers can be set:
|
|||
* `gpe_interrupt`
|
||||
* Integer
|
||||
* The bit in GPE (SCI) used to notify about a change on the KCS.
|
||||
* `wait_for_bmc`
|
||||
* Boolean
|
||||
* Wait for BMC to boot. This can be used if the BMC takes a long time to boot
|
||||
after PoR:
|
||||
- AST2400 on Supermicro X11SSH: 34 s
|
||||
* `bmc_boot_timeout`
|
||||
* Integer
|
||||
* The timeout in seconds to wait for the IPMI service to be loaded.
|
||||
Will be used if wait_for_bmc is true.
|
||||
|
||||
|
||||
[IPMI]: https://www.intel.com/content/dam/www/public/us/en/documents/product-briefs/ipmi-second-gen-interface-spec-v2-rev1-1.pdf
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
```
|
||||
|
|
@ -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/)
|
||||
23
Documentation/flash_tutorial/ext_standalone.md
Normal file
23
Documentation/flash_tutorial/ext_standalone.md
Normal file
|
|
@ -0,0 +1,23 @@
|
|||
# Flashing firmware standalone
|
||||
|
||||
If none of the other methods work, there are three possibilities:
|
||||
|
||||
## Desolder
|
||||
You must remove or desolder the flash IC before you can flash it.
|
||||
It's recommended to solder a socket in place of the flash IC.
|
||||
|
||||
When flashing the IC, always connect all input pins.
|
||||
If in doubt, pull /WP, /HOLD, /RESET and alike up towards Vcc.
|
||||
|
||||
## SPI flash emulator
|
||||
If you are a developer, you might want to use an [EM100Pro] instead, which sets
|
||||
the onboard flash on hold, and allows to run custom firmware.
|
||||
It provides a very fast development cycle without actually writing to flash.
|
||||
|
||||
## SPI flash overwrite
|
||||
It is possible to set the onboard flash on hold and use another flash chip.
|
||||
Connect all lines one-to-one, except /HOLD. Pull /HOLD of the soldered flash IC
|
||||
low, and /HOLD of your replacement flash IC high.
|
||||
|
||||
|
||||
[EM100Pro]: https://www.dediprog.com/product/EM100Pro
|
||||
|
Before Width: | Height: | Size: 5 KiB After Width: | Height: | Size: 5 KiB |
|
Before Width: | Height: | Size: 4.5 KiB After Width: | Height: | Size: 4.5 KiB |
111
Documentation/flash_tutorial/index.md
Normal file
111
Documentation/flash_tutorial/index.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
# Flashing firmware tutorial
|
||||
|
||||
Updating the firmware is possible using the **internal method**, where the updates
|
||||
happen from a running system, or using the **external method**, where the system
|
||||
is in a shut down state and an external programmer is attached to write into the
|
||||
flash IC.
|
||||
|
||||
## Contents
|
||||
|
||||
* [Flashing internaly](int_flashrom.md)
|
||||
* [Flashing firmware standalone](ext_standalone.md)
|
||||
* [Flashing firmware externally supplying direct power](ext_power.md)
|
||||
* [Flashing firmware externally without supplying direct power](no_ext_power.md)
|
||||
|
||||
## General advice
|
||||
|
||||
* It's recommended to only flash the BIOS region.
|
||||
* Always verify the firmware image.
|
||||
* If you flash externally and have transmission errors:
|
||||
* Use short wires
|
||||
* Reduce clock frequency
|
||||
* Check power supply
|
||||
* Make sure that there are no other bus masters (EC, ME, SoC, ...)
|
||||
|
||||
## Internal method
|
||||
|
||||
This method using [flashrom] is available on many platforms, as long as they
|
||||
aren't locked down.
|
||||
|
||||
There are various protection schemes that make it impossible to modify or
|
||||
replace a firmware from a running system. coreboot allows to disable these
|
||||
mechanisms, making it possible to overwrite (or update) the firmware from a
|
||||
running system.
|
||||
|
||||
Usually you must use the **external method** once to install a retrofitted
|
||||
coreboot and then you can use the **internal method** for future updates.
|
||||
|
||||
There are multiple ways to update the firmware:
|
||||
* Using flashrom's *internal* programmer to directly write into the firmware
|
||||
flash IC, running on the target machine itself
|
||||
* A proprietary software to update the firmware, running on the target machine
|
||||
itself
|
||||
* A UEFI firmware update capsule
|
||||
|
||||
More details on flashrom's
|
||||
* [internal programmer](int_flashrom.md)
|
||||
|
||||
## External method
|
||||
|
||||
External flashing is possible on many platforms, but requires disassembling
|
||||
the target hardware. You need to buy a flash programmer, that
|
||||
exposes the same interface as your flash IC (likely SPI).
|
||||
|
||||
Please also have a look at the mainboard-specific documentation for details.
|
||||
|
||||
After exposing the firmware flash IC, read the schematics and use one of the
|
||||
possible methods:
|
||||
|
||||
* [Flashing firmware standalone](ext_standalone.md)
|
||||
* [Flashing firmware externally supplying direct power](ext_power.md)
|
||||
* [Flashing firmware externally without supplying direct power](no_ext_power.md)
|
||||
|
||||
**WARNING:** Using the wrong method or accidentally using the wrong pinout might
|
||||
permanently damage your hardware!
|
||||
|
||||
**WARNING:** Do not rely on dots *painted* on flash ICs to orient the pins!
|
||||
Any dots painted on flash ICs may only indicate if they've been tested. Dots
|
||||
that appear in datasheets to indicate pin 1 correspond to some kind of physical
|
||||
marker, such as a drilled hole, or one side being more flat than the other.
|
||||
|
||||
## Using a layout file
|
||||
On platforms where the flash IC is shared with other components you might want
|
||||
to write only a part of the flash IC. On Intel for example there are IFD, ME and
|
||||
GBE which don't need to be updated to install coreboot.
|
||||
To make [flashrom] only write the *bios* region, leaving Intel ME and Intel IFD
|
||||
untouched, you can use a layout file, which can be created with ifdtool and a backup
|
||||
of the original firmware.
|
||||
|
||||
```bash
|
||||
ifdtool -f rom.layout backup.rom
|
||||
```
|
||||
|
||||
and looks similar to:
|
||||
|
||||
```
|
||||
00000000:00000fff fd
|
||||
00500000:00bfffff bios
|
||||
00003000:004fffff me
|
||||
00001000:00002fff gbe
|
||||
```
|
||||
|
||||
By specifying *-l* and *-i* [flashrom] writes a single region:
|
||||
```bash
|
||||
flashrom -l rom.layout -i bios -w coreboot.rom -p <programmer>
|
||||
```
|
||||
|
||||
## Using an IFD to determine the layout
|
||||
flashrom version 1.0 supports reading the layout from the IFD (first 4KiB of
|
||||
the ROM). You don't need to manually specify a layout it, but it only works
|
||||
under the following conditions:
|
||||
|
||||
* Only available on Intel ICH7+
|
||||
* There's only one flash IC when flashing externally
|
||||
|
||||
```bash
|
||||
flashrom --ifd -i bios -w coreboot.rom -p <programmer>
|
||||
```
|
||||
|
||||
**TODO** explain FMAP regions, normal/fallback mechanism, flash lock mechanisms
|
||||
|
||||
[flashrom]: https://www.flashrom.org/Flashrom
|
||||
|
|
@ -5,7 +5,7 @@
|
|||
|
||||
## Using flashrom
|
||||
This method does only work on Linux, if it isn't locked down.
|
||||
You may also need to boot with `iomem=relaxed` in the kernel command
|
||||
You may also need to boot with 'iomem=relaxed' in the kernel command
|
||||
line if CONFIG_IO_STRICT_DEVMEM is set.
|
||||
|
||||
|
||||
|
|
@ -19,7 +19,7 @@ time). The file gcov-io.c is unchanged.
|
|||
+#define BITS_PER_UNIT 8
|
||||
+#define LONG_LONG_TYPE_SIZE 64
|
||||
+
|
||||
+/* There are many gcc_assertions. Set the value to 1 if we want a warning
|
||||
+/* There are many gcc_assertions. Set the vaule to 1 if we want a warning
|
||||
+ message if the assertion fails. */
|
||||
+#ifndef ENABLE_ASSERT_CHECKING
|
||||
+#define ENABLE_ASSERT_CHECKING 1
|
||||
|
|
|
|||
|
|
@ -1,16 +1,16 @@
|
|||
# coreboot architecture
|
||||
|
||||
## Overview
|
||||
## Overwiew
|
||||
![][architecture]
|
||||
|
||||
[architecture]: comparison_coreboot_uefi.svg
|
||||
[architecture]: comparision_coreboot_uefi.svg
|
||||
|
||||
## Stages
|
||||
coreboot consists of multiple stages that are compiled as separate binaries and
|
||||
are inserted into the CBFS with custom compression. The bootblock usually doesn't
|
||||
have compression while the ramstage and payload are compressed with LZMA.
|
||||
|
||||
Each stage loads the next stage at given address (possibly decompressing it).
|
||||
Each stage loads the next stage a 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.
|
||||
|
|
@ -41,7 +41,7 @@ The bootblock loads the romstage or the verstage if verified boot is enabled.
|
|||
|
||||
### Cache-As-Ram
|
||||
The *Cache-As-Ram*, also called Non-Eviction mode, or *CAR* allows to use the
|
||||
CPU cache like regular SRAM. This is particularly useful for high level
|
||||
CPU cache like regular SRAM. This is particullary usefull for high level
|
||||
languages like `C`, which need RAM for heap and stack.
|
||||
|
||||
The CAR needs to be activated using vendor specific CPU instructions.
|
||||
|
|
@ -85,7 +85,7 @@ The ramstage does the main device init:
|
|||
* CPU init (like set up SMM)
|
||||
|
||||
After initialization tables are written to inform the payload or operating system
|
||||
about the current hardware existence and state. That includes:
|
||||
about the current hardware existance and state. That includes:
|
||||
|
||||
* ACPI tables (x86 specific)
|
||||
* SMBIOS tables (x86 specific)
|
||||
|
|
|
|||
|
|
@ -7,10 +7,10 @@ to the point of providing its own custom language.
|
|||
The overhead of learning this new syntax is (hopefully) offset by its lower
|
||||
complexity.
|
||||
|
||||
The build system is defined in the toplevel `Makefile` and `toolchain.mk`
|
||||
The build system is defined in the toplevel `Makefile` and `toolchain.inc`
|
||||
and is supposed to be generic (and is in fact used with a number of other
|
||||
projects). Project specific configuration should reside in files called
|
||||
`Makefile.mk`.
|
||||
`Makefile.inc`.
|
||||
|
||||
In general, the build system provides a number of "classes" that describe
|
||||
various parts of the build. These cover the various build targets in coreboot
|
||||
|
|
@ -36,7 +36,7 @@ TODO: explain how to create new classes and how to evaluate them.
|
|||
### subdirs
|
||||
`subdirs` contains subdirectories (relative to the current directory) that
|
||||
should also be handled by the build system. The build system expects these
|
||||
directories to contain a file called `Makefile.mk`.
|
||||
directories to contain a file called `Makefile.inc`.
|
||||
|
||||
Subdirectories are not read at the point where the `subdirs` statement
|
||||
resides but later, after the current directory is handled (and potentially
|
||||
|
|
@ -62,21 +62,6 @@ supported options are:
|
|||
|
||||
`position` and `align` are mutually exclusive.
|
||||
|
||||
### Adding Makefile fragments
|
||||
|
||||
You can use the `add_intermediate` helper to add new post-processing steps for
|
||||
the final `coreboot.rom` image. For example you can add new files to CBFS by
|
||||
adding something like this to `site-local/Makefile.mk`
|
||||
|
||||
```
|
||||
$(call add_intermediate, add_mrc_data)
|
||||
$(CBFSTOOL) $< write -r RW_MRC_CACHE -f site-local/my-mrc-recording.bin
|
||||
```
|
||||
|
||||
Note that the second line must start with a tab, not spaces.
|
||||
|
||||
See also <project:../tutorial/managing_local_additions.md>.
|
||||
|
||||
#### FMAP region support
|
||||
With the addition of FMAP flash partitioning support to coreboot, there was a
|
||||
need to extend the specification of files to provide more precise control
|
||||
|
|
@ -98,4 +83,4 @@ The default implementation just returns `COREBOOT` (the default region) for
|
|||
all files.
|
||||
|
||||
vboot provides its own implementation of `regions-for-file` that can be used
|
||||
as reference in `src/vboot/Makefile.mk`.
|
||||
as reference in `src/vboot/Makefile.inc`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
Before Width: | Height: | Size: 12 KiB After Width: | Height: | Size: 12 KiB |
|
|
@ -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.**
|
||||
Some files were not shown because too many files have changed in this diff Show more
Loading…
Add table
Add a link
Reference in a new issue